All chapters
  1. Start hereAn agent is a model call in a loop
  2. Chapter 1One call: what a model is from the outside
  3. Chapter 2The loop: where a call becomes an agent
  4. Chapter 3The abstraction ladder: six rungs over one call
  5. Chapter 4The eight jobs of a harness
  6. Chapter 5Context: deciding what the model sees
  7. Chapter 6Tools: what the model may ask for, and where it runs
  8. Chapter 7MCP: one way to plug tools into any harness
  9. Chapter 8RAG: retrieval is context assembly
  10. Chapter 9Control flow and state: stopping, pausing and resuming
  11. Chapter 10Guardrails: identity, approval and the output contract
  12. Chapter 11Reliability and cost: retries, budgets and the failures that will happen
  13. Chapter 12Observability and evals: knowing what the agent did, and whether it was right
  14. Chapter 13Many agents: more loops, and what each one costs
  15. Adopt · 1SDKs: the same loop in Python, TypeScript and Java
  16. Adopt · 2Coding harnesses: a finished harness for software work
  17. Adopt · 3Frameworks and graph runtimes: the loop as a library
  18. Adopt · 4Managed platforms: someone else runs the loop
  19. Adopt · 5Build your own: a whole harness in one file
  20. DecideBuild or adopt: who runs each job?
  21. ReferenceGlossary
  22. AboutAbout this site
Chapter 2

The loop: where a call becomes an agent

The model asks for a tool, code runs it and sends the result back, and that repeats until the model stops asking. Thirty lines, and what they leave out.

The broker's email has gone to the model in one HTTP call, and the reply has come back. It is not a quote. It is not even a sentence. The reply says, in JSON, that the model would like someone to run check_underwriting_rules for 18 Gulf Shore Blvd, and then it ends.

Nothing else happens. The reply sits in a variable. No rule was applied, no price exists, and the broker is still waiting. The model cannot go any further, because all it can do is write text, and it has already forgotten the call. If this request is going to turn into a quote, some program has to read that reply, run the function, and call the model again with the answer.

That program is short. This chapter writes it, runs it, and then reads it a second time to list what it does not do.

An agent is not a special kind of model. It is a model call, some code that answers the model's tool requests, and a loop around both. The model asks, the harness decides and calls, the tool does.

1. The reply that asks for something#

One call showed what goes into a request and what comes back. One part of the request matters most here: the tools list. It describes functions the caller is able to run, each with a name, a sentence of description and a JSON Schema for its arguments. The miniature in examples/quote-email/agent_minimal.py offers a single tool, check_underwriting_rules, which takes an address, a year and a floor area.

When a request carries tools, the model has two ways to answer. It can write text, as before. Or it can write a tool request: a block that names one of the offered tools and supplies arguments for it. Here is the first reply in a run of the miniature. It comes from the scripted fake model that ships with the example, which answers in the response shape of the Messages API; the token counts are that fake's estimate from character length, not a real tokenizer's.

{
  "id": "msg_fake_01",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_fake_01",
      "name": "check_underwriting_rules",
      "input": {"address": "18 Gulf Shore Blvd, Naples FL", "year_built": 1998, "sqft": 2400}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {"input_tokens": 109, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 42}
}

Two fields carry the whole message. Inside content there is a block of type tool_use. It has an id, which identifies this one request; a name, which is one of the tools the request offered; and an input, which the model wrote to fit that tool's schema. The model read "built 1998, 2,400 sq ft" in the email and produced the integers 1998 and 2400. Those four fields, type, id, name and input, are the ones a loop needs.

The second field is stop_reason, with the value tool_use. The stop reason says why the model stopped writing. This value means: I am not finished, I am waiting for the result of what I asked for.

It is worth being exact about what has happened, because the usual wording hides it. People say "the model called a tool". It did not. Anthropic's documentation puts it plainly: "The model never runs anything on its own. It emits a structured request, your code (or Anthropic's servers) runs the operation, and the result flows back into the conversation." The model has produced a description of a call. Whether that call ever happens is up to whoever receives the reply.

2. The answer has to travel back in a new call#

So the program runs the function and gets an outcome. How does the model learn it?

There is no open connection to answer on. The call is over, and the model kept nothing from it. The only way to tell a model anything is to put it in the next request. So the program makes a second call, and that call has to contain everything: the original email, the model's own tool request, and the outcome. The outcome goes in a tool result: a block of type tool_result, placed in a message with the role user, that carries the id of the request it answers.

This is the complete messages list at the moment the miniature makes its second call, printed from the same run.

[
  {
    "role": "user",
    "content": "From: broker@coastal-brokers.example\n\nPlease quote homeowners for 18 Gulf Shore Blvd, Naples FL, built 1998, 2,400 sq ft."
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "toolu_fake_01",
        "name": "check_underwriting_rules",
        "input": {"address": "18 Gulf Shore Blvd, Naples FL", "year_built": 1998, "sqft": 2400}
      }
    ]
  },
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_fake_01",
        "content": "{\"outcome\": \"quote\", \"premium_band\": \"high\", \"reasons\": [\"eligible; flood zone AE\"]}"
      }
    ]
  }
]

Read it as a conversation the model sees for the first time. A user wrote an email. An assistant asked for a rules check. A user supplied the result. The model reading this has no memory of having been that assistant. It continues the transcript from where it ends.

Three details in this list are rules of the API, not style. Each one is a way a hand-written loop gets rejected.

The pairing is by id. tool_use_id in the result must equal id in the request. When a reply holds two requests, the ids are what tell the model which result belongs to which.

The order is fixed. The documentation requires that tool result blocks "immediately follow their corresponding tool use blocks in the message history", with no other message in between. Inside the user message, the result blocks come first and any text comes after them; the documentation labels text placed before a result as a 400 error.

The role is user, even though no person wrote this message. The Messages API has two roles in the message list. Everything the model wrote is assistant. Everything it is given, whether a broker's email or a function's output, is user. That is why the term on this site is tool result, and why "who is the user" is never a safe question to answer from the role field.

One optional field completes the shape. A tool result may carry is_error, which the documentation describes as "Set to true if the tool execution resulted in an error." The model then reads the content as a failure and can ask again or give up. The miniature never sets it. Why that matters comes later on this page.

3. The whole agent, about thirty lines#

Now the program. The code below is lines 19 to 50 of examples/quote-email/agent_minimal.py, shown in its three functions and unchanged. It demonstrates that a working agent needs one function that makes the call, one that does the work, and one loop that connects them. A successful run proves that these lines are enough to carry a request through a tool call to an answer. It does not prove they are safe to leave running, and section 7 is about that difference.

The call#

call_model is one HTTPS POST, written with Python's standard library so that nothing is hidden.

def call_model(messages: list[dict]) -> dict:
    """One HTTPS POST. The model keeps nothing, so every call carries the full history."""
    body = {"model": "claude-opus-5-5", "max_tokens": 16000, "tools": TOOLS, "messages": messages}
    request = urllib.request.Request("https://api.anthropic.com/v1/messages", json.dumps(body).encode(), {
        "x-api-key": os.environ["ANTHROPIC_API_KEY"],
        "anthropic-version": "2026-10-21",
        "content-type": "application/json"})
    with urllib.request.urlopen(request, timeout=120) as reply:
        return json.load(reply)

Line 22 builds the request body from four things: a model id, a cap on the reply length, the tool list and the messages. The tool list and the full message list go out on every call; that is the docstring's point. There is no system field, so this agent has no instructions beyond the email itself. Lines 23 to 26 add the endpoint and three headers: the key, read from the environment at the moment of the call, the API version, and the content type. Lines 27 and 28 send the request, wait at most 120 seconds, and parse the reply into a dictionary. If the server answers with an error status, urlopen raises an exception, and nothing in this function catches it.

The tool#

run_tool is the code that acts. The model asked; this function does.

def run_tool(name: str, args: dict) -> str:
    """The model asked; our code acts. Here there is only one tool."""
    zone = FLOOD_ZONES.get(args["address"].lower(), "X")
    return json.dumps({"outcome": "quote", "premium_band": "high" if zone == "AE" else "standard",
                       "reasons": [f"eligible; flood zone {zone}"]})

Line 33 looks the address up in FLOOD_ZONES, a one-entry dictionary of simulated data defined at the top of the file. Lines 34 and 35 turn the flood zone into an outcome and return it as a JSON string, because a tool result's content is text the model will read. Two things are missing on purpose. The function never looks at name: with one tool there is nothing to choose between, where a real harness would pick the function by name and refuse a name it does not know. And it trusts args. The schema says address is required, but nothing here checks that the model supplied it.

The loop#

agent is the part that makes the other two an agent. It is twelve lines: the signature, a one-line description, and ten lines of work.

def agent(email: str, call=call_model) -> str:
    """The loop: call, run the tools the model asked for, send the results back, repeat."""
    messages = [{"role": "user", "content": email}]
    while True:  # no turn limit, no budget, no checkpoint: that is the harness's job
        response = call(messages)
        messages.append({"role": "assistant", "content": response["content"]})
        if response["stop_reason"] != "tool_use":
            return "".join(block["text"] for block in response["content"] if block["type"] == "text")
        results = [{"type": "tool_result", "tool_use_id": block["id"],
                    "content": run_tool(block["name"], block["input"])}
                   for block in response["content"] if block["type"] == "tool_use"]
        messages.append({"role": "user", "content": results})

Take it a line at a time, because every line is one of the rules from section 2 turned into code.

Line 38 takes the email and a function to call the model with. The default is call_model, the real HTTP call. Passing a different function is how the same loop runs against the scripted fake model with no network.

Line 40 starts the message list with one user message, the email. This list is the entire state of the run. It exists only in this function's memory.

Line 41 is while True. The loop has no counter and no budget. The comment says so, and says whose job that is.

Line 42 makes one model call with the whole list. Line 43 appends the reply to the list as an assistant message, with its content exactly as received. Nothing is filtered or summarized. The next call must contain the tool_use block, or the result that follows would point at a request that is not there.

Line 44 is the only decision in the function, and the model makes it. If the stop reason is anything other than tool_use, line 45 joins the text blocks of the reply and returns them. That is the single exit.

Lines 46 to 48 handle the other case. For each tool_use block in the reply, the code calls run_tool with the block's name and input, and wraps the return value in a tool_result block carrying the same id. A reply can hold several tool requests; the comprehension answers each one. Line 49 appends all the results as one user message, and the while goes around again.

That is all. A turn is one pass through this loop: one model call, plus the tool calls that reply asked for.

Diagram: The agent loop · four steps, and the one exit

Read left to right, then back to the start. Steps 1, 3 and 4 are plain code in the harness. Only step 2 depends on what the model wrote, and it is the only way out of the loop.

  1. 1 · Call
    1. Send the whole message list: One request to the model with every message so far. Append the reply to the list unchanged.
  2. 2 · Check
    1. Read stop_reason: If it is tool_use, the model is waiting for results: go on to step 3.
    2. Anything else: return the text: The only exit. These thirty lines treat every other stop reason as a finished answer.
  3. 3 · Act
    1. Run each tool the model asked for: The harness calls its own function once per tool_use block, with the arguments from the block.
  4. 4 · Return
    1. Append the results, go to step 1: One user message holds a tool_result block per request, matched by id. Then the loop calls the model again.

The diagram shows why this is called an agent loop and not a pipeline. Three of the four steps are fixed code. The second step branches on something the model wrote, and it is the only branch. The code does not know in advance how many times it will go around, or which tool it will run next. It finds out from each reply.

4. Run it#

The command below runs the loop against FakeModel, the scripted stand-in from fake_model.py. It uses no network and no key. What the run can show is that the loop's mechanics and message shapes work end to end. What it cannot show is how a live model would behave: the fake follows plain rules, and no live API call was made for this page.

cd examples/quote-email
/opt/homebrew/bin/python3 agent_minimal.py --fake
{"decision": "quote", "missing_fields": [], "reasons": ["eligible; flood zone AE"], "premium_band": "high"}

One line comes out: the text of the model's last reply. To see the replies the loop received on the way, add --verbose, which prints each one before the loop acts on it. The first line is the reply shown in section 1. The second is this, wrapped here for reading:

{
  "id": "msg_fake_02",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "{\"decision\": \"quote\", \"missing_fields\": [], \"reasons\": [\"eligible; flood zone AE\"], \"premium_band\": \"high\"}"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 210, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 37}
}

Three things are worth noticing. The stop reason is now end_turn, so line 44 sent the loop to its exit. The content is a text block whose text happens to be JSON; the loop returned it without looking inside. And input_tokens went from 109 on the first call to 210 on the second. Those are the fake's estimates, but the direction is real: the second call carried the first call's messages again, plus two more. Every turn of an agent pays for the whole conversation so far. Context is about that cost.

5. One run, message by message#

The run made two model calls and one tool call. Put on a timeline, with one column for each of the three actors, it looks like this.

Diagram: One run of the thirty-line agent · four messages, two model calls, one tool call

Time runs down the page. The harness here is the thirty lines of agent_minimal.py. Every arrow that touches the model is one complete HTTPS request or its reply. The model and the tool never talk to each other: every message passes through the harness.

  1. Harness (the 30 lines) to Model: Call 1: the email and the tool list. One HTTPS POST. The message list holds one user message, the broker's email.
  2. Model to Harness (the 30 lines): stop_reason tool_use: check_underwriting_rules. The reply holds one tool_use block with an id, a tool name and arguments. Nothing has been checked yet.
  3. Harness (the 30 lines) to Tool: run_tool(name, input). The harness appends the reply to the list, then calls its own function with the arguments the model wrote.
  4. Tool to Harness (the 30 lines): quote, premium band high, flood zone AE. The function returns a JSON string. The harness wraps it in a tool_result block that carries the same id.
  5. Harness (the 30 lines) to Model: Call 2: email, tool request, tool result. A second, complete HTTPS POST. It carries all three messages, because the model kept nothing from call 1.
  6. Model to Harness (the 30 lines): stop_reason end_turn: the decision as text. The reply holds one text block and no tool request, so the loop ends.
  7. Harness (the 30 lines): Return the text. The function returns the text of the last reply, unchecked. The message list is discarded.

The important thing in the picture is what is absent: there is no arrow between the model and the tool. The model never reaches the rules function, and the function never hears from the model. Every message passes through the harness, which is here the thirty lines. That middle position is the reason a harness can do anything useful at all. Whatever is going to be checked, limited, recorded or refused has to be checked, limited, recorded or refused by the code in the middle, because nothing else sees both sides.

The second thing to notice is that both arrows into the model are complete, independent HTTP calls. The run feels like one conversation, but the model took part in it twice, from zero each time.

6. What the model decides, and what the code decides#

In an ordinary program, the order of operations is in the source. Read the code and you know that the address is verified, then the property is looked up, then the rules run. In this loop, the source does not say which tool runs or how many times. The model chooses the next step at run time, one reply at a time, from what it has read so far. That is the precise sense in which this is an agent and a single call is not.

The split of authority is still clear, and it is worth stating as a rule. The model decides what to ask for and when to stop asking. The code decides everything else: which tools exist, whether a request is run, what comes back, and whether the loop goes around again. The thirty lines use almost none of that authority. They run every request and return every result. But the authority is theirs, and the rest of this site is about using it.

When the order of steps is known in advance, a loop like this is the wrong tool; plain code that calls the model at fixed points is simpler to test and to reason about. Eight jobs draws that line between a workflow and an agent loop.

Two properties of the wire format decide how far these twelve lines stretch.

Several requests in one reply. The documentation says "By default, Claude may call multiple tools in a single response", and asks the caller to "return one tool_result for each tool_use block, all together in the next user message". Lines 46 to 49 already do this: one result per block, one user message. They run the tools one after another, which is correct but not fast. A caller who wants one request at a time sets disable_parallel_tool_use: true inside the tool_choice object of the request.

More than two stop reasons. Line 44 asks one question: is the stop reason tool_use? Every other value takes the exit. The API documents seven values, and several of them do not mean "here is my answer".

What the thirty lines do with each stop reasonSeven documented values; the loop tells only one of them apart

The meanings are quoted from the quick-reference table in the Claude API documentation, read on 2026-11-16. The full treatment of stop reasons is on One call.

stop_reasonDocumented meaningWhat line 44 doesIs that right?
tool_use"Claude is calling a tool."Runs the tools and calls againYes
end_turn"Claude completed its response naturally."Returns the textYes
max_tokens"The response reached your max_tokens limit."Returns the textNo. The text is cut off. If the cut falls inside a tool request, the documentation says to retry with a higher max_tokens.
stop_sequence"Claude emitted one of your stop_sequences."Returns the textDoes not arise: this request sets no stop sequences
pause_turn"A server-tool loop reached its iteration limit."Returns the textDoes not arise here: the request has no server tools. With them, the documentation says to send the conversation back, including the paused reply, so the model can continue.
refusal"Claude declined to respond."Returns the textNo. A refusal is returned as if it were a decision.
model_context_window_exceeded"The response filled the model's context window."Returns the textNo. The run ended because it ran out of room, not because it finished.

pause_turn exists because Anthropic can also run a loop of its own. For server tools such as web_search, the tool runs on Anthropic's servers inside the call, and the model may use it several times before the reply comes back. The tools on this page are client tools: your application runs them.

A loop that treats "cut off", "refused" and "finished" as the same event is the first sign that thirty lines are a demonstration. The next section collects the rest.

7. What the thirty lines leave out#

The miniature is a simplified demonstration, and the comment on line 41 admits it. To see what a production loop must add, do not start from a list of features. Start from the quote request and ask what could happen to it on a bad day. Each failure below has one cause, and the cause is a line you have already read.

The loop that does not end. Suppose the rules function answers that the address is not recognized, and the model responds by asking again with the address spelled a little differently, and again. Each reply has the stop reason tool_use, so line 44 never takes the exit. Each turn sends a longer history than the last and is billed for it. The cause: the only thing that can end this loop is the model's own stop reason, because line 41 has no counter and no budget. Stop conditions belong to Control flow and state; the money side belongs to Reliability and cost.

The crash in the middle. The tool has returned its outcome, and before the second call the process is restarted by a routine deploy. The broker's request is now nowhere. No error was reported, because nothing was left running to report one, and a restart cannot continue the run because it does not know there was one. The cause: the run's entire state is the messages list created on line 40, a local variable. Saving and resuming a run belongs to Control flow and state.

The request nobody questioned. Today the one tool reads simulated data, so running it blindly is harmless. Give the same loop a tool that sends the reply email, and line 47 will send whatever the model asks, to whatever address the model writes, for any caller. The model writes its requests from text it has read, and part of that text is an email from outside the company. The cause: between the model's request on line 46 and the call on line 47 there is no decision at all. Who may use which tool, and when a person must approve, belongs to Guardrails; how and where a tool runs belongs to Tools.

The answer nobody read. The run above printed clean JSON because the fake model is scripted to. A live model may put a sentence in front of the JSON, leave out reasons, or return a premium_band that no rule produced. Line 45 returns it all the same, and the first program to notice is the one downstream that tries to parse it or, worse, the one that prices from it. The cause: line 45 joins the text and returns it without checking it against anything. The output contract belongs to Guardrails.

The call that fails once. The API documents HTTP 429 as rate_limit_error and 529 as overloaded_error, "The API is temporarily overloaded." Either one, on the second call, raises an exception on line 27. It passes straight up through agent, and the run ends with a stack trace, having thrown away a tool result it already had. The same gap exists on the tool side: an exception inside run_tool ends the run, where a tool result with is_error would have let the model react. The cause: one failed attempt is treated as the end of the run, because nothing between line 42 and line 27 tries again. Retries, fallback and their limits belong to Reliability and cost.

The question a week later. The broker phones to ask why the premium band was high. The team has one line of output. Which tool the model asked for, with which arguments, what came back, how many calls it took and what they cost were all in the messages list and the usage fields, and all of it was discarded when the function returned. The cause: nothing in the loop writes anything down. Traces, and the evals that tell you whether a change made runs better, belong to Observability and evals.

The same six, side by side:

On a bad dayThe cause in the thirty linesThe job it belongs toWhere it is solved
The model keeps asking and the loop never endsLine 41: while True, no counter, no budget3 Control flowControl flow and state
A restart loses the request without a traceLine 40: the state is one local list4 State, memory, durabilityControl flow and state
Any tool request is run, for any callerLines 46 to 47: no decision between request and call5 Identity, permissions, approvalGuardrails
Malformed or invented output goes downstreamLine 45: the text is returned unchecked6 Output contractGuardrails
One 429 or 529 ends the runLines 27 and 42: no second attempt7 Reliability and costReliability and cost
Nobody can say what the run didNo line records anything8 Observability and evalsObservability and evals

The numbers in the third column are not decoration. They are six of the eight jobs that Eight jobs sets out as a checklist. The other two, context assembly and tools, are present in the thirty lines in their barest form: the context is "append everything, send everything", and the tool is one trusted function in the same process. Both become problems of their own as soon as a run is long or a tool can change something, and Context and Tools start there.

None of the six is a defect in the model. A better model does not add a counter to line 41 or save line 40's list to disk. They are all properties of the code in the middle, which is the only place they can be fixed.

8. Who runs the loop#

Twelve lines are easy to write, and section 7 is why most teams stop writing them by hand. The loop itself is the same wherever it runs: call, check, act, return. What changes from product to product is whose code it is, and therefore who can add the missing parts.

There are three answers. The loop can be your own code, as in the miniature. It can be a library that runs in your process: you hand over tools and instructions, and the library makes the calls and runs your functions. Or it can run on a vendor's servers, where you send a task and receive events.

The table lists where the loop lives for a few named products. It covers only the loop. The words are the ones this site uses throughout: YOU BUILD, BUILT IN (a library runs it in your process) and MANAGED (a vendor runs it on its servers).

Where the loop runsExampleWho runs the loopStatus noted in the vendor's documentation
Your own codeagent_minimal.py, or a provider SDK with a hand-written loopYOU BUILD
A helper inside the provider SDKThe tool runner in Anthropic's SDKs (Python, TypeScript, C#, Go, Java, PHP, Ruby)BUILT INBeta
An agent SDKClaude Agent SDK; OpenAI Agents SDKBUILT IN
An agent frameworkLangChain create_agent (its loop runs on LangGraph)BUILT IN
A managed platformClaude Managed AgentsMANAGEDBeta
A managed platformAmazon Bedrock AgentCore (its Harness is the managed agent loop)MANAGED

The tool runner row was read in Anthropic's documentation on 2026-11-16, which describes it as handling "the agentic loop, error wrapping, and type safety". The other rows come from this site's checked baseline of 2026-11-14. The table is not a ranking, and it says nothing about the six gaps: a product that runs the loop for you may or may not stop it, save it, guard it or record it. Each job page has its own table for that, and Build or adopt puts them together.

One thing does not change in any row. Wherever the loop runs, the messages on the wire are the ones from section 2: a tool request out of the model, a tool result back in, the whole history on every call. When a library or a platform behaves in a way you did not expect, the request it actually sent is where the explanation is, and you can now read it.

What you have, and what is still open#

You can now write an agent without a library: one call, one function that does the work, and twelve lines that pass a tool request one way and a tool result the other until the model stops asking. You can also say exactly what those lines do not do, and point at the line responsible each time.

The quote request, meanwhile, is only safe on a good day. Nothing stops its loop, saves it, guards it, checks its answer, retries its call or records its run. Every product in this field exists to take some of that work off your hands, and each takes a different amount. The ladder sorts them into six rungs, starting from the raw HTTP call you just wrote, and asks of each rung what it hides and what it cannot change.

The loop is the part everyone has in common, and it is the easy part. What you are choosing, when you choose how to build an agent, is who writes the code around it.