Stopping conditions and budgets
How an agent loop ends: the model finishes, or a limit stops it. Stop reasons, turn and budget caps, and detecting loops that go nowhere.
Every loop needs an exit
An agent is a loop (see What is an agent), and a loop that can run forever eventually will. Anthropic describes agent runs as ending when the task is complete or when a stopping condition such as a maximum number of iterations is reached6. The design question is which exits you provide and which one you want to fire in normal operation.
Exit 1: the model says it is done
In Anthropic’s tool-use loop, you keep going while stop_reason is tool_use. The loop exits on any other stop reason: end_turn, max_tokens, stop_sequence or refusal. Each means either a final answer or a stop your application must handle1.
Diagram: my own, following the stop reasons listed in 1.
end_turn is the exit you want. The others are not failures of the loop, but each needs a decision: raise a token limit, retry, or surface a refusal to the user.
Exit 2: a cap on turns
A turn cap bounds tool-use round trips. In the Claude Agent SDK, max_turns counts tool-use turns only2. Without a limit, the loop runs until Claude finishes, which suits well-scoped tasks but can run a long time on open-ended prompts2.
Exit 3: a cap on spend
A budget cap stops the run on a spend threshold. The SDK exposes max_budget_usd for this, and its documentation recommends setting a budget as a sensible default for production agents2. Because cost is what actually hurts, a budget is often the more honest limit than a turn count.
When either cap fires, the SDK reports it in the result’s subtype: success, error_max_turns, error_max_budget_usd, error_during_execution and, for structured output, error_max_structured_output_retries23. Only success carries a final answer, so branch on the subtype rather than on whether some text came back23.
Diagram: my own. The model’s decision is the intended exit; caps are backstops.
Exit 4: catching loops that make no progress
A cap stops a runaway only after it has burned its allowance. Practitioners add a detector for no progress. One approach is to fingerprint each tool call by name and arguments and stop when the same fingerprint repeats within a short window4. Another is to track whether the agent is genuinely advancing toward the goal, not merely counting steps, since a cap alone misses a loop that wastes effort without ever hitting the limit5.
Diagram: my own illustration of the repeated-call check described in 4 and 5.
Guidance from these practitioner sources is consistent that a hard cap should be treated as a circuit breaker, not the primary control5. These are blog-level sources rather than specifications, so treat the details as practice rather than standard.
A sensible default stack
- Let the model stop on its own (
end_turn). - Set a turn cap that is generous for the task, so it only fires on a bug.
- Set a spend cap per run, and count sub-agents in it where your framework allows.
- Detect repeated identical calls and stop or escalate.
- On any forced stop, return a partial result with the reason, not silence. Failure handling is covered in Error handling and recovery, and handing off to a person in Human in the loop.
- Record the stop reason in your traces so you can see how often each exit fires.
Sources
- [1]How tool use works — Anthropic, Claude Platform docsPARAPHRASED
- [2]How the agent loop works — Anthropic, Claude Agent SDK docsPARAPHRASED
- [3]Handling stop reasons — Anthropic, Claude Agent SDK docsPARAPHRASED
- [4]Detect tool-call loops, dead ends, and repeated agent actions — OneUptime · 2026PARAPHRASED
- [5]How to prevent agent infinite recursion — GAASPARAPHRASED
- [6]Building effective agents — Erik Schluntz and Barry Zhang · Anthropic · 2024PARAPHRASED