The Agent Loop
Decide, act, observe, repeat — with a worked example.
Let's trace a real agent task through the loop.
The task
"Add a theme field to the User model, update the migration, and fix the tests."
Step by step
1. Decide. The model reads the goal and available tools, and chooses: search for the User model.
2. Act. It calls search("class User").
3. Observe. It gets back three files: models/user.py, schemas/user.py, tests/test_user.py.
4. Decide. Now it knows the landscape. It calls read_file on each.
5. Act / Observe. It reads all three files.
6. Decide. It plans: edit the model, add a migration, update the schema, fix tests.
7. Act. It edits models/user.py, runs the migration generator, updates tests.
8. Observe. It runs pytest — two tests fail.
9. Decide. Read the failure, fix the test fixtures.
10. Act / Observe. Edit, re-run tests — all green.
11. Decide. Done. Summarize.
What this teaches us
- The model re-plans after every observation. The loop is the intelligence.
- Tool results become context — that's how the model "sees" the codebase.
- Most real tasks are 10–50 loop iterations, not one prompt.
Failure modes of the loop
| Symptom | Cause | Fix | | --- | --- | --- | | Loops forever | No clear goal / no stop signal | Add "done" criteria & step limit | | Goes off the rails | Bad tool description | Rewrite the tool docs | | Loses the thread | Context too large | Summarize, trim old tool output | | Over-eager edits | No plan step | Ask for a plan before editing |
Watch your agent's loop a few times (Windsurf's Flows makes this easy). Once you can predict its next step, you're ready to design agents yourself.