CONCEPT An agent is a loop, not a call
The whole "agent" abstraction reduces to one control structure: call the model, inspect
stop_reason, and decide whether to run a tool and loop again or stop. There is no
magic — you write the loop; the model decides, at each turn, whether it needs a tool or is done.
stop_reason == "end_turn". Its continue
condition is stop_reason == "tool_use": run the requested tool, append the result as a
user-role tool_result, and call again.The canonical cycle:
- Call
messages.create(...)with the full history and your tools. - Append the whole
response.contenttomessagesas anassistantturn (see 1.6 — all blocks, not just text). - Branch on
stop_reason:end_turn→ the model is finished. Break.tool_use→ run the tool(s), append atool_result, loop.
| stop_reason | Meaning in the loop | Loop action |
|---|---|---|
end_turn | Model finished its answer naturally | Exit the loop |
tool_use | Model wants to call a tool | Run tool → append tool_result → loop |
max_tokens | Output hit max_tokens (truncated) | Handle: raise cap or continue; don't treat as done |
pause_turn | Server-tool loop paused | Re-send the assistant turn as-is (no "Continue." msg) |
DIAGRAM The canonical while-loop
as assistant turn"] C --> D{"stop_reason?"} D -->|end_turn| E["🟢 Done — return final text"] D -->|tool_use| F["🔵 Run the requested tool(s)"] F --> G["Append tool_result
(role: user)"] G --> B D -->|max_tokens| H["🟠 Truncated — raise cap / continue"] classDef ep fill:#e2d4f0,stroke:#764ba2,color:#3d1a5b; classDef done fill:#d4edda,stroke:#28a745,color:#155724; classDef tool fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; classDef warn fill:#fff3cd,stroke:#ffc107,color:#856404; class B ep; class E done; class F,G tool; class H warn;
CODE Minimal loop skeleton
# The canonical agent loop: branch on stop_reason until end_turn. import anthropic client = anthropic.Anthropic() messages = [{"role": "user", "content": "What's the weather in Paris?"}] for _ in range(10): # bound the loop → no infinite spin resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=TOOLS, messages=messages, ) # Append the WHOLE turn (text + tool_use + thinking). See 1.6. messages.append({"role": "assistant", "content": resp.content}) if resp.stop_reason == "end_turn": break # model is done → exit if resp.stop_reason == "tool_use": tool_results = [] for block in resp.content: if block.type == "tool_use": result = run_tool(block.name, block.input) # your dispatch tool_results.append({ "type": "tool_result", "tool_use_id": block.id, "content": result, }) # tool_result blocks go back in a USER-role turn. messages.append({"role": "user", "content": tool_results}) continue # loop: model sees the results else: raise RuntimeError("loop exceeded max iterations")
range(10)
(not while True without a guard) and an explicit branch that only breaks on
end_turn. Everything else is a variation on this skeleton.TRADE-OFFS How to bound the loop
✅ Bounded iterations (recommended)
- Guarantees termination even if the model keeps calling tools
- Caps worst-case token spend & latency
- Fails loudly instead of silently spinning
⚠️ Unbounded while True
- A stuck model can loop forever → runaway cost
- Hard to observe or interrupt in production
- Only safe with a separate stop signal / budget guard
EXAM TRAPS
create() once, getting
stop_reason="tool_use", and returning that as the answer. → A tool_use stop means
the model is waiting on you to run the tool and call again. Treating it as final leaves the task
unfinished.while True without a
max-iteration bound (or budget/stop check) can spin forever if the model never emits end_turn.
Always cap it.tool_result in an assistant turn. →
tool_result blocks are user-role content. Wrong role breaks the alternation and the
next call fails.max_tokens or pause_turn like
end_turn. → Only end_turn means "done." pause_turn means re-send the
assistant turn as-is; max_tokens means the output was truncated.PRACTICE
Q1 · Your agent returns immediately with "I'll check the weather" and never answers. Why?
You almost certainly returned on the first stop_reason="tool_use" instead of
looping. The model emitted a tool_use block and is waiting for you to run the tool, append a
tool_result, and call again. Wrap the call in the canonical loop and only stop on
end_turn.
Q2 · What role must the tool_result message use, and why?
user. Tool outputs are fed back to the model as user-role content containing
tool_result blocks (each keyed by tool_use_id). This keeps roles alternating
assistant → user → assistant and lets the model consume the results on the next turn.
Q3 · Why prefer a bounded loop over while True?
To guarantee termination and cap cost. A model that keeps requesting tools (or gets stuck)
would loop forever under while True, running up tokens and latency. A max-iteration bound fails
loudly and predictably; you can still raise the bound where genuinely needed.