D1 · Agentic Architecture › Cluster 1 · Foundations

1.3 · The Loop Mechanics

The canonical agent loop — call, branch on stop_reason, repeat

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.

🔑 The loop's exit condition is 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:

  1. Call messages.create(...) with the full history and your tools.
  2. Append the whole response.content to messages as an assistant turn (see 1.6 — all blocks, not just text).
  3. Branch on stop_reason:
    • end_turn → the model is finished. Break.
    • tool_use → run the tool(s), append a tool_result, loop.
stop_reasonMeaning in the loopLoop action
end_turnModel finished its answer naturallyExit the loop
tool_useModel wants to call a toolRun tool → append tool_result → loop
max_tokensOutput hit max_tokens (truncated)Handle: raise cap or continue; don't treat as done
pause_turnServer-tool loop pausedRe-send the assistant turn as-is (no "Continue." msg)

DIAGRAM The canonical while-loop

flowchart TD A([Seed messages with user turn]) --> B["🟣 messages.create(model, tools, messages)"] B --> C["Append WHOLE response.content
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")
Note the two structural safeguards: a bounded 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

Trap: Forgetting to loop — calling 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.
Trap: An infinite loop with no termination guard. → while True without a max-iteration bound (or budget/stop check) can spin forever if the model never emits end_turn. Always cap it.
Trap: Putting tool_result in an assistant turn. → tool_result blocks are user-role content. Wrong role breaks the alternation and the next call fails.
Trap: Treating 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.