Skip to content
Tutorials Center
My learning

Topics

Lesson 49 of 53 ยท Projects

Project: A Tool-Using Agent

Build a small agent in Python: a tool registry, a ReAct loop, safety limits, a readable trace and tests that run against a scripted fake model.

In this project you build a complete, small agent: a program that lets a language model decide which tools to call, runs those tools for it, feeds the results back and repeats until the model gives a final answer. You have met the ideas in Tool Use and Function Calling and Building an Agent Loop. Here you put them together into one tidy piece of software with limits, logs and tests.

No model API is reachable from the browser, so the "model" in our examples is a plain Python function that plays a fixed role. That is not a cheat: it is how professional agent code is tested. Everything around the model (the registry, the parser, the limits, the trace) is real and works unchanged with a real API. You only replace one function.

Four parts of the agent

Tool registry Names, descriptions and safe functions.
Loop Ask the model, run the tool, repeat.
Limits Step cap, repeat guard, output cap.
Trace A log of every step.

The model is one swappable function.

1 / 2

The design in one picture

The loop is small. The model sees the conversation, answers with either an action or a final answer, and our code does the rest. Errors are not exceptions that crash the program: they become observations the model can read and react to.

flowchart TD
    A["Question"] --> B["Model reply"]
    B -->|"Final Answer"| E["Return answer"]
    B -->|"Action: tool[input]"| C["Check limits and run tool"]
    C --> D["Observation (or error text)"]
    D --> B
    C -->|"Step limit reached"| F["Stop with status step_limit"]

Observations flow back to the model; only a final answer or a limit ends the loop.

We use the text format from the ReAct pattern, because it is easy to read and to parse:

TEXT
Thought: I need the height of the Eiffel Tower.
Action: search[eiffel tower height]

or, when the model is done, Final Answer: .... Real APIs offer structured tool calls instead (see function calling), and then the parser disappears, but the rest of the design stays the same.

Step 1: a tool registry

A registry is a dictionary from tool name to a function plus a description. A decorator keeps registration next to the function, and the descriptions are later pasted into the system prompt, so the model learns what exists from the same place the code does.

Two tools are enough: a calculator and a tiny knowledge-base search. The calculator deserves care. It would be easy to call eval() on whatever the model sends, and that would let a manipulated model run arbitrary Python. Instead we parse the expression with the ast module and accept only numbers and a few operators. Everything else is rejected.

Finally, run_tool is the single door through which every call passes. It never raises: unknown tools and failing tools both turn into a short Error: ... string. A model that reads "unknown tool 'wiki'. Available: calculator, search" can correct itself on the next step.

Python A tool registry with a safe calculator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Never pass model output to eval(), exec(), a shell or a SQL string. The model's text is untrusted input, just like a form field. If a tool must do something powerful, give it a narrow, validated interface. See Prompt Injection and LLM Security.

Step 2: the loop with safety limits

Now the heart of the project. run_agent keeps a list of messages (the conversation the model sees) and a trace (a log for humans). On every step it:

  1. calls the model with the messages;
  2. looks for Final Answer:. If found, it stops with status done;
  3. otherwise looks for Action: name[input]. If the reply has neither, it answers with a hint and lets the model try again;
  4. refuses a call that is identical to an earlier one, because a model that repeats itself is usually stuck;
  5. runs the tool, truncates the observation to max_chars so one huge result cannot fill the context window, and appends it as the next user message;
  6. gives up after max_steps and returns status step_limit.

The returned dictionary always has the same shape (status, answer, steps, trace), whatever happened. That makes the agent easy to call from other code and easy to test.

To run the loop we need a model. planner below is a scripted fake model: it looks at how many observations it has received and replies accordingly, even reading numbers out of earlier observations to build the calculator call. It plays the part of a well-behaved model solving the question "how many times taller is Mount Everest than the Eiffel Tower?".

Python The agent loop with a trace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The printed trace reads like a short story: thought, call, result, repeat, final answer. This is the most valuable debugging tool an agent project has. When a real model misbehaves, you open its trace and see exactly which step went wrong, which tool it called and what it saw. In production you would write the same records as JSON lines to a log file and attach a request ID, as described in Deploying and Monitoring LLM Apps.

Notice what the agent does not do. It does not decide anything itself; every decision comes from model(messages). To use a real API you would write a function with the same signature that sends messages to the provider and returns the reply text. The rest of the code would stay as it is.

Truncating observations is a blunt tool. A smarter agent summarizes long results or stores them outside the conversation and passes a reference. See Memory, Planning and Context Management.

Step 3: tests with a scripted model

An agent is hard to test when the model is random and costs money. With a scripted model it becomes ordinary software: you decide exactly what the "model" says, and assert what the loop does. Each test below targets one guard:

  • the happy path finishes in four steps with the right answer;
  • an unknown tool is reported as an observation instead of crashing;
  • a runaway model that never finishes is stopped by the step limit;
  • a repeated call is blocked;
  • a malformed reply gets a hint;
  • the calculator refuses code and huge exponents;
  • a flood of output is truncated.

The tiny runner at the bottom finds every function whose name starts with test_. It is a stand-in for Pest or pytest, but the test functions would run unchanged under pytest.

Python Seven tests for the agent

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Try breaking the agent on purpose. Change max_steps=3 to max_steps=4 in the runaway test and watch it fail; delete the seen check in run_agent and see which test notices. A test that cannot fail is not testing anything.

Extending the project

Once the basics work, here are good next steps, roughly in order of value:

  • Add a tool. Write current_date(argument) that returns a fixed date, decorate it, and write a test where the scripted model uses it. Descriptions in the system prompt update automatically.
  • Validate arguments. Tools that need several arguments should take JSON and validate it, as in Getting Structured Output (JSON).
  • Budget more than steps. Track tokens and money, not just the number of calls. See Counting Tokens and Estimating Cost.
  • Ask before dangerous actions. For tools that send email or delete data, add a confirmation step that a human must approve.
  • Evaluate it. Collect ten questions with known answers and score the agent on all of them every time you change a prompt, as in Project: An Evaluation Harness.

Remember the rule of thumb from MCP, Workflows and Multi-Agent Systems: if a fixed sequence of steps solves the task, write a plain workflow. Reach for an agent only when the path really depends on what the tools return.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does run_tool turn every failure into an 'Error: ...' string instead of raising?

    Errors become observations. The model sees what went wrong and can try a different tool or input, while the program keeps running.
  2. 2. What is the main reason the calculator parses the expression with ast instead of calling eval()?

    Model output is untrusted. Whitelisting numbers and a few operators means nothing else can execute.
  3. 3. A model keeps replying with the same Action and never gives a final answer. Which guards stop it?

    The repeat check tells the model it is repeating itself, and max_steps guarantees the loop ends with status step_limit.
  4. 4. What makes a scripted fake model useful in tests?

    You choose each reply, so you can trigger every branch of the loop and assert exactly what it does without calling an API.

Summary

  • An agent is a loop around one swappable function, the model, plus a registry of tools.
  • A registry maps names to functions and descriptions; the descriptions go into the system prompt.
  • Route every tool call through one function that never raises and returns error text instead.
  • Guard the loop: a step limit, a repeated-call check, truncated observations and no eval.
  • A trace of thought, call and result for every step is the best debugging aid.
  • A scripted model turns agent behavior into ordinary, deterministic tests.

Next: switch from using models to building one in Project: A Tiny Character-Level Language Model.