T2 · Intermediate · 9 minMoving · Last reviewed: 2026-08-19Early draft

The Agent Loop

In one line · Every agent's heart is one loop: plan → act → observe → repeat — and without clear bounds, that loop burns your money.

Glossary:AgentTool CallingTrace
TL;DR

An agent runs in a cycle: the model plans a step, your code executes it with a tool, the result comes back for the model to observe, and it decides to continue or stop. The part people underestimate is 'when does it stop?' — stop conditions, iteration caps, and cost budgets are the difference between a production agent and a surprise bill.

Why it matters

Every loop iteration = a fresh model call carrying all the accumulated context — so cost grows with each turn, it doesn't stay flat. The classic rite of passage for every agent builder is 'the agent that kept looping overnight.' Understanding the loop and its bounds is the first real production skill in agents.

The loop is four repeating steps: (1) plan — the model decides the next step, (2) act — your code runs the requested tool, (3) observe — the tool's result goes back to the model, (4) repeat — it either continues or says 'done.' You write the loop; the model fills it with decisions.

An analogy

Like a taxi driver on the meter in a city they don't know: each time they check the map (plan), drive a street (act), see where they got (observe), and decide whether to continue or arrive. If you never said 'stop after an hour or 200 pounds' — they can keep circling with the meter running.

A research agent asked about the best charts library. Turn 1: it searches and finds 5 libraries. Turn 2: opens the docs of the top two. Turn 3: compares, discovers one is archived, drops it. Turn 4: decides it has enough and answers. Four turns, each a decision built on the last.

How it works

The code is a while loop: send the messages to the model → if it returns final text, exit → if it returns a tool request, execute it and append the result to the messages → back to the top. Every tool result is appended to the context, so the context balloons turn after turn — which is why late turns cost more than early ones.

For developers

The production bounds are four, and all live in your code, not the model: (1) max iterations — a hard cap on turns (start at 10–15), (2) a token/cost budget tracked during the run that cuts off when spent, (3) a wall-clock timeout, (4) an explicit give-up exit — if the model isn't progressing, stop and report how far it got instead of retrying forever. And log a trace of every turn so you can later see where the money went.

Practice

🧪 Try it: write a simple agent loop with one tool (a calculator or search), and from line one add: max 5 iterations + a token counter printed each turn. Then do something evil: make the tool always return an error, and watch what the model does — you'll see with your own eyes why the cap isn't a luxury.

Common mistakes

The fatal mistake: while(true) with no cap, trusting 'the model will know when to stop.' It won't always — a tool returns a vague error and the model retries the same way twenty times. Second mistake: an iteration cap without a cost budget — 10 turns with a huge context can cost more than 50 small ones.

When to use it

The full bounded loop is required in any real agent running without moment-to-moment supervision: research tasks, code fixing, automated processing. The bounds aren't a 'later optimization' — they're the first lines you write.

When NOT to use it

If your task completes in one or two known tool calls, don't build an open loop — a fixed sequence is simpler and cheaper. And the unbounded loop (no caps) should never be written, not even 'temporarily, just for testing.'

LET'S BUILD ITDone reading — now build it yourself.Challenge: the agent that never stops