We earn commissions when you shop through the links below.
If you’ve been wondering how to build an AI agent with Claude API, you’re in the right place. Claude’s API — built by Anthropic — has matured into one of the most capable foundations for building agents that can reason through problems, use tools, and take multi-step actions autonomously. In this guide, I’ll walk you through the core concepts and show you working code to get an agent running from scratch.
What Makes an AI Agent Different from a Simple Chatbot?
A chatbot responds to messages. An agent acts. It can decide to use a tool (like a web search, a calculator, or a database query), observe the result, and then continue reasoning — looping until the task is complete. The key ingredients are:
- A capable LLM — Claude 3.5 Sonnet or Claude 3 Opus work well here
- Tool definitions — functions the model can call
- An agentic loop — your code that keeps feeding tool results back to Claude
- Memory — conversation history passed with each request
Claude’s API supports tool use natively, which makes implementing this pattern much cleaner than older prompt-hacking approaches.
Setting Up Your Environment
You’ll need Python 3.10+ and the Anthropic SDK. Install it:
pip install anthropicSet your API key as an environment variable:
export ANTHROPIC_API_KEY=sk-ant-...I write my agent code inside Cursor — the AI-native editor is particularly useful when you’re iterating on agentic logic since you can ask it to explain tool-call flows and refactor loops without leaving the editor.
Defining Tools
Claude accepts tool definitions as JSON schemas. Here’s how to define two simple tools — a calculator and a weather lookup (stubbed for demonstration):
tools = [
{
"name": "calculate",
"description": "Evaluate a mathematical expression and return the result.",
"input_schema": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "A valid Python math expression, e.g. '2 ** 10'"
}
},
"required": ["expression"]
}
},
{
"name": "get_weather",
"description": "Get the current weather for a given city.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name, e.g. 'Berlin'"
}
},
"required": ["city"]
}
}
]Implementing the Tool Handlers
These are plain Python functions. The agent loop will call them when Claude requests a tool:
import math
def handle_tool_call(tool_name: str, tool_input: dict) -> str:
if tool_name == "calculate":
try:
result = eval(tool_input["expression"], {"__builtins__": {}}, vars(math))
return str(result)
except Exception as e:
return f"Error: {e}"
elif tool_name == "get_weather":
# Replace with a real API call in production
city = tool_input["city"]
return f"The weather in {city} is 22°C and sunny."
return "Unknown tool"Note: Never use bare eval() in production with untrusted input. This is simplified for illustration — use a proper expression parser like simpleeval in real code.
The Agentic Loop
This is the core of how to build an AI agent with Claude API. The loop sends messages to Claude, detects tool use requests, executes them, feeds results back, and continues until Claude produces a final text response:
import anthropic
client = anthropic.Anthropic()
def run_agent(user_message: str) -> str:
messages = [
{"role": "user", "content": user_message}
]
while True:
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=4096,
tools=tools,
messages=messages
)
# Check if Claude wants to use a tool
if response.stop_reason == "tool_use":
# Append Claude's response (which includes tool_use blocks)
messages.append({
"role": "assistant",
"content": response.content
})
# Process each tool call
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = handle_tool_call(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": result
})
# Feed results back to Claude
messages.append({
"role": "user",
"content": tool_results
})
else:
# Claude is done — extract the final text
for block in response.content:
if hasattr(block, "text"):
return block.text
return "No response generated."
# Test it
print(run_agent("What is 2 to the power of 16, and what's the weather in Tokyo?"))Run this and you’ll see Claude invoke both tools in a single turn, collect the results, and synthesize a coherent final answer. That’s the complete agentic loop.
Adding a System Prompt
Real agents need behavioral constraints. Add a system parameter to your API call:
response = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=4096,
system="You are a helpful assistant. Always use tools when you need factual or computed information. Be concise.",
tools=tools,
messages=messages
)A good system prompt reduces hallucination in tool selection and keeps the agent focused on its task domain.
Handling Memory and Long Conversations
The messages list is your memory. Every turn appends to it, giving Claude full context of the conversation. For long-running agents, you’ll eventually hit context limits. Common strategies:
- Summarization — periodically ask Claude to summarize earlier turns and replace them
- Sliding window — keep only the last N messages plus the system prompt
- External memory — store embeddings in a vector database and retrieve relevant context per turn
For production agents, I’d lean toward external memory — it scales better and lets the agent recall facts from previous sessions.
Deploying Your Agent
Once you’re past the prototype stage, you need somewhere to run your agent continuously. Railway is my go-to for this — you can deploy a Python FastAPI or Flask wrapper around your agent loop in minutes, with environment variable management built in and automatic deploys from GitHub. It handles the infrastructure so you can focus on agent behavior.
A minimal FastAPI wrapper looks like this:
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Query(BaseModel):
message: str
@app.post("/agent")
def agent_endpoint(query: Query):
result = run_agent(query.message)
return {"response": result}Push to GitHub, connect Railway, and you have a live agent API endpoint.
Common Pitfalls When Building Claude Agents
Infinite loops: If a tool always returns an error, Claude may keep retrying. Add a max iterations counter to your loop.
Token bloat: Tool results get appended to context. Large results (like full HTML pages) can eat tokens fast. Truncate or summarize tool outputs before passing them back.
Ambiguous tool descriptions: Claude decides which tool to use based on your description. Vague descriptions lead to wrong tool choices. Be specific about what each tool does and when to use it.
Missing error handling: Tools fail. Always return a meaningful error string from your handler rather than letting exceptions bubble up — Claude can reason about errors and try alternative approaches.
Where to Go From Here
Knowing how to build an AI agent with Claude API is the foundation, but production agents get more complex fast. You’ll want to explore:
- Parallel tool use — Claude can request multiple tools in a single response; process them concurrently
- Agent orchestration — multiple specialized agents calling each other
- Human-in-the-loop — pausing the agent for approval before high-stakes actions
- Structured outputs — using tool calls as a forcing function for JSON output
If you want to go deeper on AI engineering patterns more broadly, Udemy has solid courses on LLM application development that cover agent architectures, RAG pipelines, and evaluation strategies — worth browsing if you’re onboarding a team or want structured learning beyond documentation.
Final Thoughts
The pattern for how to build an AI agent with Claude API is genuinely straightforward once you internalize the loop: send messages, check for tool use, execute tools, append results, repeat. Claude handles the reasoning. You handle the infrastructure and tool implementations. Start simple with one or two tools, get the loop working correctly, then layer in memory, better error handling, and deployment. The hard part isn’t the code — it’s designing tools that are specific enough for Claude to use reliably and scoping agent behavior tightly enough that it doesn’t go off-rails in production.