Skip to content

Grokem · https://www.grokem.com/ai-and-machine-learning/ai-agents/how-to-build-an-ai-agent-in-python-with-a-tool-calling-loop-step-by-step

AI AgentsTutorialBeginner level

How to Build an AI Agent in Python With a Tool-Calling Loop, Step by Step

You build a small AI agent in plain Python: a message history, two tools, and a loop that runs tool calls until the model gives a final answer. A stand-in model keeps the result checkable offline, and you swap in a real one at the end.

Pankaj Nigam

Technical Writer

Published
  • 30 min to complete
  • 0 sec

Tested with
  • Python
  • Python standard library: json and re modules
Your progress
  1. How to Build an AI Agent in Python With a Tool-Calling Loop, Step by Step6 min(finished)
    0%

Before you start

4
  • Python 3 installed and runnable from a terminal (python3 or python)
  • A text editor
  • Basic comfort with Python functions, dictionaries and lists
  • No API key is needed for the main build; you only need one for the optional last step

An AI agent is a language model placed inside a loop. The model either asks for a tool (function calling) or gives a final answer. Your code runs the tool, adds the result to the conversation, and asks the model again. This looping process is what separates a plain model call from an agent.

In this tutorial you build that loop yourself, with no framework and no third-party package. To keep the result checkable on any machine, you first drive the loop with a small scripted stand-in for the model. The loop does not care who produces the replies, so the same code works when you connect a real model later.

Message historyModelTool call orfinal answer?Answerexecute_tool(TOOLS lookup)Tool resultFinal answerTool callmax_steps limit
One pass of the loop: ask the model, run the tool, store the result, repeat.

By the end you have one file, agent.py, that:

  • keeps a message history,
  • looks up tools by name,
  • runs the tool the model asks for,
  • feeds the result back,
  • stops on a final answer or after a step limit.

The model call for a real provider is not shown here, because its request format depends on the provider. Check your provider's official function-calling documentation for that part.

Step 1 of 10: Create the project folder and file

Make a folder and an empty agent.py inside it, then confirm Python runs. A single file keeps every piece of the loop visible at once.

On Windows, use python instead of python3.

bash
mkdir tool-loop-agent
cd tool-loop-agent
touch agent.py
python3 --version

Step 2 of 10: Import the modules and write two tools

Open agent.py and add the imports and two plain Python functions. Tools are ordinary functions: the agent gains abilities by calling them, so start with ones that are easy to check.

add returns a number. word_count returns how many words a text has.

python
import json
import re

def add(a, b):
    return a + b

def word_count(text):
    return len(text.split())

Step 3 of 10: Register the tools in a lookup table

Append a dictionary that maps a tool name to its function and a short description. The model will name a tool as text, so your code needs a safe way to turn that name into a function without running arbitrary strings.

The description is what you would later show to a real model so it can choose between tools.

python
TOOLS = {
    "add": {
        "function": add,
        "description": "Add two numbers. Arguments: a, b.",
    },
    "word_count": {
        "function": word_count,
        "description": "Count the words in a text. Argument: text.",
    },
}

Step 4 of 10: Write a function that runs one tool safely

Append execute_tool. It looks the name up, calls the function with the arguments the model supplied, and always returns a JSON string. Returning an error as text, instead of crashing, lets the model see what went wrong and react.

Two failures are handled: an unknown tool name, and arguments that do not match the function.

python
def execute_tool(name, arguments):
    tool = TOOLS.get(name)
    if tool is None:
        return json.dumps({"error": "unknown tool: " + name})
    try:
        result = tool["function"](**arguments)
    except TypeError as exc:
        return json.dumps({"error": str(exc)})
    return json.dumps(result)

Step 5 of 10: Add a scripted stand-in for the model

Append fake_model. It receives the message history and returns one of two shapes: a tool call, or a final answer. A stand-in makes the run repeatable and free, so you can test the loop before any real model is involved.

This one reads the two numbers from the question and asks for add. When the last message is a tool result, it turns that result into the final answer.

python
def fake_model(messages):
    last = messages[-1]
    if last["role"] == "tool":
        return {"type": "final", "content": "The answer is " + last["content"] + "."}
    numbers = [int(n) for n in re.findall(r"\d+", last["content"])]
    return {
        "type": "tool_call",
        "name": "add",
        "arguments": {"a": numbers[0], "b": numbers[1]},
    }

Step 6 of 10: Write the tool-calling loop

Append run_agent, the heart of the agent. Each pass asks the model for a reply. A final reply ends the loop. A tool call is executed, and both the call and its result are added to the history so the next pass can see them.

The max_steps limit is a guard: without it, a model that keeps asking for tools would loop forever.

python
def run_agent(question, model, max_steps=5):
    messages = [{"role": "user", "content": question}]
    for step in range(1, max_steps + 1):
        reply = model(messages)
        if reply["type"] == "final":
            print(f"[step {step}] final answer")
            return reply["content"]
        name = reply["name"]
        arguments = reply["arguments"]
        print(f"[step {step}] model asks for {name}({arguments})")
        result = execute_tool(name, arguments)
        print(f"[step {step}] tool result: {result}")
        messages.append({"role": "assistant", "tool_call": reply})
        messages.append({"role": "tool", "name": name, "content": result})
    return "Stopped: step limit reached."

Step 7 of 10: Add an entry point and run the agent

Append the entry point, then run the file. You are checking that the loop takes two passes: one to call the tool, one to answer.

python
if __name__ == "__main__":
    answer = run_agent("What is 17 plus 25?", fake_model)
    print("Answer:", answer)
bash
python3 agent.py

Step 8 of 10: Check the output against the expected result

Compare your terminal with the expected output below. Step 1 shows the tool call and its result, and step 2 shows the final answer. If you see this, the loop, the tool lookup and the history all work.

If the lines differ, see the troubleshooting list.

Step 9 of 10: Test the step limit with a model that never stops

Append a second stand-in that always asks for a tool that does not exist, and run it with max_steps=3. This proves two guards at once: the unknown-tool error comes back as data, and the loop ends by itself.

Put this block above the if __name__ line, or replace the entry point with the version below.

python
def stubborn_model(messages):
    return {
        "type": "tool_call",
        "name": "multiply",
        "arguments": {"a": 1, "b": 2},
    }

if __name__ == "__main__":
    print("Answer:", run_agent("What is 17 plus 25?", fake_model))
    print("Answer:", run_agent("Multiply 1 and 2", stubborn_model, max_steps=3))
bash
python3 agent.py

Step 10 of 10: Replace the stand-in with a real model

Write one function with the same shape as fake_model: it takes messages and returns either {"type": "tool_call", "name": ..., "arguments": {...}} or {"type": "final", "content": ...}. Inside it, call your provider and convert its reply into those two shapes. Because run_agent only depends on that shape, nothing else changes.

The request and response format, the way tools are described to the model, and the parameter names differ by provider. Read your provider's official function-calling page for them, and keep your API key in an environment variable, never in the file. Pass your new function as the model argument of run_agent.


Expected result

After step 7 (first version of the entry point): [step 1] model asks for add({'a': 17, 'b': 25}) [step 1] tool result: 42 [step 2] final answer Answer: The answer is 42. After step 9 (the first run is repeated, then the step-limit test): [step 1] model asks for add({'a': 17, 'b': 25}) [step 1] tool result: 42 [step 2] final answer Answer: The answer is 42. [step 1] model asks for multiply({'a': 1, 'b': 2}) [step 1] tool result: {"error": "unknown tool: multiply"} [step 2] model asks for multiply({'a': 1, 'b': 2}) [step 2] tool result: {"error": "unknown tool: multiply"} [step 3] model asks for multiply({'a': 1, 'b': 2}) [step 3] tool result: {"error": "unknown tool: multiply"} Answer: Stopped: step limit reached.

Troubleshooting

ProblemLikely causeFix
command not found: python3 (or 'python' is not recognized)Python is not installed, or your system uses a different command name.Install Python 3 from the official Python site, then try python instead of python3, or py on Windows.
IndexError: list index out of range inside fake_modelThe question passed to run_agent has fewer than two whole numbers, so the stand-in cannot read both arguments.Use a question with two numbers, such as "What is 17 plus 25?". A real model does not have this limit.
Nothing is printed when you run agent.pyThe entry point is missing, or it is indented inside another block.Make sure the if __name__ == "__main__": line starts at the left margin and its body is indented by four spaces.
NameError: name 'stubborn_model' is not definedThe entry point that uses stubborn_model sits above its definition, or two entry points exist.Define stubborn_model before the if __name__ line and keep only one entry-point block.
The tool result is {"error": "... unexpected keyword argument ..."}The model sent argument names that do not match the function's parameters.Compare the keys in arguments with the function signature (a and b for add, text for word_count) and fix the model's reply.
The loop prints "Stopped: step limit reached." for a normal questionThe model never returns a final reply, or the tool result is not added to the history.Check that both append lines in run_agent run after every tool call, and that your model function returns type final once it has a tool result.

Frequently asked questions

What makes a program an AI agent rather than a single model call?

The loop. An agent keeps asking the model, runs the tools it requests and feeds the results back until the model gives a final answer. A single call has no such cycle.

Do I need a framework to build an agent?

No. The loop in this tutorial uses only the json and re modules from the Python standard library. Frameworks wrap the same idea.

Why use a fake model first?

It makes the run repeatable, free and offline, so you can test the loop, the tool lookup and the step limit before debugging a provider.

Why does the loop need a step limit?

A model can keep requesting tools without ever finishing. The limit guarantees the program ends, as the unknown-tool test in step 9 shows.

Why return errors as text instead of raising them?

The model can read an error message in the history and try a different tool or arguments. An exception would stop the whole agent.

How do I connect a real model?

Write a function that takes the messages, calls your provider and returns either a tool call or a final reply in the shapes used here. The request format is in your provider's official documentation.

Next steps

  • Add a third tool, register it in TOOLS, and write a stand-in reply that calls it.
  • Let the model call two tools in a row before answering, and check the history after each pass.
  • Connect a real model by following your provider's official function-calling documentation.
  • Add memory by keeping the message history between questions instead of starting a new list.

From Grokem: https://www.grokem.com/ai-and-machine-learning/ai-agents/how-to-build-an-ai-agent-in-python-with-a-tool-calling-loop-step-by-step

Finished this article?

How did this strike you?

Be the first to react – it is anonymous.

Community

Questions about this?

Ask in Questions and help and get help from other readers.

Ask a questionBrowse Questions and help

Comments

No comments yet. Share what worked for you, or ask a question.

Keep learning

Picked for this article

Related reading, discussions and learning paths on the same subject.

All in AI Agents

From the community

Learning paths

Learning pathBeginner

Infrastructure basics for data work

The ground a data project stands on: the command line, how a name finds a server, packaging an app in a container, where files and databases live, keeping secrets out of code, backups you have tested and a cloud bill you control.

7 lessonsabout 15 minStart

Learning pathIntermediate

SQL for data work

From removing duplicates and window functions to modelling for reporting, cohort analysis, indexes and query plans: the SQL a working analyst or engineer uses every week, each lesson with queries that were run.

8 lessonsabout 90 minStart

Choose what we may use. You can change this at any time with “Privacy choices” at the foot of every page. Details are in the Cookie policy and the Privacy policy.

Strictly necessary

Remembers your theme, the lessons you marked as done and this choice. It stays on your device, tracks nothing and cannot be switched off.

Always on
What exactly is collected, and why

Google Analytics

Collects
The pages you view, your device and browser type, your language, how you reached the site and your approximate location (country and city, worked out from your IP address).
Why
To understand which pages and lessons are used, so we can improve them.
Stored
Two cookies, _ga and _ga_<id>, for up to 2 years. Google acts for us; the data is processed by Google, including outside your country.

Grokem’s own counts

Collects
The pages you open and how long you stay, how far you scroll, where you came from, your device type, browser, screen size, language and time zone. Your IP address is turned into a code that changes every day; it is never stored as it is.
Why
To see how long lessons are read and where readers leave. Not shared with anyone.
Stored
A random visitor ID, a visit ID and the time of your last page view in your browser’s storage (gr_vid, gr_sid, gr_last). No name or email is attached.