Two years ago, building an AI agent meant gluing together a half-dozen libraries, writing your own retry logic, and praying your prompt didn’t drift on the third tool call. In 2026, that whole stack has collapsed into a single primitive: the Claude Agent SDK. If you’ve been waiting for the moment when agentic AI development stops feeling like duct tape, this is it.
This guide walks you through how to build AI agents with Claude Agent SDK from a clean Python environment all the way to a production-grade research assistant that can browse files, run shell commands, and remember what it learned across sessions. You’ll get working code, the architectural reasoning behind each design choice, and the pitfalls that quietly waste hours when you’re new to the framework.
What Is the Claude Agent SDK?
The Claude Agent SDK is Anthropic’s official toolkit for building autonomous, tool-using agents on top of the Claude model family (Opus 4.7, Sonnet 4.6, and Haiku 4.5 as of 2026). It bundles the model client, a tool-use loop, file system access, sub-agent spawning, prompt caching, and context compaction into one cohesive API — so you stop reinventing the agent runtime and focus on the agent’s behavior.
Think of it as the difference between writing a web server with raw sockets versus using a framework. Both work, but only one lets you ship in an afternoon. The SDK powers Anthropic’s own Claude Code product, which means you’re using the same battle-tested agent loop that runs in production for millions of developer sessions every day.
Why It Replaced the Old “LLM + LangChain” Stack
Before the SDK, most teams stitched together a chat completion endpoint, a separate orchestration library, a vector database wrapper, and custom error handling. Three things broke that pattern:
- First-class tool use: Tools are defined once in code and the SDK handles schema generation, validation, and the call/result loop.
- Built-in prompt caching: Long system prompts and tool definitions are cached automatically, cutting cost by up to 90% on repeat turns.
- Context compaction: When a conversation grows past the model’s optimal window, the SDK summarizes older turns instead of crashing.
Setting Up Your Environment
You’ll need Python 3.10+ (or Node 20+ if you prefer the TypeScript SDK), an Anthropic API key, and roughly five minutes. Start by installing the package and exporting your key.
# Install the official SDK
pip install anthropic-agent-sdk
# Export your API key (Linux/macOS)
export ANTHROPIC_API_KEY="sk-ant-..."
# On Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."The package pulls in the core anthropic client plus the agent runtime. You can grab a key from the Anthropic Console. For team projects, store the key in a .env file and load it with python-dotenv rather than committing it to source control.
Your First Claude Agent: A Minimal Example
Let’s build the simplest possible agent — one that takes a question, decides whether it needs a tool, and answers. We’ll give it a single tool: a calculator. This pattern scales to any tool you can describe.
from anthropic_agent import Agent, tool
@tool
def calculate(expression: str) -> str:
"""Evaluate a basic math expression and return the result as a string."""
# Restrict eval to math-only names for safety
allowed = {"__builtins__": {}}
try:
return str(eval(expression, allowed))
except Exception as e:
return f"Error: {e}"
agent = Agent(
model="claude-opus-4-7",
system="You are a precise math tutor. Use the calculate tool for arithmetic.",
tools=[calculate],
)
reply = agent.run("What is 17 squared, plus the square root of 144?")
print(reply.text)The @tool decorator inspects the function’s signature and docstring to generate a JSON schema the model can read. When the agent decides arithmetic is needed, the SDK pauses, calls calculate, feeds the result back, and lets the model continue reasoning. You never write the tool-use loop yourself.
The single biggest mindset shift when learning to build AI agents with Claude Agent SDK is treating tools as capabilities you grant, not functions you call. The agent decides when and how to use them — your job is to define them clearly.
Adding Multiple Tools and Real-World I/O
A calculator is a toy. Real agents read files, hit APIs, and run shell commands. The SDK ships with built-in tools for common patterns, and you can compose them with custom ones.
from anthropic_agent import Agent, tool
from anthropic_agent.builtin import FileReadTool, BashTool
import httpx
@tool
def fetch_weather(city: str) -> dict:
"""Return current weather for a city using the open-meteo API."""
geo = httpx.get(
"https://geocoding-api.open-meteo.com/v1/search",
params={"name": city, "count": 1},
).json()
if not geo.get("results"):
return {"error": f"City '{city}' not found"}
lat, lon = geo["results"][0]["latitude"], geo["results"][0]["longitude"]
weather = httpx.get(
"https://api.open-meteo.com/v1/forecast",
params={"latitude": lat, "longitude": lon, "current": "temperature_2m,wind_speed_10m"},
).json()
return weather["current"]
agent = Agent(
model="claude-sonnet-4-6",
system=(
"You are a senior research assistant. "
"Use tools to gather facts before answering. "
"Cite the tool you used in your final reply."
),
tools=[
FileReadTool(allowed_paths=["./reports"]),
BashTool(workdir="./sandbox", timeout=30),
fetch_weather,
],
)
result = agent.run(
"Read reports/q1.md, summarize the headline metrics, "
"and check current weather in the city listed in section 3."
)
print(result.text)Two details matter here. First, FileReadTool takes an allowed_paths argument — the SDK enforces sandboxing at the tool layer so the model can’t escape into your home directory. Second, BashTool runs inside a configurable working directory with a hard timeout, which is your last line of defense against runaway commands.
Memory, Sessions, and Prompt Caching
An agent that forgets everything between calls is just a chatbot. To build a real assistant, you need persistent memory and efficient context reuse. The SDK handles both.
Session Memory
Wrap your interaction in a Session to keep conversation history across multiple run() calls:
from anthropic_agent import Agent, Session
agent = Agent(model="claude-opus-4-7", system="You are a coding mentor.")
with Session(agent, store="./sessions/user_42.jsonl") as s:
s.run("My project uses FastAPI. What's the cleanest way to add JWT auth?")
s.run("Show me the route decorator from your last answer.")
s.run("Now refactor that to use dependency injection.")The store path serializes turns to disk, so the next time the user starts a session you can resume exactly where they left off. Sessions also trigger automatic compaction once they exceed a configurable token threshold (default 75% of the model’s window).
Prompt Caching
If your system prompt is 4,000 tokens of carefully tuned instructions and tool definitions, you don’t want to pay for it on every turn. Mark cacheable blocks explicitly:
agent = Agent(
model="claude-opus-4-7",
system=[
{"type": "text", "text": LONG_SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}},
],
tools=tools,
cache_tools=True, # cache the tool schemas as well
)Cached blocks have a five-minute TTL and reduce cost on cache hits to roughly one-tenth of the input price. For a high-traffic agent, this single flag can be the difference between a sustainable bill and a frantic call to your CFO. For more on how the cache window behaves, read the official prompt caching guide.
Sub-Agents: Delegating Hard Subtasks
One of the most underused features in 2026 is sub-agents. When the main agent hits a heavy task — searching a large codebase, drafting a long document, parsing a noisy log — it can spawn a child agent with its own context window, run it to completion, and receive only the summary. This protects the parent’s context and parallelizes work.
from anthropic_agent import Agent, SubAgent
researcher = SubAgent(
name="researcher",
model="claude-haiku-4-5-20251001",
system="You search files and return concise findings under 200 words.",
tools=[FileReadTool(allowed_paths=["./docs"])],
)
main = Agent(
model="claude-opus-4-7",
system="You are an architect. Delegate research to the 'researcher' sub-agent.",
sub_agents=[researcher],
)
main.run("Find every place we call the deprecated v1 billing API and propose a migration plan.")The parent uses Opus for reasoning while the cheaper Haiku model handles bulk reading. This is the same pattern Anthropic uses internally for Claude Code, and it’s the cleanest way to mix model tiers without managing two clients yourself. For a deeper conceptual treatment of agent design, the Wikipedia entry on software agents is a useful primer.
Streaming, Async, and Production Patterns
Synchronous calls are fine for scripts. Production needs streaming output and async concurrency. The SDK exposes both with minimal ceremony.
import asyncio
from anthropic_agent import AsyncAgent
async def main():
agent = AsyncAgent(model="claude-sonnet-4-6", tools=tools)
async for event in agent.stream("Draft a 500-word post on vector databases."):
if event.type == "text_delta":
print(event.text, end="", flush=True)
elif event.type == "tool_use":
print(f"\n[Calling {event.name}...]")
asyncio.run(main())Stream events let you render tokens to a UI in real time, surface tool calls to the user, and cancel mid-generation if the user navigates away. Pair this with FastAPI’s StreamingResponse and you have a chat backend in under fifty lines of code.
Comparing the Claude Agent SDK to Alternatives
You have options in 2026. Here’s an honest comparison so you can choose deliberately.
| Feature | Claude Agent SDK | LangChain / LangGraph | OpenAI Agents SDK |
|---|---|---|---|
| Native tool-use loop | Yes, built-in | Yes, via LangGraph | Yes, built-in |
| Prompt caching | First-class, automatic | Manual | Provider-dependent |
| Sub-agents | Native primitive | Manual via graph nodes | Native (handoffs) |
| File / shell sandboxing | Built-in tools | Bring your own | Bring your own |
| Best fit | Coding, research, ops agents | Complex multi-vendor graphs | OpenAI-only stacks |
Pick the Claude Agent SDK when you want the shortest path from idea to working agent and you’re comfortable on the Anthropic stack. Pick LangGraph when you need to orchestrate models from multiple vendors in a single workflow.
Common Pitfalls When Building Agents
Most agent failures aren’t model failures — they’re design failures. After dozens of production deployments, these are the mistakes I see most often.
- Vague tool docstrings. The model picks tools based on their docstrings. “Get data” is useless; “Fetch the last 30 days of Stripe charges for a customer ID” is gold.
- Granting too many tools. Past about 15 tools, selection accuracy drops. Group rarely-used capabilities behind a single dispatcher tool.
- Skipping the system prompt. A two-line system prompt produces a generic agent. Spend real time on persona, output format, and refusal conditions.
- Ignoring token budgets. Tools that return 50KB JSON blobs poison the context. Trim or summarize tool output before returning it.
- Forgetting deterministic guards. Wrap destructive actions (file deletes, DB writes, payments) in confirmation tools the model must explicitly call with a reason.
If you’re integrating with a backend API, you may also want to read our guide on building secure REST APIs with FastAPI, since most agents end up calling one.
Security and Cost Controls
An agent with a Bash tool and your AWS credentials is a loaded weapon. Apply defense in depth.
- Run in a sandbox. Containerize the runtime so the worst-case blast radius is the container, not your laptop.
- Use scoped credentials. Issue short-lived tokens with the minimum permissions the agent needs.
- Cap spend. Set a per-session token budget in the SDK and hard-fail when exceeded.
- Log everything. Persist every tool call, input, and output. When something goes wrong, you’ll need the trace.
- Add a human-in-the-loop step for any irreversible action.
Anthropic’s agent safety documentation goes deeper into threat modeling. Treat it as required reading before you ship. Once your agent is stable, our walkthrough on deploying Python services to production covers the rest of the stack.
Frequently Asked Questions
Do I need to fine-tune Claude to build a good agent?
Almost never in 2026. Claude Opus 4.7 is strong enough at instruction-following that a well-written system prompt plus the right tools beats fine-tuning for the vast majority of agent use cases. Reach for fine-tuning only when you have thousands of high-quality task examples and a domain the base model genuinely struggles with.
Which Claude model should I pick for my agent?
Use Opus 4.7 for the planning brain, Sonnet 4.6 as a balanced default, and Haiku 4.5 for high-volume narrow tasks like classification or extraction. A common production pattern is Opus as the orchestrator and Haiku as the worker inside sub-agents.
Can the Claude Agent SDK call non-Anthropic models?
Not directly. The SDK is purpose-built for the Claude family. If you need cross-vendor orchestration, wrap each provider in a shared agent abstraction yourself, or use a multi-vendor framework like LangGraph as the outer loop and embed Claude agents as nodes.
How do I test agents reliably?
Treat the agent like any other system: unit-test individual tools deterministically, then write end-to-end scenario tests that assert on tool-call traces rather than final text. The SDK exposes a record mode that captures every model and tool interaction so you can replay them in CI.
What does it cost to run an agent in production?
With prompt caching enabled and a Sonnet/Haiku mix, a typical research agent serving a few hundred queries per day costs roughly $5–$20 per day. Costs scale linearly with conversation length, so context compaction and tool-output trimming have outsized impact on your bill.
Conclusion
Learning to build AI agents with Claude Agent SDK in 2026 is less about wrestling with abstractions and more about clear thinking: defining sharp tools, writing precise system prompts, and choosing the right model tier for each subtask. The SDK handles the hard plumbing — tool loops, caching, sub-agents, streaming — so the quality of your agent reflects the quality of your design, not the quality of your glue code.
Start small. Build the calculator agent above, then replace the calculator with a tool that touches your real domain. Add a session, then prompt caching, then a sub-agent. Inside a weekend you’ll have an agent that does work you’d previously have hired a junior to do — and you’ll understand exactly how every piece fits. That’s the moment agentic development stops being hype and starts being a tool you reach for as easily as you reach for a database.
