Chapter 19 · Hands-on: build real projects
Build a tiny agent with tools
An agent loop asks the model what to do, runs the tool it picks, shows it the result and repeats until done.
Chapter 19 · Hands-on: build real projects
An agent loop asks the model what to do, runs the tool it picks, shows it the result and repeats until done.
An agent is a loop. Think: the model picks a tool. Act: your code runs it. Observe: the result goes back to the model. Repeat until the model gives an answer, or until a step limit you set stops it.
In the agent loop lesson you saw that an agent is a model plus a loop. Now you write that loop in about eighty lines of Python. There is no framework: you will see every step.
You need a local model running, as in Run an open model on your computer and Call your local model from code. The code uses the address and message format of one popular runner (Ollama), with the model name llama3.2 as an example, or any small model your runner lists.
We use the pdf-chat folder again, with the notes.txt from Set up a local vector database.
Open a terminal in pdf-chat and activate its virtual environment. Check notes.txt exists with a few lines (below is an example). Make sure your model runner is running. requests should already be installed from the RAG lesson; if not, pip install requests.
cd pdf-chat
.venv\Scripts\Activate.ps1The library closes at 8 pm on weekdays.
Books can be borrowed for two weeks.
The canteen serves lunch from 12 to 2. Check: Your line starts with (.venv), and notes.txt is in the folder.
The calculator never uses Python’s eval, which would run any code the model wrote. Instead it parses the expression into a tree and only accepts numbers and a few operators. Anything else is refused, and large powers are capped. The notes search only reads lines of notes.txt that contain the words you give it. Both return plain text.
Both are inside the file in the next step; read them first.
Check: You can say, in one sentence, what each tool can and cannot do.
Save the file below as agent.py. Notice the loop in run_agent:
"format": "json".answer, the loop finishes.MAX_STEPS = 5 is the safety cap. The for loop simply cannot run a sixth time.This simple JSON style works with almost any model. Some runners also offer built-in “tool calling”; the idea is the same.
import ast
import json
import operator
import sys
import requests
MODEL_NAME = "llama3.2" # any small model your runner lists
URL = "http://localhost:11434/api/chat"
MAX_STEPS = 5 # the agent can never loop forever
SYSTEM = """You are a careful assistant with two tools.
Tools:
- calculator: input is a maths expression such as "12 * (3 + 4)".
- search_notes: input is a word or phrase to look for in the user's notes.
Reply with JSON only, in one of two shapes.
To use a tool: {"tool": "calculator", "input": "2 + 2"}
To finish: {"answer": "your final answer"}
Use at most one tool per reply. After a tool result arrives, use it to answer."""
OPS = {
ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul,
ast.Div: operator.truediv, ast.Pow: operator.pow, ast.USub: operator.neg,
}
def calculator(expression):
"""Safe maths: only numbers and + - * / ** and brackets. Nothing else is allowed."""
def walk(node):
if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
return node.value
if isinstance(node, ast.BinOp) and type(node.op) in OPS:
left, right = walk(node.left), walk(node.right)
if isinstance(node.op, ast.Pow) and abs(right) > 10:
raise ValueError("power too large")
return OPS[type(node.op)](left, right)
if isinstance(node, ast.UnaryOp) and type(node.op) in OPS:
return OPS[type(node.op)](walk(node.operand))
raise ValueError("only numbers and + - * / ** are allowed")
return str(walk(ast.parse(expression, mode="eval").body))
def search_notes(query):
"""Read-only: look for lines in notes.txt that contain the query."""
with open("notes.txt", encoding="utf-8") as f:
hits = [line.strip() for line in f if query.lower() in line.lower()]
return "\n".join(hits[:5]) or "No matching lines."
TOOLS = {"calculator": calculator, "search_notes": search_notes}
def ask_model(messages):
reply = requests.post(
URL,
json={"model": MODEL_NAME, "messages": messages, "stream": False, "format": "json"},
timeout=300,
)
reply.raise_for_status()
return reply.json()["message"]["content"]
def run_agent(task):
messages = [{"role": "system", "content": SYSTEM}, {"role": "user", "content": task}]
for step in range(1, MAX_STEPS + 1):
text = ask_model(messages)
print(f"[step {step}] model said: {text}")
messages.append({"role": "assistant", "content": text})
try:
action = json.loads(text)
except json.JSONDecodeError:
messages.append({"role": "user", "content": 'Reply with valid JSON only.'})
continue
if "answer" in action:
return action["answer"]
tool = TOOLS.get(action.get("tool"))
if tool is None:
result = "Unknown tool. Use calculator or search_notes."
else:
try:
result = tool(str(action.get("input", "")))
except Exception as error: # a bad input should not crash the agent
result = f"Tool error: {error}"
print(f"[step {step}] tool result: {result}")
messages.append({"role": "user", "content": f"Tool result: {result}"})
return "Stopped: reached the step limit without a final answer."
if __name__ == "__main__":
task = " ".join(sys.argv[1:]) or "When does the library close, and how many minutes is that after 5 pm?"
print("\nFinal answer:", run_agent(task)) Check: The file is saved in pdf-chat next to notes.txt.
Run the agent with its built-in question, which needs both tools: find the closing time, then do the sums. The trace prints each step so you can follow its reasoning. Small local models can be slow on a CPU.
python agent.py Check: You see lines like [step 1] model said: {"tool": "search_notes", …}, then tool result: lines, and finally Final answer:. The exact words and number of steps depend on your model.
Learning to read failures is the main skill. Try these three and read the trace each time:
python agent.py "What is the library's phone number?"MAX_STEPS = 1 and run the default question. The agent should stop with the step-limit message.python agent.py "Use the calculator on __import__('os')". The calculator should refuse, and the agent carries on.Use the loop stepper below to see how the limit changes a run.
Check: The program never runs forever, never crashes, and always ends with a final line.
Ideas for later: a third read-only tool, such as today’s date; printing how long each step takes; asking you to confirm (input()) before any tool runs. Keep the cap, and keep every tool the least powerful it can be.
Pick a run, then change MAX_STEPS. This replays a scripted example of the Python loop; it is not a live model.
Task: “When does the library close, and how many minutes is that after 5 pm?”
{"tool": "search_notes", "input": "library"}The library closes at 8 pm on weekdays.{"tool": "calculator", "input": "(20 - 17) * 60"}180{"answer": "It closes at 8 pm, which is 180 minutes after 5 pm."}Final answer: It closes at 8 pm, which is 180 minutes after 5 pm.
A scripted replay of the loop in step 3, not a live model. A real small model will word things differently.
What do you see?
Who actually runs a tool in this agent?
Why does the calculator avoid Python’s eval?
What does MAX_STEPS protect you from?