Agentic loop lifecycle: stop_reason control flow and tool results

1.The request, execute, return cycle

Tool use is a contract between your application and Claude. You declare which operations exist and what shape their inputs take, and Claude decides when to call them. Claude never runs anything itself. It sends back a structured request, your code performs the operation, and the result goes back into the conversation. Claude never sees your implementation. It sees only the schema you defined and the result you return.

Claude can't run your code, so every call to a client-executed tool is a round trip, and your application has to drive it. The agentic loop is that round trip, repeated until the task is done. The documentation gives it a standard five-step shape:

1. Send a request with your tools array and the user message. 2. Claude responds with stop_reason "tool_use" and one or more tool_use blocks. 3. Execute each tool and format the outputs as tool_result blocks. 4. Send a new request containing the original messages, the assistant's response, and a user message with the tool_result blocks. 5. Repeat from step 2 for as long as stop_reason is "tool_use".

The Agent SDK describes the same cycle from the inside. Claude receives the prompt along with the system prompt, tool definitions and conversation history. It evaluates the current state and decides what to do next. The SDK runs the tools Claude requested, and the cycle starts again. The SDK counts each full cycle as one turn.

Sources12

2.Branching on stop_reason

A single field decides which way the loop goes. Every Messages API response includes a stop_reason that says why Claude stopped generating. The loop's control flow depends on that field and nothing else in the response.

The rule is short. If stop_reason is "tool_use", run the tools and continue the conversation. On any other value, leave the loop: either Claude has given its final answer, or it stopped for a reason your application has to deal with separately. "end_turn" is the normal exit and means Claude finished its response naturally. The other values are exits too, but they don't mean the work succeeded.

A simple request shows what this means in practice. The loop doesn't need a tool call before it can end. The Agent SDK says Claude keeps calling tools and processing the results until it produces a response with no tool calls. If a question can be answered directly, that happens on the very first request. A first-iteration "end_turn" with only text means the task is finished. It isn't a bug.

The documentation recommends checking stop_reason explicitly in your response-handling code and giving each value its own branch:

def handle_response(response):
    match response.stop_reason:
        case "tool_use":
            return handle_tool_use(response)
        case "max_tokens":
            return handle_truncation(response)
        case "model_context_window_exceeded":
            return handle_context_limit(response)
        case "pause_turn":
            return handle_pause(response)
        case "refusal":
            return handle_refusal(response)
        case _:
            # Handle end_turn and other cases
            return next(
                (block.text for block in response.content if block.type == "text"),
                "",
            )

if response.stop_reason == " ? ":
    # Extract and execute the tool
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)
            # Return result to Claude for final response

Sources312

3.Adding tool results to the conversation history

Running the tool is only half of each iteration. On every request, Claude sees the prompt, system prompt, tool definitions and the conversation history you send. If the result isn't in that history, Claude can't use it to decide what to do next.

Each tool_use block has three fields: an id, a name, and an input that matches the tool's input_schema. The id lets you pair each result with its request. Your tool_result block repeats that id in its tool_use_id field, and it goes inside a message with the user role:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

The next request must contain three things: the original messages, the assistant's complete response including its tool_use blocks, and this user message. The continuation message needs one tool_result for every tool_use block in the response. If one is missing, the API rejects the request with an error saying tool_use ids were found without tool_result blocks immediately after them. Once the result is in the history, Claude uses it to continue answering the original prompt.

Failures go back to Claude in the same way. If the tool throws an error, for example a network failure, return the error message as the content and set "is_error": true. Claude can then explain the failure to the user, or try the call again with the missing information filled in.

One detail of message structure matters a lot. Don't put a text block after the tool_result blocks. The documentation warns that this teaches Claude to expect user input after every tool use. Claude may then end its turn early with an empty "end_turn" response.

Sources234

4.Model-driven decisions versus pre-configured sequences

Nothing in the loop you have just seen says which tool runs next. Your code defines the available operations and their schemas, and Claude determines when and how to call them. On each iteration Claude evaluates the current state, which includes every tool_result already in the history, and decides how to proceed: call another tool, call several, or give a final answer. The result of one call can change what it does next.

This is what separates an agent from a workflow. Anthropic draws the line this way: in a workflow, LLMs and tools are orchestrated through predefined code paths. In an agent, the LLM dynamically directs its own process and tool usage. A hard-coded sequence such as "always call search, then fetch, then summarise", or a decision tree your code walks regardless of what the results say, is a workflow. The loop only counts as agentic when the choice of the next action comes from Claude's reasoning over the history.

The two are not ranked. Workflows offer predictability and consistency for well-defined tasks. Agents are the better option when flexibility and model-driven decision-making are needed. Your loop's job in the agentic case is to stay mechanical: run what Claude asked for, return the results, and let stop_reason say when it is finished.

Sources125

5.Termination anti-patterns

Because stop_reason is the loop's control signal, three tempting shortcuts are wrong.

1. Parsing natural language to decide when to stop. Scanning Claude's prose for phrases such as "I'm done" or "task complete" is fragile. The tool-use documentation gives the general rule: if you're writing a regex to extract a decision from model output, that decision should have been a tool call. For termination, the structured signal already exists, and it is stop_reason.

2. Making an iteration cap the primary stopping mechanism. The SDK loop runs until Claude produces a response with no tool calls. A limit such as max_turns or max_iterations is a safeguard, and the documentation's own example uses it to prevent runaway sessions. Hitting the cap is not a normal finish. The result subtype becomes error_max_turns, which means the turn limit was hit before the task finished, and no result field is available. If your loop routinely ends this way, the cap is doing the job that stop_reason should do.

3. Treating assistant text as a completion indicator. A response can carry text, tool calls, or both. Claude often writes a sentence such as "I'll check the weather" in the same response as a tool_use block, and that response has stop_reason "tool_use". If you stop because text is present, you abandon the task mid-step. In the other direction, a response with no text can still be a legitimate end_turn. Branch on stop_reason, not on whether text exists.

Sources12

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A task must go through at least one tool call before an "end_turn" response counts as a valid finish.Why is that wrong?

   The loop ends at the first response with no tool calls, and that can be the very first response. A text-only "end_turn" on iteration one means the task is complete.

   Covered in Branching on stop_reason

2. 2.Adding the assistant's text to the history is enough to keep the loop going, and the tool_use and tool_result blocks can be left out.Why is that wrong?

   The next request must include the assistant's full response and a user message with the tool_result blocks. Without them Claude has no record of the result and may ask for the same call again.

   Covered in Adding tool results to the conversation history

3. 3.A loop that always calls the same tools in a fixed order is an agent, because it uses tool_use and tool_result blocks.Why is that wrong?

   Using the tool API does not make a loop agentic. When code fixes the path, it is a workflow; an agent is one where the LLM dynamically directs its own process and tool usage.

   Covered in Model-driven decisions versus pre-configured sequences

4. 4.Setting max_turns is the correct way to decide when an agentic loop is finished.Why is that wrong?

   The loop finishes when Claude returns a response with no tool calls. A turn cap prevents runaway sessions, and reaching it is reported as the error_max_turns result, not as success.

   Covered in Termination anti-patterns