Skip to content

Knowledge base

The agent loop

What an agent is made of, how to build one in plain code, and how to debug the step that failed instead of re-running the whole loop.

Written by

Updated:

Agentic Engineering 5

Our position. We teach the loop so a team debugs the step that failed instead of re-running the whole thing (opens in a new tab) and hoping for a better dice roll. Bad perception means fixing the context, and a bad decision is a model or instruction problem. A failed action means fixing the tool, and a bad observation means giving the agent a real signal.

Production agents are mostly ordinary code with small model loops inside. The engineer sets how tight each loop runs, which tools it may call and when it exits.

What is an agent, and how do you build one?

Before you can pick a methodology for building an agent, it helps to be exact about what an agent is. An agent is not the model. The large language model is a static, stateless function: text in, a prediction of the next tokens out, no memory and no awareness of whether its last output worked. The agent is the program wrapped around it, a while loop that runs the ReAct cycle (Reason, Act, Observe): the model reasons, emits a structured tool call, the execution environment runs the tool and appends the result to the context, and the loop re-invokes the model until a terminal condition is hit. The intelligence is emergent from the feedback loop, not from a spark inside the weights; the same static model in a single shot is less reliable, because autoregressive generation compounds each early error across every later token, where the loop lets the model observe a failure and course-correct.

Two mechanisms carry the weight. Tool use is closure over the environment: a tool is a declared capability, a named function with a typed JSON schema injected into context; the model emits JSON, the environment owns and runs the code behind it, and the changed environment becomes the next observation. Without that closure the agent writes code blind and terminates on the first plausible guess. And autonomy is elastic, not binary: the engineer tightens the loop (max iterations near one, approval gates before state-mutating actions) for high-risk or low-visibility work and loosens it for low-risk, high-context work inside strong guardrails, re-tightening whenever the environment’s structural determinism drops. The cybernetic caveat holds throughout: the agent drives toward a setpoint that is only ever a test or a spec, so a wrong test or an incomplete spec gives it a false zero, and convergence on a flawed target is not correctness.

Practitioners building production agents arrive at the same deflation from the field. The recurring lesson is that agents are software: most production agents are mostly deterministic code with small LLM loops sprinkled in, and the load-bearing trick is turning a sentence into structured JSON, so tool use is just JSON plus code rather than an alien entity touching the world (12-Factor Agents talk, HumanLayer (opens in a new tab), 3 July 2025). The discipline that follows is to own the parts frameworks hide: own your control flow (a prompt selects the next step, a switch statement dispatches the JSON, you decide how and when the loop exits), own your prompts (past a quality bar you write every token by hand, because the model is a pure function of the tokens you feed it), own your context window, and keep the agent stateless so you can serialize, pause, and resume it.

The structure that works is small, focused micro agents of three to ten steps inside a mostly deterministic DAG, not one long autonomous loop that degrades as its context grows; the design target is the bleeding edge, the task the model cannot quite do reliably, engineered to be reliable anyway (12-Factor Agents talk, HumanLayer (opens in a new tab), 3 July 2025). This reframes what an agent SDK is for: the framework is a wishlist, not a mandate, and the durable pattern is libraries over frameworks and scaffold-then-own over an opaque wrapper.

Building one well is as much a mindset shift as a technical task. The reliable stance is to treat the model as a probabilistic driver you dispatch, not a deterministic function you control; engineers who try to code away that nondeterminism build worse agents, which is why juniors sometimes ship working agents faster than seniors (Why (Senior) Engineers Struggle to Build AI Agents (opens in a new tab), 26 November 2025). Three of the article’s rules extend the loop above: an error is just another input, caught and fed back so the agent recovers rather than crashes; text is the new state, so preserve the user’s raw words instead of collapsing them to a boolean; and agents are literalists, so tools want verbose, idiot-proof names and schemas (user_email_address, not email) with the docstring carrying the context. Because you cannot unit-test reasoning, behavior is measured with evals, reliability as pass^k, quality via an LLM judge, plus a trace of the intermediate steps, rather than assertions alone (Why (Senior) Engineers Struggle to Build AI Agents (opens in a new tab), 26 November 2025).

The platform vendors now say the same thing about frameworks. As models improve, heavy scaffolding turns from an asset into a liability, hiding the model’s own intelligence, so the design goal is to unhobble the model: give it tools and a minimal prompt and set it loose (Anthropic – Building the Future of Agents with Claude (opens in a new tab), 2 October 2025, vendor). Anthropic reports that stripping the coding specifics out of the Claude Code SDK left a general agentic-loop runtime with nothing coding-specific remaining, and that a memory tool lets a single agent improve across runs, closing the gap where a human gets better by the fifth attempt but a base model does not (Anthropic – Building the Future of Agents with Claude (opens in a new tab), 2 October 2025, vendor).

Owning your control flow has a concrete shape: put the orchestration in real code and call the model only where it is genuinely needed. One worked pipeline drives issue, implement, review, PR, and feedback as typed workflow steps (each returns a structured success or a failure with the next action), passes a JSON schema as the SDK’s output format so responses validate, and enforces the boundary with hooks that deny a direct git push and redirect to the workflow, while the agent treats the pipeline as a black box and follows the returned instructions (Dev Workflows as Code (opens in a new tab)). The reason to move orchestration out of the prompt is that a single agent asked to also run the process wobbles once its context fills, skipping or repeating steps.

Resources

Articles

Posts

Talks and videos