The agent loop

Safety limits

An agent decides its own next step. So the code around it has to set limits. There are four.

1. A turn limit. Models can get stuck. They retry a failing tool, or search in circles. Cap the number of model calls (5 to 20 is typical). When you hit the cap, return a clear "stopped" result.

2. Approval for actions with side effects. A side effect is a change in the real world. Reading data is low-risk. Pausing a campaign, sending an email or changing a budget is not. Keep a list of tools that need a person's OK. When the model asks for one, ask the person first. If they say no, tell the model with an error result. Don't just skip it silently:

NEEDS_APPROVAL = {"pause_campaign", "send_email"}

if block["name"] in NEEDS_APPROVAL and not approve(block):
    result = {"type": "tool_result", "tool_use_id": block["id"], "is_error": True,
              "content": "The user declined this action."}

3. A log of every step. Record each tool call and its input. When an agent gives a strange answer, the log of what it looked at is how you find out why.

4. Small tool results. Every turn sends the entire conversation again, including every tool result so far. A tool that returns 5,000 tokens of raw data makes every later turn slower and more expensive. Return only the fields the model needs.

Watch out: cost grows faster than the number of turns. Turn 10 re-sends turns 1 to 9. Prompt caching, covered later, cuts the cost of that repeated start a lot.

def stuck_model(messages):
    return {"stop_reason": "tool_use", "tool": "search", "input": "same query"}

def run(model, max_turns=5):
    messages = ["Find the refund policy"]
    for turn in range(1, max_turns + 1):
        reply = model(messages)
        if reply["stop_reason"] == "end_turn":
            return f"done in {turn} turns"
        if reply["stop_reason"] != "tool_use":
            return f"stopped: {reply['stop_reason']}"
        messages.append("tool result")
    return f"gave up after {max_turns} turns"

print(run(stuck_model))
print(run(lambda m: {"stop_reason": "max_tokens"}))
print(run(lambda m: {"stop_reason": "end_turn"}))

base, per_turn = 1000, 500
sent = [base + per_turn * k for k in range(5)]
print(sent)
print(sum(sent))

You don't always write the loop yourself

The Anthropic Python SDK includes a tool runner that runs this loop for you. You write ordinary Python functions with type hints, labels such as campaign_id: str that say what kind of value each one is. It builds the schemas, calls the tools and feeds back the results:

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def get_campaign(campaign_id: str) -> str:
    """Get one campaign's metrics by id. Call this when the user asks about a specific campaign.

    Args:
        campaign_id: Campaign id, e.g. cmp_101.
    """
    return json.dumps(fetch_campaign(campaign_id))

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5", max_tokens=4000, tools=[get_campaign],
    messages=[{"role": "user", "content": "How is cmp_104 doing?"}],
)
for message in runner:
    print(message)

The @beta_tool line above the function is a decorator: it turns your function into a tool definition. The text in triple quotes becomes the tool's description.

Still, it's worth writing the loop by hand once (you will, below). Then you know what the runner does, where to add approval steps and what to log. Hosted options such as Claude Managed Agents go further. They run the loop and the tools on Anthropic's servers.

Stop reasons that aren't success

Looping until end_turn isn't enough. A reply that stops at max_tokens was cut off, and it may never reach end_turn, so your loop spins forever. Handle each stop reason on purpose, and keep a limit on turns.

Keep tool results small

A huge raw API response fills the context and costs tokens on every later turn. Return only the fields the model needs for the task.