The Agent Loop

The Agent Loop: Think → Act → Observe

Strip away the frameworks and every agent is the same fifteen lines: a model, some tools and a bounded loop. Learn where its state lives, what controls it and how it fails, and every agent product becomes legible.

The loop in fifteen lines

This is a complete agent. The model thinks and picks a tool; your code acts; the result is appended and the model observes it on the next call. Two details carry the contract from Inside a Tool Call: append the model’s full content, and send every result back in one user message.

def run_agent(task: str, max_steps: int = 20) -> str:
    messages = [{"role": "user", "content": task}]
    for _ in range(max_steps):                         # a budget, never while True
        resp = client.messages.create(
            model="claude-opus-5", max_tokens=16000,
            tools=TOOLS, messages=messages)
        messages.append({"role": "assistant", "content": resp.content})
        if resp.stop_reason == "end_turn":
            return "".join(b.text for b in resp.content if b.type == "text")
        if resp.stop_reason != "tool_use":             # max_tokens, pause_turn, refusal
            raise AgentStopped(resp.stop_reason, messages)
        results = [run_tool(b) for b in resp.content if b.type == "tool_use"]
        messages.append({"role": "user", "content": results})   # one message
    raise AgentStopped("max_steps", messages)

The answer is the joined text blocks, not content[0].text: with thinking on by default on current models, the first block is often a thinking block.

You rarely need to write this by hand. The SDK’s Tool Runner (client.beta.messages.tool_runner) runs the same loop for tools you define, with max_iterations as the step guard. When to use it, the Agent SDK or a hosted harness instead is in Who Owns the Loop.

State is messages[], and it only grows

The loop remembers nothing except the array it re-sends. After one cycle it holds four turns, and every later call re-reads all of them.

[{"type": "text", "text": "I'll check the order first."},
 {"type": "tool_use", "id": "toolu_01", "name": "get_order",
  "input": {"order_id": "A-1042"}}]

[{"type": "tool_result", "tool_use_id": "toolu_01",
  "content": "{\"status\": \"shipped\", \"eta\": \"2026-09-29\"}"}]

Growth is the cost driver. Take 3,000 tokens of system prompt and tools, and 2,000 tokens added per step (the call plus its result). Call n reads 3,000 + 2,000 × (n − 1) tokens, so a 20-step run looks like this:

Most of each call is a prefix the previous call already sent, which is why Prompt Caching changes an agent’s bill so much. When the history itself gets too long, the newest Claude models expect history to stay append-only: use server-side compaction or context editing rather than deleting old turns (see Context Management).

Control is stop_reason

The loop has one branch point. Handle each value explicitly; treating “anything but tool_use” as success ships truncated and refused answers as if they were finished.

The full list, including stop_sequence, is in Messages API. The Tool Runner does not auto-resume pause_turn, so handle it if you use server tools.

Tool errors go back as results

If a tool raises inside your loop, the request is left with an unanswered tool_use and the model never learns what happened. Catch it and send it back. Models read TimeoutError: inventory API after 5s and retry, switch tools or tell the user.

def run_tool(block) -> dict:
    try:
        out = str(TOOL_FNS[block.name](**block.input))
        if len(out) > 8000:
            out = out[:8000] + "\n[truncated: 8,000 of %d chars]" % len(out)
        return {"type": "tool_result", "tool_use_id": block.id, "content": out}
    except Exception as e:                  # unknown tool, bad args, timeout
        return {"type": "tool_result", "tool_use_id": block.id,
                "content": f"{type(e).__name__}: {e}", "is_error": True}

Guards: the stops that belong to you

The model decides when it is done. You decide when it has had enough. Every guard ends the same way: stop, record why, and return partial progress marked as incomplete, never as success.

A long run can also die for reasons outside the loop: a deploy, a crash, an expired container. Surviving that is Agent Durability.

How the loop fails

Next: The Agentic Spectrum: Workflows to Autonomy, and why most problems need less than a full agent.