Build Your Own Agent Loop

Start from brute force

The first version most people write is a for out in model_outputs loop that counts steps, indexes tools[out["name"]][out["arg"]] directly, and checks if steps == max_steps: break at the bottom of the body. It handles the happy path in O(n) time and O(n) space for n moves, and it passes every test where the model behaves. It fails in two exact places. A hallucinated tool name or argument raises KeyError: 'web' instead of being observed, so the loop dies on the most common model mistake. And because the cap is checked after a step runs, max_steps = 0 still consumes the final and returns "answered" with steps = 1.

The approach

The loop is a state machine with one cursor. The insight is that steps is both the counter and the index: the move for step n is model_outputs[n], so one integer tracks progress and enforces the budget. The reference starts pessimistic, with answer = None and status = "max_steps", so every exit that is not a final answer is already correct and needs no code of its own. The invariant: steps moves have been consumed, and observations holds one entry per tool move among them, in order.

The guard while steps < max_steps and steps < len(model_outputs) runs before any move is read, which is what makes a zero cap take zero steps. Inside, it reads out = model_outputs[steps], then increments steps, so the final counts as a step. A final sets answer and status = "answered" and breaks. A tool call unpacks name, arg and checks in order: name not in tools appends "unknown_tool", arg not in tools[name] appends "unknown_arg", and otherwise the looked-up result is appended. Checking the name first is what makes the second lookup safe.

Walk through an example

The first example’s tools, with two bad calls added before the answer and max_steps = 5: each pass reads model_outputs[steps], increments steps, and takes exactly one branch.

Complexity

Reference: O(s) time, where s is the number of moves consumed (at most min(max_steps, len(model_outputs))), because each pass does a constant number of dict lookups, and O(s) space for observations. Naive for loop: the same O(n) time and space for n moves. It is not slower, it is wrong: it crashes on a hallucinated name and overruns a zero cap.

Edge cases to test

• max_steps = 0 with a final waiting: the guard fails before anything is read, so the result is steps = 0, answer = None, status = "max_steps".
• model_outputs = []: the same result, zero steps and "max_steps". Running out of moves is neither an error nor an answer.
• The walkthrough’s four moves with max_steps = 3: three observations, steps = 3, answer = None, "max_steps". The cap wins even though the final was the very next move.
• A move after the final, e.g. a final "a" followed by a tool call: the loop breaks at the final, so steps = 1 and observations = [], and the trailing call never runs.
• A tool whose result is falsy, tools = {"s": {"a": ""}}: the observation is the empty string "", not "unknown_arg". Membership checks get this right; tools[name].get(arg) or "unknown_arg" does not.
• A tool named after an inherited object key, such as "toString": Python dict membership sees only real keys, but in JavaScript "toString" in tools is true for any plain object, so an in check reports "unknown_arg" instead of "unknown_tool". Object.hasOwn(tools, name) is the exact check.

Common mistakes

• Incrementing steps before reading model_outputs[steps]: the loop skips the first move and indexes one past the end, so a lone final raises IndexError.
• Checking arg in tools[name] before confirming name in tools — a KeyError on the hallucinated tool.
• Collapsing both lookups into tools.get(name, {}).get(arg, "unknown_arg"): a hallucinated tool name is then reported as "unknown_arg", and the model gets the wrong feedback.
• Treating “ran out of moves” and “hit the cap” as different statuses — both are "max_steps".
• Setting the answer on a final but forgetting to break: the loop keeps consuming moves, inflating steps and running tool calls after the agent said it was done.

Follow-ups an interviewer asks next

The tools are real functions with side effects. What changes?

The lookup becomes a call, tools[name](arg), wrapped so an exception becomes an observation such as "error: timeout" instead of killing the loop. Add a per-call timeout, and make side-effecting tools idempotent or guarded, because the model may repeat a call. The step cap still bounds the total.

The model is called live instead of reading a list.

Each step becomes out = model(history), where history is the conversation so far plus every observation, so the model sees what its tools returned. The loop shape is unchanged: one call per step, the same branches, the same cap. The new costs are latency and tokens, because the history grows every step; long runs summarize or trim it.

How do you cap cost instead of steps?

Track a budget beside steps, for example tokens or dollars spent, and add it to the guard: while steps < max_steps and spent < budget. Charge each model call and each tool call as it happens. Keep the step cap too, because a cheap model stuck repeating one call can spin for a long time under a dollar limit.

The model calls the same tool with the same argument over and over.

Detect the repeat: keep a set of (name, arg) pairs already executed, and on a repeat either return the cached observation or append a message such as "repeated_call" so the model is told it is stuck. Some agents stop after a few identical calls in a row rather than waiting for the step cap.

Where this shows up

This is the ReAct inner loop every coding agent, deep-research agent, and copilot runs: read the model’s move, execute a tool, feed the observation back, repeat until it answers or the budget trips. Distinguishing this inner loop (act/observe until done) from the outer verify/retry loop is the whole mental model of agent design — and the step cap is what stops a runaway from burning your budget.

Reference solution

def agent_loop(model_outputs, tools, max_steps):
    observations = []
    answer = None
    status = "max_steps"
    steps = 0
    while steps < max_steps and steps < len(model_outputs):
        out = model_outputs[steps]
        steps += 1
        if out["type"] == "final":
            answer = out["text"]
            status = "answered"
            break
        name, arg = out["name"], out["arg"]
        if name not in tools:
            observations.append("unknown_tool")
        elif arg not in tools[name]:
            observations.append("unknown_arg")
        else:
            observations.append(tools[name][arg])
    return {"answer": answer, "steps": steps, "observations": observations, "status": status}


T = {"search": {"cats": "felis catus"}, "calc": {"2+2": "4"}}
print(agent_loop([{"type": "tool", "name": "search", "arg": "cats"}, {"type": "final", "text": "felis catus"}], T, 5))
# -> {'answer': 'felis catus', 'steps': 2, 'observations': ['felis catus'], 'status': 'answered'}

type Move = { type: 'final'; text: string } | { type: 'tool'; name: string; arg: string };
type Tools = Record<string, Record<string, string>>;
type Result = { answer: string | null; steps: number; observations: string[]; status: 'answered' | 'max_steps' };

function agentLoop(modelOutputs: Move[], tools: Tools, maxSteps: number): Result {
  const observations: string[] = [];
  let answer: string | null = null;
  let status: 'answered' | 'max_steps' = 'max_steps';
  let steps = 0;
  while (steps < maxSteps && steps < modelOutputs.length) {
    const out = modelOutputs[steps];
    steps++;
    if (out.type === 'final') {
      answer = out.text;
      status = 'answered';
      break;
    }
    if (!(out.name in tools)) observations.push('unknown_tool');
    else if (!(out.arg in tools[out.name])) observations.push('unknown_arg');
    else observations.push(tools[out.name][out.arg]);
  }
  return { answer, steps, observations, status };
}

const T: Tools = { search: { cats: 'felis catus' }, calc: { '2+2': '4' } };
console.log(agentLoop([{ type: 'tool', name: 'search', arg: 'cats' }, { type: 'final', text: 'felis catus' }], T, 5));
// -> { answer: 'felis catus', steps: 2, observations: ['felis catus'], status: 'answered' }