The agent loop is six stages: intake, context, inference, tool execution, persistence, termination. The piece on What Is an Agent Loop? introduced the six stages at the conceptual level. This piece walks through each stage at the implementation level — what each stage actually does, what goes wrong at each one, and how the operator fixes it.
The vocabulary in this piece is enough to debug most agent systems. The next step after this piece is to read the Loops vs Graphs and Agent Memory and State pillars.
Stage 1 — Intake
The intake stage receives the goal. It decides what the agent is trying to do, on what input, and against what success criteria.
What good intake looks like. A specific goal, with named inputs, an explicit success criterion, and an explicit deadline. "Find the three slowest tests in this folder and report their names and durations" is good intake. "Make the tests faster" is weak intake.
Common failure: vague goal. The agent defaults to clarifying questions, or worse, picks a single interpretation and runs with it. The fix is to make the goal specific at the intake stage, not to make the agent better at guessing.
Common failure: missing success criterion. The agent declares success without producing the artifact. The fix is to make the success criterion explicit at intake. "Produce a markdown file at reports/slow-tests.md." "Return a JSON object with the test names and durations."
Common failure: hidden deadline. The agent runs until it terminates on its own, which may be forever. The fix is to make the deadline explicit at intake. "Decide in under 60 seconds." "Stop after ten iterations."
Intake is the cheapest stage to fix. Most agent debugging starts here.
Stage 2 — Context
The context stage gathers what the agent needs to act well. It decides what to put in front of the model.
What good context looks like. A bounded set of files, a bounded set of retrieved chunks, a bounded set of prior notes, and a bounded system prompt. Each piece has a clear purpose and a clear exclusion criterion.
Common failure: context window overflow. The context exceeds what the model can read. The agent's behavior becomes unpredictable; the earliest parts of the conversation are silently dropped. The fix is at intake — decide what is canonical and what is summarized. The piece on Why Context Explodes Without Bounding treats this in detail.
Common failure: stale canonicality. The context includes notes from a year ago that no longer reflect the workspace's reality. The agent treats the stale notes as true. The fix is at the memory layer — reindex, edit, or remove the stale notes. The piece on Memory Design Mistakes treats this pattern.
Common failure: retrieval contamination. The semantic index returns chunks that look relevant but are not current. The agent uses them. The fix is at the retrieval layer — narrower queries, better chunking, explicit recency filters.
Context is the most expensive stage to debug, because failures here look like model failures. They are not.
Stage 3 — Inference
The inference stage is the model's contribution. The model reads the context and produces the next piece of output.
What good inference looks like. Output that matches the constraints, addresses the task, and uses the tools it has been given. The output is specific, not hedged. The model can refuse the task when refusal is the right answer.
Common failure: hallucinated facts. The model produces facts that are not in the workspace. The fix is at the context stage — include the canonical source for any fact the model needs to use. The piece on Best Ways to Ask an Agent for Things treats the prompting patterns that reduce hallucination.
Common failure: tool overuse. The model calls tools when no tool is needed. The fix is at the constraints piece — explicitly tell the model when tool use is appropriate and when it is not.
Common failure: refusal. The model refuses a task that should be doable. The fix is at the role piece — reframe the role so the model understands what kind of work it is being asked to do.
Inference failures are rare. When they happen, the fix is almost always at the context or constraints stage, not at the model.
Stage 4 — Tool execution
The tool execution stage is where the agent's thinking meets the real world. The model produces a tool call; the platform runs the tool; the result comes back.
What good tool execution looks like. Tools that are specific, named clearly, return errors loudly, and produce results in a form the agent can reason about. Tools that fail visibly when they should fail, and succeed visibly when they should succeed.
Common failure: silent failure. The tool returns a success status but did not do the work. The agent treats the result as truth. The fix is at the tool layer — make success and failure visible, and have the agent check.
Common failure: malformed result. The tool returns a result the agent cannot interpret. The agent either retries forever or treats the malformed result as success. The fix is at the tool contract — return results in a stable shape, and have the agent validate the shape before using the result.
Common failure: tool contamination. A bad tool result gets propagated through the rest of the loop. The fix is at the persistence stage — do not write bad results to durable memory.
Tool execution is the stage where most production agent bugs originate. The piece on Three Rules for Picking the First Plugin treats the design choices.
Stage 5 — Persistence
The persistence stage records what happened in a place that survives the loop iteration. The agent writes to a file, updates a state store, appends to long-term memory.
What good persistence looks like. A clear contract for what gets written where. Long-term notes go to the long-term memory file. Wiki-worthy facts go to the wiki. Transient state goes to the state store. Durable artifacts get their own files.
Common failure: append-only drift. The long-term memory file grows without bound. Contradictions accumulate. The fix is a review pass that edits or deletes entries. The piece on Wiki Memory treats the discipline that prevents this drift.
Common failure: wrong layer. A fact that belongs in the wiki is written to the long-term memory file. A fact that belongs in long-term memory is written to the wiki. The fix is a routing rule for which layer is responsible for which kind of fact. The Agent Memory and State pillar names the rule.
Common failure: silent loss. A loop iteration produces something useful but does not persist it. The next iteration starts from scratch. The fix is at the loop design — every iteration that produces a useful result must persist that result.
Persistence is the stage where agent work compounds or evaporates. The discipline of persistence is what makes a long-running agent system possible.
Stage 6 — Termination
The termination stage decides whether to run another iteration. This is the stage most agent designs skip, and the stage where most agent failures originate.
What good termination looks like. A written predicate that the next operator can read. "The file reports/slow-tests.md exists and contains the test names and durations." "The API returned 200 with a non-empty body." "The user said done."
Common failure: vibe termination. The loop terminates when the agent feels done. The signal is that some runs end at three iterations and others end at thirty. The fix is a written predicate.
Common failure: success theater. The loop terminates with a "done" message that did not produce the artifact. The fix is to make the artifact's existence the predicate.
Common failure: runaway loop. The loop terminates only when the iteration cap is hit. The cap is a backstop, not a termination condition. The fix is a real termination condition; the cap is the last resort.
The piece on Why Agents Stall treats this stage in depth.
How the stages compose
The six stages run in order, but the order is not strict. A loop might do partial context, partial inference, partial tool execution, then more context. The stages are a vocabulary, not a schedule.
What the stages buy is legibility. When the agent does something wrong, the operator can ask "which stage failed?" and get a useful answer. Each stage has a different fix. Naming the stage names the fix.
Takeaway
The agent loop is six stages. Each stage is its own design problem. Each stage has its own failure modes. The fix for each failure mode is at the stage where the failure originated, not at the model. The next step is to read the Loops vs Graphs and Agent Memory and State pillars.