Claude Agent SDK

What is Claude Agent SDK?

The Claude Agent SDK is Anthropic's own library for building custom, production-grade AI agents in Python or TypeScript — built on top of the same agent harness, tool loop and context management that power Claude Code, exposed as code you call directly rather than a CLI you type into. It ships two APIs (a one-shot query() function and a stateful ClaudeSDKClient for multi-turn sessions), the full Claude Code toolset (file read/write/edit, bash execution, web search and fetch), hooks that intercept agent behavior at each step, subagents for delegating focused subtasks, and native Model Context Protocol (MCP) support for both in-process and external tool servers. Unlike this category's other major-lab SDKs — OpenAI Agents SDK, Google ADK and Microsoft Agent Framework all reach other model providers through a LiteLLM-style integration — the Claude Agent SDK runs Claude models only; a GitHub issue asking Anthropic to support other providers was closed as "not planned." The Python and TypeScript wrapper packages themselves carry an MIT license, but Anthropic's own docs state that use of the SDK as a whole is governed by its Commercial Terms of Service, and the compiled Claude Code CLI binary the wrapper bundles and spawns as a subprocess isn't published as source — so it doesn't clear this index's bar for a genuinely, fully self-hostable open-source tool.

What does Claude Agent SDK do?

Calling query() spawns a claude CLI subprocess over stdio and streams back an async iterator of messages for a one-off task; ClaudeSDKClient holds that subprocess open across turns for an interactive, stateful conversation. The agent gets Claude Code's full built-in toolset by default — file read/write/edit, bash execution, web search and fetch — gated per-call by allowed_tools/disallowed_tools allowlists or a broader permission_mode. You can define your own tools as plain Python or TypeScript functions with the @tool decorator and mount them as an in-process MCP server (no subprocess management), or connect external MCP servers the same way Claude Code does. Hooks let you intercept and approve or block specific tool calls (e.g. every Bash command) before they run, and subagents let one session spawn focused specialist agents for a subtask. For production you either self-host the subprocess yourself — Anthropic's hosting docs cover session persistence, scaling and multi-tenant isolation across Docker/Kubernetes/sandbox providers like Modal, E2B and Fly Machines — or hand the whole thing to Claude Managed Agents, a separate Anthropic-hosted REST API where Anthropic runs the agent and the sandbox and your app just sends events and streams results back, with no infrastructure of your own to operate.

How Claude Agent SDK works

1. 1Install the SDK (pip install claude-agent-sdk or npm install @anthropic-ai/claude-agent-sdk) and set ANTHROPIC_API_KEY — the package bundles a matching Claude Code CLI binary, no separate install.
2. 2Call query() for a one-shot task, or open a ClaudeSDKClient session for a multi-turn, stateful conversation — either spawns a claude CLI subprocess and streams back messages.
3. 3Grant the built-in Claude Code toolset (files, bash, web search/fetch) via allowed_tools, or define custom tools with the @tool decorator and mount them as an in-process MCP server; add hooks to approve or block specific tool calls.
4. 4Deploy by self-hosting the subprocess on your own infrastructure (Docker, Kubernetes, or a sandbox provider like Modal or E2B), or route the same workload to Claude Managed Agents, a separate Anthropic-hosted REST API, for zero infrastructure to operate.

Who is Claude Agent SDK for?

• Developers who already use Claude Code and want the same agent loop, tools and context management as a library inside their own application, not just a terminal tool
• Teams building a single-vendor Claude-based agent who don't need multi-provider flexibility — the tradeoff for the SDK's tight integration with Claude Code's own toolset
• Teams that want to skip building the agent loop, tool execution and context management themselves and are comfortable running a subprocess-based architecture (or handing that off entirely to Claude Managed Agents)

Key features

• Two APIs: query() and ClaudeSDKClient: A simple async query() function for one-off tasks, and a stateful ClaudeSDKClient for interactive, multi-turn sessions that hold the same subprocess open across exchanges.
• Full Claude Code toolset by default: File read/write/edit, bash execution, and web search/fetch are available out of the box, gated per-call by allow/deny lists or a broader permission mode.
• In-process custom tools (SDK MCP servers): Define Python or TypeScript functions as tools with the @tool decorator and mount them as an in-process MCP server — no subprocess management, faster and easier to debug than an external MCP server.
• Hooks: Intercept agent behavior at specific lifecycle points — e.g. approve or block a specific Bash command before it runs — for custom guardrails the built-in permission system alone doesn't cover.
• Subagents: Spawn specialized agents for focused subtasks from within a session, rather than hand-rolling task delegation yourself.
• Claude Managed Agents (optional hosted layer): A separate Anthropic-hosted REST API — Anthropic runs the agent and the sandbox, your app sends events and streams results, for teams that don't want to operate subprocess hosting infrastructure themselves.

What are Claude Agent SDK's use cases?

• Bug-fixing agent embedded in an internal tool: A team wires query() into an internal dashboard so an engineer can describe a bug and the agent reads the repo, proposes a fix and opens a draft PR — the same quickstart Anthropic's own docs walk through.
• Long-running triage agent: An email or support-ticket triage agent runs as a long-lived ClaudeSDKClient session per user, held open across many turns, deployed as a persistent container per Anthropic's own 'long-running sessions' hosting pattern.
• Skip self-hosting entirely: A team that doesn't want to operate subprocess infrastructure, session persistence or multi-tenant isolation routes the same agent code to Claude Managed Agents instead, trading some infrastructure control for zero hosting to operate.

What does Claude Agent SDK integrate with?

• Model Context Protocol (MCP) — both in-process SDK servers and external MCP servers
• Claude Managed Agents (Anthropic-hosted REST API deployment target)
• Sandbox/hosting providers: Modal, Cloudflare Sandboxes, Daytona, E2B, Fly Machines, Vercel Sandbox
• OpenTelemetry (OTLP traces, metrics and logs export)
• Amazon Bedrock and Google Cloud regional endpoints (via ANTHROPIC_BASE_URL routing)

Why use Claude Agent SDK?

• Anthropic's own official library, built on the same agent harness that powers Claude Code itself — not a third-party wrapper reverse-engineering Claude's tool-calling behavior.
• The full built-in Claude Code toolset (files, bash, web search/fetch) plus native MCP support ships by default — you're not rebuilding a tool loop or a permissions layer from scratch.
• A genuine choice between self-hosting the subprocess yourself (with a documented cookbook for Docker/Kubernetes/sandbox providers) or handing the whole thing to Claude Managed Agents, Anthropic's own hosted REST API — the same 'self-host or managed' shape this category's other major-lab SDKs offer.
• Actively developed and dated: Agent Skills shipped as a new capability, and Anthropic reversed a controversial June 2026 billing change (a separate 'Agent SDK credit') within a day of it taking effect after user backlash — a vendor that responds fast, if also one that changes billing terms with real turbulence.

Pros & cons

Claude Agent SDK pricing

• SDK (self-hosted)Free
• Claude API usage (pay-as-you-go)$1–$10 / MTok input, $5–$50 / MTok output / by model
• Claude Managed Agents (hosted)Token rates + $0.08/session-hour / usage-based

See current pricing on code.claude.com ↗Compare Claude Agent SDK alternatives →

Claude Agent SDK review

The Claude Agent SDK is Anthropic's answer to the same question Microsoft, Google and OpenAI have already answered with their own official SDKs — but it takes the most tightly-integrated, least model-agnostic approach of the four. Instead of a general-purpose agent framework that happens to support Claude, it's the literal agent harness behind Claude Code, exposed as a library: the same tools, the same agent loop, the same context management, callable from your own Python or TypeScript code, with a genuine choice between self-hosting the subprocess yourself or handing it to Claude Managed Agents, Anthropic's own hosted REST API. The tradeoff for that tight integration is real: it runs Claude models only (a GitHub issue asking for other providers was closed "not planned"), the MIT license on the wrapper packages doesn't extend to the closed-source CLI binary they bundle and spawn, and Anthropic changed how programmatic usage is billed twice in six weeks in mid-2026, reversing a planned split onto a separate credit pool on the day it was due to take effect. Pick it if you're already committed to Claude and want its exact production harness as a library rather than reimplementing a tool loop yourself; pick one of its three multi-provider siblings if vendor flexibility matters more than the depth of that integration.

Anthropic's own agent-building library — the literal Claude Code harness exposed as code, with the tightest single-vendor integration in this category's four major-lab SDKs, and the only one of the four with no supported path to another model provider.

Frequently asked questions