Stop reason
Every agent runs a loop: ask Claude, run the tool it asks for, ask again. The trap is in how the loop decides to stop. The wrong options all stop on something that looks like a signal (some text, a polite closing line, a turn count) instead of the one field the API gives you for exactly this: stop_reason.
D1 Agentic ArchitectureExam guide 1.1About 15 minutes
stop_reason is "tool_use" and stop when it is "end_turn"; never stop because of the reply's wording or an iteration cap.Start here: the waiter and the menu
A waiter keeps going back to the kitchen while the customer is still ordering, and stops when the customer closes the menu. The waiter does not stop because the customer said “great” halfway through, and does not stop after exactly three trips.
Claude's API tells your code the same thing in one field. Every response carries a stop_reason: a short label saying why Claude stopped writing. "tool_use" means “I want a tool run; send me the result”. "end_turn" means “I'm finished with this turn”. Your loop (the code that keeps calling Claude) reads that label after every call, and nothing else decides when it stops.
stop_reason field, or something else?
stop_reason: right. Continue on"tool_use", stop on"end_turn".- Any text in the reply: wrong. Claude often writes a short line and asks for a tool in the same reply.
- The wording (“done”, “task complete”, “Anything else?”): wrong. Wording varies.
- A turn counter: fine as a safety net, wrong as the main stop.
Words in the question that tell you which side you're on
Points to reading stop_reason
- “loop ends too early”, “loop never ends”
- “decide when the agent is done”
- “after each response”
- “tool results”
Points to the trap
- “checks the reply for ‘done’”
- “looks for phrases like ‘I have finished’”
- “stops after 10 iterations”
- “if the response contains text”
Try it: change the stop_reason, change the loop
A customer asks a support agent: “Where is my order 4471?” The run is fixed. On turn 1 Claude says “Let me check that order.” and asks for lookup_order (stop_reason: "tool_use"). On turn 2 it asks for check_carrier, with no text ("tool_use" again). You pick what turn 3 returns, from all six real values, and you pick how the loop decides to stop.
req holds the model, max_tokens and tools. The replies, tool results and dates are made up for the example. The stop_reason values and what each one means are real. run_tools, text_of, has_tool_calls and hand_to_person stand for your own small helpers.
Things to try: end_turn + (b), the exam answer. Then end_turn + (c): whatever you pick, the customer only gets “Let me check that order.” Then tool_use + (e): the cap walks away from a tool call. Last, max_tokens + (b), then + (a), to see why real code handles the other four.
All six values
The exam guide tests two of them. The other four are real values in the Messages API, worth knowing so the extra ones in the simulator make sense.
| Value | What it means | What your loop should do | On the exam? |
|---|---|---|---|
tool_use | Claude wants one or more tools run. | Run each tool, append the tool_result blocks to the conversation, call Claude again. | Yes (guide 1.1) |
end_turn | Claude has finished its turn. | Show the answer. End the loop. | Yes (guide 1.1) |
max_tokens | The reply hit the max_tokens limit you set and was cut off. | Don't show it as final. Raise max_tokens (or ask Claude to continue) and resend. | Beyond the exam guide |
stop_sequence | A stop sequence your app set has fired. The response's stop_sequence field says which. | Take the text before it, as your app intended. | Beyond the exam guide |
pause_turn | A long turn using a server tool (one Anthropic runs, such as web search) has paused. | Send the response back as-is so Claude continues. | Beyond the exam guide |
refusal | Claude declined for safety reasons. stop_details gives a category when there is one. | Don't blindly resend the same request. Tell the user, or route to a person. | Beyond the exam guide |
The traps
| Trap | What the wrong option looks like | Why it loses |
|---|---|---|
| Text as a stop sign | Stop as soon as the response includes any text | Claude often writes text and asks for a tool in the same response, so the loop ends before the tool runs. The exam guide names this anti-pattern. |
| Parsing the wording | Stop when the reply contains a phrase such as “task complete” | Only usually works. Wording varies, so the loop sometimes stops mid-task or runs on. The field exists so you don't have to parse text. |
| Cap as the main stop | Stop after a fixed number of iterations, such as 10 | Cuts off long tasks and wastes calls on short ones. A cap is only a safety net. |
| Different problem | Replace the loop with a fixed sequence of tool calls | It removes Claude's ability to choose the next step from what it just learned. It answers a design question, not a stopping one. |
Practice: three exam-style questions
Answer first, then open “Think it through”.
Rule to remember
Exam guide 1.1: “Continue the loop when stop_reason == "tool_use"; terminate when "end_turn".” And: “Anti-patterns: parsing natural-language signals to determine termination; arbitrary iteration caps as the primary stop; checking assistant text content as a completion indicator.”