
Every agent framework I've tried hides the same simple thing underneath. Before I put any agent in front of a client's data, I build the core loop by hand so I know exactly what it's doing. This post shows you how to build an AI agent from scratch with tool calling, in plain Python.
The whole idea in one paragraph
You send the model three things: the conversation, a system prompt, and a list of tools it may use. The model either answers in text, or replies "call this tool with these arguments". If it asks for a tool, your code runs it, adds the result to the conversation and calls the model again. When the model answers without asking for a tool, you're done. That loop is the agent.
Step 1: Describe the tools
Tools are just functions, described in a way the model understands. Here's a small support agent for a shop with two tools:
TOOLS = [
{
"name": "get_order_status",
"description": "Look up the status and tracking number of an order by its ID.",
"input_schema": {
"type": "object",
"properties": {"order_id": {"type": "string", "description": "Order ID like #1042"}},
"required": ["order_id"],
},
},
{
"name": "search_help_docs",
"description": "Search the shop's help articles (shipping, returns, sizes).",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
},
]
The description matters more than people think. It's how the model decides which tool fits. Write it like you'd explain the function to a new colleague.
Step 2: Write the functions
def get_order_status(order_id: str) -> dict:
# In real life: query your database or the Shopify API.
orders = {"#1042": {"status": "shipped", "tracking": "BD123456"}}
return orders.get(order_id, {"error": "Order not found"})
def search_help_docs(query: str) -> dict:
docs = {"returns": "Returns are accepted within 14 days, unused, with the receipt."}
hits = [text for key, text in docs.items() if key in query.lower()]
return {"results": hits or ["No matching article."]}
def run_tool(name: str, args: dict) -> dict:
if name == "get_order_status":
return get_order_status(**args)
if name == "search_help_docs":
return search_help_docs(**args)
return {"error": f"Unknown tool {name}"}
Notice run_tool. The model never touches your systems directly. It asks; your code decides.
Step 3: The agent loop
This uses Anthropic's Python SDK (pip install anthropic, with ANTHROPIC_API_KEY set). The same pattern works with OpenAI or Gemini; only the field names change.
import json
import anthropic
client = anthropic.Anthropic()
MODEL = "claude-sonnet-5-5" # use any current model ID
SYSTEM = (
"You are the support assistant for a small online shop. "
"Use the tools to check facts. If you can't find the answer, say so "
"and offer to pass the question to a human."
)
def ask(question: str, max_steps: int = 8) -> str:
messages = [{"role": "user", "content": question}]
for _ in range(max_steps):
response = client.messages.create(
model=MODEL, max_tokens=1024, system=SYSTEM,
tools=TOOLS, messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
return "".join(b.text for b in response.content if b.type == "text")
results = []
for block in response.content:
if block.type == "tool_use":
output = run_tool(block.name, block.input)
print(f"tool {block.name}({block.input}) -> {output}")
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(output),
})
messages.append({"role": "user", "content": results})
return "Sorry, I couldn't finish that. A person will follow up."
print(ask("Where is my order #1042, and can I still return it?"))
Run it and you'll see the model call get_order_status, then search_help_docs, then answer using both results. Two tools, one loop, and it already behaves like an agent.
What the loop is doing
stop_reason == "tool_use"means the model wants a tool. Anything else means it's finished.- The assistant message goes back into the history exactly as returned, including the tool request.
- Tool results go back as a user message, each tied to the request by
tool_use_id. max_stepsstops it from looping forever if something goes wrong.
That's the whole mechanism. Frameworks add retries, memory, tracing and multi-agent routing on top, but this is the engine.
Before you connect it to anything real
The demo above only reads data. The moment an agent can write (send an email, refund an order, update a CRM), you need guardrails:
- Least privilege. Only give the tools it needs for this job.
- Validate arguments in code. Check the order belongs to the customer asking. Never trust the model's arguments blindly.
- Human approval for risky actions. My agents send refunds, deletes and outgoing emails to a person first, usually over Telegram.
- Treat outside text as data. An email or web page can contain instructions like "ignore your rules". The model must never act on those. This is prompt injection, and it's real.
- Log every tool call with its arguments and result. You'll need it the first time a client asks "why did it do that?"
When to reach for a framework
I start without one. I add a framework, or the provider's agent SDK, when I need things like long-running sessions, persistent memory, several agents handing work to each other, or built-in tracing. By then I know what the framework is doing for me, which makes it much easier to debug.
FAQ
Do I need LangChain or another framework to build an AI agent? No. A basic agent is a loop around one API call. Build it by hand first.
What is tool calling? You describe functions to the model with a name, description and input schema. The model replies with a tool name and arguments, your code runs it and sends the result back.
How do I stop an agent from doing something dangerous? Limit its tools, validate arguments, require approval for write actions, cap the steps and log everything.
Need an agent that works with your own systems? That's the core of my AI automation work.


