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.
| Aspect | Tool Runner (beta) | Manual loop |
|---|---|---|
| Who runs the loop | The SDK | Your code |
| Tool definitions | @beta_tool-decorated Python fns; schemas auto-generated | You write tools=[…] JSON Schemas |
| Result plumbing | Handled for you | You build each tool_result |
| Intercept before exec | Not the point of it | Yes — gate / approve / log per call |
| Best for | Fast, straightforward agents | Approval, 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;
== 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.