The agentic loop and stop conditions

An agent is, at its core, a model calling tools in a loop. Your code sends the conversation and the tool definitions. The model either answers or asks for one or more tool calls. Your code runs those tools, sends the results back, and calls the model again. Everything else in this course (subagents, handoffs, approvals) is built on this cycle, so it pays to know exactly how it starts, turns and stops.

One turn, step by step

1. Call the Messages API with messages and tools.
2. Append the assistant response to messages, unchanged.
3. Read stop_reason. If it’s tool_use, run every tool_use block in the response and reply with one tool_result per block, matched by tool_use_id.
4. Repeat until the model stops asking for tools, or until one of your guards fires.

The tool_result message has strict formatting rules. It must come straight after the assistant message that requested the tools, with nothing in between. In that user message the tool_result blocks come first, and any text goes after them. If a tool fails, send the error text as the content with is_error: true. The model can then retry with different input or explain the failure. Write errors the way you’d want them on-call: “kubectl timed out after 30s; the API server may be overloaded” helps far more than “failed”.

Stop reasons you must handle

Only end_turn (and a stop_sequence you planned for) means “done as intended”. Everything else is either “keep going” (tool_use, pause_turn) or “something cut the turn short”.

Stop conditions you own

The model decides when it’s finished, but you decide when it must stop. The API docs say it plainly: tool_use and pause_turn can repeat indefinitely, so every production loop needs an iteration cap. Common guards:

• Max steps. A hard limit on model calls. When you hit it, fail loudly. Don’t return whatever text happens to be lying around as if it were an answer.
• Budget. Track token usage per call and stop above a spend threshold.
• Wall clock. An incident bot that answers after 20 minutes has missed the point.
• No progress. The same tool called with the same input three times in a row is a loop, not an investigation.

HTTP errors such as 429 or 529 are a separate channel. Handle them with retries and backoff around the API call, not as stop reasons.

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment
MAX_STEPS = 8


def run_agent(task, tools, run_tool):
    messages = [{"role": "user", "content": task}]
    for step in range(MAX_STEPS):
        resp = client.messages.create(
            model="claude-opus-5-5", max_tokens=2048,
            tools=tools, messages=messages,
        )
        messages.append({"role": "assistant", "content": resp.content})

        if resp.stop_reason == "tool_use":
            results = []
            for block in resp.content:
                if block.type != "tool_use":
                    continue
                try:
                    out, failed = run_tool(block.name, block.input), False
                except Exception as exc:  # report it to the model, don't hide it
                    out, failed = f"{type(exc).__name__}: {exc}", True
                results.append({"type": "tool_result", "tool_use_id": block.id,
                                "content": out, "is_error": failed})
            messages.append({"role": "user", "content": results})
        elif resp.stop_reason == "pause_turn":
            continue
        elif resp.stop_reason == "end_turn":
            return resp
        else:
            raise RuntimeError(f"stopped early: {resp.stop_reason}")
    raise RuntimeError(f"no final answer after {MAX_STEPS} steps")

Recap

• The loop is: call the model, read stop_reason, run every requested tool, send matching tool_result blocks, repeat.
• end_turn is the normal exit. tool_use and pause_turn mean “continue”. max_tokens, model_context_window_exceeded and refusal mean the turn was cut short.
• Report tool failures with is_error: true and a useful message.
• Always add your own caps (steps, budget, time), and fail loudly when they fire.