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.

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:
- 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.
- 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.
- 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. - 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_resultblocks, never in the system prompt. - 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
- Anthropic, Building effective agents, December 19, 2024
- Anthropic, Tool use with Claude, Define tools and Handle tool calls, as of October 31, 2026
- OpenAI, A practical guide to building agents, 2025