Chapter 02 · 13 min read · Updated
The Agent Loop
Every coding agent runs one small loop: gather history, call the model with its tools, then act on a tool call or stop on plain text.
Prefer one idea per screen? Read it as 11 slides →
In this chapter11
- 02.1Concept explanation
- 02.2Why it matters
- 02.3How it works: a closer walk
- 02.4Real code: the loop inside Codex's turn.rs
- 02.5Code MVP: a working agent loop
- 02.6Real code: mini-swe-agent, the toy loop finished
- 02.7Real code: pi's two loops, and how a user steers mid-turn
- 02.8Real code: pi refuses to run a tool call that got cut off
- 02.9Read the source yourself
- 02.10Connecting to the bigger picture
- 02.11Key takeaways
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:
- 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. - 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.
- You type: "Add an architecture diagram to the README."
- The harness builds a prompt (Chapter 3 covers exactly what goes in it) and calls the model.
- The model thinks, then asks for a tool call:
shellwith commandcat README.md. It does not run anything; it asks. - 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 sharedcall_idso the model knows which result belongs to which call. - The harness calls the model again, now with the README contents included.
- The model asks for another tool call: an edit that inserts the diagram.
- The harness applies the edit, appends the result, calls again.
- 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] No counter. A lap takes queued messages only when
can_drain_pending_inputis true. Your opening request sets that flag false (inputis not empty), so it is sampled first. - [2]
clone_history()copies the conversation. AResponseItemis 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_promptshapes the copy for this model: it pairs calls with outputs, and it strips images or audio when that input is off. - [3]
run_sampling_requestsends the list and handles the reply. If the stream fails, this function can retry before returning the error. - [4] Go round again if the model asked for more work, or if you typed something during the lap.
- [5] Otherwise
breakreturns control to you. A stop hook in the elided lines can add a prompt and force one more lap. - [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_flightinturn.rswaits for those futures and records each successful output. A future that fails is logged and not written into the history. - [7] A message or reasoning item does not by itself set
needs_follow_up. Assistant text is stored inlast_agent_messageonly 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 setsneeds_follow_up. A completed response withend_turnfalse 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:
historygrows every lap. That growth is the quadratic problem (Chapter 4).max_turnsis a crude kill switch. Real harnesses make this a proper budget (Chapter 12).TOOLSis 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]
while Truewith no counter. Each lap is onestep(), which is your loop body:query()asks the model,execute_actions()runs what it asked for. - [2] In your toy, a plain-text reply meant "done". Here it is a mistake. The tool-call parser raises
FormatErrorwhen a reply has no tool call, names a tool other thanbash, or has arguments with nocommand. 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 defaultmax_consecutive_format_errors). - [3]
InterruptAgentFlowis 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.finallyalways callssave. That writes every message so far to disk only whenoutput_pathis set. It defaults toNone. A crash still appends an exit message and then re-raises, so a run that was given a path keeps the file. - [4] The loop returns only when the last message has role
"exit". A crash re-raises instead, sorundoes not return. The normal exit is not written by the environment._check_finishedraisesSubmittedwhen the return code is 0 and, after leading whitespace is stripped, the first line isCOMPLETE_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 withecho COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT. - [5] Your
max_turnsbecomes three checks before every model call. The step cap comparesstep_limitwithn_calls, and the time cap compareswall_time_limit_secondswith elapsed time. Both default to0, which turns the check off. The cost cap is on by default:cost_limitis3.0. - [6]
self.envruns each action in order (locally, in Docker, and so on).format_observation_messagesturns 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] The outer
while (true)usually runs once. It repeats when follow-up messages are waiting (see [6]). It also runs one extra lap when afinishTurnhook returnscontinueand this lap did not already schedule tool results or steering. - [2] The inner loop is your toy's loop.
hasMoreToolCallsstarts 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] Messages waiting for this lap, both steering and anything
prepareNextTurnprepared, go intocurrentContext.messagesand intonewMessages.declareToolChangestells the model about a tool-set change, either by inserting a system message or by fillingtoolsAddedandtoolsRemovedon a system message that is already queued. - [4]
stopReasonrecords 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] After the tool calls, the loop asks for steering messages.
Agent.steer()inagent.tsfills that queue. Those tool calls still run, and your correction is appended before the next model call. - [6] Follow-ups wait longer.
Agent.followUp()queues messages that are delivered only when the inner loop is done, andcontinuerestarts 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] 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] No tool calls leaves
hasMoreToolCallsfalse, which ends the inner loop unless steering is waiting. That is pi's "plain text means done". - [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 withparseStreamingJson, which uses thepartial-jsonlibrary and will return an object from incomplete JSON. When that block is marked finished, the parser runsparseToolCallArguments, 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.failToolCallsFromTruncatedMessageanswers every call with an error that ends "Re-issue the tool call with complete arguments." - [4] Otherwise
executeToolCallsruns them: in parallel by default, one at a time if the config or any requested tool asks for sequential mode. - [5]
terminateis 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] Each result enters the history carrying the
toolCallIdof the call it answers: pi's version of thecall_idlink 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.
- mini-swe-agent,
src/minisweagent/agents/default.py. Read the file straight through. Then openinteractive.pynext to it and find which methodInteractiveAgentoverrides to ask you before a command runs. - pi,
packages/agent/src/agent-loop.ts. Trace one prompt throughrunLoopon paper: write downhasMoreToolCallsandpendingMessagesafter every lap of a two-tool-call task. - pi,
packages/agent/src/agent.ts. Find wheregetSteeringMessagesandgetFollowUpMessagesare wired to the two queues. Then readcontinue(): what happens to queued messages when the last message in the history is the assistant's? - Codex,
codex-rs/core/src/session/turn.rs. Intry_run_sampling_request, list every line that setsneeds_follow_upto true. Expect tool calls and a denied or directly answered tool request (both arrive throughoutput_result.needs_follow_up), an unfinishedend_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?