D1 · Agentic Architecture › Cluster 3 · Tool Use

3.5 · Tool Runner vs. Manual Loop

Let the SDK drive the loop — or drive it yourself when you need control

CONCEPT Two ways to run the agentic loop

The tool round-trip (3.1) repeated until end_turn is the agentic loop. You can either hand that loop to the SDK's Tool Runner or write it yourself as a manual loop. Same round-trip underneath — the question is how much of it you want to own.

AspectTool Runner (beta)Manual loop
Who runs the loopThe SDKYour code
Tool definitions@beta_tool-decorated Python fns; schemas auto-generatedYou write tools=[…] JSON Schemas
Result plumbingHandled for youYou build each tool_result
Intercept before execNot the point of itYes — gate / approve / log per call
Best forFast, straightforward agentsApproval, custom logging, conditional/gated exec
🔑 Tool Runner is client.beta.messages.tool_runner. You pass @beta_tool-decorated functions; the SDK generates schemas, runs the loop, executes the tools, and feeds results back — the whole agentic loop, hands-off.
Reach for the manual loop when you need human-in-the-loop approval, custom logging, or conditional/gated execution — anything where you must inspect or intercept a tool_use before it runs (see 3.6). The Runner executes tools for you, so it's the wrong tool when you must sit in that gap.

DIAGRAM Where your code sits

flowchart TD subgraph TR["Tool Runner (SDK-driven)"] A1([call tool_runner]) --> A2["SDK: loop + run @beta_tool fns"] A2 --> A3([final answer]) end subgraph ML["Manual loop (you-driven)"] B1([create]) --> B2{stop_reason
== tool_use?} B2 -->|no| B3([done]) B2 -->|yes| B4["🟣 intercept: log / approve / gate"] B4 --> B5[run tool] --> B6[append tool_result] --> B1 end classDef sdk fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; classDef you fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; class A2 sdk; class B4 you;

CODE Both side by side

Tool Runner — the SDK drives the whole loop

from anthropic import beta_tool

@beta_tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""   # docstring → description
    return lookup_weather(city)                     # schema auto-generated

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8", max_tokens=1024,
    tools=[get_weather],                          # pass the decorated fns
    messages=[{"role": "user", "content": "Weather in Paris?"}],
)
# The SDK runs the loop: calls Claude, executes get_weather, feeds
# the tool_result back, repeats until end_turn. You just read the result.

Manual loop — you own each step (needed for gating / logging)

messages = [{"role": "user", "content": "Weather in Paris?"}]
while True:
    resp = client.messages.create(model="claude-opus-4-8", max_tokens=1024,
                                  tools=TOOLS, messages=messages)
    if resp.stop_reason != "tool_use":
        break                                          # end_turn → done
    messages.append({"role": "assistant", "content": resp.content})

    results = []
    for tu in [b for b in resp.content if b.type == "tool_use"]:
        log(tu.name, tu.input)                     # custom logging — your hook
        out = run_tool(tu.name, tu.input)         # conditional/gated exec here
        results.append({"type": "tool_result",
                        "tool_use_id": tu.id, "content": out})
    messages.append({"role": "user", "content": results})

TRADE-OFFS Convenience vs. control

✅ Tool Runner

  • Least code — schemas + loop + plumbing handled
  • Fewer contract bugs (ids, roles, alternation)
  • Ideal for straightforward, fully-automatable agents

⚠️ Manual loop

  • More code and more ways to break the 3.2 contract
  • …but full control: intercept before exec, gate, log, branch
  • Required for human-in-the-loop and conditional execution
Default to the Tool Runner for speed; drop to the manual loop the moment you need to approve, log, or conditionally run a tool.

EXAM TRAPS

Trap: Using the Tool Runner when you need approval gates. → The Runner executes tools for you; it's not where you insert a human-in-the-loop check. Use the manual loop to intercept a tool_use before running it (3.6).
Trap: Hand-writing JSON Schemas for the Tool Runner. → With @beta_tool the SDK auto-generates schemas from the function signature/docstring; you pass the functions, not JSON.
Trap: Believing the Runner changes the API. → Underneath it's the same stateless round-trip; it just automates the loop. The contract (matching ids, user-role results) still governs.

PRACTICE

Q1 · A fully-automated read-only research agent — Tool Runner or manual?

Tool Runner. No approval or gating needed, so let the SDK handle the loop, schemas, and result plumbing. Less code, fewer contract bugs.

Q2 · Any tool that spends money must be approved by a human first. Which approach, and why?

Manual loop. You need to intercept the tool_use before execution to require approval — the Runner runs tools for you, so it can't sit in that gap (see 3.6).

Q3 · How does the Tool Runner know each tool's input schema?

It auto-generates the schema from the @beta_tool-decorated function's signature and docstring — you don't write input_schema by hand.