The agent loop

The stepsCopy Anchor Link

1. Send the model the goal, the history and the tool definitions.
2. If the reply is a tool call, run it.
3. Append the call and its result to the history.
4. Call the model again.
5. If the reply is a final answer, stop.

Around the loop, add limits: a maximum number of steps, a cost cap and a timeout. Also log every call, so you can see what the agent did, and give a person a way to interrupt.

What goes wrongCopy Anchor Link

The model picks the wrong tool, repeats the same call, or loses the goal as the history grows. Unclear tool errors make the model retry the same call over and over. Context fills with old results. Fixes are in the harness: clear tool errors, a step limit, trimming or summarizing old output and checks the agent can run itself.

Try itCopy Anchor Link

Step through the loop in the demo. Watch the context grow with each tool call, and see where the loop stops.

A trace of three turnsCopy Anchor Link

Goal: "What is the total for order 8123 including shipping?" Invented token counts. The goal plus the tool definitions take 450 tokens.

Turn 1 sends 450 tokens. The model replies with a call to get_order (30 tokens). Your program runs it, and the tool result adds 100 tokens.

Turn 2 sends 450 + 30 + 100 = 580 tokens. The model calls get_shipping (30 tokens) and the result adds 120.

Turn 3 sends 580 + 30 + 120 = 730 tokens. The model writes the final answer and the loop stops.

The new information was about 280 tokens, but the loop sent 450 + 580 + 730 = 1,760. Each turn resends the whole history, so a long run costs far more than the sum of its parts.

What goes wrong: the repeat spiralCopy Anchor Link

The symptom is a log showing the same tool with the same arguments five times in a row, each returning the same result. The model does not see progress and tries again. Confirm it by logging every call and checking for identical pairs of tool name and arguments. A simple fix is for the harness to notice a repeat and either stop the run or return the message "You already tried this and got this result. Try something different."

When the loop is the wrong toolCopy Anchor Link

Read the logs of twenty runs. If every run makes the same three calls in the same order, the model is not deciding anything. Write those three calls as plain code and skip the loop. It will be faster, cheaper and easy to test.

Where this connectsCopy Anchor Link

Agents need tests of their own, and the loop needs limits for cost and steps. See Trajectory evals for agents and Human approval.

The codeCopy Anchor Link

The loop from the steps above, in Python. It stops when the model answers, and also after 10 steps. Tool results go back in a message with the role "user", because from the model's side your program is the one answering its request. tools is the list of tool definitions and run_tool is your function that runs one, as in the tool-use lesson.

from anthropic import Anthropic

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment

def run_agent(goal, tools, run_tool, max_steps=10):
    messages = [{"role": "user", "content": goal}]
    for _ in range(max_steps):
        reply = client.messages.create(model="claude-sonnet-5-5", max_tokens=1000, tools=tools, messages=messages)
        messages.append({"role": "assistant", "content": reply.content})
        if reply.stop_reason != "tool_use":
            return reply.content[0].text  # no tool call: this is the final answer
        results = []
        for block in reply.content:
            if block.type == "tool_use":
                try:
                    output = run_tool(block.name, block.input)
                except Exception as e:  # return the error as a result so the model can recover
                    output = f"Error: {e}"
                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
        messages.append({"role": "user", "content": results})
    return "Stopped: step limit reached."