The Agent Loop

The Agent Loop is the fundamental execution pattern of Loop Engineering. It is the repeating cycle that an AI agent follows to accomplish a goal: reason about the current state, take an action, observe the result, verify it against criteria, and iterate until the goal is met.

Every major autonomous coding tool implements this pattern. Claude Code (github.com/anthropics/claude-code) runs it in your terminal. Aider (github.com/paul-gauthier/aider, 30K+ GitHub stars) runs it as a Git-first CLI cycle: edit a file, run tests, read the output, try again. SWE-Agent (github.com/princeton-nlp/SWE-Agent, 15K+ stars) from Princeton NLP wraps the same loop around an issue-solving workflow. The implementation surfaces differ, but the underlying cycle is the same.

The Core Loop

        ┌─────────────────────────────┐
        │          GOAL               │
        │   (testable success state)   │
        └──────────────┬──────────────┘
                       ▼
              ┌─────────────────┐
              │    REASON       │
              │  Analyze state, │
              │  decide action   │
              └────────┬────────┘
                       ▼
              ┌─────────────────┐
              │      ACT        │
              │  Execute tools, │
              │  modify state    │
              └────────┬────────┘
                       ▼
              ┌─────────────────┐
              │    OBSERVE      │
              │  Read feedback, │
              │  capture result  │
              └────────┬────────┘
                       ▼
              ┌─────────────────┐
              │    VERIFY       │
              │  Check against │
              │  success state  │
              └────────┬────────┘
                       ▼
              ┌────────────────┐
              │  Goal met?      │── Yes ──▶ Return Result
              └───────┬────────┘
                      │ No
                      ▼
              ┌─────────────────┐
              │   UPDATE STATE  │
              │  Feed results   │
              │  back in         │
              └────────┬────────┘
                       │
                       └──────▶ Back to REASON

This pattern descends from the ReAct framework (Reason + Act, Yao et al., 2022), which demonstrated that interleaving reasoning steps with action steps significantly improves model performance on complex tasks. Every modern agent loop is a descendant of ReAct -- with guards, verification, and state management added on top.

Why Verification Matters More Than Architecture

A common mistake in loop engineering is over-investing in the architecture of the loop while under-investing in verification. Control engineering teaches the same lesson: a perfect controller with a bad sensor produces chaos. A mediocre controller with a good sensor converges reliably. Translated to loop engineering:

The controller is the LLM -- it reasons about what to do
The sensor is the verifier -- it checks whether the action produced the desired result
A powerful model with weak verification will confidently pursue the wrong thing
A basic model with strong verification will converge on the correct result through iteration

Deterministic vs. LLM Verification

Verification Type	Examples	Strengths	Weaknesses
Deterministic	Test suites, type checkers, compilers, linters, API status codes	Fast, objective, cannot be gamed	Only works for mechanically checkable properties
LLM-as-Judge	Second model grades output against criteria	Flexible, handles subjective qualities	Can be gamed, can collude with actor

The strongest production loops use deterministic verification wherever possible and reserve LLM-as-judge for genuinely unquantifiable properties like writing tone or user experience quality.

The Loop in Real Tools

Claude Code (github.com/anthropics/claude-code, docs at code.claude.com/docs) implements the agent loop with several concrete primitives:

/loop -- Re-runs a prompt on a schedule (e.g., every 5 minutes for polling)
Sub-agents -- Defined in .claude/agents/, enabling a maker/checker split where one agent implements and another reviews
Worktrees -- isolation: worktree on a subagent gives each parallel agent its own Git checkout
Deterministic verification -- After each turn, Claude Code runs linters, type checkers, and test commands to validate the action

After each turn, a separate small model checks whether the goal is met -- so the agent that wrote the code is not the one grading it. This is the verification loop built directly into the tool.

Aider's Git-First Loop

Aider (github.com/paul-gauthier/aider) demonstrates the agent loop in its purest form. Every iteration follows this cycle:

REASON: model reads the current git diff and conversation context
ACT:    model edits a file
OBSERVE: aider runs `git diff` and optional commands (e.g., tests)
VERIFY: model reads the diff output and test results
ITERATE: if tests fail or the diff looks wrong, try again

You can run it with a single command:

aider --model claude-3.5-sonnet --verbose

Aider's key insight is that Git commits are the verifier. The model proposes a change, Aider commits it, and if something breaks, the diff tells you exactly what went wrong. The loop terminates when the tests pass and the model confirms the goal is met.

Codex CLI

OpenAI's Codex CLI (github.com/openai/codex) implements the same pattern with matching primitives:

/goal -- Keeps working across turns until a verifiable stopping condition holds
Sub-agents -- Defined as TOML files in .codex/agents/, each with its own model and reasoning effort
Worktrees -- Built-in worktree support for parallel threads

Cursor Agent Mode

Cursor's Agent mode runs the loop inside the editor: describe a goal, and the agent reads code, makes changes across files, runs tests, and fixes errors until the task is complete. The same goal-act-verify cycle; the surface is the IDE.

Windsurf Cascade

Windsurf (windsurf.ai) implements the loop through its Cascade agent, which manages multi-step execution with built-in verification at each step. Unlike simpler loops, Cascade tracks dependencies between steps and can verify intermediate results before proceeding.

The Loop in Pseudocode

Stripped to its essentials, an agent loop is a control loop -- closer to a thermostat or a REPL than to a chat:

state = init_state(goal)

for step in range(MAX_STEPS):
    thought = model.reason(state)
    action  = model.choose_action(state)
    result  = tools.execute(action)
    state   = update(state, thought, action, result)
    state   = compact(state)              # Keep context under budget

    if verifier.passes(state):             # Deterministic check
        return success(state)
    if no_progress(state) or budget.exhausted():
        return escalate_to_human(state)

return escalate_to_human(state)

Almost everything interesting in loop engineering is a decision about one of these lines: what counts as verifier.passes, how compact keeps the context window from overflowing, how no_progress is detected, and what tools the agent is allowed to call.

Token Cost and Context Management

Production Failure Modes

Failure Mode	Description	Guard
Exception handling breakdown	Agent encounters an error and continues with corrupted state	Catch all tool exceptions; reset state on unrecoverable errors
Blind retries	Agent repeats the exact same failing action indefinitely	Track action history; detect duplicates and escalate
Context overflow	Agent's context window fills up and quality degrades silently	Compact aggressively; isolate sub-tasks; externalize state
Infinite loops	Agent never satisfies its termination condition	Always set `MAX_STEPS`, token budget, and wall-clock timeout

Each of these is a failure of the verify or update state phases of the loop. The agent loop is only as robust as its termination conditions.

Layered Loops

Loops can be composed in layers, each adding a capability. Climb a layer only when the one below demonstrably isn't enough.

Level 1: The Agent Loop

The base pattern -- a model calling tools in a loop until a task is complete. This is what Claude Code, Aider, and Codex CLI all provide out of the box. Pick any model, plug in tools, and you have a working agent loop.

Impact: Automates work. An agent can read files, write code, call APIs, and make changes in the real world -- all within a single loop.

Level 2: The Verification Loop

Wraps a grader around the agent output. The agent runs, its output is scored against a rubric, and if it fails, the result goes back with feedback for another attempt. Claude Code implements this with its separate verification model -- the agent that wrote the code is not the one grading it.

Impact: Ensures work quality and correctness. The tradeoff is increased latency and cost per run -- worth it when quality matters more than speed.

Example: A documentation agent runs, and the grader checks that all links resolve, CI checks pass, and the diff is scoped to what was requested. No manual review needed to catch those classes of error.

Level 3: The Event-Driven Loop

Connects the agent to external systems. An event fires -- a new document lands, a schedule triggers, a webhook arrives -- and the agent runs. Claude Code's /loop command implements this: claude "/loop 5m /check-deploy" runs the check-deploy prompt every 5 minutes.

Impact: Automated work at scale. Supports cron schedules, webhooks, and message-channel triggers.

Human-in-the-Loop

Automation does not mean removing humans. At every level of the loop stack, there are natural points where human oversight adds value. A deterministic grader can check whether tests pass; it takes a human to notice the architecture is wrong for the use case.

The discipline is to keep a real check -- tests, types, or a human gate -- inside every cycle. A fast loop without genuine verification simply produces wrong answers faster. The three key touch points:

Agent loop -- Require human approval before sensitive actions (deletes, deployments, payments)
Verification loop -- Human acts as grader for sensitive workflows where automated checks are insufficient
Event-driven loop -- Human approves outputs before they are returned to end users

Best Practices Summary

Start simple. A single agent loop with a deterministic verifier beats an elaborate multi-layer system you cannot debug.
Always set limits. Define MAX_STEPS, a token budget, and a wall-clock timeout before starting any loop.
Verify deterministically. Use test suites, linters, type checkers, and exit codes as your verifier. Only fall back to LLM-as-judge when no mechanical check exists.
Separate maker from checker. The model that wrote the code should not be the one grading it.
Detect stuck states. Track action history, detect repeated failures, and escalate rather than retrying forever.

Next Steps

Learn about Task Loop for task management within loops
Explore State Persistence for making loops resilient
Study Auto-correction Loop for advanced self-correction patterns

Agent Loop