Agent Loop Engineering
The definitive exhaustive technical report on designing, building, and operating autonomous agent loops — algorithms, primitives, prompting techniques, stop conditions, cost controls, and failure modes defining production agentic systems in 2026.
What Is Loop Engineering?
Loop engineering is the discipline of designing automated loops that schedule, coordinate, and verify work — replacing manual turn-by-turn prompting of AI agents with autonomous systems that discover tasks, hand them off to agents, verify results, persist state, and repeat until a termination condition is met. The field crystallized in June 2026 when Addy Osmani and Boris Cherny demonstrated that five building blocks — Discover, Handoff, Build, Verify, Persist — plus Schedule and Memory form a minimal complete loop that works consistently across Claude Code, OpenAI Codex, and custom runtimes.
A prompt is a single, stateless request to a model. A harness is the runtime environment around an agent — tools, memory, permissions, prompts, and the loop logic itself. Loop engineering is harness engineering focused on the orchestration layer: making agents iterate productively without human micro-steering. You stop prompting the agent — you build the system that prompts it instead.
The Five Primitives + Memory
Every agent loop, regardless of framework or model, is composed of these five functional primitives plus the memory layer that connects iterations into a coherent, stateful system.
The sensor layer. Reads the environment — file system changes, git diffs, error logs, ticket queues, webhook payloads — and transforms raw signals into task descriptions the loop can act on.
- File system watchers (fs events, git diffs)
- LLM-based change classification ("what changed?")
- Error log aggregation and deduplication
- Ticket/issue queue polling
- Human task submission
- Scheduled time-based triggers
Context too thin → agent guesswork. Context too heavy → agent optimizes for the crowd. Sweet spot: task-specific context windows with minimal but complete scope.
- Context bundling (task + relevant files + history)
- Agent routing by capability/specialty
- Priority triage and queue management
- Rate limiting per agent
- Retry budgets per handoff target
The agent's core work loop. Receives a task, selects and calls tools, observes results, reasons about next steps, and iterates until done or stopped. Claude Code and OpenAI Codex are both ReAct-based at their core.
- ReAct: Think → Act → Observe → Think...
- Tool use with structured output schemas
- Inner monologue / scratchpad reasoning
- Step-level token counting and cost tracking
- Subagent spawning for parallel work streams
The quality gate that separates a loop from a hamster wheel. Without a separate evaluator checking whether the goal condition is met, the loop has no signal to stop.
- Automated: build, test, lint, type-check
- LLM judge: rubric-scored output evaluation
- Diff-based verification (only expected files changed)
- Human approval for sensitive operations
- Cross-agent validation
Write stop conditions before the loop runs. "Good enough" is not verifiable. "Contains X data points, under Y words, no hallucinated facts" is.
What makes loops stateful rather than stateless. Each iteration must read what previous iterations did, update shared state, and hand that state to the next turn.
- State files (JSON/YAML on disk)
- Database-backed task history
- Vector DB for semantic memory retrieval
- AGENTS.md / CLAUDE.md project conventions
- Checkpoint snapshots for crash recovery
- Memory summarization to prevent context overflow
Determines when the loop activates. Dominant 2026 pattern for coding workflows: continuous with human-in-the-loop pauses at verification gates.
- Cron triggers for periodic work
- Event-driven (git hooks, CI, webhooks)
- Continuous daemon mode with sleep/wake cycles
- One-shot (run once, produce output, exit)
- Queue-based (async task processing)
The Core Agent Loop
The 6-stage cognitive loop that powers every modern agentic system, from simple ReAct implementations to complex multi-agent hierarchies.
Agent Loop Algorithms & Techniques
From foundational patterns to advanced reasoning topologies — the algorithmic toolkit for building reliable agentic systems.
ReAct
Reason + Act interleaved. Each turn: observe → think → act → repeat. From Yao et al. (2022). The backbone of every major coding agent in 2026.
# ReAct loop pseudocode while not stopped: obs = observe(env) thought = model.think(obs, memory) action = model.act(thought, tools) env = env.apply(action) memory.append(obs, thought, action)
- Best for: single-task, well-defined goals
- Strength: simple, predictable, debuggable
- Weakness: no branching, no backtracking
Reflexion
Verbal reinforcement learning via self-reflection. Agent generates a trajectory, critiques its own performance with a score, and uses critique as context for retry. From Shinn et al. (2023).
# Reflexion — reflect then retry trajectory = agent.run(task) reflection = model.critique(trajectory, feedback) if reflection.score < threshold: memory.write(reflection) trajectory = agent.run(task) # retry
- Best for: tasks with clear success/failure signals
- Strength: eliminates systematic errors on retry
- Weakness: needs a ground-truth feedback signal
Self-Refine
Single model alternating between generating output and critique. Output → Critique → Refined Output → Critique... until the critique stabilizes. From Madaan et al. (2023/2024). Most widely adopted in 2025-2026.
# Self-Refine loop output = model.generate(task) for i in range(max_iters): critique = model.critique(output) if critique.is_minor(): break output = model.refine(output, critique)
- Best for: code generation, writing, design tasks
- Strength: single model, no ground truth needed
- Weakness: can oscillate without convergence signal
Tree of Thoughts (ToT)
Branching reasoning that explores multiple parallel solution paths. Generates N candidate thoughts at each step, evaluates each branch, prunes dead ends, continues the most promising paths. Enables backtracking.
# ToT — branch, evaluate, prune thoughts = [model.think(task)] while not all(terminal(t) for t in thoughts): candidates = [] for t in thoughts: children = model.expand(t, k=3) for c in children: c.score = model.evaluate(c) candidates.extend(children) thoughts = top_k(candidates, k=best_k)
- Best for: combinatorial problems, strategic planning
- Strength: systematic exploration, backtracking
- Weakness: exponential token cost with depth
Graph of Thoughts (GoT)
Generalizes ToT to arbitrary graphs — thoughts can merge (synthesize from multiple parents), split (branch without merging back), or loop (feedback). ETH Zürich (Besta et al., 2023). Operations: Generate, Select, Aggregate, Integrate.
- Best for: complex multi-constraint optimization
- Strength: most flexible reasoning topology
- Weakness: harder to implement and debug
ReAcTree
Hierarchical LLM agent trees with explicit control flow. Recursively decomposes tasks into subtasks, executes leaf actions, propagates results up the tree. Outperforms ReAct on long-horizon benchmarks (WAH-NL, ALFRED). Nov 2025.
- Best for: long-horizon household / robotics tasks
- Strength: hierarchical decomposition scales linearly
- Weakness: control flow overhead for simple tasks
Prompting Techniques for Agent Loops
Include "think step by step" to trigger explicit reasoning traces. Embed as structured JSON/markdown so the verifier can read it.
- Works best with ≥70B models
- Add "put reasoning in <reasoning> tags"
Append "Let's think step by step" to any prompt. Minimal overhead, meaningful accuracy gains on multi-step reasoning.
- Minimal token cost
- Can combine with structured output
Provide 3-5 exemplars of (task → reasoning → answer). Model infers the pattern and applies it to new inputs.
- Examples must be diverse, not templated
- Labeled examples better than unlabeled
JSON-schema tool definitions constrain the model's response shape. Critical for tool-calling loops where the runtime needs parseable actions.
- MCP tool definitions are schema-constrained
- Use markdown code fences for multi-line
Set the agent's role, what it must/must not do, tools available, and exact output format per situation. The harness encodes the safety and quality policy.
- Context is a scarce resource — prioritize signal
- Giant instruction files crowd out the task
Agent writes intermediate reasoning to a private scratchpad before producing a final output. Stripped from final response but kept in context for subsequent turns.
- Cursor, Claude Code use this pattern
- Can be surfaced to the verifier
Assign a persona ("You are a senior security engineer") with domain-specific context. For multi-agent loops, each agent gets a role-specific prompt encoding expertise boundaries.
- Works with supervisor/worker patterns
- Can conflict with the task — test carefully
Explicit negative constraints ("do not modify the auth module") are more reliable than positive constraints alone. Encode safety boundaries as hard constraints the verifier can check.
- "Only modify files listed in this ticket"
- "Never call this tool without human approval"
Assemble prompts from reusable modules: base-role, tool-descriptions, output-format, constraint-list, verification-criteria. Harness composes modules per task type.
- Reuse across task types
- Enables prompt version control
Stop Conditions & Verification
Stop conditions are where loops live or die. Fuzzy success criteria is the #1 cause of runaway token burn in production systems.
"The task is done when it looks good" is not a stop condition. "The task is done when tests pass, the linter is clean, and the diff touches only the files listed in this ticket" is. A fuzzy success criteria means the agent loops forever, burning tokens until the API rate limit, token budget, or monthly bill stops it.
Stop Condition Types Ranked by Reliability
| Type | Reliability | Example |
|---|---|---|
| Hard Count | Highest | Max 20 tool calls per task |
| Hard Budget | Highest | Token budget exhausted → stop |
| Automated Pass | High | Build succeeds, tests pass |
| Diff Check | High | Output matches expected schema |
| LLM Judge | Medium | Second model scores ≥ 8/10 |
| Human Gate | Contextual | Deploy requires human approval |
| Fuzzy | Unreliable | "Looks good" — avoid |
Count-based conditions are most reliable because they're entirely mechanical. Hybrid production pattern: stop if max_iters OR (output_verified AND no_hallucinations)
Memory & State Management
Persistence is what separates a loop from a series of unrelated API calls. Without state management, every iteration starts from scratch.
The model's context window is the primary short-term memory. Strategies: selective context windowing, conversation summarization at turn N, pruning low-value messages.
- LLM summarization of old conversation turns
- Importance-weighted message retention
- Sliding window: keep last K turns
- Context compression at 70% capacity
Survives session boundaries. Mem0's 2026 algorithm uses single-pass hierarchical extraction — converts interaction history into structured facts. Yu et al. (2026) trains memory operations as callable RL tools.
- File system: AGENTS.md, CLAUDE.md conventions
- Vector DB: semantic similarity search
- Structured DB: task history, outcomes
- Agentic Memory: RL-trained store/retrieve/summarize
In 2025-2026, AGENTS.md (Claude Code) and CLAUDE.md / .cursorrules are converging toward a cross-tool standard. These files encode: project conventions, allowed/disallowed actions, tool preferences, verification criteria, and task-specific instructions. Drop one into any repo and the agent reads it on startup.
Store embeddings in a vector DB. Retrieve top-K semantically relevant items per new task. Mem0's 2026 algorithm: single-pass hierarchical extraction — faster and more token-efficient than naive chunk retrieval.
JSON/YAML on disk: task queue, iteration counter, current goal, completion status. Written by the loop, read by the loop. Simple, auditable, works without a database. Checkpoint each iteration for crash recovery.
Strategies: (1) summarize old turns into a single gist, (2) drop irrelevant tool call transcripts, (3) move completed task history to persistent storage, (4) enforce a max-context budget per task type.
Multi-Agent Orchestration Patterns
How agents coordinate, delegate, and collaborate. The pattern shapes the loop's scalability, reliability, and cost profile.
Multiple agents participate in a shared conversation thread. A chat manager coordinates flow, determining which agents respond and in what order. Agents assigned roles: researcher, critic, synthesizer, executor.
- Useful for: brainstorming, code review, quality gates
- Risk: combinatorial explosion of messages
- Mitigation: max-turns per agent, relevance filtering
Claude Code runs 8 parallel subagents when a plan is drafted: architecture, coding standards, UI design, performance, security, compatibility, documentation, testing. Each subagent evaluates from its specialty. Supervisor synthesizes into a final plan.
- Supervisor is typically the same model
- Workers are smaller/faster models for speed
- Aggregation step prevents context overflow
In 2026, supervisor/worker coordination is increasingly mediated by MCP (Model Context Protocol). The supervisor uses MCP tools to invoke worker capabilities, and results flow back through the same protocol. This standardizes tool discovery, authentication, and result schema across the multi-agent system.
Cost & Token Budgeting
Agentic workloads consume 10–100x more tokens than chat. LLM FinOps is a first-class engineering discipline in 2026.
A 10-turn loop sends roughly 50x the tokens of a single linear call. Most variance is path-dependent — driven by retrieval thrash, retry loops, and context re-sends. Falconer's shared knowledge layer cuts median loop length by 50%+.
Token Budget Patterns
Failure Modes & Guardrails
The six failure modes that cost production teams the most — and how to prevent each one.
Termination condition is missing, misconfigured, or model-dependent. Loop keeps running until API rate limit, token budget, or monthly bill stops it.
- Hard cap: max iterations + token budget
- Write verifiable stop conditions before running
- Add circuit breakers per tool call type
Agent calls tools, gets results, but results don't advance the task. Keeps retrying the same failed approach. Detection: track diff of outputs — if nothing changes for N turns, trigger pause.
- Track state diffs between iterations
- Same error 3x → escalate to human review
- Different error each turn → systematic failure
Agent confidently asserts something that isn't true. Subsequent reasoning builds on the hallucination. Verification must be external and automatic, not model self-assessment.
- Always verify against ground truth (file system, API)
- Use structured output validation
- Second model cross-checks critical claims
Error in one stage (bad input, auth failure, API timeout) propagates to all subsequent stages. Without error isolation, a single failure aborts the entire loop.
- Try-catch around each tool call
- Isolate agent state from runtime errors
- Graceful degradation: partial result > no result
Long-running loops encounter token expiration, API key rotation, or permission revocation mid-execution. Agent may not detect this and continues with invalid credentials.
- Check token validity before each major stage
- Use short-lived credentials where possible
- Store auth state in the state file for recovery
Context fills with tool call history. Model starts losing earlier context — forgets what it was trying to do. Triggers degraded reasoning or truncated output.
- Monitor context fill percentage
- Trigger summarization at 70% capacity
- Move completed work to persistent state
A reliability agent watches the primary agent's trace spans, detects failure modes (loop, auth error, cascade), then dispatches a remediation sub-agent with a constrained toolset. This is moving from experimental to standard practice in SRE teams running agentic on-call systems.
Human-in-the-Loop & Safety
Where and when to insert human judgment into an autonomous loop. Anthropic's guidance: intervene when it matters, automate where it doesn't.
When to Insert Humans
Model Context Protocol (MCP)
The open standard (Anthropic, 2024-2025) for connecting agents to external systems — replacing fragmented per-vendor integrations with a universal client-server protocol.
- Universal tool discovery protocol
- Standardized tool schema (JSON schema)
- Resource access (files, databases, APIs)
- Persistent connection (no re-auth per call)
- Server-side caching of tool responses
- Tool calls route through MCP client
- MCP servers: local or remote
- Tool descriptions auto-generate from schema
- Multi-agent: each agent has own MCP client
- Supervisor uses MCP to invoke workers
Vague tool descriptions → model misuses the tool. Feb 2026 arXiv paper "MCP Tool Descriptions Are Smelly" showed 60%+ of MCP tool call errors trace back to insufficient descriptions. Invest in high-quality tool documentation.
Harness Engineering
The discipline that makes the difference between a working agent and a reliable one.
The model is one input into a running agent. Everything else — prompts, tools, hooks, sandboxes, feedback loops — is the harness, and that's where most of the engineering leverage actually lives. Harness engineering is the specific form of context engineering for coding agents.
Rolling, task-specific context that evolves with the loop — not a giant instruction dump at startup. Includes: current goal, relevant files, prior iterations, verification status.
Tools are the agent's API. Good: narrow scope (do one thing), clear I/O schemas, informative errors, idempotent where possible. Bad: vague descriptions, complex parameters, hidden side effects.
Hooks run at lifecycle events: on_tool_call, on_file_write, on_error, on_stop, on_review_requested. Claude Code hooks: lint on write, format on edit, verify on stop. Used for linting, formatting, verification triggers.
Isolate agent actions from production systems. File system sandboxes, network restrictions, read-only tool views for sensitive operations. The harness enforces permissions the model can't self-regulate.
Tool results → model's context, verification signals → loop control, cost data → routing decisions. Well-designed feedback loops are the difference between a harness that steers and one that just watches.
Trace spans per tool call, token burn per turn, cost attribution per task, loop length distribution. OpenAI Agents SDK and LangChain both provide built-in tracing. Feeds the reliability agent pattern.
Real-World Implementations
How the major platforms implement their agent loops — and what you can learn from their architecture.
OpenAI published "Unrolling the Codex Agent Loop" — the most detailed public explanation of a major lab's agent runtime. Codex CLI's loop has three layers: outermost schedules work, middle manages context and tool routing, innermost is the model's core ReAct loop. Tool calls are first-class operations with structured output schemas.
Claude Code runs 8 parallel subagents when a plan is drafted: architecture, coding standards, UI design, performance, security, compatibility, documentation, and testing. Each subagent evaluates from its domain specialty. Uses hooks for lifecycle callbacks on file writes, edits, and stops.
LangGraph exposes the loop as a stateful graph with nodes (agents, tools) and edges (conditional transitions). Built-in support for ReAct, Plan-and-Execute, Supervisor, and custom multi-agent topologies. Includes LangSmith tracing for observability.
CrewAI implements role-based agents with explicit task delegation and result aggregation. AutoGen (Microsoft) provides a conversation-based multi-agent framework where agents exchange messages and a manager coordinates. Both ship with supervisor patterns and built-in human-in-the-loop gates.
Claude Code Hooks Lifecycle
# Claude Code hooks lifecycle on_tool_call: # Runs after every tool call result on_file_write: # Runs after Claude writes a file on_file_edit: # Runs after Claude edits a file on_stop: # Runs when Claude stops (done or max_iters) on_review: # Human approval gate — pauses loop until approved # Example: auto-lint on file write def on_file_write(path): if path.endswith(".py"): result = run("ruff check", path) if result.exit_code != 0: return {"type": "edit", "path": path, "prompt": "Fix lint errors"} return {"type": "continue"}
Evolution Timeline
From simple ReAct to learned memory policies — the key milestones that shaped loop engineering as a discipline.
Maturity Ladder
From manual prompting to adaptive autonomous loops — where you are, and what it takes to move up.
The minimum viable production loop includes: (1) a separate evaluator that checks goal conditions, (2) hard cost caps that stop the loop before budget exhaustion, (3) automated verification that cannot be faked by the agent, and (4) a state persistence layer. Loops below L3 are experiments that should not run unattended.
Key Resources
Primary sources, frameworks, and reference implementations.