Terminare con stop_reason

An agentic loop is simple: you send a request, Claude responds, and you decide whether to keep going. The hard question is when to stop.

Every API response carries a stop_reason field. This is the model's own signal about why it stopped generating. Your loop should listen to that signal — not guess by reading the words in the reply.

This lesson teaches one rule that separates robust agents from fragile ones: let end_turn end the loop, not your string matching.

Claude returns one of four stop_reason values on every turn:

• end_turn — the model finished its response naturally. The task turn is complete.
• tool_use — the model wants to call a tool. Run it, append the result, and continue.
• max_tokens — output was truncated by your max_tokens limit.
• stop_sequence — a custom stop sequence you configured was hit.

These four values are a complete, reliable contract. Your control flow should branch on them directly.

A tempting shortcut is to read the model's text and look for a keyword like "done" or "finished" to decide the loop is over.

This is a classic anti-pattern. Text is probabilistic. The model might say "I'm done thinking, now let me call a tool" — and your matcher stops too early. Or it phrases completion differently and your loop runs forever.

Never parse text for completion signals. The structured stop_reason exists precisely so you don't have to.

Here is the correct shape of the loop. You inspect stop_reason each turn. When it is tool_use, you run the tools and append their results to the conversation. You repeat until stop_reason is end_turn.

Notice the loop is driven entirely by the structured signal — no text inspection decides termination.

One reason the loop works: the model keeps no state between requests. Each API call must include the FULL messages history.

That is why, after a tool_use turn, you append the assistant's tool-call content AND the tool results back into messages before the next request. The model re-reads the entire conversation and decides whether more tools are needed or it can finish with end_turn.

Drop history, and the model loses the thread — it can't reach a coherent end_turn.

A common mistake is treating tool_use as a terminal state. It is not. It means "pause, run this tool, then come back to me."

When you see tool_use, you:

• Execute the requested tool(s) in your own code.
• Append the tool_result blocks to messages.
• Send the request again so the model can continue.

Only end_turn means the work for this turn is genuinely finished.

The deeper principle: let the model decide when it is done. The model has the full context — the user's goal, the tool results, the conversation so far. It is better positioned than a hard-coded rule to judge whether the task is complete.

Your job as the architect is to provide good tools and clear instructions, then trust the end_turn signal. Reserve hard-coded control flow for guarantees you cannot leave to probability.

You should still add a maximum-iteration guard — but understand its role. An iteration cap is a safety net to prevent runaway loops or cost blowouts. It is NOT the primary stop mechanism.

The primary stop is always end_turn. The cap only fires in the rare pathological case where the model never converges. If your loop relies on the cap to end normally, your design is broken.

max_tokens is a distinct case that needs its own handling. It means the response was truncated mid-generation — the model did not finish its thought.

Treating this as a clean completion would silently cut off the agent's work. Depending on your design you might raise max_tokens, ask the model to continue, or flag the turn. What you must NOT do is fall through and assume the task is done.

If model-driven decisions are the default, when do you reach for deterministic code?

For guarantees — outcomes that must hold every single time regardless of the model's judgment. Examples: a precondition that blocks a refund until get_customer returns a verified ID, or a hook that rejects any refund over a policy threshold.

These are 100% deterministic enforcement points. Termination, by contrast, is a model-driven decision you read from stop_reason. Don't confuse the two: hard-code guarantees, trust end_turn for flow.

A production-grade agentic loop combines all the pieces:

• Branch on stop_reason — never on text.
• Resend full history each turn (the model is stateless).
• tool_use → run, append, continue. end_turn → stop.
• Handle max_tokens explicitly — truncation is not completion.
• Keep an iteration cap as a safety net only.

This is the backbone of every reliable agent you'll architect.

A support agent built on the Agent SDK sometimes loops forever and sometimes stops before calling a needed tool. The loop currently breaks when the assistant's text contains the word "resolved". What is the correct fix?

Key takeaways:

• Terminate on stop_reason, never by parsing text for words like "done" or "resolved".
• end_turn ends the loop; tool_use means run tools, append results, and continue.
• Handle max_tokens explicitly — truncation is not completion.
• The model is stateless: resend the full message history every turn.
• Termination is a model-driven decision; the iteration cap is only a safety net.
• Reserve hard-coded enforcement for guarantees (preconditions, hooks), not for ending the loop.

Let end_turn end the loop. That single discipline makes your agents predictable and production-ready.