Say a support lead wants help with refund requests. Most of them follow the same steps: find the order, check that it was delivered, check the amount, issue the refund, and reply to the customer. A chatbot can explain those steps. An AI agent can do them.
The difference is a loop. An AI agent is a program that gives a language model a goal and a set of tools, lets the model decide which tool to call next, runs that tool, and feeds the result back until the job is done. In Python, the core of that loop fits in about 40 lines. This guide builds a working refund agent step by step, explains each part, and shows the guardrails that keep it from doing something you did not intend.
Key Takeaways
- An AI agent is a language model in a loop: it picks a tool, your code runs the tool, and the result goes back to the model until it has an answer.
- The model never runs code itself. It returns a request to call a tool, and your program decides whether to run it.
- Good tool descriptions do most of the work. The model chooses tools based on their names, descriptions and input schemas.
- Every agent needs limits: a maximum number of steps, clear errors when a tool fails, and a person’s approval before any action that is hard to undo.
- Start with a single agent and a few tools. Add more agents or frameworks only when one loop can no longer do the job.
What Is an AI Agent?
An AI agent is software that uses a language model to decide which actions to take, not only what text to write. You describe the tools it can use, such as “look up an order” or “issue a refund”, and the model chooses when to call them and with which inputs.
Anthropic’s engineering team draws a useful line in Building Effective Agents. In a workflow, your code decides the order of steps and the model fills in each one. In an agent, the model decides the steps itself, based on what it learns along the way. Workflows are easier to test and cheaper to run. Agents are worth it when you cannot list the steps in advance.
A refund request is a good fit for an agent because the path changes from case to case. One order is not found, another is still in transit, a third was already refunded. The agent reads each result and decides what to do next.
How Does the Agent Loop Work?
Every tool-using agent, whatever the model or framework, runs the same cycle:
- Your program sends the model the task, the conversation so far and the list of tools.
- The model replies with either a final answer or one or more tool calls. A tool call names the tool and gives its inputs as JSON.
- Your program runs each requested tool and sends the results back.
- Repeat until the model gives a final answer or you hit a limit.
Step 3 is the important one for safety. The model only asks. Your code decides what actually runs, which is where you add checks, approvals and logs.
Step 1: Set Up the Project
The example uses Python 3.10 or later and the official Anthropic Python SDK with a Claude model. The same pattern works with any model API that supports tool calling; only the request and response field names change.
pip install anthropic
export ANTHROPIC_API_KEY="your-key-here" Step 2: Write the Tools
Tools are plain Python functions. Here they work on an in-memory dictionary so the example runs on its own. In a real system they would call your order database or payments API.
import json
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY
MODEL = "claude-opus-5-5"
ORDERS = {
"A-1001": {"customer": "Dana", "item": "Desk lamp", "total": 49.00, "status": "delivered"},
"A-1002": {"customer": "Lee", "item": "Office chair", "total": 189.00, "status": "in transit"},
}
def get_order(order_id: str) -> dict:
order = ORDERS.get(order_id)
if order is None:
raise KeyError(f"No order with ID {order_id}")
return order
def refund_order(order_id: str, reason: str) -> dict:
order = get_order(order_id)
if order["status"] == "refunded":
raise ValueError(f"Order {order_id} was already refunded")
order["status"] = "refunded"
return {"order_id": order_id, "refunded_usd": order["total"], "reason": reason} Notice that the functions raise clear errors. The model will read those messages and use them to decide what to do next, so “No order with ID A-9999” is far more useful than a stack trace.
Step 3: Describe the Tools to the Model
The model cannot see your Python code. It only sees a name, a description and a JSON schema for each tool. Write the description the way you would brief a new teammate: what the tool does, what it returns and when to use it.
TOOLS = [
{
"name": "get_order",
"description": "Look up an order by its ID. Returns the customer name, item, "
"total in USD and shipping status.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {"type": "string", "description": "Order ID, for example A-1001"},
},
"required": ["order_id"],
},
},
{
"name": "refund_order",
"description": "Refund an order in full. Only use it after looking up the order "
"and confirming it was delivered and not already refunded.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {"type": "string", "description": "Order ID to refund"},
"reason": {"type": "string", "description": "Short reason for the refund"},
},
"required": ["order_id", "reason"],
},
},
]
FUNCTIONS = {"get_order": get_order, "refund_order": refund_order}
NEEDS_APPROVAL = {"refund_order"}
SYSTEM = (
"You handle refund requests for an online store. Look up each order before "
"acting on it. Only refund delivered orders. If a request does not qualify, "
"say why. Keep replies to the customer short and friendly."
) The system prompt sets the rules of the job, and the descriptions repeat the ones that matter most. That repetition is deliberate: the model reads the tool description at the moment it decides to call the tool.
Step 4: Run Tools Safely
This function sits between the model and your code. It is the one place where every tool call passes, which makes it the right place for approvals and error handling.
def run_tool(name: str, args: dict) -> tuple[str, bool]:
"""Run one tool call. Returns (output, is_error)."""
if name not in FUNCTIONS:
return f"Unknown tool: {name}", True
if name in NEEDS_APPROVAL:
answer = input(f"\nThe agent wants to run {name}({args}). Allow? [y/N] ")
if answer.strip().lower() != "y":
return "A person declined this action.", True
try:
return json.dumps(FUNCTIONS[name](**args)), False
except Exception as exc:
return f"Error: {exc}", True Two choices here matter. First, a refund waits for a person to type “y”, so the agent can prepare the action but cannot complete it alone. Second, errors go back to the model as text instead of crashing the program, so the agent can recover, for example by asking the customer for the right order number.
Step 5: Write the Agent Loop
def run_agent(task: str, max_steps: int = 10) -> str:
messages = [{"role": "user", "content": task}]
for step in range(1, max_steps + 1):
response = client.messages.create(
model=MODEL,
max_tokens=16000,
system=SYSTEM,
tools=TOOLS,
messages=messages,
)
# No tool calls requested: the model is done (or stopped early).
if response.stop_reason != "tool_use":
text = "".join(b.text for b in response.content if b.type == "text")
return text or f"Stopped without an answer ({response.stop_reason})."
# Keep the model's full reply, including its tool calls.
messages.append({"role": "assistant", "content": response.content})
# Run every tool call and send all the results back in one message.
results = []
for block in response.content:
if block.type == "tool_use":
output, is_error = run_tool(block.name, block.input)
print(f"[step {step}] {block.name}({block.input}) -> {output}")
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
"is_error": is_error,
})
messages.append({"role": "user", "content": results})
return "Stopped: reached the step limit."
if __name__ == "__main__":
print(run_agent("Hi, I'm Dana. Order A-1001 arrived broken. Can I get a refund?")) A few details in this loop prevent common bugs:
- The step limit. Without
max_steps, a confused agent can call tools forever and run up a bill. Ten steps is plenty for this job. - The stop reason. Tools only run when
stop_reasonis"tool_use". If the reply was cut off by the token limit or declined by the model, the loop stops instead of running a half-formed tool call. - The full reply goes back. The assistant message is appended exactly as received, so each tool result can be matched to its call through
tool_use_id. - All results in one message. The model can ask for several tools at once. Send all the results back together, in a single user message.
What Happens When You Run It
For Dana’s request, a typical run looks like this. The model’s exact wording will vary.
[step 1] get_order({'order_id': 'A-1001'}) -> {"customer": "Dana", "item": "Desk lamp", "total": 49.0, "status": "delivered"}
The agent wants to run refund_order({'order_id': 'A-1001', 'reason': 'Arrived broken'}). Allow? [y/N] y
[step 2] refund_order({'order_id': 'A-1001', 'reason': 'Arrived broken'}) -> {"order_id": "A-1001", "refunded_usd": 49.0, "reason": "Arrived broken"}
Hi Dana, I'm sorry the desk lamp arrived broken. I've refunded the full $49.00 for order A-1001. Now try order A-1002. The agent looks it up, sees the chair is still in transit, and explains that it cannot refund an order that has not arrived. Nobody wrote an if statement for that case. The model read the status and the rule in the system prompt and chose not to call the refund tool.
How to Make the Agent Production Ready
The example covers the loop. A real deployment needs a few more pieces:
- Logs for every tool call. Record the task, each tool name, its inputs, its output and who approved it. When something goes wrong, the log is how you find out why.
- Least privilege. Give the agent its own credentials with only the permissions its tools need. Our guide on how to secure AI agents in the enterprise covers identity, approvals and prompt injection in detail.
- Treat inputs as untrusted. A customer message can contain instructions aimed at the agent. Keep risky actions behind approvals, so a misleading message cannot complete them alone.
- A way to stop it. Someone on the team should be able to stop a running agent, keep it from restarting and see what it already did. Our guide to the AI agent kill switch walks through each layer.
- Test with real cases. Collect 20 to 50 past requests, run the agent on them, and check the results before and after every change to the prompt or tools.
- Use the SDK’s tool runner when you are ready. The Anthropic Python SDK includes a tool runner that handles this loop for you. Writing the loop once by hand makes it much easier to understand and debug what the runner does.
When Do You Need More Than One Agent?
Usually later than you think. One agent with a handful of well-described tools handles a surprising amount of work. Split the job across several agents when one agent needs too many tools to choose between reliably, when parts of the work need different permissions, or when independent tasks can run in parallel. Our explainer on multi-agent systems covers when that trade-off pays off, and compound AI systems explains how agents fit into larger products.
Back to the Refund Queue
The support lead from the opening now has an agent that finds the order, checks it against the rules, prepares the refund and drafts the reply. A person still approves each refund with one keystroke, and every step is on the record. That is the shape most useful agents take: the model handles the reading and deciding, and your code decides what it is allowed to do.
Frequently Asked Questions
Do I Need a Framework to Build an AI Agent in Python?
No. The loop in this guide is plain Python and the model provider’s SDK. Frameworks such as LangGraph or CrewAI add features like saved state and multi-agent coordination, which help on larger projects. Start without one so you know what the framework is doing for you.
Does the Model Run My Python Functions?
No. The model returns the name of a tool and the inputs it wants to use. Your program decides whether to run the function, runs it, and sends back the result. That is why approvals and checks belong in your code.
How Many Tools Can One Agent Use?
There is no fixed number, but choice gets harder as the list grows, especially when tools overlap. Keep each tool focused on one job with a clear description. If you need dozens, group them or split the work across agents.
What Does an AI Agent Cost to Run?
Each step is a model request, and every request resends the conversation so far, so cost grows with the number of steps and the size of tool results. Keep tool outputs short, set a step limit, and measure the cost per completed task on real examples before you scale up.





