Lesson 04 — A Tool-Heavy Research Assistant

The Claude Agent SDK at its sweet spot: 5 tools, unbounded tool-call order, ~120 lines of Python.

Agents Module 2 Claude Agent SDK Tool-Heavy

Why this is the SDK's sweet spot

• Many tools — 5 in this lesson (search, fetch × 2 backends + a final-answer tool).
• Order is data-driven — the next tool depends on what the previous tool returned. No fixed graph.
• No multi-agent role play — one agent, one loop.
• Cost matters but isn't extreme — tens of cents per run, not tens of dollars.
• Claude is the model — by construction.

Hits every condition on L03 Slide 11's “Pick it when” list.

The assistant we're building

Real example question: “What changed in Linux kernel 6.14's networking stack?”

The agent decides on its own which sources to consult, in what order, and when it has enough material to write the report.

The five tools

Why mocked, not real?

• Real web search needs API keys (Tavily, Serper, etc.) and the wire format changes month-to-month.
• The agent shape is what matters in this lesson — the tool implementations are deterministic Python so the lab is reproducible.
• Module 6 (Plan F) wires the same agent into the cross-framework scorecard with real tools as an optional swap.

The system prompt

You are a research assistant. To answer a question:
1. Check `pkb.search` first; fetch any promising doc with `pkb.fetch`.
2. If you need more, use `web_search`; fetch with `web_fetch`.
3. When you have enough material, call `write_report(intro, bullets, sources)`.
Always cite sources by URL or doc_id. Be concise.

The prompt does not prescribe an exact tool order — it gives the LLM a strategy. The LLM picks the actual sequence per question.

The write_report final-answer tool pattern

• Instead of relying on the LLM to format the final answer as plain text, give it a tool whose only job is to record the structured answer.
• This guarantees the structure (intro + bullets + sources) and makes the answer parsable for downstream code.
• The SDK supports this naturally — write_report is just a normal @tool-decorated function that returns "saved".
• You stop the loop when this tool is called and the next turn yields end_turn.

The @tool definitions

@tool
def pkb_search(query: str) -> str:
    """Search the personal knowledge base by substring. Returns
    a list of '{doc_id}: {title} - {one-line snippet}' lines."""
    hits = [f"{k}: {v['title']} - {v['snippet']}"
            for k, v in PKB.items() if query.lower() in v['text'].lower()]
    return "\n".join(hits) if hits else "no matches"

@tool
def pkb_fetch(doc_id: str) -> str:
    """Fetch the full text of a PKB doc by id."""
    return PKB.get(doc_id, {}).get("text", f"unknown doc: {doc_id}")

Two of the five shown here; the others (web_search, web_fetch, write_report) follow the same pattern — one function, one decorator, one docstring.

The agent assembly

from anthropic import Anthropic
from anthropic.agents import Agent

agent = Agent(
    client=Anthropic(),
    model="claude-3-5-sonnet-latest",
    system=SYSTEM_PROMPT,
    tools=[pkb_search, pkb_fetch, web_search, web_fetch, write_report],
    max_turns=15,
    max_cost_usd=0.50,
    on_step=log_step,
)
report = agent.run(question)
print(report.final_text)

~12 lines of glue around the tool definitions. The agent loop, message-dance, and stop conditions are all inside Agent.run().

A real run trace

[step 1] tools=[pkb_search]            cost=$0.003
[step 2] tools=[pkb_fetch]             cost=$0.007
[step 3] tools=[web_search]            cost=$0.011
[step 4] tools=[web_fetch, web_fetch]  cost=$0.018
[step 5] tools=[write_report]          cost=$0.024
[step 6] tools=[]                      cost=$0.026  (end_turn)

Note: turn 4 has parallel tool calls — the SDK runs both web_fetch calls concurrently, and the LLM gets both results back together.

Parallel tool calls — free with the SDK

• When the LLM emits 2+ tool_use blocks in one turn, the SDK runs them all (asyncio) and returns their results together.
• This is the kind of optimisation that L02's hand-rolled loop could have done but didn't.
• The SDK gives you it for free — no extra config, no extra code.

Cost and latency profile

• ~6 turns is typical for a moderate question (~$0.02–$0.05 with Sonnet).
• Latency: ~15–25 seconds end-to-end. Parallel tool calls cut ~3–5 seconds off the long-tail runs.
• Compare with L02: hand-rolled, no parallelism, ~30% slower for the same question shape.

For a research assistant that gets called interactively a few times an hour, this is a comfortable budget.

What's left to wire (Module 6 hook)

Recap & what's next

• Tool-heavy = SDK sweet spot. 5 tools, data-driven order, one model — this is exactly the shape Agent(...) was built for.
• The write_report tool pattern gives you structured final answers without an extra schema layer.
• Parallel tool calls are free — the SDK detects independent tool uses in a single turn and fans them out automatically.