Module 13: Agents and automation offline · Lesson 13.1 · about 30 min
What an agent is
An agent is a model that uses tools in a loop until a job is done. Watch the loop, then build a small agent in Python that reads files on your own machine with Gemma 4.
Module 13 · about 30 minutes · read first: 11.3. You’ll be able to explain the agent loop and run a small file-reading agent on your own machine.
1. Why this matters
Chat answers one question. An agent does a job, such as “go through this folder and tell me which invoices are overdue”. The same pattern runs coding assistants, research helpers and report bots. With a local model it works on your own files, with no usage limit and nothing uploaded.
2. The loop
Think of a new office assistant who cannot leave their desk. They can only ask you to fetch things: “please bring me the March folder”. You fetch it, they read it, and they ask for the next thing, until they can write their answer. The model is the assistant; your code does the fetching.
An agent is a model plus tools plus a loop. A tool is a small function in your code that the model is allowed to ask for by name.
- Think: the model reads the task and everything so far.
- Act: it asks for a tool, with arguments (
read_file("invoices/march.txt")). - Observe: your code runs the tool and puts the result into the conversation.
- Repeat until the model replies with plain text instead of a tool call: that is the final answer.
You met one round of this in Lesson 11.3. An agent simply keeps going. Here is one small job, turn by turn. Watch the bar: every turn adds to what the model has to read.
The task. "Which files mention a deadline?" The system message and task are about 500 tokens. The context is set to 8,192 tokens.
Turn 1: act. The model does not answer yet. It replies with a tool call: list_files("."). Your code runs it and adds the result, three file names (about 30 tokens).
Turn 2: act again. The model asks for read_file("brief-a.txt"). Your code reads the file and adds up to 4,000 characters, about 1,000 tokens.
Turn 3. It reads brief-b.txt too: another 1,000 tokens. The context now holds about 2,600 tokens, a third of the window.
Done. This time the model replies with plain text and no tool call: "brief-b.txt has a deadline of 12 December." No tool call means the loop stops and the text is the answer.
3. A small agent in Python
Make a folder agent, and inside it a folder workspace with a few text files. Save as agent.py:
import pathlib
import ollama
MODEL = "gemma4:12b"
ROOT = pathlib.Path("workspace").resolve() # the only folder the agent may touch
def inside(path):
p = (ROOT / path).resolve()
if not p.is_relative_to(ROOT):
raise ValueError("that path is outside the workspace")
return p
def list_files(folder: str = ".") -> str:
"""List the files in a folder of the workspace.
Args:
folder: folder path inside the workspace, "." for the top
"""
return "\n".join(sorted(x.name for x in inside(folder).iterdir())) or "(empty)"
def read_file(path: str) -> str:
"""Read a text file in the workspace (first 4,000 characters).
Args:
path: file path inside the workspace
"""
return inside(path).read_text(encoding="utf-8", errors="ignore")[:4000]
TOOLS = {f.__name__: f for f in (list_files, read_file)}
def run(task, max_steps=8):
messages = [
{"role": "system", "content": "You are a careful assistant. Use the tools to do the task. "
"When you are done, reply with a short report."},
{"role": "user", "content": task},
]
for step in range(1, max_steps + 1):
reply = ollama.chat(model=MODEL, messages=messages, tools=list(TOOLS.values()),
options={"temperature": 0})
messages.append(reply["message"])
calls = reply["message"].get("tool_calls") or []
if not calls: # no tool asked for: this is the final answer
return reply["message"]["content"]
for call in calls:
name, args = call["function"]["name"], call["function"]["arguments"]
print(f"step {step}: {name}({args})")
try:
result = TOOLS[name](**args) if name in TOOLS else f"there is no tool called {name}"
except Exception as err: # tell the model what went wrong instead of crashing
result = f"error: {err}"
messages.append({"role": "tool", "content": str(result), "tool_name": name})
return "Stopped after the step limit."
if __name__ == "__main__":
print(run(input("Task: ")))
Run python agent.py and type a task such as “Which files mention a deadline? Give the dates.” You will see each step printed, then the report. The inside check means even a confused model cannot read files outside workspace (Lesson 13.8 adds more guard rails).
Which model? Tool use needs a model trained for it. Gemma 4 12B and up, Qwen3.8-27B and gpt-oss handle multi-step tool use well; E2B and E4B work for one or two steps but lose track on longer jobs.
Maths and principle
Principle: an agent repeats think, act, observe; every step adds tokens to the context, so long jobs get slower and can overflow it.
Equation: context after n steps ≈ task + Σ (model’s call + tool result). With 4,000-character file reads (about 1,000 tokens each), 6 steps ≈ 6,000+ tokens.
Analogy: a detective with a notebook. Each clue (tool result) is written in; each decision reads the whole notebook again. Where it breaks: the notebook has a fixed number of pages (the context window). Long jobs need tools that return short results, or a step that summarises the notebook.
Try it: your context is 8,192 tokens and each step adds about 1,200. How many steps fit after a 500-token task? ((8,192 − 500) ÷ 1,200 ≈ 6.)
- agent
- a model, a few tools and a loop in your code that keeps going until the model stops asking for tools
- step
- one turn of the loop: the model asks for a tool, your code runs it, the result is added to the conversation
- context after n steps
- the task plus everything every step added (each call and each result); the model re-reads all of it every turn
- step limit
- the most turns the loop may run, so a confused model cannot go round forever
- Physical meaning
- An agent is a model with a notebook and an errand runner. Each errand writes another page into the notebook. When the notebook (the context window) is full, the agent forgets the start of the job, so short tool results mean longer jobs are possible.
“An agent is a smarter kind of model.” No. It is the same model you chat with. What makes it an agent is the loop in your code: the model asks for a tool, your code runs it, and the result goes back. Take away the loop and you have plain chat again.
4. Worked example
Made-up numbers. A freelance designer has 40 client briefs in workspace. Task: “List clients whose brief mentions a deadline in December.” Gemma 4 12B on a 16 GB graphics card takes 9 steps (one list, eight reads; it reads only files whose names look like briefs) and 70 seconds, and returns five names with dates. A cloud agent would have needed every brief uploaded.
5. Practice
- Run the agent with the task “How many files are in the workspace?”. How many steps does it take?
- Ask it to read
../secret.txt. What happens, and why? - Add a tool
count_words(path)and ask “Which file is longest?”.
Answers
- One tool call (
list_files) and then the answer: two rounds of the loop. insideraises an error, the model sees “that path is outside the workspace”, and usually reports it cannot read the file.- Write it like
read_filewith a docstring, returnlen(inside(path).read_text(...).split()), and add it to the tuple inTOOLS.
New words: agent (a model using tools in a loop), tool (a function the model may ask to run), step limit (the most rounds the loop may run), ReAct (the reason-then-act pattern most agents follow).
- An agent is a model, a few tools and a loop: think, act (ask for a tool), observe (read the result), repeat.
- The loop ends when the model replies with plain text instead of a tool call; a step limit makes sure it always ends.
- Your code runs the tools, never the model, so your code decides what the agent can reach (the
insidecheck). - Every step adds tokens to the context; short tool results let an agent work longer before the window fills.
- Multi-step tool use needs a model trained for it, such as Gemma 4 12B and up.
Check yourself
Sources
- Yao et al. (2022), ReAct: Synergizing Reasoning and Acting in Language Models, https://arxiv.org/abs/2210.03629
- Schick et al. (2023), Toolformer: Language Models Can Teach Themselves to Use Tools, https://arxiv.org/abs/2302.04761
- ollama Python library, tool calling, https://github.com/ollama/ollama-python
Your ticks stay in this browser. Save them as a file on the course home.
Updated 2026-11-22. Prices and model names change fast: check the official source before you buy.