What is the outer loop of an agent?

The outer loop wraps entire agent runs in a bigger cycle: a trigger fires, the loop frames a task from external state, the agent runs its whole inner plan-act-observe loop as one step, something independent verifies the result, state is recorded, and the loop repeats until a stopping condition is met. Designing that cycle — not prompting each step — is loop engineering.

Why does an agent loop need a hard iteration cap?

Because a goal loop's natural state is 'keep going'. If the goal turns out to be unachievable — one file the agent simply cannot fix — an uncapped loop will retry it forever, burning budget while making zero progress. A max-iterations cap plus a budget ceiling turns an invoice surprise into a loud, cheap stop.

What happens if the agent verifies its own work?

It ships plausible mistakes. Models are systematically overconfident about their own completions, so a self-reporting loop finishes fast and green — and some of the work is quietly broken. The fix is the verification split: a verifier that is not the implementer (a test suite or a fresh reviewer agent) decides what counts as done.

What is state amnesia in an agent loop?

A loop without external memory starts every run from scratch: it re-does work it already finished, picks targets at random, and its iteration count stops correlating with progress. A checkpoint the loop reads before framing the task and writes only after verification is what turns isolated runs into forward progress.

Can a well-guarded loop still fail to finish?

Yes — and that's by design. A well-guarded loop that hits its cap with work remaining stops loudly and escalates the leftovers to a human inbox. Ending with 7 of 8 items verified-done and one honest escalation is a success; a loop that never ends, or ends by lying, is the failure.

Lab · Loop Engineering

The Loop Designer.

Don't read about loop engineering — break a loop, then fix it. An agent must migrate 8 files overnight, unattended. You design its outer loop: toggle the hard cap, the independent verifier, and the external memory, hit Run, and watch what actually happens to your budget and your codebase.

hard cap · verification split · external memory · stopping conditions

HARD CAP

Max iterations + budget ceiling. The bluntest guard — the only thing standing between a stuck loop and your invoice.

VERIFIER

Who decides "done"? The agent's own claim, or something independent — tests, a reviewer with fresh context.

MEMORY

A checkpoint outside the model recording done/next. Without it every run starts from amnesia.

STOP

Loops must end loudly — goal verified, or cap hit and leftovers escalated to a human. Never silently.

loop-designer.sim — goal: "migrate all 8 files to the new session API"

The repo — 8 files to migrate

BUDGET BURNED$0.00

Iterations

0/8

Verified done

Bugs shipped

Design your loop, then run it

Hard cap — stop after 15 iterationsGuard 1 · max_iterations + budget ceiling

Independent verifier — tests decideGuard 2 · off = the agent grades its own work

External memory — checkpoint fileGuard 3 · off = every run starts from amnesia

The four runs every loop engineer should feel once

The simulator above is honest about one thing most tutorials skip: the agent is good but not perfect — it succeeds about 70% of the time, and one file (legacy_parser.py) is beyond it entirely. Every classic loop failure comes from how the outer loop handles those two facts. Run all four scenarios:

🔥 The $500 Hour — no cap

Memory and verifier on, cap off. The loop grinds through 7 files beautifully… then hits the impossible one and retries it forever. Nothing is wrong with any single iteration — that's what makes runaways expensive. The cap isn't pessimism; it's the price of unattended.

🔁 Groundhog Day — no memory

Cap and verifier on, memory off. With no checkpoint, each iteration picks a target blindly — re-migrating finished files while real work waits. The cap trips with most of the queue untouched. Busy is not the same as progressing.

🚢 Plausible Mistakes — no verifier

Cap and memory on, verifier off. The agent grades its own homework, so failures get reported as wins. It finishes fast, green across the board — and the reveal shows what actually shipped. A loop without a verifier is a machine for shipping plausible mistakes at scale.

✅ The Well-Guarded Loop — all three

Cap, verifier, and memory on. Failures become retries, retries become verified progress, and the impossible file gets escalated loudly when the cap trips. 7 of 8 verified-done plus one honest escalation is what success looks like — a loop that ends loudly, never silently.

Now flip the guards yourself and re-run. The lesson worth internalizing: the same agent produced all four outcomes. Only the loop around it changed.

Check yourself

1 · The loop keeps failing on the same file with no cap set. Each iteration looks reasonable. What actually stops it?

A goal loop's natural state is "keep going". Every guard that stops a runaway is machinery you add — max_iterations, a wall-clock limit, a budget cap that alerts when it trips.

2 · With the verifier off, the loop finished fastest and everything showed green. Why is that the worst outcome of the three failures?

Runaways cost money and amnesia costs time — both are loud. Self-verified success is silent: the loop reports victory while shipping defects. That's why the verifier must not be the implementer.

3 · The well-guarded loop ended with 7/8 done and one file escalated to a human. Is that a failure?

Loops don't replace judgement; they conserve it. The human inbox for leftovers is a design feature — the alternative is either a runaway or a lie.

Questions

Is the 70% success rate realistic?

Directionally, yes. Real agents succeed at different rates per task type, but no agent is at 100% on nontrivial work — which is the whole point. Loop design is about what happens on the 30%, because unattended, the failures compound.

What maps to what in a real setup?

The hard cap is max_iterations plus a token/dollar budget. The independent verifier is your test suite, linter, or a reviewer subagent with fresh context. The checkpoint is a state file, markdown board, or issue tracker the loop reads before framing each task and writes after verification.

Where does the inner loop fit?

Each single iteration here — "agent attempts auth/token.py" — is an entire inner plan→act→observe run compressed into one box. This lab is about everything around that box. To drive the inner loop itself, run the Agent Loop Simulator.

You just did loop engineering.

Same agent, four outcomes — the guards were the difference. Now go design real ones.

The Loop Engineering Handbook → Lab: The Inner Loop → Cheatsheet: Loop Engineering → Flashcards: Loop Engineering →

Finished this one? 0 / 61 Labs done

Explore the topic

See this alongside everything else on the same subject — handbooks, system designs, challenges and tools, in one place.

AI Agents & Tools