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.
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_reason | Meaning | What you do | Loop? |
|---|---|---|---|
| end_turn | Model finished its answer naturally. | Return the text; stop. | 🟢 Exit |
| tool_use | Model wants to call one or more tools. | Run the tool(s) → append tool_result in a user turn → call again. | 🔵 Continue |
| max_tokens | The output hit its cap and is truncated. | Raise max_tokens, stream, or continue the turn. | 🟠 Depends |
| stop_sequence | Output hit a custom sequence you supplied. | Handle the delimiter/protocol boundary you defined. | 🟠 Depends |
| pause_turn | A server-side tool ran its own loop and paused. | Re-send the assistant turn as-is; the server resumes. | 🟣 Continue |
| refusal | Safety classifier/model declined. HTTP 200. | Inspect stop_details.category; content may be empty/partial. | 🔴 Exit |
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
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)
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
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.resp.content[0].text before checking stop_reason. →
On refusal the content can be empty → IndexError. Always branch first.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.