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

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:

  [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:

• 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.

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:

$ 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:

# ...

.env

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

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

PS> $env:UV_ENV_FILE = ".env"

$ 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