How to Build an AI Agent From Scratch in Python

Agent frameworks are useful, but they can hide the simple mechanics underneath. Building an agent yourself, without a framework, is the best way to understand how agents actually work, and the result is often small, fast and easy to debug. In this tutorial, you will build an ai agent from scratch in Python: a tool calling agent that can use a calculator, search notes and read files, running in a loop until it completes a task. You will learn the ai agent loop, llm function calling python patterns, and the safeguards production agents need.

Start with the core idea.

What an Agent Really Is

An agent is a language model running in a loop with tools:

  • Send the conversation and available tools to the model.
  • If the model responds with a tool call, execute the tool and add the result to the conversation.
  • Repeat until the model responds with a final answer instead of a tool call.

That loop is the entire foundation. Everything else, such as memory, planning and multi-agent orchestration, builds on it.

What You Need

  • Python 3.10 or later.
  • An API key for a model provider that supports tool calling, such as Anthropic, OpenAI or Google.
  • The provider's Python SDK.
  • Basic Python knowledge.

This tutorial describes the pattern generally; the code structure is nearly identical across providers, with small differences in message formats.

Step 1: Set Up the Project

Create a folder named simple-agent and a virtual environment inside it by running python -m venv .venv, then activate it. Install your provider SDK, for example pip install anthropic or pip install openai. Store your API key in an environment variable rather than in code.

Create a file named agent.py.

Step 2: Define Your Tools as Python Functions

Write three simple functions:

calculate takes a math expression as a string and returns the result. Use a safe expression evaluator, such as a small parser or a restricted library, rather than Python's eval, which can execute arbitrary code.

search_notes takes a query and returns lines from a notes file that contain the query.

read_file takes a file name and returns its contents, but only for files inside an allowed folder. Check the resolved path to prevent access outside that folder.

Each function returns a string, which is what the model will read.

Step 3: Describe the Tools for the Model

The model cannot see your Python code. It needs a description of each tool in JSON schema format: a name, a description explaining when to use it, and the parameters with types and descriptions.

For example, the calculate tool's description might say: Evaluate a mathematical expression and return the numeric result. Use this for any arithmetic rather than calculating mentally. Its parameters include expression, a string.

Good descriptions are the most important factor in whether the agent chooses tools correctly.

Create a dictionary mapping tool names to the Python functions so you can dispatch calls.

Step 4: Write the Agent Loop

Create a function named run_agent that takes a user task:

  • Initialize a messages list with the user's task.
  • Start a loop with a maximum number of iterations, such as ten, to prevent runaway behavior.
  • In each iteration, call the model API with the system prompt, messages and tool definitions.
  • Append the model's response to the messages list.
  • Check whether the response includes tool calls. If not, return the model's text as the final answer.
  • If it does, for each tool call, look up the function, parse the arguments, execute the function inside a try block and capture the result or the error message.
  • Append each tool result to the messages list, referencing the tool call ID so the model knows which result belongs to which call.
  • Continue the loop.

If the loop reaches the maximum iterations, return a message saying the task could not be completed.

This is the complete python ai agent tutorial core: around 50 lines of code.

Step 5: Write a System Prompt

The system prompt guides behavior:

You are a helpful assistant that completes tasks using the available tools. Think about which tools you need before acting. Use the calculator for all arithmetic. If a tool returns an error, try to correct your input or explain the problem. When the task is complete, give a concise final answer.

Step 6: Test the Agent

Run the agent with a task like: Read the file budget.txt, add up all the expenses and tell me the total. Watch the loop: the model calls read_file, then calculate with the sum, then responds with the total.

Add print statements showing each tool call and result. Visual description: your terminal shows lines such as Calling read_file with budget.txt, followed by the result, then Calling calculate with an expression, then the final answer.

Step 7: Handle Errors Gracefully

Errors are normal in agents. Instead of crashing, return error messages as tool results, such as Error: file not found. Allowed files are listed below. Models are good at recovering when errors are informative.

Also handle API errors with retries and exponential backoff for rate limits and temporary failures.

Step 8: Add Safety Controls

Even a simple agent without framework needs safeguards:

  • Maximum iterations to prevent infinite loops.
  • Path restrictions for file access.
  • Safe evaluation instead of eval.
  • Confirmation prompts before tools that change data or send messages.
  • Timeouts for slow tools.
  • Logging of every tool call for debugging.

Never give an agent unrestricted shell access or credentials beyond what the task needs.

Step 9: Add Conversation Memory

To make the agent conversational, keep the messages list between user turns instead of resetting it. For long conversations, summarize older messages when the list grows large to stay within the context window.

Troubleshooting Common Issues

The model never calls tools: improve tool descriptions and mention tools in the system prompt.

Malformed tool arguments: validate arguments and return clear error messages so the model can retry.

Tool result not matched: ensure you include the correct tool call ID in each result message.

Loops that repeat the same call: return more informative results, and stop if the same call repeats several times.

Rate limit errors: add retry with backoff and reduce iterations.

When to Use a Framework Instead

Building from scratch is ideal for learning, small agents and full control. Frameworks such as LangGraph, the OpenAI Agents SDK or Google ADK become valuable when you need persistence, complex orchestration, tracing integrations or human-in-the-loop workflows at scale.

Frequently Asked Questions

Do I need a framework for production? Not necessarily. Many production agents are simple loops with good tools, logging and safety controls.

Can tools run in parallel? Yes. Many models can request multiple tool calls at once, which you can execute concurrently.

Conclusion

You have built an ai agent from scratch in Python: defining tools as functions, describing them with JSON schemas, running the agent loop, returning tool results and adding error handling and safety controls.

Key takeaways: the agent loop is simple, tool descriptions drive behavior, errors should become informative tool results, and limits and restrictions are essential. Next, add a tool that calls a real API you use, and add logging that records each run for review.