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.
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.
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.
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.
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.
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.
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.
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.
if __name__ == "__main__":
answer = run_agent("What is 17 plus 25?", fake_model)
print("Answer:", answer)
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.
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))
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
| Problem | Likely cause | Fix |
|---|---|---|
| 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_model | The 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.py | The 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 defined | The 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 question | The 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









