The Core Agent Loop

An on-call bot receives this at 02:14:

user: Which service caused the checkout incident, and what changed in deploy 4471?

Its first version sends one prompt and hopes the model already knows. Its second version is more ambitious: while not done: calling tools as fast as the model proposes them. By 02:16 it has called search_deploy eleven times with identical arguments, the transcript is 90k tokens, and no answer has arrived. Both versions miss the same thing: a cycle with fixed phases and a hard bound on how many times it may run.

The cycle

goal + user request
      │
      ▼
┌───────────────┐
│  THINK        │  reason: what is known, what is missing
└──────┬────────┘
       ▼
┌───────────────┐
│  ACT          │  commit to exactly one action
└──────┬────────┘
       ▼
┌───────────────┐
│  OBSERVE      │  run it, append the result to the scratchpad
└──────┬────────┘
       ▼
goal met? ── no ──► THINK again (step cap not reached)
       │
      yes / cap hit
       ▼
answer, or bounded failure

Each phase answers a question the others cannot. Think is where the model decides what to do next. Act is where the world gets touched — one tool call, not a wish list. Observe is where reality is written down. Skipping observe is exactly what produced those eleven identical calls: the model never saw its own previous result, so as far as it knew, nothing had happened yet.

The scratchpad — the list of thought, action, observation triples re-sent every iteration — is the loop's only memory. Without it, each turn starts amnesiac. With it, step 6 can cite the file step 2 read, which is the property that makes multi-tool tasks solvable at all, and the property Evaluating Memory Quality exists to measure in a shipped product.

The bound matters as much as the cycle. while not done: has no answer for a confused model, and confusion is the common case here rather than the exception. A step cap plus a goal check means the loop ends either way: with a result, or with a failure a human can inspect.

The engine is a for loop with an explicit done signal. Each iteration hands the full scratchpad back to the model:

import json

MAX_STEPS = 6

def run_agent(goal, ask, act, emit):
    scratchpad = []                    # every (thought, action, observation) triple
    for step in range(MAX_STEPS):      # the cap is structural, not a runtime hope
        thought = ask(goal, scratchpad)
        action = thought.get("action")  # {"tool": ..., "args": ...} or None

        if action is None:             # the model called done(answer) explicitly
            return {"status": "done", "answer": thought["answer"],
                    "steps": step, "trace": scratchpad}

        observation = act(action["tool"], action["args"])
        scratchpad.append({"step": step, "action": action,
                           "observation": observation})
        emit("agent.step", {"step": step, "tool": action["tool"],
                             "result_bytes": len(json.dumps(observation))})

    return {"status": "step_cap", "steps": MAX_STEPS, "trace": scratchpad}

Run against the 02:14 request:

goal: Which service caused the checkout incident, and what changed in deploy 4471?

step 0  search_deploy(incident="checkout")  → {"service": "payments-api", "deploy": 4471}
step 1  get_diff(deploy=4471)               → {"files": 12, "summary": "retry budget 5s → 1s"}
step 2  action=None                         → answer ready

status=done steps=3

Four lines carry the design:

1. ask(goal, scratchpad) — the model sees every prior observation, so step 1 acts on what step 0 found. The cost is real: each round re-sends the transcript, so scratchpad size is the loop's main cost lever.
2. action is None — completion is a signal the model emits, not a guess about its prose. Inferring done from fluent text ends runs early with confident wrong answers.
3. observation = act(...) — state stores the tool's return value, never the model's paraphrase of it. Paraphrase is where facts drift.
4. for step in range(MAX_STEPS) — a bug in the done check cannot unbound the run the way a while loop would.

When the cap hits, the function returns a structured failure carrying the trace instead of the last thing the model said. The guards themselves — iteration cap, goal check, token budget — are the subject of Stopping Conditions and Budgets.

Two structural choices decide whether this loop is debuggable a week later.

States as data, not recursion. Write the transitions as named values and assert the legal ones:

THINK ──act──► ACT ──observe──► OBSERVE ──not done──► THINK
  ▲                                                         │
  └────────────────────── done ─────────────────────────────┘

Recursive run() calls hide the transition history inside the call stack, so OBSERVE → ACT — acting twice without looking — is invisible. With an explicit state variable that sequence fails an assertion at the exact line it happened. Keep the scratchpad attached to OBSERVE, because a state you can name is a state you can log, and a state you can log is a state you can compare between a passing run and a failing one.

Failure modes, in the order they show up in real runs:

• Runaway loop. while not done: with no cap: a confused model re-issues calls until the token budget drains. The cap must be structural — see Stopping Conditions and Budgets.
• Echo step. The model repeats its previous action because its observation never reached the prompt. The scratchpad was built but not re-sent, which looks from the model's side exactly like nothing happened.
• Silent finish. The model returns prose with no done signal and no goal check. The loop either keeps working on a finished task or accepts a fluent answer the goal check would have rejected.
• Blind run. No trace events. The run failed at 02:14 and nothing can explain why. Emit one structured event per iteration — step index, action, arguments, observation size, latency — into the same pipeline you use for Tracing LLM Calls, and the run replays offline step by step with the exact inputs.

This gives you a bounded machine that can touch the world. What it does first, in what order, and whether it reorganizes after a surprise is Planning Strategies for Agents, the topic that follows this one.