D1 · Agentic Architecture › Cluster 2 · Stop Reasons

2.1 · The Six stop_reason Values

The router every agent loop hangs off

CONCEPT Why stop_reason is the control signal

The Messages API is stateless: every POST /v1/messages is a fresh request, and the model tells you why it stopped generating via a single field — response.stop_reason. That field is the branch point for your entire agent loop. Get the routing wrong and you either exit early, loop forever, or crash reading content[0] on a turn that has no content.

🔑 Branch on stop_reason BEFORE you read content. Some stops (refusal, some errors) can arrive with empty content. Reading content[0] first is a classic index-error bug.

There are six values you must handle. Two of them exit the loop; the rest mean "do something, then call the API again."

stop_reasonMeaningWhat you doLoop?
end_turnModel finished its answer naturally.Return the text; stop.🟢 Exit
tool_useModel wants to call one or more tools.Run the tool(s) → append tool_result in a user turn → call again.🔵 Continue
max_tokensThe output hit its cap and is truncated.Raise max_tokens, stream, or continue the turn.🟠 Depends
stop_sequenceOutput hit a custom sequence you supplied.Handle the delimiter/protocol boundary you defined.🟠 Depends
pause_turnA server-side tool ran its own loop and paused.Re-send the assistant turn as-is; the server resumes.🟣 Continue
refusalSafety classifier/model declined. HTTP 200.Inspect stop_details.category; content may be empty/partial.🔴 Exit
⚠️ Some Claude 4.x models additionally emit model_context_window_exceeded — the context window was exhausted. This is distinct from max_tokens (which is an output-cap truncation). Fix it by compaction or splitting the conversation, not by raising max_tokens. See 2.3.

DIAGRAM The stop_reason router

flowchart TD R([response.stop_reason]) --> ET{end_turn?} ET -->|Yes| X1["🟢 return text · STOP loop"] ET -->|No| TU{tool_use?} TU -->|Yes| K1["🔵 run tools → append tool_result → loop"] TU -->|No| PT{pause_turn?} PT -->|Yes| K2["🟣 re-send assistant turn as-is → loop"] PT -->|No| MT{max_tokens?} MT -->|Yes| K3["🟠 raise cap / stream / continue"] MT -->|No| RF{refusal?} RF -->|Yes| X2["🔴 handle decline · do NOT read content[0]"] RF -->|No| SS["🟠 stop_sequence → handle your delimiter"] classDef exit fill:#d4edda,stroke:#28a745,color:#155724; classDef stop fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef loop fill:#d1ecf1,stroke:#17a2b8,color:#0c5460; class X1 exit; class X2 stop; class K1,K2,K3 loop;

CODE A router that branches before touching content

Every robust agent loop starts here. Notice the branch on stop_reason comes before any read of resp.content.

# Stateless: we resend the full `messages` list each turn.
resp = client.messages.create(
    model="claude-opus-4-8", max_tokens=4096,
    tools=TOOLS, messages=messages,
)

# Branch on WHY it stopped — before reading content[0].
if resp.stop_reason == "end_turn":
    return resp.content            # 🟢 done
elif resp.stop_reason == "tool_use":
    handle_tool_use(resp, messages)  # 🔵 run tools, append tool_result, loop (2.2)
elif resp.stop_reason == "pause_turn":
    resume_server_tool(resp, messages) # 🟣 re-send as-is, no "Continue." (2.4)
elif resp.stop_reason == "max_tokens":
    handle_truncation(resp)          # 🟠 raise cap / stream / continue (2.3)
elif resp.stop_reason == "refusal":
    handle_refusal(resp)             # 🔴 check stop_details, content may be empty (2.5)
elif resp.stop_reason == "stop_sequence":
    handle_delimiter(resp)           # 🟠 your custom protocol boundary (2.6)
A single stop_reason switch, evaluated first, is the backbone of every correct agent loop. The rest of Cluster 2 is one page per non-trivial branch.

EXAM TRAPS

Trap: "There are four stop reasons." → The 4-value myth. Older docs listed end_turn, max_tokens, stop_sequence, tool_use. Modern agents must also handle pause_turn and refusal (six total), plus model_context_window_exceeded on some 4.x models. An answer that only handles four is incomplete.
Trap: Reading resp.content[0].text before checking stop_reason. → On refusal the content can be empty → IndexError. Always branch first.
Trap: Treating max_tokens as "the conversation got too long." → It means the output was truncated at its cap. Context exhaustion is a different signal (model_context_window_exceeded). Don't conflate them (2.3).

PRACTICE

Q1 · Your loop only handles end_turn, tool_use, and max_tokens. What breaks in production?

Any pause_turn (server-side tool paused) and refusal (safety decline) fall through your switch. The pause_turn case will look like a stall; the refusal case will often crash on content[0] since content may be empty. You must handle all six.

Q2 · Which two stop_reason values normally EXIT the loop, and which continue it?

Exit: end_turn (done) and refusal (declined — stop and report). Continue: tool_use and pause_turn always loop; max_tokens and stop_sequence depend on your design.

Q3 · Why does statelessness make stop_reason the primary control signal?

Because the server keeps no session, each response is self-describing: the model can only tell you "why I stopped" via stop_reason. Your code owns the loop, so that field is the only thing steering the next request.