0 · The Agent Loop — The Operator's Model

An AI coding agent can run commands, read files, and edit code on its own, and it does so faster than you can watch. That speed is useful only if you can predict what the agent will do next; otherwise each action is a surprise you have to inspect. Prediction starts with an accurate model of what the agent actually does on every turn. This module builds that model so the rest of the curriculum has something concrete to shape.

An AI coding agent is not autocomplete. It runs a loop: it perceives the state of your project, plans a step, takes an action (reads a file, runs a command, edits code), observes the result, and decides what to do next, repeating until the task is done or it gets stuck. Everything else in this curriculum is about shaping that loop.

flowchart LR
  P[Perceive<br/>read state] --> L[Plan<br/>next step]
  L --> A[Act<br/>edit / run]
  A --> O[Observe<br/>result]
  O --> P

When the model was only a chatbot, it handed back text and you did the work. Once it can act — run the tests, read the error, edit the file, run them again — a new class of problem appears. The work happens faster than you can watch, and the agent will push forward on a wrong assumption with the same confidence it shows on a right one. The operator's job is to shape the loop so that speed works in your favor rather than against you.

That gives the whole curriculum one measure, the dial every later module turns:

How long can the agent run before it needs you?

A poorly driven agent needs you every few seconds. A well-operated one runs for many steps, checks its own work, and comes back with something you can trust. Lengthening that runway safely is the skill this course teaches.

You operate the loop by controlling three things: what the agent can see (context), what you ask it to do (the spec), and how it checks itself (verification). The next three modules are exactly those three levers.

Those levers line up with terms you may have met elsewhere. What is often called prompt engineering, writing a good ask for a single turn, is in its durable form the spec (Module 2). Context engineering is the first lever, controlling what the agent can see (Module 1). And beyond driving one run well, harness engineering shapes what the agent can do: its tools, permissions, reusable workflows, and checks (Module 4). A short way to hold the three: a prompt is what you say, context is what the agent sees, and the harness is what it can do.

Concept

The loop runs one turn at a time. Give the agent a task in Triage and it runs the cycle: it perceives by reading app/triage/classify.py, it plans a change, it acts by editing the file and running pytest, it observes the test output, and that observation feeds the next plan. The feedback step — observe, then re-plan — is what separates an agent from a chatbot, and it is the source of both the power and the failure modes.

This is also why "agent" sits apart from "chatbot" and "autocomplete." Autocomplete predicts the next token in your editor and never leaves it. A chatbot answers in one shot and stops. An agent closes the loop: it takes an action, sees the result, and revises. Acting on what it observed is what lets an agent finish a real task, and it is also what lets it run a long way in the wrong direction.

There are three failure modes you will see most. The loop breaks in predictable ways, and each one has a signature you can learn to name the moment it starts.

• Lost context. The agent forgets a constraint you set or a file it read earlier, and contradicts itself. The tell: it re-asks something already settled, or re-introduces a bug it just fixed. (Fixed in Module 1.)
• Plausible-but-wrong. An edit that compiles, reads cleanly, and is wrong. The tell: it sounds confident and the diff looks tidy, but nothing actually checked the behavior. (Fixed in Module 3.)
• Thrashing. The agent loops without converging, trying variation after variation. The tell: three attempts in and the diff is churning rather than shrinking. (Fixed by a sharper spec, Module 2, or a reset, Module 1.)

You are not learning to prevent these by watching harder. You are learning to recognize them quickly, because each one has a lever later in the course that removes it. Practice that recognition now — read each transcript and name the mode from its tell:

The interactive version needs JavaScript; the same transcripts and answers are here without it.

Transcript A:

turn 4 — agent: I'll add the Category enum value in app/models.py.
            (edits app/models.py, adds PRIORITY)
turn 9 — agent: Where is the Category enum defined? Let me search the tree…

Which failure mode?

Lost context — it edited app/models.py on turn 4, then re-asks where the enum lives on turn 9. Re-asking the settled is the tell. (Fixed in Module 1.)

Transcript B:

agent: Done — added the priority label and updated the classifier.
       Diff is +12 / −3, reads cleanly, the function is tidy.
       (no test written, nothing run)

Which failure mode?

Plausible-but-wrong — confident tone, a tidy diff, and nothing checked the behavior. Clean-looking and unverified is the tell. (Fixed in Module 3.)

Transcript C:

attempt 1: tweak the regex → still failing
attempt 2: rewrite the regex another way → still failing
attempt 3: revert, try a third variation → diff is now larger than when it started

Which failure mode?

Thrashing — three attempts in, the diff is churning and growing rather than shrinking toward green. Variation without converging is the tell. (Fixed by a sharper spec, Module 2, or a reset, Module 1.)

Guided Lab

On the Practice Repo, you will start the agent on the Triage app, narrate one full turn of the loop as it runs, then hand it a deliberately under-specified task and watch a failure mode appear so you can name it by its tell.

On the Practice Repo, work through the following.

1. Clone Triage and start the agent in the repo root:

   git clone https://github.com/mrfelixwong/agentic-engineering-triage triage && cd triage
   claude
   

   Expected: the agent opens at the repo root. The classifier you will watch it work on lives at app/triage/classify.py; confirm it is there with ls app/triage/classify.py → the path prints (no No such file or directory).

2. Give the agent one small, fully specified task and narrate the loop as it runs:

   add a one-line docstring to the _normalize function in app/triage/classify.py

   Expected: one clean turn of the loop. Say "perceive" when it reads app/triage/classify.py, "plan" when it states what it will change, "act" when it edits the file, "observe" when it reads the result back. You can point at all four steps, in order, at least once.

3. Now hand it a deliberately under-specified task — one that names a goal but not where the change goes — and watch a failure mode surface:

   add a "priority" label to the classifier

   Expected: the task is under-specified on purpose (it does not say that labels are the Category enum in app/models.py, the alias map in app/triage/classify.py, and the guide in app/llm/prompts.py), so the loop visibly strains. You will see at least one tell: the agent guesses a path and opens the wrong file first, or grep-scans the tree blindly before it finds where labels live, or edits something you did not ask for (for example rewriting the classification function, or touching app/main.py) on its way to the change. Name the tell out loud as it happens — guessing a path and re-reading after a miss is the lost-context / thrashing signature; an unrequested edit that looks tidy is the plausible-but-wrong signature.

4. Mark the first moment a failure mode appeared and write down its one-line tell.

   Expected: a specific line in the transcript — the path it guessed wrong, the blind scan, or the unrequested edit — paired with the name of the failure mode it belongs to.

On your own codebase, do the same on your real repo: give the agent one tightly specified task and narrate the loop, then give it one under-specified task and watch where its runway ends — the first point it guesses, stalls, or needs you. That point is what Modules 1–3 push outward.

Keep the artifact

A personal failure-tells note: the three loop failure modes and the exact signature each showed in your session (the line where it forgot a constraint, the tidy-but-wrong diff, the churn). Keep it next to your editor. Recognizing these in one glance is the seed of the judgment you will sharpen in Module 7.

Self-check

You did it right if you can point at a specific moment where the agent perceived, where it planned, and where an observation changed its next move — and you can name which failure mode (if any) showed up and what its tell was.

Recall

Before moving on: name the three levers you use to operate the agent loop, and which module teaches each.

Answer

Context — Module 1; Specification — Module 2; Verification — Module 3. Everything later scales these three or decides when to use them.