A person feeds a message card into a Python-powered machine whose pipes loop messages through a brain and a tool panel with a wrench, table and magnifier until a DONE crate comes out.

Build an AI Agent From Scratch in Python: The Agentic Loop

by Stephen Gruppetta Updated Reading time estimate 41m intermediate ai

You know how LLMs work, and you may already use AI agents to help you write code. However, an LLM isn’t an agent. What sits between them is the agentic loop. In this tutorial, you’ll build an AI agent from scratch in Python by writing the harness that turns a language model into an agent. You’ll do this in about ninety lines of code, with no frameworks.

By the end of this tutorial, you’ll understand that:

  • An AI agent is a language model wrapped in a harness, which is a loop that passes information between you, the model, and a set of tools.
  • The Chat Completions API doesn’t remember earlier messages between calls, so the harness resends the whole conversation context with every request.
  • A tool is any action the harness can perform for the model, such as running a Python function. The model learns about the tool only through its description, which includes a JSON schema for its arguments.
  • The model never runs a tool itself. It returns a tool call, and the harness decides whether to run the tool and send back the result.
  • Running the model in a loop lets it chain tool calls, using each result to decide its next step until it has an answer.

You’ll start with a single call to an LLM, which fails at the very first task you give it. Each step that follows moves you closer to fixing that failure, until the model can explore a folder it has never seen and summarize what’s inside. Here’s a glimpse of the agent you’ll build, as it asks the harness to run two tools, one after the other, before it answers:

Language: Text
  [model -> harness] please run list_files{"folder":"habits"}
  [harness -> tool] list_files({'folder': 'habits'})
  [tool -> harness] 31 characters
  [harness -> model] sending 3 message(s)
  [model -> harness] please run read_file{"path":"habits/habits.py"}
  [harness -> tool] read_file({'path': 'habits/habits.py'})
  [tool -> harness] 664 characters
  [harness -> model] sending 5 message(s)
  [model -> harness] text reply (538 characters)

You can download the code for each step and the sample habits folder that the agent explores by clicking the link below:

Take the Quiz: Test your knowledge with our interactive “Build an AI Agent From Scratch in Python: The Agentic Loop” quiz. You’ll receive a score upon completion to help you track your learning progress:


Interactive Quiz

Build an AI Agent From Scratch in Python: The Agentic Loop

Test your understanding of how an AI agent works in Python, from the harness and conversation context to tool calls and the agentic loop.

Prerequisites and Setup

You should be comfortable with the following topics to get the most out of this tutorial:

You don’t need any experience with AI agents or agent frameworks. If you don’t have all of the prerequisite knowledge before you start, that’s okay. You can always stop and review the resources linked here if you get stuck.

Set Up the Project and Your API Key

You’ll talk to a model through the OpenAI Python library, so you’ll need an OpenAI API key. This tutorial uses Python 3.15 and uv to manage the project, so you’ll need to install uv if you don’t have it. You can create a project and add the library to it:

Language: Shell
$ uv init --python 3.15 ai-agent
$ cd ai-agent
$ uv add openai==3.31.0

If you have Git installed, the uv init command also creates a Git repository with a .gitignore file. Before you save your API key anywhere, add .env to the end of .gitignore so that you don’t commit your key by accident:

Language: Text Filename: .gitignore
# ...

.env

Next, create a file named .env in the ai-agent/ folder and place your API key in it:

Language: Text Filename: .env
OPENAI_API_KEY=<your-api-key>

The OpenAI library reads your API key from the OPENAI_API_KEY environment variable. You can ask uv to load the .env file into the environment every time you use uv run in that terminal session by setting the UV_ENV_FILE variable. Select your operating system below:

Language: Windows PowerShell
PS> $env:UV_ENV_FILE = ".env"
Language: Shell
$ export UV_ENV_FILE=.env

Every API call in this tutorial costs a small amount of money, so you’ll need to set up billing for your OpenAI account. Throughout this tutorial, you’ll use gpt-6-luna, a capable, inexpensive model.

Meet the habits Folder

The downloadable materials include a folder called habits. Place it inside your ai-agent/ project folder, next to the script you’ll write. Your project should look like this:

ai-agent/
│
├── habits/
│   └── ...
│
├── .env
├── ai_agent.py
└── pyproject.toml

The uv init command also creates a few other files, such as main.py and README.md. You won’t need them in this tutorial, so you can leave them alone or delete them.

You won’t look inside habits in this tutorial, and that’s on purpose. First, its contents don’t matter. Second, finding out what’s in it is the job you’ll give your agent.

Step 1: Talk to an LLM Directly

Before you build anything around a model, you can see what it does on its own. In this step, you’ll send a single question to an LLM and print its answer.

The finished code for this step is in source_code_step_1/ in the materials you downloaded earlier.

Create a file named ai_agent.py and add the following code:

Language: Python Filename: ai_agent.py
from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "What's in the habits folder?"}],
)

print(response.choices[0].message.content)

The OpenAI object is the client you use to talk to the models hosted by OpenAI. You’ll call client.chat.completions.create() every time you want to send something to the model. This method uses OpenAI’s Chat Completions API. You pass the name of the model and a list of messages.

Each message is a dictionary with a role and some content. The role tells the model who sent the message. In this case, you’re the user. Later in this tutorial, you’ll also see messages that come from the model itself and from tools. The messages argument is a list because a conversation usually has more than one message, even though you have only one so far.

The object returned by .create() has a .choices attribute. The name is plural because the API can return more than one response. However, you’ll ask for only one, so you can take the first item and fetch the text from its .message.content attribute.

You can run the script from your terminal:

Language: Shell
$ uv run ai_agent.py
I can't access your device's folders from here. If you share the folder
contents or paste a file listing, I can tell you what's in it.

You’ve sent a message to a language model and received a reply. However, the reply is a polite refusal. The model can’t read what’s in habits. In this request, all it can do is receive text and return text.

Your output will differ from the example shown here and from the output of any other run of the same script. LLMs rarely give the same reply twice. However, the overall message will be the same, and that’s what matters in this tutorial.

Step 2: Wrap the Model in a Harness

In the previous step, the model told you it couldn’t access your files. That’s true, and it’ll stay true. The model will never read a file directly. Instead, you’ll build infrastructure around the model to access files on its behalf. This infrastructure is the harness, and it starts as a plain while loop.

The finished code for this step is in source_code_step_2/ in the materials you downloaded earlier.

Create the Harness Loop

Instead of hard-coding a single question, you can let the user type messages in a loop. You’ll also move the model’s name into a constant so that you only need to change it in one place:

Language: Python Filename: ai_agent.py
from openai import OpenAI

client = OpenAI()
MODEL = "gpt-6-luna"

while True:
    user_input = input("you -> harness: ")
    messages = [{"role": "user", "content": user_input}]

    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
    )
    reply = response.choices[0].message

    print(f"harness -> you: {reply.content}")

The while True loop is the harness. Notice the prompt in input(). You’re no longer sending your question directly to the model. You’re sending it to the harness, which builds the list of messages and passes it on to the model. When the reply comes back, it goes to the harness first, and the harness passes it on to you.

You’ll also notice that the reply is now the .message object itself, rather than its .content. You’ll need the whole object later in this tutorial.

The loop keeps running. You can stop it at any time by pressing Ctrl+C.

Trace the Flow of Information

Before you run the script, you’ll add a helper function called trace() that prints a line every time information moves from one part of the system to another. You can call it just before the harness sends a message to the model and just after the reply comes back:

Language: Python Filename: ai_agent.py
from openai import OpenAI

client = OpenAI()
MODEL = "gpt-6-luna"

def trace(sender, receiver, text):
    print(f"  [{sender} -> {receiver}] {text}")

while True:
    user_input = input("you -> harness: ")
    messages = [{"role": "user", "content": user_input}]

    trace("harness", "model", "sending a message")
    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
    )
    reply = response.choices[0].message
    trace("model", "harness", f"text reply ({len(reply.content)} characters)")

    print(f"harness -> you: {reply.content}")

Each line that trace() prints shows who’s sending, who’s receiving, and a short description of what’s being sent. When the model replies, the trace shows the length of the reply rather than the reply itself, which keeps the output short.

You’ll build an agent with several moving parts, and most of what happens is invisible unless you print it. The trace lines make the flow visible, and you’ll read them after every run to follow what’s happening behind the scenes.

You can run the script and ask the same question as before:

Language: Shell
$ uv run ai_agent.py
you -> harness: What's in the habits folder?
  [harness -> model] sending a message
  [model -> harness] text reply (129 characters)
harness -> you: I can't see your files or folders from here. If you paste the
folder listing or upload its contents, I can tell you what's in it.

You can follow the trace line by line. You send your question to the harness. The harness sends a message to the model. The model sends a text reply of 129 characters back to the harness, and the harness passes the reply on to you.

The model still can’t see the folder, which is no surprise since nothing has changed from the model’s point of view. However, the harness keeps running and waits for your next message. That’s where the next problem shows up.

Step 3: Give the Harness a Short-Term Memory

The harness from the previous step lets you keep chatting since it has a while True loop. In the same session, you can ask a follow-up question that refers back to the folder. Here’s the whole session so far, with the new lines highlighted:

Language: Shell
$ uv run ai_agent.py
you -> harness: What's in the habits folder?
  [harness -> model] sending a message
  [model -> harness] text reply (129 characters)
harness -> you: I can't see your files or folders from here. If you paste the
folder listing or upload its contents, I can tell you what's in it.
you -> harness: Can you look inside it for me?
  [harness -> model] sending a message
  [model -> harness] text reply (99 characters)
harness -> you: Sure—what would you like me to look inside? Upload a photo or
file, or tell me what "it" refers to.

The model asks what “it” refers to, even though you mentioned the habits folder in your previous message. So why doesn’t the model know what you were talking about?

You can find the answer in the harness. Every time the loop runs, it creates a new list called messages that contains only your latest message. The model therefore receives only that message with each request. It doesn’t store anything between API calls. Every request starts with a blank slate.

The finished code for this step is in source_code_step_3/ in the materials you downloaded earlier.

The fix is to give the harness a short-term memory. You create the list of messages once, before the loop starts, and keep adding to it:

Language: Python Filename: ai_agent.py
from openai import OpenAI

client = OpenAI()
MODEL = "gpt-6-luna"

def trace(sender, receiver, text):
    print(f"  [{sender} -> {receiver}] {text}")

messages = []

while True:
    user_input = input("you -> harness: ")
    messages.append({"role": "user", "content": user_input})

    trace("harness", "model", f"sending {len(messages)} message(s)")
    response = client.chat.completions.create(
        model=MODEL,
        messages=messages,
    )
    reply = response.choices[0].message
    messages.append(reply)
    trace("model", "harness", f"text reply ({len(reply.content)} characters)")

    print(f"harness -> you: {reply.content}")

You make two changes to how you handle messages. You append each new user message to messages instead of creating a new list. You also append the model’s reply because its responses are part of the conversation, too. The reply isn’t a dictionary like your message, but it already contains the role "assistant" and the reply’s content, so the API accepts it in the list.

This list is the conversation context, and the harness sends all of it to the model with every request. The trace now shows how many messages the harness sends each time.

You can run the script and try the same two questions:

Language: Shell
$ uv run ai_agent.py
you -> harness: What's in the habits folder?
  [harness -> model] sending 1 message(s)
  [model -> harness] text reply (120 characters)
harness -> you: I can't access your folders from here. Share the folder
listing or upload its contents, and I can tell you what's in it.
you -> harness: Can you look inside it for me?
  [harness -> model] sending 3 message(s)
  [model -> harness] text reply (150 characters)
harness -> you: I don't have access to your device's folders in this chat. If
you upload the "habits" folder or paste its file listing, I can look through
it for you.

The first request sends one message. The second request sends three: your first question, the model’s first reply, and your follow-up. This time, the model knows that “it” is the habits folder.

Resending the conversation context is also why long conversations with an LLM cost more than short ones. Every new request sends the whole conversation, which includes all your messages and all the model’s replies. Even if you just type “thank you” at the end of a long chat, the model receives every message that came before it. The whole conversation also has to fit in the model’s context window, so a very long chat will eventually fail.

You now have a chat with an LLM that can follow a conversation. However, you don’t have an agent yet.

Step 4: Describe a Tool the Model Can Request

The model now follows the conversation. It knows you’re asking about the habits folder, but it still replies, “I don’t have access to your device’s folders in this chat.” It can talk about the folder, but it can’t do anything about it.

To act, the model needs tools, which the harness runs on its behalf. A tool is any action the harness can perform, such as listing files, reading a file, or calling a web service. In the agent you’ll build, each tool is a Python function. In this step, you’ll write your first tool and tell the model about it.

The finished code for this step is in source_code_step_4/ in the materials you downloaded earlier.

Write the First Tool

The first tool lists the files in a folder. You can define it near the top of ai_agent.py:

Language: Python Filename: ai_agent.py
from pathlib import Path

from openai import OpenAI

client = OpenAI()
MODEL = "gpt-6-luna"

def list_files(folder):
    return "\n".join(path.name for path in Path(folder).iterdir())

# ...

The function creates a Path object from the folder name and uses .iterdir() to iterate through the items in that folder. It then joins their names into a single string, with each name on a new line. There’s nothing specific to AI in list_files(). It’s a regular Python function that returns a string.

Describe the Tool With a Schema

The harness can call list_files() whenever it needs to. However, the model needs to know that the tool exists. You describe each tool in a format that the OpenAI API understands, which includes a schema. A schema describes the shape of the tool’s arguments, such as {"folder": "habits"}, where folder is the parameter and "habits" is the value the model chooses. The description is mostly boilerplate code:

Language: Python Filename: ai_agent.py
# ...

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "list_files",
            "description": "List the files in a folder.",
            "parameters": {
                "type": "object",
                "properties": {"folder": {"type": "string"}},
                "required": ["folder"],
            },
        },
    },
]

# ...

Each item in the TOOLS list describes one tool. Here’s what each part of the description does:

  • "name" matches the name of the function, list_files.
  • "description" tells the model what the tool does. This is the only explanation the model gets, so keep it clear.
  • "parameters" describes the function’s parameters as a JSON schema. The "properties" dictionary lists one parameter, folder, which is a string.
  • "required" tells the model that it should always provide folder, since list_files() won’t work without it.

The model never sees your Python function. It sees only this description, which tells it what the tool does and what arguments to pass.

Pass the Tool to the Model

You can pass TOOLS to the model in the main loop. For now, you’ll print whatever tool calls come back with the reply. You can also comment out the trace for the model’s reply, since a reply with a tool call may not contain any text. You’ll restore the trace with a new version in the next step:

Language: Python Filename: ai_agent.py
# ...

while True:
    user_input = input("you -> harness: ")
    messages.append({"role": "user", "content": user_input})

    trace("harness", "model", f"sending {len(messages)} message(s)")
    response = client.chat.completions.create(
        model=MODEL,
        tools=TOOLS,
        messages=messages,
        reasoning_effort="none",
    )
    reply = response.choices[0].message
    messages.append(reply)
    # trace("model", "harness", f"text reply ({len(reply.content)} characters)")
    print(reply.tool_calls)

    print(f"harness -> you: {reply.content}")

You also set reasoning_effort to "none". The reasoning effort controls how much the model thinks before it replies. The Chat Completions API doesn’t support function tools with any other reasoning effort for gpt-6-luna, and it raises a BadRequestError if you leave the argument out.

You can run the script and ask the familiar question once more:

Language: Shell
$ uv run ai_agent.py
you -> harness: What's in the habits folder?
  [harness -> model] sending 1 message(s)
[ChatCompletionMessageFunctionToolCall(
    id='call_s5va3nhg2PuXeeHPnNjANV1c',
    function=Function(arguments='{"folder":"habits"}', name='list_files'),
    type='function',
)]
harness -> you: None

This time, the model doesn’t reply with text. The content of the reply is None, and the harness has nothing to tell you. Instead, the reply contains a tool call. The model is asking the harness to call list_files with the argument folder set to "habits".

You never told the model that the tool’s argument should be "habits". You asked a question in plain English, and the model worked out which tool could answer it and which argument to pass. Notice that the tool call also has an ID. You’ll need it in the next step.

This version of the harness can’t answer a tool call yet, so stop the script with Ctrl+C before you type another message. You’ll fix that in the next step.

Step 5: Run the Tool and Send the Result Back

In the previous step, the model requested a tool, and the harness printed None and moved on. Nobody ran list_files(), and the model never found out what’s in habits. In this step, the harness will run the tool and send the result back to the model.

The finished code for this step is in source_code_step_5/ in the materials you downloaded earlier.

Split Out ask_model() and run_tool()

The harness now does two different jobs. It asks the model something, and it runs tools when the model asks it to. You can move each job into its own function. The first one, ask_model(), contains the code that talks to the model:

Language: Python Filename: ai_agent.py
# ...

def ask_model(messages):
    trace("harness", "model", f"sending {len(messages)} message(s)")
    response = client.chat.completions.create(
        model=MODEL,
        tools=TOOLS,
        messages=messages,
        reasoning_effort="none",
    )
    reply = response.choices[0].message
    messages.append(reply)

    for call in reply.tool_calls or []:
        trace(
            "model",
            "harness",
            f"please run {call.function.name}{call.function.arguments}",
        )
    if reply.content:
        trace(
            "model",
            "harness",
            f"text reply ({len(reply.content)} characters)",
        )

    return reply

# ...

The first half of ask_model() is the code you already had in the loop. The second half replaces the trace you commented out in the previous step. A reply can contain tool calls, text, or both, so there’s a trace for each case. A single reply can also contain more than one tool call, which is why the trace for tool calls is in a for loop.

When there are no tool calls, .tool_calls is None. In that case, the expression reply.tool_calls or [] gives the for loop an empty list, so the loop doesn’t run.

The traces for tool calls and text replies go from the model to the harness. The model only ever talks to the harness, never to you directly.

The second function, run_tool(), runs a single tool call:

Language: Python Filename: ai_agent.py
import json
# ...

def run_tool(call):
    args = json.loads(call.function.arguments)
    trace("harness", "tool", f"{call.function.name}({args})")
    result = list_files(**args)
    trace("tool", "harness", f"{len(result)} characters")
    return result

# ...

The model sends the arguments as a JSON string, so you convert them into a dictionary with json.loads(). You then call list_files() and unpack the dictionary so that each key becomes a keyword argument. The function returns the result, and the trace shows its length.

You may have noticed that list_files() is hard-coded in run_tool(). There’s only one tool for now, and this keeps the code focused on what’s happening. You’ll change this in the next step.

Send the Result Back to the Model

You can now use ask_model() and run_tool() in the main loop:

Language: Python Filename: ai_agent.py
# ...

while True:
    user_input = input("you -> harness: ")
    messages.append({"role": "user", "content": user_input})
    reply = ask_model(messages)

    if reply.tool_calls:
        for call in reply.tool_calls:
            result = run_tool(call)
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result,
                },
            )

        reply = ask_model(messages)

    print(f"harness -> you: {reply.content}")

When the reply contains tool calls, the harness runs each one. It then adds the result to messages as a new message with the role "tool". The "tool_call_id" key links the result to the tool call that asked for it, using the ID you saw in the previous step. Once all the tool calls have run, the harness sends the conversation back to the model in the line reply = ask_model(messages). The model can now see the results.

When the reply contains no tool calls, the harness skips the if block and prints the reply.

The diagram below shows how information flows through the harness. You talk to the harness, and the harness talks to the model and to the tools. The model and the tools never talk to each other or to you:

Diagram of a person connected to a harness box, where a while True loop exchanges messages with the model and calls a tools box containing list_files().
A Language Model Wrapped in a Harness

The model may not always choose the same tools as in the examples here. If the harness crashes, for example because the model passes a file to list_files(), restart it and try again. You can run the script and ask the same question you’ve been asking throughout this tutorial:

Language: Shell
$ uv run ai_agent.py
you -> harness: What's in the habits folder?
  [harness -> model] sending 1 message(s)
  [model -> harness] please run list_files{"folder":"habits"}
  [harness -> tool] list_files({'folder': 'habits'})
  [tool -> harness] 31 characters
  [harness -> model] sending 3 message(s)
  [model -> harness] text reply (86 characters)
harness -> you: The `habits` folder contains three files: `README.md`,
`habits.json`, and `habits.py`.

You can follow the trace line by line:

  1. The harness sends your question to the model as one message.
  2. The model asks the harness, “Please run list_files with the folder habits.” It can’t run the tool itself. All it can do is ask nicely: “Dear harness, can you please call the tool for me?”
  3. The harness calls the tool, and the tool returns a string of 31 characters to the harness.
  4. The harness sends three messages to the model: your question, the model’s tool call, and the tool’s result.
  5. The model now has what it needs, so it sends a text reply to the harness, which passes it on to you.

The answer is correct. Those are the three files in habits. A real harness might make a decision at item 3 in the list above, such as asking you for permission before running the tool. Your harness runs the tool immediately.

Good job! The model asked for a tool, the harness ran it, and the model used the result to answer your question.

Step 6: Add Tools Without Hard-Coding Names

The model can now list the files in a folder. To see how it handles a harder question, you can ask a follow-up in the same session. Here’s the whole session, with the new lines highlighted:

Language: Shell
$ uv run ai_agent.py
you -> harness: What's in the habits folder?
  [harness -> model] sending 1 message(s)
  [model -> harness] please run list_files{"folder":"habits"}
  [harness -> tool] list_files({'folder': 'habits'})
  [tool -> harness] 31 characters
  [harness -> model] sending 3 message(s)
  [model -> harness] text reply (86 characters)
harness -> you: The `habits` folder contains three files: `README.md`,
`habits.json`, and `habits.py`.
you -> harness: Can you read the contents of the .py file?
  [harness -> model] sending 5 message(s)
  [model -> harness] please run list_files{"folder":"habits"}
  [harness -> tool] list_files({'folder': 'habits'})
  [tool -> harness] 31 characters
  [harness -> model] sending 7 message(s)
  [model -> harness] text reply (154 characters)
harness -> you: I can see that `habits.py` is in the folder, but I don't have
a tool here to open or read its contents. If you paste the file text, I can
help explain it.

The model lists the files again, even though the answer is already in the conversation context. It wants to know which .py files the folder contains. That makes sense. The contents of the folder may have changed since your first question.

However, once it finds habits.py, it gets stuck. The model knows exactly what’s missing, and it says so: it doesn’t have a tool that reads files.

The finished code for this step is in source_code_step_6/ in the materials you downloaded earlier.

Add a read_file() Tool

Adding a new tool requires two changes. You define the function, and you describe it in TOOLS:

Language: Python Filename: ai_agent.py
# ...

def list_files(folder):
    return "\n".join(path.name for path in Path(folder).iterdir())

def read_file(path):
    return Path(path).read_text()

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "list_files",
            "description": "List the files in a folder.",
            "parameters": {
                "type": "object",
                "properties": {"folder": {"type": "string"}},
                "required": ["folder"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read a text file and return its contents.",
            "parameters": {
                "type": "object",
                "properties": {"path": {"type": "string"}},
                "required": ["path"],
            },
        },
    },
]

# ...

The new function, read_file(), uses Path.read_text() to return the contents of a file as a string. Its description in TOOLS follows the same pattern as the first tool, with a single required parameter called path, which needs to be a string.

Map Tool Names to Functions

There’s still a problem in run_tool(): it calls list_files() regardless of which tool the model asks for. You can replace the hard-coded name with a dictionary that maps each tool name to its function:

Language: Python Filename: ai_agent.py
# ...

TOOL_FUNCTIONS = {
    "list_files": list_files,
    "read_file": read_file,
}

# ...

def run_tool(call):
    args = json.loads(call.function.arguments)
    trace("harness", "tool", f"{call.function.name}({args})")
    result = TOOL_FUNCTIONS[call.function.name](**args)
    trace("tool", "harness", f"{len(result)} characters")
    return result

# ...

Notice that list_files and read_file have no parentheses in TOOL_FUNCTIONS. You’re storing the functions themselves, so TOOL_FUNCTIONS[call.function.name] gets the function and (**args) calls it.

The harness now looks up the function using the name the model sent. To add a third tool, you’d need only a function, a description in TOOLS, and one more entry in TOOL_FUNCTIONS.

You can restart the script and ask about the folder, then ask for the file directly:

Language: Shell
$ uv run ai_agent.py
you -> harness: What's in the habits folder?
  [harness -> model] sending 1 message(s)
  [model -> harness] please run list_files{"folder":"habits"}
  [harness -> tool] list_files({'folder': 'habits'})
  [tool -> harness] 31 characters
  [harness -> model] sending 3 message(s)
  [model -> harness] text reply (74 characters)
harness -> you: The `habits` folder contains:

- `README.md`
- `habits.json`
- `habits.py`
you -> harness: Read the habits.py file and tell me what's in it.
  [harness -> model] sending 5 message(s)
  [model -> harness] please run read_file{"path":"habits/habits.py"}
  [harness -> tool] read_file({'path': 'habits/habits.py'})
  [tool -> harness] 664 characters
  [harness -> model] sending 7 message(s)
  [model -> harness] text reply (556 characters)
harness -> you: `habits.py` is a small command-line habit tracker. It:

- Loads habit data from `habits.json`, or starts with an empty dictionary if
  the file doesn't exist.
- Saves data as formatted JSON.
- Records a check-in for a habit by appending today's date.
- Reports a habit's streak by counting its saved check-ins.

Run it with a command and a habit name, for example
`python habits.py done reading` to log a check-in, or
`python habits.py streak reading` to print the count. The "streak" is just
the total number of check-ins—it doesn't verify consecutive days.

This time, the request in the second user prompt names the file: “Read the habits.py file and tell me what’s in it.” Therefore, the model skips list_files and asks for read_file immediately, with the path habits/habits.py. The harness runs the tool, which returns 664 characters, and sends seven messages back to the model. As you requested, the model replies with a summary rather than the whole file.

The summary is accurate. The file has functions to load and save the data, record a check-in, and calculate a streak. The model even spots a quirk in the code: the streak counts every check-in rather than consecutive days.

Step 7: Close the Agentic Loop

The harness can now run either tool. You can restart the script and give it a task that needs both tools:

Language: Shell
$ uv run ai_agent.py
you -> harness: Summarize the content of all the Python files in the habits
folder.
  [harness -> model] sending 1 message(s)
  [model -> harness] please run list_files{"folder":"habits"}
  [harness -> tool] list_files({'folder': 'habits'})
  [tool -> harness] 31 characters
  [harness -> model] sending 3 message(s)
  [model -> harness] please run read_file{"path":"habits/habits.py"}
harness -> you: None
you -> harness:

The model asks for list_files to find all the Python files, and the harness runs it. When the model sees the list of files, it asks for read_file. However, nothing happens after that. The harness prints None and waits for your next message.

Can you spot why? Look at the main loop again:

Language: Python Filename: ai_agent.py
# ...

while True:
    user_input = input("you -> harness: ")
    messages.append({"role": "user", "content": user_input})
    reply = ask_model(messages)

    if reply.tool_calls:
        for call in reply.tool_calls:
            result = run_tool(call)
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result,
                },
            )

        reply = ask_model(messages)

    print(f"harness -> you: {reply.content}")

When the first reply contains tool calls, the if block runs them and asks the model again. However, the second reply also contains a tool call, and there’s no code to deal with it. The harness moves on to the print() call, but the reply has no text, so you see None. Your harness expects only a single round of tool calls.

The finished code for this step is in source_code_step_7/ in the materials you downloaded earlier.

All you need to do is change if to while:

Language: Python Filename: ai_agent.py
# ...

while True:
    user_input = input("you -> harness: ")
    messages.append({"role": "user", "content": user_input})
    reply = ask_model(messages)

    while reply.tool_calls:
        for call in reply.tool_calls:
            result = run_tool(call)
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result,
                },
            )

        reply = ask_model(messages)

    print(f"harness -> you: {reply.content}")

This inner while loop is the agentic loop, sometimes called the agent loop. The outer while True loop handles your messages one at a time, and the inner loop lets the model keep working on each one until it has an answer.

Now, the harness keeps going for as long as the model asks for tools. If the result of one tool call makes the model realize it needs another tool, the harness runs that one, too. The loop ends only when the model replies without asking for a tool, usually with a text reply. That should do it. Next, you’ll check whether it works.

You can restart the script and ask the same question:

Language: Shell
$ uv run ai_agent.py
you -> harness: Summarize the content of all the Python files in the habits
folder.
  [harness -> model] sending 1 message(s)
  [model -> harness] please run list_files{"folder":"habits"}
  [harness -> tool] list_files({'folder': 'habits'})
  [tool -> harness] 31 characters
  [harness -> model] sending 3 message(s)
  [model -> harness] please run read_file{"path":"habits/habits.py"}
  [harness -> tool] read_file({'path': 'habits/habits.py'})
  [tool -> harness] 664 characters
  [harness -> model] sending 5 message(s)
  [model -> harness] text reply (538 characters)
harness -> you: The `habits` folder contains one Python file, `habits.py`.
It's a small command-line habit tracker that stores data in `habits.json`:

- `load()` reads the saved habit data, or returns an empty dictionary if the
  file doesn't exist.
- `save(data)` writes the data as formatted JSON.
- `check_in(habit)` records today's date for the named habit.
- `streak(habit)` reports the number of recorded check-ins for that habit.
- From the command line, `done <habit>` records a check-in, while
  `streak <habit>` prints the check-in count as "days."

The trace shows the agentic loop at work. The model asks for list_files, and the harness runs it. The model looks at the list of files and decides that it needs to read habits.py, so it asks for read_file. The harness runs the second tool and sends five messages to the model. Only then does the model reply with text.

Each sending N message(s) line in that trace tells you only how many messages went to the model. Click one below to see the full messages list the harness sent with that request:

Interactive diagram — enable JavaScript to view.

The inspector shows how each request includes the earlier messages and tool results. You didn’t tell the model which tools to use or in what order. It decided that by itself, one step at a time, based on what each tool returned. If habits contained more Python files, the model would most likely request read_file for each of them, sometimes all in one reply. That’s why the harness loops over reply.tool_calls.

This is what an agent is: a model in a harness, with tools it can ask for and a loop that lets it decide its next step. Congratulations, you’ve built an AI agent from scratch!

Here’s the complete code for your agent:

Language: Python Filename: ai_agent.py
import json
from pathlib import Path

from openai import OpenAI

client = OpenAI()
MODEL = "gpt-6-luna"

def list_files(folder):
    return "\n".join(path.name for path in Path(folder).iterdir())

def read_file(path):
    return Path(path).read_text()

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "list_files",
            "description": "List the files in a folder.",
            "parameters": {
                "type": "object",
                "properties": {"folder": {"type": "string"}},
                "required": ["folder"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read a text file and return its contents.",
            "parameters": {
                "type": "object",
                "properties": {"path": {"type": "string"}},
                "required": ["path"],
            },
        },
    },
]

TOOL_FUNCTIONS = {
    "list_files": list_files,
    "read_file": read_file,
}

def trace(sender, receiver, text):
    print(f"  [{sender} -> {receiver}] {text}")

def ask_model(messages):
    trace("harness", "model", f"sending {len(messages)} message(s)")
    response = client.chat.completions.create(
        model=MODEL,
        tools=TOOLS,
        messages=messages,
        reasoning_effort="none",
    )
    reply = response.choices[0].message
    messages.append(reply)

    for call in reply.tool_calls or []:
        trace(
            "model",
            "harness",
            f"please run {call.function.name}{call.function.arguments}",
        )
    if reply.content:
        trace(
            "model",
            "harness",
            f"text reply ({len(reply.content)} characters)",
        )

    return reply

def run_tool(call):
    args = json.loads(call.function.arguments)
    trace("harness", "tool", f"{call.function.name}({args})")
    result = TOOL_FUNCTIONS[call.function.name](**args)
    trace("tool", "harness", f"{len(result)} characters")
    return result

messages = []

while True:
    user_input = input("you -> harness: ")
    messages.append({"role": "user", "content": user_input})
    reply = ask_model(messages)

    while reply.tool_calls:
        for call in reply.tool_calls:
            result = run_tool(call)
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call.id,
                    "content": result,
                },
            )

        reply = ask_model(messages)

    print(f"harness -> you: {reply.content}")

What Real Agents Add

The harness you’ve built has everything that makes an agent an agent. However, the agents you use every day, such as Claude Code and other AI coding agents, add a lot on top of this loop. Here are some of the main additions:

  • Permissions: Your harness runs every tool the model asks for. A real harness decides first. It may ask you before it edits a file or runs a shell command, limit which files the tools can read, and refuse some requests outright.
  • Turn limits: The inner while loop runs for as long as the model keeps asking for tools. A real harness limits how many rounds it allows, so a confused model can’t loop forever or run up a large bill.
  • Error handling: If a tool raises an exception or the model sends a tool call your harness doesn’t expect, your harness crashes. In one of the test runs for this tutorial, the model passed habits/habits.py to list_files(), and .iterdir() raised a NotADirectoryError. A real harness catches the error and sends it back to the model as the tool result, so the model can try something else.
  • More tools: Real agents can edit files, run commands, search the web, and more. Protocols such as the Model Context Protocol let an agent use tools that other people have written.
  • Long-term memory: The messages list disappears when the script stops. Real agents can also store information in files that persist between sessions, such as project instructions or notes, and load them into the conversation context when they start.

A turn limit sounds like one extra if, but stopping at the right moment and leaving a conversation the API will still accept takes some care. Write the inner loop of a harness that enforces a turn limit:

Loading exercise...

If you’d rather not write all this yourself, you can use a framework. Pydantic AI, LangGraph, and CrewAI all build on the same loop you’ve written here, and they handle much of the extra work for you.

You may not need to build an agent at all. Ready-made harnesses, such as Claude Code, Codex CLI, Gemini CLI, and OpenCode, already have the agentic loop, tools, permissions, and memory built in. They aren’t limited to coding, either. OpenClaw, for example, is an open-source AI assistant that runs on your own machine. You talk to it through chat apps such as WhatsApp or Telegram.

Conclusion

You’ve built an AI agent from scratch in Python, starting from a single call to an LLM. You wrapped the model in a harness, gave it short-term memory through the conversation context, described tools it could request, and closed the agentic loop so the model could chain tool calls until it had an answer. Along the way, the trace() helper showed you every message moving between you, the harness, the model, and the tools.

Many Python developers now work with agents every day, and so do more and more people who don’t write code at all. Knowing what’s happening behind the scenes helps you understand why an agent behaves the way it does, what it costs, and where it can go wrong.

In this tutorial, you’ve learned how to:

  • Call an LLM from Python with the OpenAI library
  • Wrap the model in a harness loop and trace the flow of information
  • Keep conversation context by resending the messages list
  • Describe tools with a JSON schema and run the tool calls the model requests
  • Close the agentic loop so the model can chain tool calls

You can download the complete code for every step, including the finished agent in source_code_step_7/, by clicking the link below:

Now, when you use an agent, you’ll know what’s going on inside it. It’s not a mystery anymore. You can extend your agent with a tool of your own or explore a framework such as Pydantic AI to build something bigger. Real Python’s LLM Application Development With Python learning path covers model APIs, prompt design, retrieval-augmented generation, and MCP in a set order, so you always know what to tackle next.

Frequently Asked Questions

Now that you have some experience building an AI agent from scratch in Python, you can use the questions and answers below to check your understanding and recap what you’ve learned.

These FAQs cover the most important concepts you’ve learned in this tutorial. Click the Show/Hide toggle beside each question to reveal the answer.

In its simplest form, an LLM takes text in and returns text. An AI agent wraps the LLM in a harness that keeps the conversation context, runs tools on the model’s behalf, and keeps asking the model until it has an answer.

A harness is the code that sits between you, the model, and the tools. In this tutorial, it’s a while loop that sends messages to the model, runs the tools the model asks for, and passes the final reply back to you.

It doesn’t. The harness keeps a list of every message and sends the whole list with each request. This short-term conversation context is also why long chats cost more than short ones.

In this tutorial, the model receives a description of each tool, including a JSON schema for its arguments. When it needs one, it returns a tool call with the tool’s name and arguments, and the harness runs the matching Python function and sends the result back as a "tool" message.

No. You can build a working agent in about ninety lines of plain Python with the openai library. Frameworks such as Pydantic AI and LangGraph add features like permissions, error handling, and memory on top of the same loop.

Take the Quiz: Test your knowledge with our interactive “Build an AI Agent From Scratch in Python: The Agentic Loop” quiz. You’ll receive a score upon completion to help you track your learning progress:


Interactive Quiz

Build an AI Agent From Scratch in Python: The Agentic Loop

Test your understanding of how an AI agent works in Python, from the harness and conversation context to tool calls and the agentic loop.

🐍 Python Tricks 💌

Get a short & sweet Python Trick delivered to your inbox every couple of days. No spam ever. Unsubscribe any time. Curated by the Real Python team.

Dictionary merging in Python 3.5+

About Stephen Gruppetta

Stephen obtained a PhD in physics and worked as a physicist in academia for over a decade before becoming a Python educator. He's constantly looking for simple ways to explain complex things in Python.

» More about Stephen

Each tutorial at Real Python is created by a team of developers so that it meets our high quality standards. The team members who worked on this tutorial are:

Master Real-World Python Skills With Unlimited Access to Real Python

Locked learning resources

Join us and get access to thousands of tutorials, hands-on video courses, and a community of expert Pythonistas:

Level Up Your Python Skills »

Master Real-World Python Skills
With Unlimited Access to Real Python

Locked learning resources

Join us and get access to thousands of tutorials, hands-on video courses, and a community of expert Pythonistas:

Level Up Your Python Skills »

What Do You Think?

Rate this article:

What’s your #1 takeaway or favorite thing you learned? How are you going to put your newfound skills to use? Leave a comment below and let us know.

Commenting Tips: The most useful comments are those written with the goal of learning from or helping out other students. Get tips for asking good questions and get answers to common questions in our support portal.


Looking for a real-time conversation? Visit the Real Python Community Chat or join the next “Office Hours” Live Q&A Session. Happy Pythoning!