The agent loop, production-grade

The loop itself is ten lines: call the model, run the tools it asks for, append the results, repeat until it stops asking. Everything else in this lesson exists because the ten-line version fails in production, and each failure gets a named control.

Everyday picture A new assistant runs errands for you. They can't do anything themselves. They come back after every errand and say: "here's what I found; next I'd like to do X." You carry out X and hand them the result. They decide the next step, and so on, until they say "done" (or you say "that's enough, you've spent the budget"). The assistant is the model, the errands are tool calls, and you are the loop in this file.

Tiny worked example "How many PTO days does alice have left, and what rolls over?" Here's the real transcript the happy-path demo produces:

[user]       How many PTO days does alice have left, and what rolls over?
[assistant]  I'll check the PTO policy and alice's balance at the same time.
             tool_use toolu_1 search_kb       {"query": "PTO rollover"}
             tool_use toolu_2 get_pto_balance {"employee": "alice", "as_of": "2026-09-25"}
[user]       tool_result toolu_1  "[hr-001] Paid time off: ... Unused PTO up to 5 days rolls over. ..."
             tool_result toolu_2  {"employee": "alice", "as_of": "2026-09-25", "days_left": 12}
[assistant]  Alice has 12 PTO days left. Up to 5 unused days roll over to next year [hr-001].
             (stop_reason: end_turn)

Two model calls, two tools run in parallel, one answer. ReAct ("reason + act") is the research name for this pattern of alternating a bit of reasoning ("I'll check both at once") with actions (tool calls). The loop itself is ten lines of code. Everything else in this file exists because the ten-line version fails in production.

flowchart LR
  G[Goal] --> T[Think<br/>choose next step]
  T --> C[Call a tool]
  C --> O[Observe result]
  O --> D{Done, or budget<br/>or step limit hit?}
  D -->|No| T
  D -->|Yes| F[Final answer<br/>or hand to human]

In code: run_agent is this loop, and it returns an AgentResult holding the final text, the stop cause, every step, the usage and the cost. search_kb and get_pto_balance are the two tools in the example.

sequenceDiagram
  participant U as User
  participant L as Your loop
  participant M as Model
  participant T as Tools
  U->>L: task
  L->>M: system + messages + tool definitions
  M-->>L: tool_use blocks (stop_reason = tool_use)
  L->>L: validate, check budget, check for loops
  L->>T: run the calls (concurrently)
  T-->>L: results or errors
  L->>M: ONE user message with every tool_result
  M-->>L: final text (stop_reason = end_turn)
  L-->>U: answer + stop cause

In code: each pass through run_agent appends the model's full assistant content, runs the requested tools, and appends every result in one user message; a Step records that one model call and the ToolExecutions it triggered.

Everyday picture Lending your car to a new driver: a full tank but no more fuel money (budget), "come back by six" (step limit), "if you drive past the same petrol station three times, you're lost, so come home" (loop detection), and "call me if anything feels off" (hand-off to a human).

flowchart TD
  R[Model response] --> S1{stop_reason?}
  S1 -->|refusal| X1[stop: refusal]
  S1 -->|max_tokens| X2[stop: max_tokens<br/>don't run half-written calls]
  S1 -->|end_turn| X3[stop: completed]
  S1 -->|tool_use| B{Over token or<br/>dollar budget?}
  B -->|yes| X4[stop: budget_exceeded]
  B -->|no| H{Called handoff_to_human?}
  H -->|yes| X5[stop: handoff]
  H -->|no| L{Same tool + same args<br/>seen N times?}
  L -->|yes| X6[stop: loop_detected]
  L -->|no| E[Run tools concurrently]
  E --> A[Append all results<br/>in one user message]
  A --> N{Step limit hit?}
  N -->|yes| X7[stop: max_steps]
  N -->|no| M[Call the model again]

"It stopped" is not an outcome you can monitor; "it stopped because of loop_detected at step 3" is.

In code: AgentConfig holds every limit (steps, tokens, dollars, the loop threshold) and the prices AgentConfig.cost uses to turn primer.agents.llm.Usage into dollars. A tool raises ToolError to send the model an actionable error result, and HANDOFF_TOOL_DEF is the hand-off tool's definition.

Everyday picture Three errands in three different shops. You can do them one after another, or send three friends at once and be done when the slowest one gets back.

flowchart LR
  M[Assistant turn<br/>tool_use A, tool_use B, tool_use C] --> A[run A]
  M --> B[run B]
  M --> C[run C]
  A --> J[One user message:<br/>tool_result A, B, C<br/>matched by tool_use_id]
  B --> J
  C --> J

In code: execute_tools runs one turn's calls on a thread pool and returns their results in the order they were asked for, turning an unknown tool name or a raised exception into an error result instead of a crash.

Each call sends the entire conversation so far. If every step adds about tokens, call sends roughly input tokens, so a run of steps sends

On the example: with and , the total is input tokens, not the you'd guess. Double to and it's , almost 4x.

In Python:

t = 500
def total_input(n):
    # Σ_k k·t: step k re-sends k steps' worth
    return sum(k * t for k in range(1, n + 1))
total_input(10)  # → 27500
total_input(20)  # → 105000
# almost 4x
round(total_input(20) / total_input(10), 1)  # → 3.8

In code: cumulative_input_tokens evaluates the formula above, times , for any run length.

The loop only depends on the LLM protocol, so the same code runs against Claude:

from primer.agents.llm import ClaudeLLM
from primer.agents.agent_loop import run_agent, AgentConfig

result = run_agent(
    ClaudeLLM(),                      # needs `pip install anthropic` + credentials
    task="How many PTO days does alice have left, and what's the rollover rule?",
    tools=HR_TOOLS,                   # name -> python function
    tool_defs=HR_TOOL_DEFS,           # Anthropic tool definitions (JSON Schema)
    system="You are an HR assistant. Use tools; cite doc ids.",
    config=AgentConfig(max_steps=8, max_cost_usd=0.50),
)
print(result.stop_cause, result.final_text)

The SDK also ships a tool runner (client.beta.messages.tool_runner) that drives this loop for you. Owning the loop, as here, is what you do when you need custom budgets, loop detection, approval gates or tracing in exactly your shape.

Answer each one out loud or on paper before you open it. If you can explain it, you know it.