AI Agents

You type "Summarise notes/q3-review.md for me" into an AI tool, and a summary of that file comes back. A file on your computer was opened and read. Yet the previous lesson showed that a model can only produce text. It cannot open anything.

The piece that closes this gap is the AI agent. An agent is a piece of software. A model can only produce text, and an agent is the program that turns some of that text into things that happen: a file opened, a search run, a document saved.

This lesson follows that one request from start to finish. It shows what the agent sends to the model, what the model sends back, who opens the file, and how the result returns to the model. After this lesson you can describe each step of an agent handling a task and say which part did what.

1. You talk to the agent, and the agent talks to the model

When you use an agent, your message does not go straight to the model. It goes to the agent, and the agent builds the request that the model receives.

What you typed:

Summarise notes/q3-review.md for me.

What the agent sent to the model:

Summarise notes/q3-review.md for me.

tools you may use:
  read_file(path)
  list_files(folder)
  write_file(path, text)

Your sentence is not the whole of what arrives. It is the first part of what arrives. The agent added a list of tools, which are actions it is willing to perform if the model asks. Here there are three: reading a file, listing the files in a folder, and writing text to a file. The word in brackets after each name is the detail the tool needs, called an argument. For read_file, the argument is path, the location of the file.

This list changes the situation for the model. With only your sentence, the model could do nothing except write a reply, and it has never seen the file. With the list, there is a choice to make: answer directly, or ask for one of the tools.

In a real agent the request holds more than this, such as system instructions and a fuller description of each tool, as the lesson on context described. The short version here keeps the parts that matter for the example.

2. Deciding to read a file is not reading a file

This step is the one most often misunderstood, and it matters more than any other in this lesson.

The situation the model is in:

prompt:  Summarise notes/q3-review.md
tools:   read_file(path)

The model's entire output:

read_file("notes/q3-review.md")

The model worked out that it cannot summarise a file it has not seen, that a tool for reading files is on offer, and that the file it needs is notes/q3-review.md. It then wrote out a request to use that tool with that file name. Such a request is called a tool call.

A tool call is tokens that describe an intended action. At this moment nothing has been opened. The file is still sitting on the disk, untouched. The model has not seen one word of it. All that exists is a short line of text saying which action the model wants.

In practice the tool call is written as structured output, so that the agent's code can read it reliably. The line above is a simplified way of showing it.

3. The software does the acting

A model's reach ends at its own output. Everything beyond that point is software.

flowchart LR
    M["The model<br/>produces text only"] -- "read_file(q3-review.md)" --> A["The AI agent<br/>software on your system<br/>or in the cloud"]
    A --> F["notes/q3-review.md<br/>opened and read<br/>by the software"]

The diagram shows three boxes. On the left is the model, which produces text and nothing more. The arrow leaving it carries the tool call. In the middle is the agent, which is software. On the right is the file.

The agent receives the model's output and recognises it as a tool call, not as an answer for the user. It then does what the call describes: it opens notes/q3-review.md and reads the contents. The file was opened and read by the software, not by the model.

The agent can run in different places. A coding agent usually runs on your own computer, where your files are. Other agents run on a company's servers in the cloud. Where the agent runs decides what it can reach: an agent on your machine can open your local files, and an agent in the cloud can reach only what it has been connected to.

4. The result goes back as another message

The agent now holds the contents of the file. It does not interpret what it found, and it does not write the summary. It reports the contents back to the model as a new message, called a tool result.

The agent's reply to the model:

tool_result: read_file
path: notes/q3-review.md

Q3 review, drafted Tuesday
Churn is the open question.
Two accounts still unsigned.
Renewals pushed to next month.

The first two lines say which tool was run and on which file. The rest is the text of the file, exactly as it was read.

Since a model keeps no memory between requests, the agent sends everything again, with the new result added at the end. The request now holds four things:

1. Your original prompt
2. The list of tools
3. The tool call the model asked for
4. The result of that call

All four are sent, every time. Nothing was thrown away. The model reads the whole request and decides again, with more in front of it than before. This time the file's contents are there, so the model has what it needs to write the summary.

This also explains why agents use many tokens. Every tool result is added to the context and sent again on each later step, so a long task carries a growing request.

5. One task, as many turns as it takes

Put the steps together and the work has the shape of a loop.

sequenceDiagram
    participant U as You
    participant A as Agent
    participant M as Model
    U->>A: Summarise notes/q3-review.md
    A->>M: Your prompt plus the list of tools
    M->>A: Tool call asking to read q3-review.md
    A->>A: Opens and reads the file
    A->>M: Everything so far plus the file contents
    M->>A: The summary
    A->>U: The summary

Reading from top to bottom: you send the request to the agent. The agent passes it to the model with the list of tools. The model decides the next step and replies with a tool call. The agent carries it out by opening the file. The agent sends the result back to the model. The model now has enough, so it writes the summary. The agent shows the summary to you.

Each round of "the model decides, the agent acts, the result comes back" is one turn. This task needed one turn with a tool and one final answer.

If one file was not enough, the same circuit runs again. Suppose the review mentions a second document. The model can reply with another tool call, read_file for that document. The agent reads it and returns the contents, and the model decides once more. This continues until the model judges that it has enough and writes an answer in place of a tool call. A larger task, such as fixing a bug across several files, can take dozens of turns. A later lesson covers this loop in detail.

6. The three jobs of an agent

Set the word "agent" aside, and what is left is a plain job description with three parts.

The third job is often overlooked. The model starts every request with nothing. The agent is the part that persists through the task. It has access to the folder, it stores each tool result, and it keeps the growing history and sends it to the model on every turn.

The first job also sets a limit. The model can ask only for tools on the list. If the agent offers no tool for sending email, the model cannot cause an email to be sent, whatever it writes. So what an agent can do is decided by the people who built it and by the permissions the user gives it.

7. What an agent makes possible

An agent takes a model that can only produce text and puts it to work on things that are not text: files, folders, searches, and other systems. The deciding comes from the model. The doing comes from the software around it.

An everyday comparison: a manager in an office reads a request, decides what should be done, and writes instructions on slips of paper. An assistant takes each slip, carries out the instruction, and brings back a note saying what happened. The manager is the model, the assistant is the agent, and the slips are tool calls. The comparison stops being accurate at one point: the manager remembers the earlier slips, while the model must be handed the full stack of slips and notes again before every decision.

The same division brings a risk. When the software acts on the model's text, a wrong decision by the model becomes a real action, such as a file overwritten with the wrong content. This is why agents ask the user for permission before some actions, and why the list of tools and the folders an agent may touch are chosen with care.

At the time of writing, common examples of agents include coding tools that read and edit the files of a project, and assistants that can search the web or work with documents. Product abilities change, so check what a given tool is allowed to do.

Interview points

• An AI agent is software that sits between the user and the model. It builds the request, including the list of tools, and the user's message is only one part of that request.
• A tool call is text generated by the model that names a tool and its arguments. Generating it performs no action.
• The agent executes tool calls. The model's reach ends at its output, and anything that touches files, networks, or other systems is done by the software.
• After running a tool, the agent returns the raw result to the model as a tool result. It does not interpret the result itself.
• Each request to the model contains the original prompt, the tool list, the earlier tool calls, and their results. The context grows with every turn, which raises token use.
• The work is a loop: the model decides, the agent acts, the result returns, and the model decides again until it produces a final answer.
• An agent has three jobs: offering the tools, running the chosen tool with the given arguments, and holding the environment of files, results, and history.
• The model can request only the tools it was offered, so the tool list and the permissions define what the agent can do and what can go wrong.

Summary

• A model produces only text, and an agent is the program that turns some of that text into actions.
• The agent adds a list of tools to the user's message before sending it to the model.
• The model answers with a tool call, which is a written request and not an action.
• The agent runs the tool and sends the result back to the model with everything that came before.
• The cycle repeats until the model has enough to write the final answer.
• An agent offers tools, runs them, and holds the environment the work happens in.