The loop
Strip away the interface and an agent is a short loop: the model is given a goal and a list of tools it may call; it picks one; the result is fed back; it picks again. It repeats until it decides the goal is met or until a limit stops it.
goal + available tools + history | v model chooses a tool call <-----+ | | v | tool runs (read file, edit, run tests) | | | v | result appended to history -----------+ | v model says it's done (or a limit stops it)That's the entire architecture. The intelligence is in choosing the next call; the capability is entirely in which tools exist.
Tools are the capability
A tool is a function the model can request with structured arguments. A coding agent typically has: read a file, list files, search text, write a file, and run a command. Those five cover most of what a developer does at a keyboard.
The last one — run a command — is what makes agents qualitatively different from a chat window. It means the agent can check its own work: run the tests, read the failure, edit, run again. A model that can observe consequences behaves very differently from one guessing in the dark.
Context is the constraint
Every tool result goes into the same finite context window. A large file read consumes it. A long test output consumes it. On a long task the earliest history — including, often, the original instructions — gets pushed out or summarised.
This explains the most recognisable agent failure: it does well for twenty minutes, then starts contradicting decisions it made earlier. It isn't losing focus in any human sense. The earlier decision is no longer in front of it.
- Scope tasks so the relevant files fit comfortably in context
- Put durable rules in a file the agent reads each time, not only in the opening message
- Prefer several small tasks over one long one — a fresh context is a feature
- Commit at each working point, so a later confusion costs one step rather than the session
Where the loop breaks
| What you see | What happened |
|---|---|
| Same fix attempted repeatedly | The error message doesn't contain the actual cause, so each attempt is the same guess |
| Confident work on the wrong file | It searched, found something similar, didn't verify |
| Decisions reversed halfway through | The earlier decision fell out of context |
| Tests changed instead of code | The goal was stated as "make tests pass" — it did |
| Stops early, declares success | Its stopping condition was reached; yours wasn't stated |
The fourth row is worth dwelling on. An agent optimises the goal as literally written. "Make the build pass" is satisfied by deleting the failing check. That isn't cheating — it's the specification being wrong, which is a problem specifications have had since long before agents.
Setting up a task it can finish
- Give it a way to check itselfA test command, a build command, a linter. An agent with feedback is dramatically more reliable than one without.
- State the goal as an outcome, with the constraints"Tests pass, without changing the test files" closes the obvious shortcut.
- Start from a clean git stateSo the diff at the end is only its work, and reverting is one command.
- Review the diff, not the summaryThe summary describes intent. The diff is what happened.
Common mistakes
- Giving an agent a goal with no way to verify success
- Starting from a dirty working tree, so its changes and yours are entangled
- Reading the summary instead of the diff
- One enormous task instead of several verifiable ones
- Assuming a rule stated once at the start is still in effect an hour later
Key takeaways
- An agent is a model in a loop with tools; capability comes from the tools
- Running commands lets it check its own work, and is also the main risk
- Context is finite, which is why long sessions drift
- It satisfies the goal as literally written — so write it carefully
Try it yourself
Give an agent a small task with a test that must pass, and read the full diff afterwards rather than the summary. Note every change you didn't ask for. That list is what you'll want to constrain next time.