Build an AI Agent From Scratch in Python: The Agentic Loop – Real Python
Build an AI Agent From Scratch in Python: The Agentic Loop by Stephen Gruppetta Updated Nov 19, 2026 Reading time estimate 41m intermediate ai Table of Contents Remove ads 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: Get Your Code: Click here to download the free sample code you’ll use to build an AI agent from scratch in plain Python, one step at a time, with no frameworks.
Agentic Loops Live Course: If you’d rather build an agent with an instructor, join Stephen in Real Python’s agentic loops live course . Over two live sessions, you’ll write the loop by hand and learn to predict what agents like Claude Code will do next. 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: Writing while loops and defining functions Working with dictionaries and lists Reading paths and files with pathlib 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.
Remove ads 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: Windows Linux + macOS 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. Remove ads Step 2: Wrap the Model in a Harness In the previous step, the model told you it couldn’t access your files.
The rest of this page is on the live site.