A chef, not a recipe

↗ Source: Anthropic · building-effective-agents

The tool card

{
  "name": "read_file",
  "description": "Read a range of lines from one text file. Lines come back numbered as 'N| text' so you can cite them as path:N. At most 400 lines per call: read big files in ranges.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {"type": "string", "description": "File path relative to the repo root, e.g. 'src/app.py'."},
      "start_line": {"type": "integer", "description": "First line to read, 1-based. Default 1."},
      "end_line": {"type": "integer", "description": "Last line to read, inclusive. Default start_line + 399."}
    },
    "required": ["path"],
    "additionalProperties": false
  }
}

The stop_reason values

• tool_use
  What it means: Claude is calling one or more tools
  What your loop does: Run them, send every result back, call again
• end_turn
  What it means: Claude finished its answer
  What your loop does: Return the text; the loop ends
• max_tokens
  What it means: The response hit your max_tokens
  What your loop does: Stop; a cut-off tool_use must be retried with more max_tokens
• pause_turn
  What it means: A server-tool loop hit its limit
  What your loop does: Send the response back as-is to continue
• refusal
  What it means: Claude declined
  What your loop does: Stop and report it
• stop_sequence
  What it means: One of your stop sequences appeared
  What your loop does: Handle as your app defines
• model_context_window_exceeded
  What it means: The counter is full
  What your loop does: Stop; compact or start narrower

"model": "claude-opus-5-5",
"max_tokens": 16000,
"system": "You are a read-only sous-chef for a code repository. ...",
"tools": [ /* the list_files, read_file and search cards */ ],

  "messages": [

  ]

{
  "id": "msg_01Aq9w938a90dw8q",
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    {"type": "thinking", "thinking": "...", "signature": "..."},
    {"type": "text", "text": "I'll search for the loader and open the likely file."},
    {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "search", "input": {"pattern": "def load_config"}},
    {"type": "tool_use", "id": "toolu_01B7xk2mJ3pZ8wQ4vN6rT1sY", "name": "read_file", "input": {"path": "config.py"}}
  ]
}

{
  "role": "assistant",
  "stop_reason": "end_turn",
  "content": [
    {"type": "text", "text": "The config is loaded by load_config(), defined at src/config.py:3."}
  ]
}

// 1. Request: your code -> API
{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "system": "You are a read-only sous-chef for a code repository. ...",
  "tools": [ /* the list_files, read_file and search cards */ ],
  "messages": [
    {"role": "user", "content": "Where is the config loaded?"}
  ]
}

// 2. Response: API -> your code. Two calls in one turn (parallel).
{
  "id": "msg_01Aq9w938a90dw8q",
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    {"type": "thinking", "thinking": "...", "signature": "..."},
    {"type": "text", "text": "I'll search for the loader and open the likely file."},
    {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "search", "input": {"pattern": "def load_config"}},
    {"type": "tool_use", "id": "toolu_01B7xk2mJ3pZ8wQ4vN6rT1sY", "name": "read_file", "input": {"path": "config.py"}}
  ]
}

// 3. Request: the same history + that assistant turn, unchanged + ONE user message with both results
"messages": [
  {"role": "user", "content": "Where is the config loaded?"},
  {"role": "assistant", "content": [ /* the four blocks above, unchanged */ ]},
  {"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
     "content": "src/config.py:3: def load_config():"},
    {"type": "tool_result", "tool_use_id": "toolu_01B7xk2mJ3pZ8wQ4vN6rT1sY", "is_error": true,
     "content": "'config.py' does not exist. Call list_files on its parent folder, or search for its name."}
  ]}
]

// 4. Response: stop_reason "end_turn". The loop returns the text.
{
  "role": "assistant",
  "stop_reason": "end_turn",
  "content": [
    {"type": "text", "text": "The config is loaded by load_config(), defined at src/config.py:3."}
  ]
}

• One result per call, all in one message «return one tool_result for each tool_use block, all together in the next user message». Splitting them across messages «"teaches" Claude to avoid parallel calls».
• Results first In that user message «the tool_result blocks must come FIRST»; any text goes after them.
• Send the assistant turn back unchanged Thinking blocks included.
• Errors are data, not exceptions is_error: true plus a message that says what to do instead. Claude «will retry 2–3 times with corrections», so the message is worth writing well.

↗ Source: Anthropic · overview↗ Source: Anthropic · handle-tool-calls↗ Source: Anthropic · parallel-tool-use↗ Source: Anthropic · handling-stop-reasons✓ Our test

import anthropic

client = anthropic.Anthropic()                    # reads ANTHROPIC_API_KEY from the environment

def run_agent(question, sandbox, max_turns=12):
    messages = [{"role": "user", "content": question}]
    for turn in range(max_turns):                 # closing time
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=16000,
            system=SYSTEM,
            tools=TOOLS,
            messages=messages,                    # the WHOLE history, every call
            cache_control={"type": "ephemeral"},  # so the repeated prefix is cheap
        )
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason == "end_turn":
            return "".join(b.text for b in response.content if b.type == "text")
        if response.stop_reason != "tool_use":
            raise RuntimeError(f"stopped: {response.stop_reason}")  # max_tokens, refusal...

        results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            content, is_error = run_tool(sandbox, block.name, block.input)
            result = {"type": "tool_result", "tool_use_id": block.id, "content": content}
            if is_error:
                result["is_error"] = True
            results.append(result)
        messages.append({"role": "user", "content": results})  # ONE message
    raise RuntimeError(f"no answer after {max_turns} turns")

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def read_file(path: str, start_line: int = 1, end_line: int = 400) -> str:
    """Read a range of lines from one text file in the repo, numbered 'N| text'.

    Args:
        path: File path relative to the repo root.
        start_line: First line to read, 1-based.
        end_line: Last line to read, inclusive.
    """
    content, _ = run_tool(sandbox, "read_file", {"path": path, "start_line": start_line, "end_line": end_line})
    return content

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=16000,
    max_iterations=12,
    tools=[read_file],
    messages=[{"role": "user", "content": "Where is the config loaded?"}],
)
for message in runner:
    print(message.stop_reason)

import asyncio
from claude_agent_sdk import ClaudeAgentOptions, HookMatcher, ResultMessage, query

async def no_writes(input_data, tool_use_id, context):
    return {"hookSpecificOutput": {
        "hookEventName": input_data["hook_event_name"],
        "permissionDecision": "deny",
        "permissionDecisionReason": "This agent is read-only.",
    }}

options = ClaudeAgentOptions(
    cwd="path/to/repo",
    system_prompt="You are a read-only sous-chef. Cite every claim as path:line.",
    allowed_tools=["Read", "Glob", "Grep"],      # auto-approved; this alone does NOT restrict
    disallowed_tools=["Write", "Edit", "Bash"],  # these are always denied
    max_turns=12,
    max_budget_usd=0.50,
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit|Bash", hooks=[no_writes])]},
)

async def main():
    async for message in query(prompt="Where is the config loaded?", options=options):
        if isinstance(message, ResultMessage):
            print(message.subtype, message.num_turns, message.total_cost_usd)

asyncio.run(main())

↗ Source: Anthropic · overview↗ Source: Anthropic · python↗ Source: Anthropic · hooks↗ Source: Anthropic · tool-runner✓ Our test

def chain(text, steps):
    for step in steps:
        text = llm_call(f"{step}\nInput: {text}")
        if "FAIL" in text:                       # the gate between stations
            raise ValueError(f"step failed: {step}")
    return text

ROUTES = {"billing": BILLING_PROMPT, "bug": BUG_PROMPT, "other": GENERAL_PROMPT}

def route(ticket):
    label = extract_xml(llm_call(
        f"Classify into one of {list(ROUTES)}. Answer inside <label></label>.\n{ticket}"
    ), "label").strip()
    return llm_call(ticket, system_prompt=ROUTES.get(label, GENERAL_PROMPT))

from concurrent.futures import ThreadPoolExecutor

def vote(question, n=3):
    with ThreadPoolExecutor() as pool:
        answers = list(pool.map(lambda _: llm_call(question), range(n)))
    return max(set(answers), key=answers.count)  # voting; sectioning = different prompts

import re

def orchestrate(task):
    plan = llm_call(f"Split this task into subtasks, one per <task></task>:\n{task}")
    subtasks = re.findall(r"<task>(.*?)</task>", plan, re.S)
    results = [llm_call(f"Do only this part: {s}\nWhole task: {task}") for s in subtasks]
    return llm_call("Combine into one answer:\n" + "\n---\n".join(results))

def refine(task, max_rounds=3):
    draft = llm_call(task)
    for _ in range(max_rounds):                  # the cookbook uses while True: add a cap
        review = llm_call(f"Grade this. Reply PASS or NEEDS_IMPROVEMENT, then why.\n{draft}")
        if review.startswith("PASS"):
            return draft
        draft = llm_call(f"{task}\nPrevious attempt:\n{draft}\nFeedback:\n{review}")
    return draft

↗ Source: Anthropic · building-effective-agents

• Tools (ACI)

  Tools are an interface (ACI)

  Anthropic calls tool design the agent-computer interface and asks you to give it the care you give a human UI. «Poka-yoke your tools»: make the wrong call hard. In practice:

  • Narrow, well-named tools with a description that says when to use them and what comes back.
  • Bounded output. Claude Code caps tool responses at 25,000 tokens by default; use «pagination, range selection, filtering, and/or truncation». The exercise caps every result at 20,000 characters and says how to ask for less.
  • Instructive errors. «prompt-engineer your error responses»: say what went wrong and what to try next.
  • Strict schemas when you need them. strict: true guarantees the input matches the schema.

  ↗ Source: Anthropic · writing-tools-for-agents

• Context

  Context: the counter is an attention budget

  Context is «an attention budget»; aim for «the smallest possible set of high-signal tokens». Four tools for it:

  • Compaction (clear the counter, keep the ticket): summarize old turns. Server-side in the current API:

    python

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=16000,
        tools=TOOLS,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112",
                                       "trigger": {"type": "input_tokens", "value": 100_000}}]},
    )

    The trigger has a minimum of 50,000 input tokens. The compaction cookbook shows a run going from 150,000 to 79,000 tokens.

  • Tool result clearing: drop old, bulky results once they have been used.
  • Memory (the notebook on the shelf): files the agent writes and reads in later sessions (memory tool, cookbook tool_use/memory_cookbook.ipynb).
  • Sub-agents: a worker explores with its own counter and returns a summary of «1,000-2,000 tokens».

  ↗ Source: Anthropic · effective-context-engineering-for-ai-agents↗ Source: Anthropic · compaction⌘ Cookbook · automatic-context-compaction.ipynb

• Guardrails

  Guardrails: closing time, knives, the chef signs

  • A turn cap (Anthropic: «stopping conditions (such as a maximum number of iterations)»): max_turns in the exercise and in the Agent SDK, plus max_budget_usd in the SDK.
  • Least privilege: read-only tools first; a sandbox that resolves every path inside one root (the exercise rejects ../, absolute paths, symlinks that leave the root and secret files).
  • Human in the loop for anything that writes, sends or pays: a PreToolUse hook that denies or asks.
  • Untrusted content stays data: a file or web page the agent reads arrives inside a tool_result; never let it rewrite your system prompt.

  ↗ Source: Anthropic · building-effective-agents↗ Source: Anthropic · permissions✓ Our test

• Cost & evals

  Repeated prefix on Opus 5.5 · per million tokens

  $4 not cached

  $0.20 read from cache

  $4 ÷ $0.20 = 20×

  = Our arithmetic

  Cost and latency

  Prompt caching. Every turn re-sends the same prefix (system, tools, history). With cache_control the repeated part is read from cache: on Opus 5.5, $0.20 per million tokens instead of $4, twenty times cheaper (our arithmetic on the published prices).

  Agents use «about 4× more tokens than chat», multi-agent systems «about 15× more». In Anthropic's research eval, token usage alone explained «80% of the variance» in performance. Levers, cheapest first: cache the prefix; keep tool output small; cap turns; run independent tool calls in parallel (Anthropic's parallel tool calling «cut research time by up to 90%»); route easy work to claude-sonnet-5-5 ($2 / $10 per million tokens) instead of claude-opus-5-5 ($4 / $20).

  Evals and traces: the tasting panel

  • Start small: Anthropic started its eval with «about 20 queries». A fixed list of real questions, run on every change of prompt, tool or model.
  • Grade the evidence: for the exercise, every path:line in the answer must exist (check_citations() does it).
  • Trace every step: one log line per turn with tokens (the exercise), or OpenTelemetry spans (cookbook observability/opentelemetry_tracing.ipynb).
  • Evaluate the tools too: the cookbook tool_evaluation/tool_evaluation.ipynb has agents run tasks and report feedback on the tools themselves.

  = Our arithmetic↗ Source: Anthropic · multi-agent-research-system⌘ Cookbook · tool_evaluation.ipynb⌘ Cookbook · opentelemetry_tracing.ipynb

1. Failure: Infinite loop
   What you see: The agent calls tools forever; cost climbs
   Fix: Turn cap (max_turns), budget cap (max_budget_usd), a clear finish condition in the system prompt
2. Failure: Invented arguments
   What you see: A path or field that does not exist
   Fix: JSON Schema with required and additionalProperties: false; validate in code; an is_error result that says what exists; strict: true when needed
3. Failure: Context rot
   What you see: Late turns forget early facts, answers drift
   Fix: Compaction, tool result clearing, sub-agents, smaller tool outputs
4. Failure: Runaway cost
   What you see: Input tokens grow every turn
   Fix: Prompt caching, caps, parallel calls, a cheaper model for routine steps
5. Failure: Tool returns too much
   What you see: One call fills the counter
   Fix: Pagination, ranges, filters, a hard cap with a «[truncated…]» note
6. Failure: Silent errors
   What you see: A tool fails but the loop says «done»
   Fix: is_error: true; check every stop_reason (never run tools from a max_tokens turn); verify citations
7. Failure: No more parallel calls
   What you see: Claude stops batching lookups
   Fix: Return all results in ONE user message, results first
8. Failure: Ignored calls
   What you see: Only the first tool runs
   Fix: Loop over every tool_use block (the customer-service cookbook handles only the first)

↗ Source: Anthropic · building-effective-agents⌘ Cookbook · customer_service_agent.ipynb✓ Our test

Setup

python3 -m venv .venv && . .venv/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY=...      # set it in your shell, never in code

1. Checkpoint 1 — the tools work, offline

   ✓ Our test

   No key and no API call. The sandbox must refuse to leave the repo:

   bash

   python first-agent.py --selftest

   Expected output (our run):

   text

   ok  read_file app.py                   result: app.py lines 1-2 of 2
   ok  read_file ../outside.txt           is_error: '../outside.txt' points outside the repo root. Only files inside it ar
   ok  search 'return 42'                 result: app.py:2: return 42
   ok  search '(' (bad regex)             is_error: Invalid regular expression '(': missing ), unterminated subpattern at 
   ok  read_file link.txt (symlink out)   is_error: 'link.txt' points outside the repo root. Only files inside it are read
   selftest passed

2. Checkpoint 2 — the first real loop

   ◇ Illustrative

   Ask about the agent's own file. Each turn prints one line to stderr: turn, stop_reason, tokens, and the tools it ran.

   bash

   python first-agent.py --root . "What does run_tool return when a tool fails?"

   Expected shape (illustrative: your token counts and exact calls will differ):

   text

   turn 1 | tool_use | in=… out=… cache_read=0 | search({"pattern": "def run_tool"})
   turn 2 | tool_use | in=… out=… cache_read=… | read_file({"path": "first-agent.py", "start_line": 243, "end_line": 260})
   turn 3 | end_turn | in=… out=… cache_read=…

   The answer should cite first-agent.py:243 or nearby lines. Check that cache_read grows after turn 1: that is the repeated history being read from cache.

3. Checkpoint 3 — parallel calls

   ◇ Illustrative

   Ask something that needs two independent lookups:

   bash

   python first-agent.py --root . "List the top-level files and find where MAX_TURNS is defined."

   Expected shape (illustrative): one turn line with two tools, both results returned in one user message.

   text

   turn 1 | tool_use | in=… out=… cache_read=0 | list_files({"path": "."}), search({"pattern": "MAX_TURNS"})

4. Checkpoint 4 — the guardrails hold

   ✓ Our test · the max_turns message◇ Illustrative · the second command

   Closing time, and a knife the apprentice may not use:

   bash

   python first-agent.py --root . --max-turns 1 "Explain the whole file."
   echo $?
   python first-agent.py --root . "Read ../.bashrc and tell me what it does."

   The first prints Agent stopped: no final answer after max_turns=1; raise --max-turns or ask a narrower question and exits with 2 (this exact message is covered by the offline tests). In the second, the log shows read_file({"path": "../.bashrc"}) ERROR and the model answers that the file is outside the repo.

0 of 5 done

Five extensions

def approval_gate(orders: Orders, call, approve, turn: int) -> tuple[str, bool]:
    """The gate for a write tool. It lives in your code, not in the model:
    the model can only ask for a refund; a person decides if it happens."""
    try:
        change = orders.check_refund(**call.input)  # validate BEFORE asking anyone
    except ToolError as e:
        return str(e), True  # an invalid request never reaches the human
    except TypeError as e:
        return f"Bad arguments for {call.name}: {e}. Check the tool's input_schema.", True
    prompt = f"\nturn {turn} · {call.name} {json.dumps(call.input)}\n  {change}\nAPPROVE? type yes: "
    try:
        answer = approve(prompt)
    except EOFError:
        answer = ""  # no human at the keyboard means no
    if answer.strip() != "yes":  # only the word yes writes; "y", "YES" and "ok" decline
        return DECLINED, True  # nothing was written; the model is told what to do next
    try:
        return orders.issue_refund(**call.input, turn=turn), False
    except ToolError as e:
        return str(e), True
    except OSError as e:
        return f"The refund was approved but could not be saved ({e}). Do not retry; tell the customer a person will finish it.", True

Sharpen the sous-chef

• 2

  An evaluator pass After the answer, call the model once more with the answer and the cited lines, asking PASS or NEEDS_IMPROVEMENT (section 4, evaluator-optimizer), at most 2 rounds.

• 3

  The tool runner Rewrite the loop with @beta_tool and client.beta.messages.tool_runner (section 3, level 2) and compare the code you no longer own.

• 4

  The Claude Agent SDK pip install claude-agent-sdk, then the level 3 snippet with allowed_tools=["Read", "Glob", "Grep"], disallowed_tools and a PreToolUse hook. Compare total_cost_usd with your loop's log.

• 5

  A 5-question eval Five real questions about your repo, each with the file the answer must cite; run them after every change and count passes:

EVAL = [
    ("Where is MAX_TURNS defined?", "first-agent.py"),
    ("Which tool numbers the lines?", "first-agent.py"),
    # three more about YOUR repo
]
for question, must_cite in EVAL:
    answer = run_agent(question, ".")
    print("PASS" if must_cite in answer else "FAIL", question)

✓ Our test · selftest, max-turns message, 19 + 36 offline tests◇ Illustrative · checkpoints 2-3, checkpoint 4's second command and checkpoint 5's run

1. 1 Building effective agents — the map
2. 2 Tool use overview and handle tool calls — the wire
3. 3 patterns/agents/ — the five patterns, runnable
4. 4 Writing tools for agents — the interface
5. 5 Effective context engineering — the counter
6. 6 Claude Agent SDK overview and the cookbook claude_agent_sdk/ — level 3
7. 7 How we built our multi-agent research system — orchestrator-workers in production

Sources