Malhar Ujawane

Blog

Explainer·(updated October 31, 2026)

How to build an AI agent from scratch in Python

How to build an AI agent: a tool registry, a model call, a loop with stop conditions, errors and approvals. One runnable stdlib Python file, then the real API.

How to build an AI agent from scratch in Python

To build an AI agent, you need four things: a model API that supports tool calling, a set of tools described with JSON schemas, a loop that sends the conversation to the model and runs whatever tool it asks for, and stop conditions so the loop ends. That’s the whole architecture; frameworks add tracing, retries and handoffs on top. Below is a complete agent in one standard-library Python file, with a scripted model so it runs offline, followed by the five lines that connect it to a real model.

What is the minimum an AI agent needs?

Anthropic’s Building effective agents describes agents as “LLMs using tools based on environmental feedback in a loop”, and OpenAI’s practical guide lists the same three components: a model, tools, and instructions. The guide also says every orchestration approach needs a “run”, “typically implemented as a loop that lets agents operate until an exit condition is reached”, with exit conditions such as a final answer, an error or a maximum number of turns.

Turned into a parts list:

Part Job In the script below
Model call Takes the message history and tool definitions, returns text or tool calls call_model()
Tools Plain functions with clear names, descriptions and schemas list_dir, read_file, write_file
Loop Runs tool calls, appends results, calls the model again run_agent()
Stop conditions Final answer, turn cap, context budget max_turns, budget_chars
Guardrails Path sandbox, approval for writes, errors returned as data safe(), approve(), is_error

If you’ve read what an AI agent is, this is the same loop with the production parts filled in.

How do you write the agent loop?

The script uses the message shapes of the Claude Messages API: the model replies with stop_reason: "tool_use" and tool_use blocks, and you answer with a user message of tool_result blocks matched by tool_use_id. The task: total two months of invoices in a workspace and write a summary file. The scripted model makes one deliberate mistake (it guesses a file name) so you can see the error path.

# build_agent.py: a complete agent loop in Python 3 stdlib, using the Claude Messages
# API message shapes (tool_use / tool_result). call_model() is a scripted stand-in so it
# runs offline with no key; replace it with client.messages.create(...) to go live.
import json, pathlib, tempfile

WORK = pathlib.Path(tempfile.mkdtemp())
(WORK / "invoices").mkdir()
(WORK / "invoices/2026-09.csv").write_text("client,amount_inr\nAcme,120000\nGlobex,45000\n")
(WORK / "invoices/2026-10.csv").write_text("client,amount_inr\nAcme,80000\n")

def safe(p):                                   # keep every path inside the workspace
    path = (WORK / p).resolve()
    if not path.is_relative_to(WORK.resolve()):
        raise PermissionError(f"{p} is outside the workspace")
    return path

def list_dir(path): return sorted(x.name for x in safe(path).iterdir())
def read_file(path):
    if not safe(path).is_file():                # instructive error: say what to try next
        raise FileNotFoundError(f"{path} does not exist; call list_dir to see real names")
    return safe(path).read_text()
def write_file(path, text): safe(path).write_text(text); return f"wrote {len(text)} chars"

TOOLS = {"list_dir": list_dir, "read_file": read_file, "write_file": write_file}
NEEDS_APPROVAL = {"write_file"}

def call_model(messages, tools):
    """Scripted stand-in for an LLM. Same input and output shapes as the real API."""
    turn = sum(m["role"] == "assistant" for m in messages)
    last = messages[-1]["content"]
    use = lambda i, name, **inp: {"type": "tool_use", "id": f"toolu_{turn}{i}", "name": name, "input": inp}
    if turn == 0:
        return {"stop_reason": "tool_use", "content": [use(0, "list_dir", path="invoices")]}
    if turn == 1:                               # one deliberate mistake: a file that does not exist
        return {"stop_reason": "tool_use", "content": [use(0, "read_file", path="invoices/sept.csv")]}
    if turn == 2:                               # recovers from the error, reads both in parallel
        files = json.loads(messages[-3]["content"][0]["content"])
        return {"stop_reason": "tool_use", "content": [use(i, "read_file", path=f"invoices/{f}")
                                                         for i, f in enumerate(files)]}
    if turn == 3:
        total = sum(int(line.split(",")[1]) for r in last for line in r["content"].splitlines()[1:])
        return {"stop_reason": "tool_use", "content": [
            use(0, "write_file", path="summary.txt", text=f"Total invoiced: INR {total:,}\n")]}
    return {"stop_reason": "end_turn", "content": [{"type": "text", "text": "Done. Total is in summary.txt."}]}

def approve(name, inp):                         # in a real app this is a UI prompt
    print(f"   approval requested: {name} {inp} -> approved")
    return True

def run_agent(task, max_turns=10, budget_chars=20_000):
    messages = [{"role": "user", "content": task}]
    for turn in range(max_turns):
        if len(json.dumps(messages)) > budget_chars:
            return "stopped: context budget exceeded"
        reply = call_model(messages, TOOLS)
        messages.append({"role": "assistant", "content": reply["content"]})
        if reply["stop_reason"] != "tool_use":
            return reply["content"][0]["text"]
        results = []
        for block in (b for b in reply["content"] if b["type"] == "tool_use"):
            print(f"turn {turn}: {block['name']}({block['input']})")
            try:
                if block["name"] in NEEDS_APPROVAL and not approve(block["name"], block["input"]):
                    raise PermissionError("user denied this action")
                out, err = TOOLS[block["name"]](**block["input"]), False
            except Exception as e:
                out, err = f"{type(e).__name__}: {e}", True
            print(f"   -> {'ERROR ' if err else ''}{str(out)[:72]!r}")
            results.append({"type": "tool_result", "tool_use_id": block["id"],
                            "content": json.dumps(out) if isinstance(out, list) else out, "is_error": err})
        messages.append({"role": "user", "content": results})
    return f"stopped: hit max_turns={max_turns}"

print("final:", run_agent("Total the invoices in ./invoices and write summary.txt"))
print("summary.txt:", (WORK / "summary.txt").read_text().strip())

Output (Python 3.14.5):

turn 0: list_dir({'path': 'invoices'})
   -> "['2026-09.csv', '2026-10.csv']"
turn 1: read_file({'path': 'invoices/sept.csv'})
   -> ERROR 'FileNotFoundError: invoices/sept.csv does not exist; call list_dir to se'
turn 2: read_file({'path': 'invoices/2026-09.csv'})
   -> 'client,amount_inr\nAcme,120000\nGlobex,45000\n'
turn 2: read_file({'path': 'invoices/2026-10.csv'})
   -> 'client,amount_inr\nAcme,80000\n'
turn 3: write_file({'path': 'summary.txt', 'text': 'Total invoiced: INR 245,000\n'})
   approval requested: write_file {'path': 'summary.txt', 'text': 'Total invoiced: INR 245,000\n'} -> approved
   -> 'wrote 28 chars'
final: Done. Total is in summary.txt.
summary.txt: Total invoiced: INR 245,000

Read the trace from the top. Turn 1 asks for a file that doesn’t exist; the tool raises, the loop catches it and returns the error as a tool_result with is_error: true instead of crashing. Turn 2 recovers and reads both files in one turn (parallel tool calls, two results in one message). Turn 3 hits the only tool that writes, so the loop asks for approval first. Turn 4 has no tool call, so the loop returns the text. Five turns, one recovered error, one approval.

Which design decisions in the loop matter most?

Errors are data, not exceptions. Anthropic’s handle tool calls docs say to return failures with is_error: true and to write instructive messages: instead of “failed”, say what went wrong and what to try next. The read_file error above names the fix (“call list_dir to see real names”). The same page notes Claude retries an invalid call “2-3 times with corrections before apologizing to the user.”

Message ordering is strict. Tool results have to come right after the assistant message that requested them, and the tool_result blocks have to come first in that user message. The loop above appends the assistant turn, then one user turn with every result. Break that order and the API returns a 400.

Every limit lives in the harness. The model never decides whether it may continue. max_turns caps the loop, budget_chars stops it before the history gets too large (a rough proxy; in production, read token counts from the API’s usage field), and safe() refuses any path outside the workspace, whatever the model asks for. Anthropic recommends “stopping conditions (such as a maximum number of iterations) to maintain control”; I’d add a budget too, because history is resent every turn and cost grows faster than turns, as I showed in what agentic AI is.

Approval sits next to the side effect. Only write_file is in NEEDS_APPROVAL, and the check runs inside the loop right before the call. In a real product approve() is a UI prompt, a Slack message or a policy engine. The design choices around it are in human-in-the-loop AI.

How do you connect the loop to a real model?

Replace call_model() with an API call and give the model real tool definitions. With the Anthropic Python SDK it looks like this; it needs an API key, so there’s no output here:

# pip install anthropic   (needs ANTHROPIC_API_KEY)
import anthropic
client = anthropic.Anthropic()

TOOL_DEFS = [
    {"name": "list_dir", "description": "List file names in a workspace directory. "
     "Use this before reading files so you use exact names. Paths are relative to the workspace.",
     "input_schema": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}},
    # read_file and write_file follow the same shape
]

def call_model(messages, tools):
    r = client.messages.create(model="claude-opus-5-5", max_tokens=4096,
                               system="You are a careful bookkeeping agent. Check file names before reading.",
                               tools=TOOL_DEFS, messages=messages)
    return {"stop_reason": r.stop_reason, "content": [b.model_dump() for b in r.content]}

Everything else stays the same, because the scripted model already used the API’s shapes. Two adjustments for a live model: the final reply can contain several blocks (pick out the text ones rather than content[0]), and a response can stop for reasons other than tool_use and end_turn, such as max_tokens, which you should treat as an error to log, not an answer. Tool descriptions are where the effort goes: Anthropic’s define tools page calls detailed descriptions “by far the most important factor in tool performance.” What tool calling is covers schemas, strict mode and tool_choice.

What should you add before production?

In the order I’d add them:

  1. Tracing. Log every model call (input tokens, output tokens, stop reason) and every tool call (arguments, result, duration) with a run ID. Without it, you can’t debug a bad run or compute cost per task.
  2. Evals. A fixed set of tasks with checkable outcomes, run on every prompt or model change. Agents regress quietly. See how to evaluate AI agents.
  3. A sandbox. safe() is a path check, not isolation. Anything that runs shell commands belongs in a container or VM; agent sandboxing goes into the options.
  4. Untrusted-input handling. File contents, web pages and emails come back as tool results and can carry instructions. Anthropic’s docs say to keep that content inside tool_result blocks, never in the system prompt.
  5. Durable state. For runs longer than a request timeout, persist the message list after each turn so a crash resumes instead of restarting, the idea behind durable execution.

What I would do

Write the loop yourself first, exactly like this file, and run it against your real tools for a week before reaching for a framework. You’ll learn where your agent actually fails, which is usually tool descriptions and tool results, not the loop. Anthropic gives the same advice: “start by using LLM APIs directly”, because wrong assumptions about what a framework does underneath are “a common source of customer error.”

Keep tools few and specific, errors instructive, limits in code, and every write behind a check. When the single loop stops being enough, the next step is splitting work across subagents, but most tasks never need it.

FAQ

What is the easiest way to build an AI agent?

A loop around a model API with tool calling: send messages and tool definitions, run any tool the model requests, append the result, repeat until the model replies with no tool call or a limit is hit. The script above is about 75 lines.

Do I need LangChain or another framework to build an agent?

No. Frameworks such as the OpenAI Agents SDK add handoffs, guardrails, approvals and resumable run state, which help later. The core loop is small enough to write and understand yourself first.

How do I stop an AI agent from running forever?

Put limits in the harness: a maximum number of turns, a token or cost budget per run, and repetition detection. Treat hitting a limit as a failure to log and review.

Which model should I use for an agent?

One with reliable tool calling on your tasks. Run the same eval set across two or three candidates and compare success rate and cost per completed task, not price per token.

Sources

Get new posts in your inbox

© 2026 Malhar Ujawane. Built with Astro.