CCA-F start here · Trap gym · Stop reason

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

At a glance: keep the loop going while 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.

Your code sends the conversation so far Claude Response content blocks + stop_reason Read stop_reason the field made for this tool_use run it, append the tool_result, send again end_turn show the answer, stop What the anti-patterns read instead any text block the wording a turn counter The simulator below thickens the box your chosen loop reads.
The one question to ask: what does the code look at to decide whether to run another step: the stop_reason field, or something else?

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.

1. Turn 3's stop_reason

2. Your loop design
What the customer sees

The loop you picked, in Python

    

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.

ValueWhat it meansWhat your loop should doOn the exam?
tool_useClaude 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_turnClaude has finished its turn.Show the answer. End the loop.Yes (guide 1.1)
max_tokensThe 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_sequenceA 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_turnA 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
refusalClaude 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

TrapWhat the wrong option looks likeWhy it loses
Text as a stop signStop as soon as the response includes any textClaude 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 wordingStop 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 stopStop after a fixed number of iterations, such as 10Cuts off long tasks and wastes calls on short ones. A cap is only a safety net.
Different problemReplace the loop with a fixed sequence of tool callsIt 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

The loop's stop sign is stop_reason: keep going on “tool_use”, stop on “end_turn”. Not the text, not the wording, not a counter.

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.”

← All traps