The agent loop

An agent starts with a goal and whatever state it can observe. The model decides on a step, the host runs a tool, and the result becomes new context. Then it goes again.

We can describe the cycle in five steps:

1. Perceive: look at the current state and the goal
2. Decide: pick the next tool to use
3. Act: run it and read the result
4. Evaluate: is the goal met?
5. Repeat: if not, back to step 1

flowchart LR
  accTitle: The agent loop
  accDescr: An agent observes the current state, decides what to do, acts with a tool, checks the result, and uses that evidence for the next observation.
  Observe --> Decide --> Act --> Check
  Check -->|New evidence| Observe
  Check -->|Goal reached| Stop

The loop is what makes agents powerful. If a command fails, the agent sees the error and tries something else. A complex task gets broken into smaller steps on its own. The plan adjusts to what actually happens. And it keeps going until the goal is reached, or it figures out it’s stuck.

Real loops are messy. A file doesn’t exist, a command fails, a tool returns something unexpected. The rest of this lesson is about what a good loop does with that mess.

Tool success is not task success

The agent runs a build and gets exit code 0. That proves the build completed. It doesn’t prove the new button looks right, that the authorization rule is safe, or that the feature works in the browser.

Every check should support a specific claim. The agent should stop when the acceptance criteria have evidence behind them. Not when the last tool call happened to succeed.

Failure should change the next step

Imagine a test command fails because a dependency is missing. Running the same command five times adds nothing. The agent should read the error, inspect the setup, install the dependency if it’s allowed to, or ask you.

A useful retry changes something: the input, the context, the tool, or the hypothesis. Repetition without new evidence is a stuck loop. When you see one, interrupt it.

Some actions are unsafe to repeat

Reading a file twice is harmless. Sending an email, charging a card, or inserting a database record twice is not.

For anything that writes, think about idempotency: can the same request run twice without creating a second effect? Idempotency keys, existence checks, transactions, or an explicit confirmation step all help, depending on what the system supports.

Give the loop boundaries

A good agent loop has limits on:

• attempts, time, and cost
• which files, services, or records are in scope
• which tools and permissions it has
• which actions need a human to approve
• what counts as stop, replan, or ask for help

The agent should ask when it lacks context, authority, or a safe way to recover. I can't verify the payment flow without sandbox access is a useful stop. Pretending the goal is done is not.

Next time you finish a task with an agent, scroll back through the trace. Mark each observation, action, and check. Find the one place where a result should have changed the plan, or where the final done needed stronger evidence. You’ll almost always find one.