Agent loop stop_reason: when to loop and when to stop

Try 3 questions on this

Pick an answer to see why each option is right or wrong.

1. Your summarisation agent sets max_tokens to 512. A share of responses return with a stop_reason of max_tokens, and your loop discards those responses as malformed and re-issues the identical request, which produces the same outcome and roughly doubles the run's latency without producing a longer summary. What's the correct approach to handling those responses?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: B is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   Your answerA.Treat the response as a client tool call, run the tool it names, and return a tool_result block.A tool call reports stop_reason of tool_use and carries a tool_use block with a name and an id. A truncated summary carries neither.The answerB.Treat the response as valid but truncated, then raise max_tokens or continue it from where it stopped.max_tokens means "The response reached your max_tokens limit", and the documentation is explicit that "The response is still valid but was truncated." The two documented remedies are to raise max_tokens or to continue the response; re-sending the identical request with the same limit reproduces the same truncation.Your answerC.Treat the response as a refusal, read its stop_details, and send the request to a fallback model.A refusal arrives as an HTTP 200 with stop_reason of refusal and non-null stop_details. This turn was cut at your output limit, and any model would cut it at the same place.Your answerD.Treat the max_tokens response as paused, append its content, and make another request to finish the server loop.Appending the assistant content and requesting again continues a pause_turn, which a server-side tool loop produces. No server tool was involved here.

   Written from platform.claude.com/docs/en/build-with-claude/handling-stop-reasons

2. Your agent loop keeps iterating while stop_reason is anything other than end_turn, on the reasoning that a turn is unfinished until Claude says it is done. A run that hits your max_tokens limit now re-sends the same messages until the retry cap fires, and a turn that ends in a refusal behaves the same way. How should you restructure the loop's exit condition?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: C is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   Your answerA.Iterate until stop_details is non-null, and return the response as soon as that field is populated.stop_details is non-null only for a refusal, so an exit gated on it would spin forever on ordinary turns and exit only on the one case you most want to inspect.Your answerB.Keep the current condition and bound the run with a fixed iteration cap so it always terminates.An iteration cap stops a run from spinning indefinitely, but the loop still spends its whole budget re-sending requests that no repetition can fix.The answerC.Iterate only while stop_reason is tool_use, and return on every other value.The documented loop shape is to iterate while response.stop_reason == "tool_use", appending the assistant message and then a user message of tool results, and otherwise to return the response. tool_use is the only value that means another request is owed; end_turn, max_tokens, refusal and the rest all leave the loop and are handled by their own branch.Your answerD.Iterate while stop_reason is tool_use or max_tokens, and return on end_turn and on refusal.A max_tokens response is truncated but valid. Re-sending the same messages under the same limit reproduces it; the response needs a higher limit or a continuation instead.

   Written from platform.claude.com/docs/en/build-with-claude/handling-stop-reasons

3. Your orchestrator ends the assistant turn as soon as every client tool_use block has been answered. Some runs return an answer with the web search findings missing, and the transcripts for those runs show a server_tool_use block in the last response with nothing following it. What's the most effective way to decide whether that turn is finished?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: A is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   The answerA.Check each server_tool_use or mcp_tool_use id for a matching result block, and continue while any of them is unmatched."Detect incomplete server tool calls by checking each server_tool_use or mcp_tool_use block's id for a matching result block", and "if a server tool call has no result block, that tool is still running, do not end the assistant turn." Completeness is decided per id, exactly as client results are matched by tool_use_id.Your answerB.Continue while stop_reason is pause_turn, which the response carries until every server tool call has produced its result.pause_turn is returned when the server-side sampling loop reaches its iteration limit while executing server tools. A response with an unfinished call need not carry it, so it is not a completeness test.Your answerC.Continue while the last content block is a server_tool_use block, and end the turn once any other block type is last.Nothing guarantees the pending call is the last block. A response can end with text while an earlier server_tool_use block is still outstanding.Your answerD.Count the content blocks in the response and continue while that count exceeds the number of results you sent back.Counting blocks conflates types. Two calls and one unrelated block can produce the same total as one call and two blocks, while a specific id stays unanswered.

   Written from platform.claude.com/docs/en/build-with-claude/handling-stop-reasons