# Watch a tiny agent work

> Read the transcript of a toy agent that lists a folder and reads a note, name each phase as observe, think or act, see how a tool is described to the model, and learn the ways the loop ends.

Page: https://schubergphilis.github.io/ai-training/concepts/agent-loop/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

So far in this course the model answered a prompt and stopped. In this
lesson we watch a toy agent. The same kind of model sits in a loop
with two tools, and its task is a question about a folder of meeting
notes. The toy is small enough to read in one sitting. Its "model" is a
script with a fixed list of replies. Every run below comes out the same
way, and there is nothing for you to install or run. You read
three transcripts. By the end you can label each line of one with the
phase it belongs to, and you can say why the run stopped.

## A model in a loop with two tools

A model takes text in and produces text out, once. It can't open a file
or look in a folder. An **agent** is software around a model that can.
The software calls the model and reads the reply. When the reply asks
for a tool, the software runs that tool and hands the result back to the
model as more text, and then calls the model again (What are AI agents: model versus agent, autonomy levels, when a prompt suffices, Agent Engineer Course). The model
supplies the judgment about what to do next, and the software supplies
the hands.

The toy has two tools. Before anything runs, the model is told what
they are, in plain text. Each tool has a name, one sentence on what it
does, and its parameters, which are the details the model has to fill
in when it asks for the tool.

```text
list_dir: List the files in a directory. Parameter: path, the directory to list.
read_file: Return the text of one file. Parameter: path, the file to read.
```

That text is the whole of what the model knows about the tools. It never
sees the code behind `list_dir`, and it doesn't need to. When it wants a
file listed, it writes a request that names the tool and fills in the
parameter, and the loop does the rest (Claude Platform 101, Claude Academy).
A tool with a vague description gets used badly, because the sentence
is all the model has to go on.

The folder the toy works in holds three short meeting notes, from 14, 21
and 28 March.

## Read the transcript

The first task is a question about the notes. The transcript below is
the toy's output, line for line. The lines that start with `model:` are
what the model produced, and the ones that start with `loop:` are what
the software around it did in response.

```text
task: Which meeting note mentions the June delivery?
1. model: call list_dir with path "notes"
   loop: ran list_dir, result: 2026-03-14-lantern.txt, 2026-03-21-budget.txt, 2026-03-28-lantern.txt
2. model: call read_file with path "notes/2026-03-14-lantern.txt"
   loop: ran read_file, result: Project Lantern, 14 March. Sensor boards moved from April to June. Ana confirms the date by Friday.
3. model: done. The note of 14 March: the sensor boards moved from April to June.
loop: stopped, the model said it is done after 3 steps
```

Read step 1 slowly, because it is the whole idea. The model didn't list
the folder. It wrote the words `call list_dir with path "notes"`, which
is text like any other reply. The loop recognized that text as a request,
ran the real `list_dir` tool on the real folder, and put the three file
names into the conversation as the next thing the model reads. In step 2
the model, now knowing the file names, asked to read the one whose name
suggested the right project. In step 3 it had what it needed and wrote an
answer instead of a request, and the loop saw that and stopped.

The model's text reached the folder only through the loop. In a real
agent the loop is also where permissions are checked and where a request
can be refused. When people say an agent "read a file", this two-line exchange
is what happened.

## Observe, think, act

The transcript has a rhythm, and the **agent loop** is that rhythm. Each
step is one turn of it: one call to the model, its reply, and the tool
run that follows, if there is one (What are AI agents: model versus agent, autonomy levels, when a prompt suffices, Agent Engineer Course). A turn has three phases:

- **Observe.** The model reads what's in front of it: the task at the
  start, and after that the result of the last tool.
- **Think.** The model decides what to do next and writes it down, either
  a tool request or an answer. In the transcript this is every `model:`
  line.
- **Act.** The loop runs the tool the model asked for and returns the
  result. In the transcript this is every `loop: ran` line.

Then the model observes the result, and the turn repeats. Step 1 of the
transcript is observe (the task), think (`call list_dir`), act (the
listing comes back). Step 2 is observe (the file names), think
(`call read_file`), act (the note comes back). Step 3 is observe (the
note) and think (`done`), with no act, because the model produced an
answer and there was nothing left to run.

The split matters when something goes wrong. A wrong answer after a
correct file read is a think problem, and the fix is in the prompt or
the model. A right request that returned an error is an act problem, and
the fix is in the tool. An agent that read the wrong file did a
reasonable think on a poor observe, and the fix is often a better tool
description or a better folder name. Naming the phase tells you where to
look.

#### Checkpoint: Label the phases

Buckets:

- Observe
- Think
- Act

Items:

- The model reads the task at the top of the transcript
- The model writes a request to list the notes folder
- The list_dir tool runs on the folder and returns three file names
- The model reads the three file names that came back
- The model picks the 14 March note as the one to read next
- The read_file tool runs and returns the text of the note
- The model reads the text of the note
- The model writes the answer instead of another request

## How the loop ends

A loop with no end is a bug, so every agent has stop rules. The toy has
two, and a real agent adds a third (What are AI agents: model versus agent, autonomy levels, when a prompt suffices, Agent Engineer Course).

The model says it is done. This is the good ending, and the first
transcript shows it: the model wrote an answer instead of a request, and
the loop stopped after 3 steps.

The step limit is reached. The loop counts the steps and stops at a
fixed number even when the model isn't finished. The limit protects
you from a model that keeps asking for tools without getting anywhere,
which runs up the bill and, with tools that change things, keeps
changing them. Here is the toy on a task with a step limit of 3, with a
script that lists the folder twice and then reads the wrong file.

```text
task: Who confirms the delivery date?
1. model: call list_dir with path "notes"
   loop: ran list_dir, result: 2026-03-14-lantern.txt, 2026-03-21-budget.txt, 2026-03-28-lantern.txt
2. model: call list_dir with path "notes"
   loop: ran list_dir, result: 2026-03-14-lantern.txt, 2026-03-21-budget.txt, 2026-03-28-lantern.txt
3. model: call read_file with path "notes/2026-03-21-budget.txt"
   loop: ran read_file, result: Budget review, 21 March. Travel spend is under plan. The training budget is approved.
loop: stopped, the step limit of 3 was reached, no answer
```

The answer was in the note of 14 March, and the model's script would
have read it in step 4. The loop didn't allow a step 4. The transcript
has no answer line, because the model never got to write one. The last
thing it did was ask to read the budget note. A limit that stops a run always
stops it in the middle of something.

A person stops it. In a real agent the loop pauses and asks before an
action that's hard to undo, and a person can say no, or close the
window at any point (Agentic AI: M1 workflows and autonomy, M2 reflection, M4 evals and error analysis, M5 autonomous agents, DeepLearning.AI). A stop of this kind looks like the step
limit from the model's side: the last request was made, and no answer
follows.

#### Checkpoint: Why did the second run stop?

In the second transcript the run ends without an answer. Why?

- The model found the answer in the budget note and stopped.
- The tool failed on the second listing, so the loop gave up.
- The loop reached its step limit before the model wrote an answer.
- The script ran out of replies, so the model had nothing more to say.

#### Pitfall: Stopped in the middle

A team gives an agent a folder of forty customer reports and a task:
read each one, write a one-line status into `summary.txt`, and finish
with a count of the reports that need a follow-up call. The agent has a
tool that writes to a file, and a step limit of 50, which the team took
as generous. Listing the folder is one step, and each report takes two
more, one read and one write, so step 50 is the read of report 25, and
the loop stops before its write. `summary.txt` has 24 lines out of 40, no total,
and no note that anything is missing. The person who opens
it the next morning sees a finished-looking file with a number of lines
that happens to be short, and nothing on the page says why. The step
limit did its job of ending the run, and it can't do the other job of
finishing the work. A run that hit a limit needs to be read as an
interrupted run. Look at the last request and at what it half did, and
then decide whether to rerun from there or throw the partial result away.

## Exercise

Here is a third transcript, on a different task over the same three
notes. Read it once. Then, on paper or in a note, write one line per
step, in the form "step, tool used, which phases", where the phases are
observe, think and act. Step 1 of the first transcript would read
"1, list_dir, observe (task), think (request), act (listing)". Finish
with one line that names how the run ended and how you know. Ten minutes
is enough.

```text
task: How many of the meeting notes are about project Lantern?
1. model: call list_dir with path "notes"
   loop: ran list_dir, result: 2026-03-14-lantern.txt, 2026-03-21-budget.txt, 2026-03-28-lantern.txt
2. model: call read_file with path "notes/2026-03-14-lantern.txt"
   loop: ran read_file, result: Project Lantern, 14 March. Sensor boards moved from April to June. Ana confirms the date by Friday.
3. model: call read_file with path "notes/2026-03-21-budget.txt"
   loop: ran read_file, result: Budget review, 21 March. Travel spend is under plan. The training budget is approved.
4. model: call read_file with path "notes/2026-03-28-lantern.txt"
   loop: ran read_file, result: Project Lantern, 28 March. The Utrecht pilot moves to July. Bram writes the short install guide.
5. model: done. Two of the three notes are about project Lantern: 14 March and 28 March.
loop: stopped, the model said it is done after 5 steps
```

A good result has five lines, four of them naming a tool and the fifth
naming none, because step 5 has a think and no act. The ending line says
the model wrote an answer, and points at the `done` line and the loop's
last line as the evidence. As you write, notice that the model read the
budget note even though its name gave the answer away. A model in a loop
does what its judgment tells it, one step at a time, and a step it could
have skipped costs the same as one it needed. Where in this transcript
would a better tool description, or a better file name, have saved a
step?

Stretch: Write the transcript a fourth run would produce for the task 'Which note names Bram?', with the fewest steps a model that read the file names carefully could take, and mark the three phases of each step.

## Recap

1. An agent is a model in a loop with tools. The model produces text,
   and when that text is a request the loop runs the tool and returns the
   result as more text. The model never runs anything itself (What are AI agents: model versus agent, autonomy levels, when a prompt suffices, Agent Engineer Course).
2. A tool is described to the model by name, purpose and parameters, in
   plain text, and that description is all the model has to decide when
   and how to ask for it.
3. Each step of the loop is observe (read the task or the last result),
   think (write a request or an answer) and act (the loop runs the
   tool). Naming the phase tells you where a mistake came from.
4. The loop ends when the model writes an answer, when the step limit is
   reached, or when a person stops it. A run that ended on a limit or a
   stop was interrupted in the middle of a step, and its output has to be
   read that way.

## References

- What are AI agents: model versus agent, autonomy levels, when a prompt suffices, Agent Engineer Course, https://lsimons.github.io/agent-engineer-course/01-what-are-ai-agents/
- Claude Platform 101, Claude Academy, https://academy.claude.com/courses/claude-platform-101
- Agentic AI: M1 workflows and autonomy, M2 reflection, M4 evals and error analysis, M5 autonomous agents, DeepLearning.AI, https://www.deeplearning.ai/courses/agentic-ai