Build AI Agents From Scratch With Python: A Working Tutorial (2026)

The fastest way to truly understand AI agents is to build one yourself — and you don’t need a heavyweight framework to do it. In this tutorial you’ll build a working AI agent from scratch in Python, using nothing but the standard library and a model API. By the end you’ll have a complete, runnable agent under 80 lines, and — more importantly — you’ll understand every line of it.

The core idea: an agent is a loop

Strip away the hype and an AI agent is a simple loop. The dominant beginner-friendly pattern in 2026 is ReAct, where the agent alternates between reasoning in natural language and acting through tools. Each turn: the model decides what to do, you run any tool it asks for, you feed the result back, and you repeat until the model produces a final answer or you hit a safety limit. That’s it. Everything else — frameworks, orchestration, memory stores — is convenience layered on top of this loop.

We’ll build an agent with one tool (a calculator), short-term memory, and a guardrail, then show you how to extend it.

Build it in 6 steps

pip install openai          # or anthropic, etc.
export OPENAI_API_KEY="your-key-here"

def calculator(expression: str) -> str:
    """Safely evaluate a basic math expression."""
    try:
        # Only allow digits and basic math operators
        allowed = set("0123456789+-*/(). ")
        if not set(expression) <= allowed:
            return "Error: invalid characters."
        return str(eval(expression))
    except Exception as e:
        return f"Error: {e}"

TOOLS = {"calculator": calculator}

import json
from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from your environment

SYSTEM_PROMPT = """You are a helpful agent.
You can use one tool: calculator(expression).
To use it, reply with ONLY this JSON: {"tool": "calculator", "input": "2+2"}
When you have the final answer, reply with: {"answer": "..."}"""

def run_agent(question, max_steps=5):
    # memory: a running list of messages
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": question},
    ]

    for step in range(max_steps):          # guardrail: never loop forever
        reply = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
        ).choices[0].message.content

        messages.append({"role": "assistant", "content": reply})

        try:
            action = json.loads(reply)
        except json.JSONDecodeError:
            return reply                    # model answered in plain text

        if "answer" in action:              # stopping condition
            return action["answer"]

        if action.get("tool") in TOOLS:     # the "act" step
            result = TOOLS[action["tool"]](action["input"])
            # feed the observation back into memory
            messages.append({"role": "user",
                             "content": f"Tool result: {result}"})

    return "Stopped: reached the step limit."

print(run_agent("What is 1234 * 9 plus 17?"))
# The agent calls the calculator tool, reads the result,
# then returns the final answer.

The loop, visualized

The complete code

Here’s the whole agent in one file. Copy it into agent.py, set your API key, and run python agent.py:

agent.py — the complete, runnable file

import json
from openai import OpenAI

client = OpenAI()

def calculator(expression: str) -> str:
    allowed = set("0123456789+-*/(). ")
    if not set(expression) <= allowed:
        return "Error: invalid characters."
    try:
        return str(eval(expression))
    except Exception as e:
        return f"Error: {e}"

TOOLS = {"calculator": calculator}

SYSTEM_PROMPT = """You are a helpful agent.
You can use one tool: calculator(expression).
To use it, reply with ONLY this JSON: {"tool": "calculator", "input": "2+2"}
When you have the final answer, reply with: {"answer": "..."}"""

def run_agent(question, max_steps=5):
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": question},
    ]
    for _ in range(max_steps):
        reply = client.chat.completions.create(
            model="gpt-4o-mini", messages=messages
        ).choices[0].message.content
        messages.append({"role": "assistant", "content": reply})
        try:
            action = json.loads(reply)
        except json.JSONDecodeError:
            return reply
        if "answer" in action:
            return action["answer"]
        if action.get("tool") in TOOLS:
            result = TOOLS[action["tool"]](action["input"])
            messages.append({"role": "user",
                             "content": f"Tool result: {result}"})
    return "Stopped: reached the step limit."

if __name__ == "__main__":
    print(run_agent("What is 1234 * 9 plus 17?"))

That’s a genuine, working AI agent — reasoning, tool use, memory, a stopping condition, and a guardrail — in well under 80 lines and with no framework.

How to extend it

Once the basics work, here’s how this same skeleton grows into something genuinely useful:

• Add more tools. Drop new functions into the TOOLS dictionary — web search, a weather API, a database query — and describe them in the system prompt. (See how to write a system prompt for an agent.)
• Upgrade memory. Swap the in-memory messages list for a vector store so the agent recalls past sessions.
• Harden it for production. Add output validation, error handling around tool calls, and approval gates for risky actions. (See how to stop your agent from failing.)
• Graduate to a framework. When projects get bigger, LangChain and similar tools handle scheduling, tracing, and tool management for you — but now you know what they’re doing under the hood.

The reason building from scratch is worth it: when you understand this loop, every agent product and framework suddenly makes sense. You can read our reviews of production agents and recognize exactly what’s happening inside them.

Frequently asked questions