Claude Agents API¶
Overview¶
The Claude Agents API is the production-ready way to build and deploy agents powered by Claude.
Creating Agents with SDK¶
Basic Agent¶
from anthropic import Anthropic
class ClaudeAgent:
"""Build agents with Claude SDK"""
def __init__(self, model: str = "claude-3-5-sonnet-20241022"):
self.client = Anthropic()
self.model = model
self.tools = []
def add_tool(self, name: str, description: str, input_schema: dict):
"""Register a tool"""
self.tools.append({
"name": name,
"description": description,
"input_schema": input_schema
})
def run(self, task: str):
"""Execute agent loop"""
messages = [
{"role": "user", "content": task}
]
while True:
# Get Claude's response
response = self.client.messages.create(
model=self.model,
max_tokens=4096,
tools=self.tools,
messages=messages
)
# Check if Claude wants to use tools
if response.stop_reason == "tool_use":
# Process tool calls
tool_results = self.process_tool_calls(response.content)
# Add Claude's response + tool results
messages.append({
"role": "assistant",
"content": response.content
})
messages.append({
"role": "user",
"content": tool_results
})
else:
# Claude is done
return self.extract_text(response.content)
def process_tool_calls(self, content):
"""Execute tools Claude requested"""
results = []
for block in content:
if block.type == "tool_use":
# Call tool
result = self.execute_tool(
block.name,
block.input
)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": result
})
return results
-
Deployment Options¶
REST API Endpoint¶
from fastapi import FastAPI
class DeployedAgent:
"""Deploy agent as API"""
def __init__(self):
self.app = FastAPI()
self.agent = ClaudeAgent()
@self.app.post("/agent/run")
async def run_agent(request):
"""Agent endpoint"""
try:
result = self.agent.run(request.task)
return {
"status": "success",
"result": result
}
except Exception as e:
return {
"status": "error",
"error": str(e)
}
def start(self):
"""Run API server"""
import uvicorn
uvicorn.run(self.app, host="0.0.0.0", port=8000)
State Management¶
Maintaining Context¶
class StatefulAgent:
"""Agent with persistent state"""
def __init__(self):
self.client = Anthropic()
self.conversation_history = []
self.user_context = {}
def add_context(self, user_id: str, context: dict):
"""Add user-specific context"""
self.user_context[user_id] = context
def run_with_context(self, user_id: str, task: str):
"""Execute with saved context"""
# Build system message with context
context = self.user_context.get(user_id, {})
system_prompt = self.build_system_prompt(context)
# Add to conversation
messages = [
*self.conversation_history,
{"role": "user", "content": task}
]
# Get response
response = self.client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=2048,
system=system_prompt,
messages=messages
)
# Save to history
self.conversation_history.append({
"role": "assistant",
"content": response.content[0].text
})
return response.content[0].text
-
Monitoring & Cost Optimization¶
Track Usage¶
class MonitoredAgent:
"""Agent with monitoring"""
def __init__(self):
self.client = Anthropic()
self.usage_log = []
def run_with_monitoring(self, task: str):
"""Execute with usage tracking"""
response = self.client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=[{"role": "user", "content": task}]
)
# Log usage
self.usage_log.append({
'task': task,
'input_tokens': response.usage.input_tokens,
'output_tokens': response.usage.output_tokens,
'cost': self.calculate_cost(response.usage)
})
return response.content[0].text
def calculate_cost(self, usage):
"""Estimate API cost"""
# Claude 3.5 Sonnet pricing (2024)
input_cost = usage.input_tokens * 0.003 / 1000
output_cost = usage.output_tokens * 0.015 / 1000
return input_cost + output_cost
3 Warnings¶
Warning 1: Unbounded Token Usage¶
# WRONG
# No token limits
response = client.messages.create(
model="claude-3-5-sonnet",
messages=messages
)
# Costs can spiral
# RIGHT
# Set max tokens
response = client.messages.create(
model="claude-3-5-sonnet",
max_tokens=1000, # Bounded!
messages=messages
)
Warning 2: No Error Handling¶
# WRONG
result = agent.run(task) # Might fail
# RIGHT
try:
result = agent.run(task)
except RateLimitError:
retry_with_backoff()
except APIError as e:
log_and_alert(e)
Warning 3: Forgotten Context Cleanup¶
# WRONG
# Conversation history grows forever
while True:
response = agent.run(task)
# Memory usage grows unbounded
# RIGHT
# Truncate old messages
if len(self.conversation_history) > 20:
# Keep last 20, drop oldest
self.conversation_history = self.conversation_history[-20:]
-
Last Updated: August 9, 2026