Two years ago, wiring Claude into a Python script meant calling the raw Messages API and writing your own loop to handle tool calls. That worked, but it forced every team to reinvent the same scaffolding: retry logic, tool dispatch, context management, and subagent coordination. On April 22, 2026, Anthropic shipped the Claude Agent SDK as a first-party Python library and gave all of that scaffolding a name and a stable interface.
The rename from "Claude Code SDK" to "Claude Agent SDK" signals more than branding. The original SDK was scoped to coding assistants running inside terminals. The new one is scoped to agents running anywhere: backend pipelines, customer-facing products, internal tools, and multi-agent systems where one Claude instance spawns others. If you built on the Claude Code SDK, your code still runs. The migration path is mechanical. But the new primitives open capabilities that were awkward or impossible before.
What the Claude Agent SDK actually ships
The SDK's core abstraction is the agent loop: a structured Python coroutine that runs Claude, receives tool calls, executes them, feeds results back, and continues until Claude signals completion or a permission callback intervenes. You no longer write this loop yourself. You define your tools, your permission policy, and your system prompt, then hand control to the SDK.
The three capabilities that matter most for production use:
- Subagent spawning - A parent agent can programmatically launch child agents with narrower contexts and tool sets. Each child runs its own loop and returns a structured result. This is how you build reliable multi-step pipelines without a single context window ballooning to 200K tokens.
- MCP tool wiring - The SDK has native support for the Model Context Protocol. You point it at an MCP server and tools appear in the agent's tool list automatically, with schema validation handled before Claude ever sees the call.
- Permission callbacks - Every tool call can be intercepted by a Python function before execution. Return
allow,deny, orask. This is how you build human-in-the-loop workflows without polling or message queues.
The TypeScript version of the SDK has existed since Claude Code launched. Python parity on April 22 means backend teams no longer need to bridge the two languages, and the Python data science ecosystem (LangChain, pandas, FastAPI) connects directly without an intermediate TypeScript layer.
The migration from Claude Code SDK
If you used the Claude Code SDK via the TypeScript @anthropic-ai/claude-code package to run Claude programmatically, the surface-level API is compatible. The package name and some method signatures changed, but the concepts map directly. Anthropic published a migration guide in their official documentation that covers the exact diff.
For Python teams starting fresh, the install is straightforward:
- Install the package.
pip install anthropicpulls the Anthropic Python SDK, which now includes the agent primitives. No separate package is required. - Define your tools. Tools are Python functions decorated with
@tool. Type annotations become the JSON schema Claude sees. No manual schema writing. - Set a permission policy. Pass a
PermissionHandlersubclass or a simple callback. Every tool call routes through it before execution. - Run the loop. Call
agent.run(prompt)and await the result. The SDK handles turn management, token counting, and tool dispatch internally.
The best agent architecture is one where Claude decides what to do and your code decides whether it's allowed to do it.
Why the permission model changes everything
The single biggest gap in DIY agent loops has always been safety. When you write your own tool dispatch, you either trust every tool call Claude makes or you bolt on ad hoc checks that are easy to miss. The Claude Agent SDK makes the permission layer a first-class citizen, not an afterthought.
A permission callback receives the tool name, the full argument payload, and the conversation context at the moment of the call. Your callback can check against a policy database, log to an audit trail, or surface a real-time confirmation to a human operator before anything executes. The agent loop pauses and resumes correctly. No message queue plumbing required.
This matters practically for three common scenarios:
- Financial operations - An agent that can query account data should not also be able to initiate transfers without a human checkpoint. The permission callback enforces that boundary at the SDK level, not in a prompt.
- External API calls - Agents that can read a CRM should not automatically be able to write to it. Separate the read and write tools, then deny writes in the permission handler until conditions are met.
- Multi-tenant systems - When one agent serves multiple users, the permission callback receives context that lets you enforce row-level isolation without baking tenant IDs into every tool prompt.
Subagents and the case for smaller contexts
The instinct when building complex agents is to give Claude everything: a massive system prompt, all available tools, and a long conversation history. That instinct is expensive and unreliable. A 200K-token context costs roughly 12x more per call than a 16K-token one, and accuracy degrades when the model has to track too many competing instructions at once.
The subagent model inverts this. A parent agent handles orchestration: it receives the user's goal, breaks it into subtasks, and spawns child agents with focused contexts. A child agent tasked with "summarize this contract" gets only the contract, a summarization tool, and a tight system prompt. It returns a structured result. The parent never sees the full contract text in its own context window.
This architecture maps cleanly onto real products. At SARVAYA, we build custom AI automation systems for clients who need agents that can read data from one platform, reason about it, and write results to another, without leaking context across tenants or blowing up API costs. The Claude Agent SDK's subagent primitives make that pattern straightforward to implement in Python for the first time.
MCP and the tool ecosystem
The Model Context Protocol, which Anthropic published as an open standard in late 2024, defines a transport-agnostic way to expose tools to language models. The Claude Agent SDK treats MCP as the default tool interface rather than a bolt-on.
In practice this means you can point the SDK at any MCP-compatible server and the tools register automatically. The current MCP ecosystem already covers GitHub, Slack, Linear, Postgres, filesystem operations, browser automation via Playwright, and dozens of other integrations maintained by the community. Your agent gets access to all of them without you writing a single tool implementation.
The SDK validates MCP tool schemas before passing calls to Claude, which eliminates a whole class of hallucinated argument errors. It also handles the transport layer: local stdio servers, HTTP+SSE servers, and WebSocket servers all work through the same SDK interface.
What this means for teams building on Claude now
The Claude Agent SDK is not the right tool for every use case. If you're building a simple chatbot, the Messages API is still the correct entry point. The SDK adds value when your use case has at least two of these characteristics: multiple tool calls per session, decisions that require human approval, tasks that benefit from parallel subagent execution, or integrations with external systems via MCP.
For teams already using AI automation in their business workflows, the SDK reduces the gap between a proof-of-concept and a production system. The scaffolding that used to take two weeks to build correctly ships on day one. You spend that time on the business logic that actually differentiates your product.
Getting started without over-engineering
Start with one tool and one permission callback. Get the loop running for a single task before you add subagents or MCP integrations. The SDK is designed so you can add complexity incrementally, and the permission layer works correctly with one tool just as it does with twenty.
The official Claude Agent SDK documentation includes working Python examples for the most common patterns: file operations, web search, multi-step data pipelines, and human-in-the-loop approval flows. Read those before designing your own architecture.
If you're building a product that needs agents handling real business operations, reach out through our project inquiry page. We've been building production Claude integrations since the API launched, and we know where the sharp edges are.
