Implement #6: Building Tool Chains and Complex Workflows

[yagop]

Closes #6

Chapter 6 turns Chapter 5's single tool round-trip into the core agent engine: a loop that drives client.messages.create until end_turn, handling sequential chains, parallel tool calls, tool_choice, and a reusable runner. Authored single-pass (per the updated skill) and verified end-to-end.

Definition of done

• Chapter at chapters/06-tool-chains.md, <=120 lines, <=4 main-line H2s plus a closer
• Every sample runnable with bun run, imported via <<< @/examples/06-tool-chains/file.ts
• One-home rule held (the append-before-tool_result ordering and the forcing gotcha live in prose, not in code comments); reader addressed as "you"; intro + sections open warm
• Samples use only real @anthropic-ai/sdk surface (verified against the SDK .d.ts); ASCII punctuation only
• Optional material (betaZodTool + toolRunner) lives in a Going-deeper :::details aside, not a main-line H2
• Linked from README.md and the .vitepress/config.ts sidebar; bun x vitepress build passes
• The runner is genuinely reusable (a Map registry + Anthropic.Tool[] + maxIterations + is_error, drop-in for the Ch.3 Telegram surface)
• Sample line budget: samples are 38-69 lines, above the issue's stated <=35 - see note below

Verification (run live against an Anthropic-compatible gateway)

Chapter budget: wc -l -> 65 (<=120); grep -c '^## ' -> 4.

Samples (all <=100 lines, comment:code <=0.40, one statement per line):

agent-loop.ts         45   sequential-chain.ts   62   agent-runner.ts        69
parallel-tools.ts     44   tool-choice.ts        38   runner-with-stream.ts  50

bunx tsc --noEmit clean; bun x vitepress build passes (all six snippets resolve). Each sample was run, not just typechecked:

• agent-loop.ts -> loop turns over twice (weather for Paris and Oslo), then a final compared answer.
• sequential-chain.ts -> find_user({"name":"Ada Lovelace"}) -> u_42, then get_balance({"userId":"u_42"}), then "balance is 1200.50 USD" - the dependent call serialized across turns by the model.
• parallel-tools.ts -> running 3 tool call(s) for this turn (Paris/Tokyo/Cairo emitted in one turn, resolved together with Promise.all).
• agent-runner.ts -> reusable runner does 19 + 23 = 42, then + 100 = 142.
• runner-with-stream.ts -> text streams across tool turns ("I'll roll a 20-sided die...", then the result), via stream + finalMessage().
• tool-choice.ts -> ran auto / any / tool / none; see gateway note below.

Notes / honesty flags

• tool_choice forcing on this gateway: the GLM gateway used for the live run does not honor forced tool_choice - all four modes returned stop_reason=end_turn, called_tool=false for the "just say hello" prompt. On Anthropic direct, any and { type: 'tool' } would force a call and return stop_reason=tool_use, which is exactly the must-keep gotcha the chapter teaches (a forced turn never reports end_turn, so the loop must keep its exit on end_turn and force only when it wants a call). The sample code is correct against the Anthropic API.
• Sample sizes vs the issue's <=35: agent-loop samples don't fit 35 readable lines, so these run 38-69 lines under the skill's current 100-line budget. That issue-DoD line is the place to reconcile.

Review flags

None.

🤖 Generated with Claude Code