Chapter 10: Real-World Patterns: Research, Automation, and Support

Start with chapters 6, 3, 4, and 9, then inspect the requirements for chapters/10-real-world.md and the six files under examples/10-real-world/. Run the first sample with bun run and verify each sample is runnable and importable as specified. Done means the chapter and all agents, approval gate, eval harness, and unified Telegram entry point meet the line, build, routing, and README/sidebar checks.

Part of the Build Your Own Coding Agent tutorial. One issue = one chapter (chapters/10-real-world.md) plus its examples/10-real-world/ samples.

Goal (1 sentence): Apply everything to three agent archetypes (research, automation, support) plus human-in-the-loop gates and a small eval harness, all wired into Telegram.

After this chapter you can

• Compose the Chapter 6 runner with domain tool sets to build research, automation, and support agents that each carry their own messages history and share a single Telegram bot client.
• Implement a human-in-the-loop approval gate that intercepts a tool_use block, emits a Telegram inline-keyboard prompt, and resumes or cancels the tool cycle based on the reply.
• Integrate RAG retrieval as a tool call for the support agent, using a retrieve_docs tool that fetches top-k chunks and a cache_control block on the static knowledge-base system prompt to cut cost across repeated queries.
• Build a minimal eval harness that replays fixture conversations through client.messages.create, extracts structured assertions from the final text block, and logs pass/fail with usage metrics to track cost per eval.
• Wire all three agents into one Telegram bot, routing /research, /automate, and /support commands to separate agent instances.

What to cover (ONE paragraph, not a list)

This chapter wires the Chapter 6 runner into three production archetypes. The research agent defines a web_search tool with input_schema, chains multiple tool_use -> tool_result turns, and controls depth with a step counter checked on each stop_reason === "tool_use" guard. The automation agent is triggered from a cron or webhook handler, passes task context through the system prompt, and forces an action on the first turn with tool_choice: { type: "any" }, then resets to auto on later turns so the loop can reach end_turn - because forced tool_choice blocks a final text reply. The support agent adds a retrieve_docs tool for top-k RAG retrieval, an escalate_to_human tool that fires a Telegram notification, and a cache_control block on the static knowledge-base system prompt to cut latency and cost across repeated queries. Safety checks inspect tool_use.name and tool_use.input before execution and short-circuit with an explanatory tool_result when a call looks destructive; token budgeting reads usage.input_tokens and usage.output_tokens after each turn and trims oldest non-system messages when the running total nears the context limit. The chapter closes by routing /research, /automate, and /support Telegram commands to their respective agent instances and measuring quality with the eval harness.

Going deeper (optional asides - keep OFF the main line)

• None

Out of scope (defer - do NOT preview)

• None

Code samples - examples/10-real-world/

• research-agent.ts - bounded multi-step web-search + synthesis.
• automation-agent.ts - cron-triggered; forced first action then auto.
• support-agent.ts - retrieve_docs + escalate_to_human + cached KB prompt.
• approval-gate.ts - intercept destructive tool_use; Telegram confirm; resume/cancel.
• eval-harness.ts - fixture replay scoring tool selection + answer quality.
• telegram-all-agents.ts - route /research /automate /support to the three agents.

Must-keep for a beginner (floor - never cut for brevity)

• The run command for the first sample.
• "Never hardcode your key; it comes from the environment" (once, in prose).
• Anything a beginner cannot infer from the code (e.g. Bun auto-loads .env, no loader needed).
• The one genuinely non-obvious gotcha: tool_choice: { type: "any" } prevents a final end_turn text reply - reset to auto on subsequent turns or the loop never terminates.

Friendliness floor (never cut - terse is not friendly)

• The chapter addresses the reader as "you", never "the user" or "one".
• The intro AND at least one section open with a warm, second-person sentence.

Key APIs (flat list, reference only - NOT a coverage checklist)

client.messages.create, client.messages.stream, stop_reason, tool_use, tool_result, tool_choice (auto/any/tool), input_schema, usage.input_tokens, usage.output_tokens, cache_control, system, tools, human-in-the-loop gate, eval harness

Prerequisites

Chapters 6 (reusable runner), 3 (Telegram raw fetch), 4 (conversation history), 9 (RAG/retrieval); a vector store for retrieve_docs.

Definition of done

• Chapter at chapters/10-real-world.md, <=120 lines, <=4 main-line H2s plus an optional "What's next" closer (paste wc -l AND grep -c '^## ' in the PR).
• Every sample runnable with bun run, imported via <<< @/examples/10-real-world/file.ts, <=35 lines, comment:code <=0.30.
• One-home rule held: no prose sentence restates an inline code comment.
• Friendliness floor held: reader addressed as "you"; intro + >=1 section open warm.
• Samples use only real @anthropic-ai/sdk surface; ASCII punctuation only.
• Optional material lives in Going-deeper asides, not main-line H2s.
• All three agents + gate + eval harness implemented and runnable with bun run.
• Unified Telegram entry point routes all three archetypes.
• Linked from README.md and the .vitepress/config.ts sidebar; bun x vitepress build passes.