Skip to content

02.1

Concept explanation

If you remember one thing from this guide, remember this: the core of every coding agent is a small loop, and it is much simpler than you think.

Here is the entire idea, lifted almost verbatim from the open-source Codex codebase (the file is literally called turn.rs):

while needs_follow_up:
    1. Gather the conversation history
    2. Send it to the LLM, along with the list of available tools
    3. Look at the response:
       - If it contains tool calls -> run them, append the results, loop again
       - If it is just text     -> we are done

That is it. There is no separate "planning engine," no mysterious reasoning module. The agentic behavior you see (the way it investigates, tries things, course-corrects) all emerges from running this one loop until the model decides it is finished.

Anthropic describes the same thing with three friendlier words: gather context, take action, verify results, repeated until the task is done. Codex's lead engineer Michael Bolin draws it as a cycle of inference and tool calls. They are all the same loop.

The two outcomes of every model call

Each time the harness calls the model, the model does exactly one of two things:

  1. It asks for a tool call: "run ls," "read this file," "apply this patch." The harness runs the tool, captures the output, appends it to the conversation, and calls the model again with the new information.
  2. It produces an assistant message: plain text for the user. This signals the end of the turn. Control returns to you.

So the loop spins on outcome 1 and stops on outcome 2. A single user request ("fix the failing tests") might spin through that loop fifty times (run tests, read the error, search for the file, read it, edit it, run tests again) before the model finally says, in plain text, "Fixed it. The bug was a stale session token."

What "output" really means

Here is a subtle point that trips people up, and Bolin calls it out directly. When you think about what a coding agent "outputs," you picture that final text message. But for a software agent, the text is not the deliverable. The deliverable is the changes it made to your machine: the files it edited, the tests it made pass, the commit it created. The assistant message is just the termination signal, a polite "I'm done, your turn."

The practical consequence, which we will use later: you do not need the agent to produce flowery prose. You need it to produce reliable tool calls. Design your instructions to guide good actions, not good paragraphs.

Turn, thread, conversation

A bit of vocabulary that the sources use consistently:

  • A turn is one cycle of "user input goes in, agent works, agent comes back with an assistant message." Inside a single turn, the inference-and-tool-call loop may run many times.
  • A thread (Codex's word) or conversation is the whole back-and-forth, made of many turns.
  • Every new turn includes the entire history of previous turns in the prompt. That detail seems innocent. It is actually the source of the biggest performance problem in the whole field, and Chapter 4 is devoted to it.

02.2

Why it matters

Understanding the loop demystifies everything else. Costs, context limits, the need for compaction, the value of subagents, the design of approval systems: all of them are consequences of this loop running and the prompt growing each time around. Once you can see the loop, the rest of the harness stops looking like a bag of tricks and starts looking like a set of sensible responses to one repeating process.

It also tells you where you can intervene. You (the user) are part of this loop. You can interrupt at any point to steer, add context, or redirect. The agent works autonomously but stays responsive. That is why Claude Code lets you press Escape to stop a running tool, or type a correction mid-stream that the model reads as soon as the current action finishes.

02.3

How it works: a closer walk

Let us trace one real turn, the kind Bolin describes in the Codex write-up.

  1. You type: "Add an architecture diagram to the README."
  2. The harness builds a prompt (Chapter 3 covers exactly what goes in it) and calls the model.
  3. The model thinks, then asks for a tool call: shell with command cat README.md. It does not run anything; it asks.
  4. The harness runs cat README.md, captures the output, and appends two things to the history: the tool call and its result, linked by a shared call_id so the model knows which result belongs to which call.
  5. The harness calls the model again, now with the README contents included.
  6. The model asks for another tool call: an edit that inserts the diagram.
  7. The harness applies the edit, appends the result, calls again.
  8. This time the model returns plain text: "I added a diagram explaining the client/server architecture." Turn over.

Notice that step 4's appended history is what makes step 5 smarter than step 2. Each tool result feeds back in. That feedback is the whole point; it is why the loop can course-correct instead of blindly executing a fixed plan.

02.4

Real code: the loop inside Codex's turn.rs

The walk above is one Codex turn. Here is run_turn, the loop in codex-rs/core/src/session/turn.rs. On the next slide you build the same skeleton in Python.

loop { // [1]
    // ... (3 lines: a queued message is one you sent while the model was running)
    let pending_input = if can_drain_pending_input {
        sess.input_queue
            .get_pending_input(&sess.active_turn)
            .await
            .0
    } else {
        Vec::new()
    };
    // ... (87 lines: record that input, then capture this lap's tools and settings)
        // Construct the input that we will send to the model.
        let sampling_request_input: Vec<ResponseItem> = async {
            sess.clone_history() // [2]
        // ...
        run_sampling_request( // [3]
        // ... (14 lines: pass the history and a cancel token, then match on success)
            let SamplingRequestResult {
                needs_follow_up: model_needs_follow_up,
            // ... (14 lines: unpack the rest, then collect hook results that finished late)
                let has_pending_input =
                    sess.input_queue.has_pending_input(&sess.active_turn).await;
            // ...
            let needs_follow_up = model_needs_follow_up || has_pending_input; // [4]
            // ... (113 lines: if the history has grown too big, compact it and go round again)
            if !needs_follow_up {
                last_agent_message = sampling_request_last_agent_message;
                // ... (105 lines: stop hooks, which can force one more lap; compaction after the turn)
                break; // [5]
            }
            continue;

Source: openai/codex, codex-rs/core/src/session/turn.rs (Apache-2.0)

match ToolRouter::build_tool_call(item.clone()) {
    // ... (1 line: log the call, record it, and queue it)
    Ok(Some(call)) => {
        // ... (24 lines: tracing, then record the call in the history)
        let tool_future: InFlightFuture<'static> = Box::pin(
            ctx.tool_runtime
                .clone()
                .handle_tool_call(call, cancellation_token),
        );

        output.needs_follow_up = true; // [6]
        output.tool_future = Some(tool_future);
    }
    // ... (1 line: a message or reasoning item, not a tool call)
    Ok(None) => {
        // ... (36 lines: record the message and show it to the user)
        output.last_agent_message = finalized_facts.and_then(|facts| facts.last_agent_message); // [7]
    }

Source: openai/codex, codex-rs/core/src/stream_events_utils.rs (Apache-2.0)

What to notice

  1. [1] No counter. A lap takes queued messages only when can_drain_pending_input is true. Your opening request sets that flag false (input is not empty), so it is sampled first.
  2. [2] clone_history() copies the conversation. A ResponseItem is one history entry. This loop acts on a message, a function call, and that call's output. The type also holds reasoning, web search, compaction, and more. for_prompt shapes the copy for this model: it pairs calls with outputs, and it strips images or audio when that input is off.
  3. [3] run_sampling_request sends the list and handles the reply. If the stream fails, this function can retry before returning the error.
  4. [4] Go round again if the model asked for more work, or if you typed something during the lap.
  5. [5] Otherwise break returns control to you. A stop hook in the elided lines can add a prompt and force one more lap.
  6. [6] A tool call is not run inline. It is queued as a future (work that finishes later) and sets needs_follow_up. After the reply finishes streaming, drain_in_flight in turn.rs waits for those futures and records each successful output. A future that fails is logged and not written into the history.
  7. [7] A message or reasoning item does not by itself set needs_follow_up. Assistant text is stored in last_agent_message only when the item is an agent message with text. A denied or directly answered tool request, in the next arm of this match, writes that answer into the history and sets needs_follow_up. A completed response with end_turn false forces another lap even if no tool ran.

Read it yourself: in turn.rs, compare the doc comment above run_turn with this chapter's pseudo-code. Then search try_run_sampling_request for end_turn: what happens when the API says the turn is unfinished but no tool was called?

02.5

Code MVP: a working agent loop

This is the skeleton the entire capstone is built around. It runs without a real model by using a tiny scripted stand-in, so you can see the control flow clearly. Replace fake_model with a real API call and it becomes a real agent.

"""
chapter 02: the agent loop.
A minimal, runnable agent loop with a fake model and one real tool.
The structure here is exactly what production harnesses use.
"""
import subprocess

# --- The tools the model is allowed to ask for (Chapter 6 expands this) ---
def tool_shell(command: str) -> str:
    """Run a shell command and return combined output."""
    result = subprocess.run(command, shell=True, capture_output=True, text=True)
    return (result.stdout + result.stderr).strip()

TOOLS = {"shell": tool_shell}

# --- A fake "model": it returns tool requests, then a final message. ---
# A real model would return these decisions itself. We script them so the
# loop's control flow is visible without an API key.
def fake_model(history: list) -> dict:
    # Count how many tool results are already in the history.
    tool_results = [h for h in history if h["role"] == "tool"]
    if len(tool_results) == 0:
        # First call: ask to list files.
        return {"type": "tool_call", "name": "shell",
                "args": {"command": "echo hello from the agent"}}
    else:
        # We already ran a tool; now produce a final answer.
        last = tool_results[-1]["content"]
        return {"type": "text", "content": f"Done. The command said: {last!r}"}

# --- The loop itself. This is the heart of every coding agent. ---
def agent_loop(user_request: str, max_turns: int = 10) -> str:
    history = [{"role": "user", "content": user_request}]

    for _ in range(max_turns):                 # a safety cap (Chapter 12)
        response = fake_model(history)         # 1 & 2: gather + call the model

        if response["type"] == "text":         # 3a: plain text -> we are done
            history.append({"role": "assistant", "content": response["content"]})
            return response["content"]

        # 3b: a tool call -> execute it, append the result, loop again.
        name, args = response["name"], response["args"]
        history.append({"role": "assistant", "content": f"(calling {name} {args})"})
        output = TOOLS[name](**args)
        history.append({"role": "tool", "content": output})

    return "Stopped: hit the turn limit without finishing."

if __name__ == "__main__":
    print(agent_loop("say hello using the shell"))

Run it and you will see the loop make one tool call, feed the result back, and then finish with a text message. That is the same shape as a fifty-step Codex session; only the number of laps and the realism of the model change.

A few things to notice, because they foreshadow later chapters:

  • history grows every lap. That growth is the quadratic problem (Chapter 4).
  • max_turns is a crude kill switch. Real harnesses make this a proper budget (Chapter 12).
  • TOOLS is one dict with one tool. Real harnesses make it a rich registry with validation and truncation (Chapter 6), and gate every call behind a permission check (Chapter 7).
  • We blindly trusted the tool call. Production code validates the arguments against a schema first.

02.6

Real code: mini-swe-agent, the toy loop finished

You just wrote agent_loop in about twenty lines. mini-swe-agent is that loop in production Python: the agent class fits in default.py. Watch what ends it, because a plain-text reply is not the end.

def run(self, task: str = "", **kwargs) -> dict:
    # ... (7 lines: docstring, then a fresh message list with the system prompt and the task)
    while True:  # [1]
        try:
            self.step()
            self.n_consecutive_format_errors = 0  # reset on any clean step
        except FormatError as e:  # [2]
            # ... (14 lines: charge for the bad reply, count it, give up after too many in a row)
        except InterruptAgentFlow as e:  # [3]
            self.add_messages(*e.messages)
        # ... (3 lines: any other crash is recorded as an exit message, then re-raised)
        finally:
            self.save(self.config.output_path)
        if self.messages[-1].get("role") == "exit":  # [4]
            break
    return self.messages[-1].get("extra", {})

def step(self) -> list[dict]:
    """Query the LM, execute actions."""
    return self.execute_actions(self.query())

def query(self) -> dict:
    """Query the model and return model messages. Override to add hooks."""
    if 0 < self.config.step_limit <= self.n_calls or 0 < self.config.cost_limit <= self.cost:  # [5]
        raise LimitsExceeded(
        # ... (14 lines: build the exit message, then the same check for wall-clock time)
    self.n_calls += 1
    message = self.model.query(self.messages)
    self.cost += message.get("extra", {}).get("cost", 0.0)
    self.add_messages(message)
    return message

def execute_actions(self, message: dict) -> list[dict]:
    """Execute actions in message, add observation messages, return them."""
    outputs = [self.env.execute(action) for action in message.get("extra", {}).get("actions", [])]  # [6]
    return self.add_messages(*self.model.format_observation_messages(message, outputs, self.get_template_vars()))

Source: SWE-agent/mini-swe-agent, src/minisweagent/agents/default.py (MIT)

What to notice

  1. [1] while True with no counter. Each lap is one step(), which is your loop body: query() asks the model, execute_actions() runs what it asked for.
  2. [2] In your toy, a plain-text reply meant "done". Here it is a mistake. The tool-call parser raises FormatError when a reply has no tool call, names a tool other than bash, or has arguments with no command. The error text goes back to the model as a user message, and the run gives up only after 3 bad replies in a row (the default max_consecutive_format_errors).
  3. [3] InterruptAgentFlow is an exception whose only job is to carry messages to append. Task finished, budget spent, time up: each is a subclass, and all go through this one line. finally always calls save. That writes every message so far to disk only when output_path is set. It defaults to None. A crash still appends an exit message and then re-raises, so a run that was given a path keeps the file.
  4. [4] The loop returns only when the last message has role "exit". A crash re-raises instead, so run does not return. The normal exit is not written by the environment. _check_finished raises Submitted when the return code is 0 and, after leading whitespace is stripped, the first line is COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT. The agent loop appends that message. The rest of the output is the submission. The task instructions (instance_template, sent as the user message) tell the model to finish with echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT.
  5. [5] Your max_turns becomes three checks before every model call. The step cap compares step_limit with n_calls, and the time cap compares wall_time_limit_seconds with elapsed time. Both default to 0, which turns the check off. The cost cap is on by default: cost_limit is 3.0.
  6. [6] self.env runs each action in order (locally, in Docker, and so on). format_observation_messages turns each output into a history message.

Read it yourself: open environments/local.py and read _check_finished. Why must the return code be 0, and which part of the output becomes the submission? Then read parse_toolcall_actions in models/utils/actions_toolcall.py to see every way a reply becomes a FormatError.

02.7

Real code: pi's two loops, and how a user steers mid-turn

pi (earendil-works/pi) keeps a reusable loop in packages/agent. Your toy has one loop, and you cannot say anything until it returns. runLoop nests two, and the gap between laps is where a mid-stream correction gets in. pi uses "turn" for one lap (one reply plus its tool calls), not for the whole request.

// Check for steering messages at start (user may have typed while waiting)
let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];

// Outer loop: continues when queued follow-up messages arrive after agent would stop
while (true) { // [1]
  let hasMoreToolCalls = true;

  // Inner loop: process tool calls and steering messages
  while (hasMoreToolCalls || pendingMessages.length > 0) { // [2]
    // ... (26 lines: between laps, a hook may swap in a new context or model)
    // Process prepared and queued messages before the next assistant response.
    for (const message of declareToolChanges(currentContext, [...preparedMessages, ...pendingMessages])) {
      // ... (2 lines: announce the message to listeners)
      currentContext.messages.push(message); // [3]
      newMessages.push(message);
    }
    pendingMessages = [];
    // ... (23 lines: a hook may edit the request just before it is sent)
    // Stream assistant response
    const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFunction);
    newMessages.push(message);

    if (message.stopReason === "error" || message.stopReason === "aborted") { // [4]
      // ... (9 lines: close the turn and the run)
      return;
    }
    // ... (38 lines: run the tool calls, shown on the next slide, then close the lap)
    pendingMessages = (await config.getSteeringMessages?.()) || []; // [5]
    // ... (3 lines: if this lap will run again, drop a one-off continuation)
  }

  // Agent would stop here. Check for follow-up messages.
  const followUpMessages = (await config.getFollowUpMessages?.()) || []; // [6]
  if (followUpMessages.length > 0) {
    // ... (2 lines)
    pendingMessages = followUpMessages;
    continue;
  }
  // ... (8 lines: one more lap if a finishTurn hook asked to continue)
  // No more messages, exit
  break;
}

Source: earendil-works/pi, packages/agent/src/agent-loop.ts (MIT)

What to notice

  1. [1] The outer while (true) usually runs once. It repeats when follow-up messages are waiting (see [6]). It also runs one extra lap when a finishTurn hook returns continue and this lap did not already schedule tool results or steering.
  2. [2] The inner loop is your toy's loop. hasMoreToolCalls starts true, so the first lap always happens, and the tool code sets it again after each reply. The second condition keeps going when you have said something new.
  3. [3] Messages waiting for this lap, both steering and anything prepareNextTurn prepared, go into currentContext.messages and into newMessages. declareToolChanges tells the model about a tool-set change, either by inserting a system message or by filling toolsAdded and toolsRemoved on a system message that is already queued.
  4. [4] stopReason records why the model stopped writing. "error" (the reply failed) and "aborted" (the call was cancelled) end the run immediately, and no tool from that reply runs.
  5. [5] After the tool calls, the loop asks for steering messages. Agent.steer() in agent.ts fills that queue. Those tool calls still run, and your correction is appended before the next model call.
  6. [6] Follow-ups wait longer. Agent.followUp() queues messages that are delivered only when the inner loop is done, and continue restarts it.

Read it yourself: in packages/agent/src/agent.ts, read PendingMessageQueue. In the default "one-at-a-time" mode, each drain returns one message, and the loop drains once per lap after tools. Type three corrections during one slow tool call and expect them on three later model calls. All three are in the prompt starting with the third of those calls. Then give your toy a one-at-a-time steering list.

02.8

Real code: pi refuses to run a tool call that got cut off

Your toy runs any tool call it gets, as the last bullet above admits. These lines from the same pi loop replace your TOOLS[name](**args), and they hold back on one specific failure your toy cannot even represent: a reply that was cut off mid-call.

// Check for tool calls
const toolCalls = message.content.filter((c) => c.type === "toolCall"); // [1]

const toolResults: ToolResultMessage[] = [];
hasMoreToolCalls = false; // [2]
if (toolCalls.length > 0) {
  // A "length" stop means the output was cut off by the token limit, so
  // every tool call in the message may carry truncated arguments. Fail
  // them all instead of executing potentially borked calls.
  const executedToolBatch =
    message.stopReason === "length" // [3]
      ? await failToolCallsFromTruncatedMessage(toolCalls, emit)
      : await executeToolCalls(currentContext, message, config, signal, emit); // [4]
  toolResults.push(...executedToolBatch.messages);
  hasMoreToolCalls = !executedToolBatch.terminate; // [5]

  for (const result of toolResults) {
    currentContext.messages.push(result); // [6]
    newMessages.push(result);
  }
}

Source: earendil-works/pi, packages/agent/src/agent-loop.ts (MIT)

What to notice

  1. [1] A real reply is a list of content blocks (text, thinking, tool calls), and it can hold several tool calls at once. Your toy's response["type"] was one or the other.
  2. [2] No tool calls leaves hasMoreToolCalls false, which ends the inner loop unless steering is waiting. That is pi's "plain text means done".
  3. [3] "length" means the reply hit the output token limit (the most tokens the model may write in one reply). While a tool call streams as JSON, pi fills its arguments with parseStreamingJson, which uses the partial-json library and will return an object from incomplete JSON. When that block is marked finished, the parser runs parseToolCallArguments, which discards the partial object and stores {} if the JSON is not valid. If the reply is cut off before the block is finished, the salvaged object can remain. Suppose a 300-line file is cut off at line 180: the call can look like a normal argument holding half a file. That is why a "length" stop runs none of the calls. failToolCallsFromTruncatedMessage answers every call with an error that ends "Re-issue the tool call with complete arguments."
  4. [4] Otherwise executeToolCalls runs them: in parallel by default, one at a time if the config or any requested tool asks for sequential mode.
  5. [5] terminate is true only when every result in the batch asks the agent to stop, which a tool or a hook can request. Normally none do, so the loop goes round again to show the model its results.
  6. [6] Each result enters the history carrying the toolCallId of the call it answers: pi's version of the call_id link from "How it works".

Read it yourself: in the same file, read failToolCallsFromTruncatedMessage and shouldTerminateToolBatch. If the model sends three tool calls and only one result sets terminate, does the agent stop? Then give your fake_model a stop_reason field and make the toy answer each call with an error when it is "length".

02.9

Read the source yourself

Four stops, smallest first. Each is the loop you built, with one more real problem solved.

  1. mini-swe-agent, src/minisweagent/agents/default.py. Read the file straight through. Then open interactive.py next to it and find which method InteractiveAgent overrides to ask you before a command runs.
  2. pi, packages/agent/src/agent-loop.ts. Trace one prompt through runLoop on paper: write down hasMoreToolCalls and pendingMessages after every lap of a two-tool-call task.
  3. pi, packages/agent/src/agent.ts. Find where getSteeringMessages and getFollowUpMessages are wired to the two queues. Then read continue(): what happens to queued messages when the last message in the history is the assistant's?
  4. Codex, codex-rs/core/src/session/turn.rs. In try_run_sampling_request, list every line that sets needs_follow_up to true. Expect tool calls and a denied or directly answered tool request (both arrive through output_result.needs_follow_up), an unfinished end_turn, and a few stream interruptions.

Exercise for you: give your agent_loop two upgrades from this chapter. First, make finishing a tool: add a submit tool, and treat a plain-text reply as an error you append to history and send back (mini-swe-agent's rule). Second, when fake_model returns "stop_reason": "length", append an error result for each tool call instead of running it (pi's rule). Script fake_model to hit both cases once and check that the loop recovers.

02.10

Connecting to the bigger picture

Chapter 1 gave you the model-versus-harness split; this chapter shows the harness's central job, driving that loop. Everything from here is about making each piece of the loop better: Chapter 3 makes the "gather history and call the model" step rich and correct; Chapters 4 and 5 keep the growing history affordable; Chapter 6 makes the tools real and safe; Chapter 12 replaces max_turns with real budgets. The agent_loop function you just wrote is, almost unchanged, the spine of the capstone in Chapter 17.

02.11

Key takeaways

  • The agent loop is tiny: call the model, run any tool it asks for, append the result, repeat until the model returns plain text.
  • Anthropic's version is "gather context, take action, verify results." It is the same loop.
  • Each model call ends one of two ways: a tool request (keep looping) or an assistant message (stop).
  • Production loops add stop rules on top of that. mini-swe-agent treats plain text as a format error and stops only on an explicit submit, pi keeps going while you have messages queued, and Codex can take another lap when a hook or the API says the turn is unfinished.
  • For a software agent, the real output is the changes on your machine, not the final text. The text is just the "I'm done" signal.
  • A turn can contain dozens of inference-and-tool laps, and each turn re-sends the whole growing history, which sets up the cost problem in Chapter 4.

Original sources for this chapter: Anthropic's How Claude Code works and OpenAI's Unrolling the Codex agent loop by Michael Bolin.


0 of 11 slides completed

Your learning progress stays in this browser.

Self-check · 5 questions

01 / 05

In the agent loop, what are the two possible outcomes of each model call?

Related chapters