Home / Learn / Data & AI / Offline AI / Lesson 13.1
All lessons

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.

Key points, meanings and formulas on one page: choose "Save as PDF" in the print box.

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.

An agent is an ordinary model that asks your code to run tools, reads what comes back, and repeats until the job is done.

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.

  1. Think: the model reads the task and everything so far.
  2. Act: it asks for a tool, with arguments (read_file("invoices/march.txt")).
  3. Observe: your code runs the tool and puts the result into the conversation.
  4. Repeat until the model replies with plain text instead of a tool call: that is the final answer.
Animation: the agent loop The agent loop: the model thinks, asks for a tool, your code runs it, the result is observed, and the loop repeats until the model writes a final answer. 1. Think 2. Use a tool 3. Observe your model+ your code Answer
The dot is the job going round. Each lap the model either asks for a tool (your code runs it and hands back the result) or decides it is finished and writes the answer. The step limit stops the dot going round forever.

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

  1. Run the agent with the task “How many files are in the workspace?”. How many steps does it take?
  2. Ask it to read ../secret.txt. What happens, and why?
  3. Add a tool count_words(path) and ask “Which file is longest?”.
Answers
  1. One tool call (list_files) and then the answer: two rounds of the loop.
  2. inside raises an error, the model sees “that path is outside the workspace”, and usually reports it cannot read the file.
  3. Write it like read_file with a docstring, return len(inside(path).read_text(...).split()), and add it to the tuple in TOOLS.

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 inside check).
  • 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

1What turns a chat model into an agent?
2Why does the agent loop have a step limit?
3A tool raises an error. What does the script do?

Sources

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.