The Agent Loop: Steps, Turns, and Stopping

Reading time ~17 min · Last reviewed Sep 2026 · Quiz at the end

Lesson 2 listed the orchestration loop first among the seven subsystems of a harness, named its failure modes (infinite loops, premature termination, silent stalls after an unexpected tool result), and then moved on. Every lesson after it assumes the loop exists. This one opens it up. The loop is the smallest piece of a harness by line count and the one every other piece hangs off: context assembly runs before each model call, guardrails run before each tool call, compaction runs when the loop notices pressure, telemetry records what the loop did. If you don't have a precise picture of the loop, you can't say where any of those things belong.

OpenAI's Codex team opens its write-up of its own harness with the line "At the heart of every AI agent is something called 'the agent loop'" (OpenAI, 2026). That is right, and the loop itself is almost embarrassingly simple: call the model, run whatever tools it asked for, feed the results back, repeat until it stops asking. The engineering is in the edges. When does it stop? What counts as one unit of work? What happens when a tool throws, when the model asks for six tools at once, when it asks for the same tool eight times in a row? This lesson answers those questions with two real harnesses as reference points, DeepSeek Harness and Codex, and ends with an argument for keeping the loop as dumb as you can.

The smallest loop that works

Start with code. Here is a complete, provider-neutral agent loop. It is Python-shaped pseudocode (the model and tools objects stand in for whatever SDK you use), but every line corresponds to something a production harness does.

import json

def run_turn(model, tools, history, user_msg, max_steps=40, max_cost=2.00):
    """One turn: zero or more steps, ending when the model owes nothing."""
    history.append({"role": "user", "content": user_msg})
    spent = 0.0

    for step in range(max_steps):
        # 1. Call the model with the full history and the tool schemas.
        reply = model.generate(history, tools=tools.schemas())
        spent += reply.cost
        # Keep the reply verbatim: text, reasoning, and tool calls.
        history.append(reply.as_message())

        # 2. Parse tool calls. No calls means the model is done.
        if not reply.tool_calls:
            return {"status": "done", "text": reply.text, "steps": step + 1}

        # 3. Execute each call. 4. Append each result, in the order requested.
        for call in reply.tool_calls:
            history.append({"role": "tool", "tool_call_id": call.id,
                            "content": execute(tools, call)})

        # 5. Check the harness-owned stop conditions.
        if spent >= max_cost:
            return {"status": "budget_exhausted", "steps": step + 1}

    return {"status": "max_steps", "steps": max_steps}


def execute(tools, call):
    """Every failure becomes text the model can read, never an exception."""
    tool = tools.get(call.name)
    if tool is None:
        return f"Error: no tool named '{call.name}'. Available: {tools.names()}"
    try:
        args = json.loads(call.arguments)
    except json.JSONDecodeError as e:
        return f"Error: arguments were not valid JSON ({e}). Resend valid JSON."
    try:
        return str(tool.run(**args))
    except Exception as e:
        return f"Error: {type(e).__name__}: {e}"

Five things in these forty lines are easy to get wrong in practice.

The history is append-only. The loop never edits or reorders an earlier message; it only appends. Codex does the same, and its write-up points out that because each request's prompt is an exact prefix of the next, the provider's prompt cache can reuse the computation, which turns an otherwise quadratic loop into roughly linear sampling cost (OpenAI, 2026). Why that matters, and how to manage it once the window fills, is lesson 6's subject.

The reply is appended whole. reply.as_message() keeps the reasoning and the tool calls alongside the text. Dropping the reasoning to save tokens is one of the most expensive "optimizations" in this field, as we'll see below.

The natural stop is the absence of tool calls. The model says it is done by answering instead of acting. Codex describes it the same way: the loop repeats until the model stops emitting tool calls and produces an assistant message, and that message marks the end of the turn (OpenAI, 2026). The OpenAI Agents SDK spells out the same rule: output counts as final when it has the desired type and contains no tool calls (OpenAI Agents SDK docs).

The other stops are the harness's. The step cap and the budget cap don't depend on the model's judgment. They exist because the model's judgment is sometimes wrong, and each returns a different status so the caller can tell "finished" from "ran out".

Errors never escape execute. A missing tool, malformed arguments, or a crashing tool all come back as strings the model reads on its next step. This is a design decision, and the section on errors below explains why it is the right one.

Naming the units: steps, turns, threads

The first thing production harnesses do to the forty-line loop is give its pieces names, because you can't set a limit, write a log line, or attach a hook to a thing without a name. The cleanest published vocabulary is DeepSeek Harness's (dsh), whose architecture document defines the loop as an explicit state machine: a step is "one model request plus the tools it calls," and a turn is zero or more steps, opening when input is claimed and closing once the agent owes nothing more (DeepSeek Harness, architecture.md (2026)). Turns live inside a session, whose append-only event log is the source of truth for everything the model sees.

That "zero" is deliberate. In dsh, a hook that runs before the first step can reject the input entirely, and the turn closes having spent no model call. The loop records turn/start, step/start, step/end and turn/end as durable events, so every unit of work has a boundary you can find in the log (DeepSeek Harness, agent-lifecycle.md (2026)).

Codex arrives at a compatible vocabulary from the protocol side. Its loop write-up calls the journey from user input to agent response one turn of a conversation (a conversation is a thread in Codex), and a turn can include many iterations of inference and tool calls (OpenAI, 2026). The follow-up post on the Codex App Server, the JSON-RPC interface that every Codex surface drives the same harness through, formalizes three primitives (OpenAI, 2026):

• Item: the atomic unit of input or output, typed (user message, agent message, tool execution, approval request, diff), with a lifecycle of item/started, optional streaming deltas, and item/completed.
• Turn: one unit of agent work initiated by user input, containing a sequence of items, ending with turn/completed.
• Thread: the durable container for a session, holding many turns, which can be created, resumed, forked and archived.

Codex doesn't publish a named "step" at the protocol level; the model-call iterations inside a turn show up as the items they produce. dsh names the step because its hooks and limits operate at that granularity. The two designs agree on the important thing: the turn is bounded by user input on one side and by the agent owing nothing more on the other, and it is a separate object from the model call.

Stopping: five ways a turn ends

A loop that never stops is a bill. A loop that stops early is a wrong answer delivered confidently. Production harnesses recognize at least five distinct stop conditions, and the most useful thing you can do is make them distinguishable in the result.

1. The model says it's done. The natural stop: a reply with no tool calls. It is also the stop you trust least, because a model can declare victory before verifying anything.

2. Step cap. A hard limit on model calls per turn. The Claude Agent SDK returns a result with subtype error_max_turns when it hits the cap, distinct from success (Claude Agent SDK docs).

3. Budget. A cap on spend, tokens, or wall-clock time. Step counts are a poor proxy for cost, since one step with a giant tool result can cost more than twenty small ones. The same SDK offers max_budget_usd, returns error_max_budget_usd when it trips, and its docs recommend a budget as the default for production agents (Claude Agent SDK docs).

4. Goal met, or not yet. The model saying "done" is a claim; a check that the goal was met is evidence. dsh gives this its own hook: agent/turn-stopping fires when the turn is about to close because the model owes nothing, and a listener that disagrees can inject a message, which runs another step instead of closing the turn. The inverse also exists: a tool result can carry a concludesTurn flag that ends the turn at that step (DeepSeek Harness, core subsystem docs (2026)). LangChain's deep agents harness uses the same idea as middleware that catches the agent just before it exits and reminds it to verify its work against the task spec (LangChain, 2026). Loops whose whole purpose is to keep going until a goal is verified, across many turns and sometimes on a schedule, are lesson 15's territory.

5. Interrupt. A human presses stop, a parent agent cancels a child, a policy hook aborts, or the process shuts down. dsh types exactly those four causes (user, parent, hook, disposed) and records the cause in the durable turn/end event, so an aborted turn is never confused with a finished one (DeepSeek Harness, core subsystem docs (2026)). A softer form of interrupt is the approval pause: in Codex, the server can ask the client for approval before running an action, which pauses the turn until the user allows or denies it (OpenAI, 2026).

Doom loops: when the model keeps doing the same thing

The step cap stops a runaway loop eventually. Loop detection stops it early, while there is still budget to do something useful. The failure has a name in the practitioner literature: LangChain calls it the doom loop, where an agent makes "small variations to the same broken approach," ten or more times in some of the traces they studied (LangChain, 2026).

Two published detectors show the design space.

Exact repeats (dsh). dsh's repeat-tool-reminder plugin, part of a guard package family its README describes as loop hygiene, watches for the same tool called with identical arguments. With the default settings it reminds the model at 3, 5 and 8 consecutive repeats: first a short nudge to analyze the previous result, then detailed reminders naming the tool and arguments. A new user message resets the count. It is explicitly advisory: it "never blocks or delays a legitimate repeated call" (DeepSeek Harness, repeat-tool-reminder (2026)). Its README is honest about the limit: only exact repeats count, so near-identical variants slip through.

Progress signals (LangChain). LangChain's loop-detection middleware tracks per-file edit counts through tool-call hooks, and after N edits to the same file it adds context suggesting the agent reconsider its approach (LangChain, 2026). This catches exactly the case exact matching misses: ten different edits to the same file, none of them working.

The two share a pattern worth copying. Neither kills the loop. Both inject a message the model reads as ordinary context, which leaves the decision with the model and keeps the intervention visible in the transcript. The hard stop stays where it was, in the step and budget caps. A sensible production policy layers them: nudge at the first sign of repetition, nudge harder at the second, and let the budget cap end things if the nudges fail.

Executing tools: order, parallelism, and barriers

Modern models often ask for several tools in one reply: read three files, grep two patterns. The minimal loop runs them one at a time. That's correct and slow. Running them all concurrently is fast and sometimes wrong, because "write the config, then run the tests" has an ordering the model expressed by the order of its calls.

The Claude Agent SDK's answer is a read/write split: read-only tools such as Read, Glob and Grep can run concurrently, while state-modifying tools such as Edit, Write and Bash run sequentially. Custom tools default to sequential unless marked read-only (Claude Agent SDK docs).

dsh formalizes the same idea. Each pending call is classified by an executionMode of either parallel or exclusive; an exclusive call runs alone and forms an ordering barrier. Classification fails closed: only an explicit opt-in is parallel, and unknown, undeclared, or throwing classifiers are treated as exclusive. The loop then runs calls through exclusive barriers and a bounded rolling pool of parallel ones, and, crucially, commits results to the session log in model order even when they finish out of order (DeepSeek Harness, tools subsystem docs (2026); agent-lifecycle.md).

A simplified version of that scheduler (batches rather than a rolling pool) fits in a few lines:

def plan_batches(calls, mode_of):
    """Runs of parallel-safe calls share a batch; exclusive calls stand alone."""
    batches, run = [], []
    for call in calls:
        if mode_of(call) == "parallel":      # fail closed: default is exclusive
            run.append(call)
        else:
            if run:
                batches.append(run)
                run = []
            batches.append([call])           # barrier
    if run:
        batches.append(run)
    return batches

async def execute_all(tools, calls, mode_of):
    results = {}
    for batch in plan_batches(calls, mode_of):
        outs = await gather(*(execute_async(tools, c) for c in batch))
        results.update({c.id: out for c, out in zip(batch, outs)})
    # Commit in the order the model asked, not the order tools finished.
    return [(c.id, results[c.id]) for c in calls]

Why insist on model order when the results are all there anyway? Three reasons. Determinism: the same run produces the same transcript, so a replay or a fork reconstructs the same context. Caching: a history whose tail order depends on which tool happened to finish first is a history whose prefix differs between otherwise identical runs. And legibility: the model paired each call with an ID and a position, and a transcript that preserves both is one a human debugger can read top to bottom.

Errors are observations, not exceptions

In ordinary software, an unexpected condition throws, the stack unwinds, and someone handles it. In an agent loop, that instinct is usually wrong. The model is the component best placed to recover from most tool failures (a wrong path, a typo in an argument, a command that needs a flag), but only if it sees the failure. An exception that unwinds the loop takes that chance away.

So production harnesses convert failures into tool results. dsh's tool registry resolves tool and listener failures as materialized error results, and a call to a tool the agent can't see returns an UNKNOWN_TOOL error rather than crashing (DeepSeek Harness, tools subsystem docs (2026)). In the Claude Agent SDK, a permission denial comes back to the model as a rejection message in the tool result, and the model usually tries a different approach (Claude Agent SDK docs). The Manus team argued for leaving failed actions in the context for the same reason: when the model sees a failed action and its stack trace, "it implicitly updates its internal beliefs" (Manus, 2025).

Not every failure belongs in the transcript, though. The useful distinction is who can fix it:

Sources for the dsh rows: architecture.md, agent-lifecycle.md and the guard package README (2026).

The quality of the error message matters as much as its presence. "Error: 404" gives the model nothing. "No file at src/auth.py; did you mean src/auth/__init__.py?" gives it the next action. This is the loop-level version of lint errors that carry their own remediation (lesson 9), and it is one of the cheapest reliability wins in a harness.

Keep the reasoning between tool calls

Reasoning models produce thinking before they act. In a tool loop, that thinking explains why the model chose this tool with these arguments, and the next step needs it. A harness that appends the tool call and the result but drops the reasoning hands the model a transcript of actions with the motives removed.

Every major provider now documents this. Anthropic's thinking docs are blunt: within a tool-use turn, you must pass the thinking blocks back "complete and unmodified," because they carry the reasoning that led to the tool requests and let the model pick up that reasoning where it stopped (Anthropic, Claude API docs). Codex's loop appends the model's reasoning output items to the input of the next request alongside the function call (OpenAI, 2026). DeepSeek went further at the model level: V3.2 kept reasoning across tool-result rounds but discarded it when a new user message arrived, and V4 "preserves reasoning content across user message boundaries" when the conversation contains tool calls, aiming for a cumulative chain of thought over long-horizon agent work (Hugging Face, DeepSeek-V4 (2026)).

The cost of getting this wrong has been measured in public. Anthropic's April 2026 Claude Code postmortem describes a change meant to clear old thinking once when resuming an idle session; a bug made it clear thinking "on every turn for the rest of the session." Users saw Claude become forgetful and repetitive, with odd tool choices: it kept working, but increasingly without memory of why it had chosen what it was doing. The dropped blocks also caused cache misses, which made usage limits drain faster (Anthropic, 2026).

Hooks: where everything else attaches

The minimal loop has five numbered points. A production loop exposes those points as hooks, and that is how it stays generic while the harness around it grows. dsh is the clearest published example, because its loop package is itself a replaceable plugin and all behavior beyond the core cycle arrives through events (DeepSeek Harness, architecture.md (2026)). Its main extension points, and what attaches to each, are:

Sources: dsh architecture.md, dsh tool-execution-pipeline.md, Claude Agent SDK docs.

Look at the table from the other direction and it doubles as a map of this course. Guardrails live on the pre-tool hook. Compaction lives on pre-step and request-error. Loop detection lives on post-tool. Verification lives on turn-stopping. Telemetry observes all of them. When someone proposes a new harness feature, the first design question is "which hook?", and if the honest answer is "none, we need to change the loop," that's a signal to push back.

One rule applies to every hook that changes what the model sees: preserve the append-only history. Codex handles mid-conversation changes to sandbox settings or working directory by appending a new message rather than editing the earlier one, specifically to protect cache hits (OpenAI, 2026). dsh goes further: under a design rule it names model-visible means logged, a runtime invariant checks that every model request can be reconstructed from the session log (DeepSeek Harness, architecture.md (2026)). A hook that silently rewrites history breaks replay, forking, and caching at once. The deeper treatment of how that log becomes the model's context is in lesson 6, and the full dsh design is taken apart in lesson 23.

Keep the loop dumb

Everything in this lesson so far adds machinery. The last point subtracts it. Anthropic's write-up on harnesses for long-running application work puts it this way: "Every component in a harness encodes an assumption about what the model can't do," and those assumptions are worth stress-testing (Anthropic, 2026). The author describes dropping a whole sprint-decomposition layer when moving from Claude Opus 4.5 to 4.6, because the newer model no longer needed it.

Apply that lens to the loop. The repeat-call reminder assumes the model gets stuck and doesn't notice. The pre-completion check assumes it declares victory early. The step cap assumes it can't judge when to give up. Each of those is true of some models on some tasks today, and each will be less true next year. A loop with those behaviors hardcoded into its control flow has to be rewritten to remove them. A loop where they are hooks can drop one with a config change and an eval run. That's the practical argument for a small generic loop with everything else attached: not elegance, but the ability to delete things as models get better.

This is the same encapsulation argument lesson 2 made with Weng's operating-system analogy, applied to the scheduler at the center. It also sets up what comes later: lesson 15 wraps this loop in goal and schedule loops that span many turns, and lesson 16 runs several of them at once. Both are easier if the single loop underneath is boring.