If you've been building on the raw Anthropic API, you know the loop. Call the API, check if it wants to use a tool, execute the tool, pass results back, repeat. It works, but you write the same scaffolding every time.
The Anthropic Agent SDK is Anthropic's answer to that scaffolding problem. Here's what it actually gives you.
What the SDK Handles
The raw API returns a response. You figure out what to do with it. The SDK gives you an agent loop — the thing that runs the API repeatedly until the agent decides it's done.
The three things the SDK abstracts:
- Tool dispatch — You define tools, the SDK calls them when the model asks, and returns results automatically.
- Conversation state — The message history is managed for you. You don't manually append user/assistant turns.
- Stop conditions — The loop terminates when the agent signals completion, rather than you deciding when to stop.
A Minimal Agent
Here's a simple agent that can search a knowledge base and answer questions:
from anthropic import Anthropic
from claude_agent_sdk import Agent, tool
client = Anthropic()
@tool
def search_kb(query: str) -> str:
"""Search the knowledge base for relevant information."""
# Your retrieval logic here
results = vector_db.search(query, k=3)
return "\n\n".join(r.text for r in results)
@tool
def get_current_date() -> str:
"""Get the current date."""
from datetime import date
return date.today().isoformat()
agent = Agent(
client=client,
model="claude-opus-4-5",
tools=[search_kb, get_current_date],
system="You are a helpful assistant with access to a knowledge base."
)
response = agent.run("What's the refund policy for orders placed last week?")
print(response.final_message)
Compare that to the raw API equivalent — you'd be writing 50+ lines of dispatch logic and message management.
What's Actually Different
The key insight is that the SDK separates what the agent can do (tools) from how the agent loop works (the SDK). This is the right abstraction.
With the raw API, your tool dispatch logic is interleaved with your business logic. With the SDK, tools are just Python functions with docstrings. The SDK handles the rest.
The SDK also surfaces events at each step of the loop — tool calls, tool results, intermediate messages. This is useful for logging, streaming UI updates, or implementing human-in-the-loop interruption points.
async for event in agent.stream("Summarize last week's tickets"):
if event.type == "tool_call":
print(f"Calling: {event.tool_name}({event.input})")
elif event.type == "message":
print(event.content, end="", flush=True)
What It Doesn't Do
The SDK doesn't handle:
- Persistence — Conversation state lives in memory. You manage storage.
- Multi-agent orchestration — This is single-agent. For multi-agent patterns you need something on top.
- Retry logic — If a tool call fails, you handle that in the tool function.
- Cost tracking — You get token counts in the response, but no built-in cost accounting.
Should You Use It?
If you're building a simple agent that calls a few tools and needs to be production-ready quickly — yes. The SDK reduces boilerplate significantly and the event streaming is genuinely useful.
If you're building complex multi-agent systems with custom orchestration — you'll probably outgrow the SDK quickly and want more control over the loop. That's not a criticism; it's just scope.
The raw API isn't going anywhere. The SDK is a layer on top for the common case. Use it when it fits.