The Claude Agent SDK is a Python and TypeScript library from Anthropic that runs the Claude Code agent loop, tools and context management inside your own application, and it was introduced in September 2025 as the renamed Claude Code SDK. People often confuse it with the Claude Code command line tool, with Anthropic's Client SDKs for calling the API directly, and with Managed Agents, where Anthropic hosts the agent. This page sets out what the SDK does, which versions are current, how it is licensed, what it costs to run, how hosting and data handling work and what has changed since the rename. It is written for developers, architects and the people who approve frameworks for a team. Every fact comes from Anthropic's own documentation, repositories, changelogs and pricing page. Last checked: 2026-11-15.
This is an independent guide from NHI Mgmt Group, based on Anthropic's public documentation as of November 2026. It is not sponsored or reviewed by Anthropic. Product features change, so confirm settings against Anthropic's current documentation.
Key takeaways
- The SDK has no licence fee, and its licences differ by language. The Python repository carries the MIT licence; the TypeScript repository states that use is subject to Anthropic's Commercial Terms of Service, which the overview says govern use of the SDK. You pay for model tokens and any paid server tools.
- It wraps the Claude Code binary. Each
query()spawns aclaudeCLI subprocess that owns a shell, a working directory and session files on disk. Both SDKs bundle a native binary for most installs. - API keys, not claude.ai login. The overview states that, unless previously approved, Anthropic does not allow third-party developers to offer claude.ai login or rate limits for products built on the SDK.
- Filesystem settings load by default. Omitting
settingSourcesloads user, project and local settings,CLAUDE.mdfiles and custom commands, so pass an empty list to isolate deployed or multi-tenant agents. - Telemetry is opt-in and cost figures are estimates. OpenTelemetry export runs only when configured, and the SDK's
total_cost_usdis a client-side estimate, not billing data.
What is Claude Agent SDK?
Anthropic's overview says the Agent SDK "gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript". It defines an agent as an application that completes a task by planning its own steps and calling tools that read files, run commands or edit code. The SDK was previously the Claude Code SDK; the migration guide says it was renamed to reflect "the SDK's broader capabilities for building AI agents beyond coding tasks."
The overview compares four ways to build with Claude. The Agent SDK embeds Claude Code's agent "in a process you operate". The Claude Code CLI is the terminal interface for interactive use. The Client SDK gives direct API access, where you write the tool loop yourself or use the beta tool runner. Managed Agents is "a hosted agent harness" with sessions in an Anthropic-managed cloud sandbox or a self-hosted sandbox. Languages other than Python and TypeScript can drive the same loop by running the CLI as a subprocess with -p and --output-format json.
| Component | What it is | Status as of 15 November 2026 |
|---|---|---|
| Agent SDK (Python and TypeScript) | Library that runs the Claude Code binary: built-in tools, permissions, sessions, hooks | Active; Python 0.2.182, TypeScript 0.3.325 |
| Claude Code SDK packages | Previous names: claude-code-sdk and @anthropic-ai/claude-code | Replaced by the Agent SDK packages; migration guide published |
| Claude Code CLI | Terminal interface; the binary the SDK bundles | Active; pinned to each SDK release |
| Managed Agents | Anthropic-hosted agent harness configured through the Claude API | Available; billed per session-hour plus tokens |
| Client SDK tool runner | Tool loop helper in the Client SDKs | Beta |
Key facts at a glance
As of 15 November 2026, from Anthropic's documentation and GitHub repositories.
| Field | Agent SDK for Python | Agent SDK for TypeScript |
|---|---|---|
| Owner | Anthropic | Anthropic |
| Package | claude-agent-sdk (import claude_agent_sdk) | @anthropic-ai/claude-agent-sdk |
| Licence | MIT (repository LICENSE) | Anthropic Commercial Terms of Service (repository LICENSE.md) |
| First release under the new name | 0.1.0, tagged 28 September 2025 | Not stated by Anthropic |
| Latest release | 0.2.182 (tagged 13 November 2026) | 0.3.325 (changelog), at parity with Claude Code v2.1.325 |
| Runtime requirement | Python 3.10 or later | Node.js 18 or later |
| Install | pip install claude-agent-sdk or uv add claude-agent-sdk | npm install @anthropic-ai/claude-agent-sdk |
| Bundled binary | Native Claude Code binary for most installs; pinned to the SDK version | |
| Versioning | Semantic versioning: "take patch releases continuously" and review the changelog before taking a minor | |
| Price | No licence fee; model and paid server tool usage billed by the provider | |
Plans and pricing
The SDK has no paid tier. Costs come from model tokens at Claude API rates, or the rates of the cloud platform you route through, plus any paid server tools. Anthropic's pricing page does not list a separate Agent SDK price. The hosting guide notes that "Anthropic token cost typically dominates container infrastructure cost by an order of magnitude or more", with a minimally provisioned container at roughly $0.05 per hour. Prices below are copied from Anthropic's pricing page as of 15 November 2026, in US dollars.
| Item | Price (Anthropic pricing page) |
|---|---|
| Web search server tool | $10 per 1,000 searches, plus standard token costs for search-generated content |
| Web fetch server tool | No additional cost; fetched content billed as tokens |
| Code execution server tool | 1,550 free hours per organisation per month, then $0.05 per hour per container; 5-minute minimum |
| Batch API | 50 percent discount on input and output tokens |
| Prompt caching | 5-minute write 1.25x, 1-hour write 2x, cache read 0.1x on most models |
| Managed Agents session runtime (for comparison with self-hosting) | $0.08 per session-hour while running, plus tokens |
Cost tracking in the SDK: result messages carry total_cost_usd, usage and per-model modelUsage (model_usage in Python). The documentation warns these are "client-side estimates, not authoritative billing data" and says not to bill end users from them; use the Usage and Cost API or the Claude Console. usage excludes subagent tokens, while total_cost_usd and modelUsage include them. The SDK uses prompt caching automatically, and max_budget_usd (maxBudgetUsd in TypeScript) caps spend per call.
Availability: the SDK works with a Claude API key or through third-party providers. Third-party developers may not offer claude.ai login or its rate limits unless Anthropic has approved it.
Models available
The SDK runs Claude models. You choose the model in the options (for example model="claude-opus-4-7" in the migration guide's example), and can mix models, for example a smaller model for subagents. Where the model is served depends on the authentication route set in the environment:
| Route | How it is configured | Notes from the docs |
|---|---|---|
| Claude API | ANTHROPIC_API_KEY | Key from the Claude Console; the SDK does not load .env files automatically |
| Amazon Bedrock | CLAUDE_CODE_USE_BEDROCK=1 and AWS credentials | Regional endpoint instead of api.anthropic.com |
| Claude Platform on AWS | CLAUDE_CODE_USE_ANTHROPIC_AWS=1, ANTHROPIC_AWS_WORKSPACE_ID and AWS credentials | Listed in the quickstart |
| Google Cloud's Agent Platform | CLAUDE_CODE_USE_VERTEX=1 and Google Cloud credentials | Regional endpoint instead of api.anthropic.com |
| Microsoft Foundry | CLAUDE_CODE_USE_FOUNDRY=1 and Azure credentials | Listed in the quickstart |
A proxy can also sit in front of the model API: the hosting guide describes setting ANTHROPIC_BASE_URL so a proxy injects the key outside the container.
Features and modes
- Built-in tools: read, write and edit files, run commands and search the web, using tool names such as
Read,Edit,Glob,Grep,BashandWebSearch.allowedToolspre-approves tools. - Permissions: modes in the Python types are
default,acceptEdits,plan,bypassPermissions,dontAskandauto, evaluated with allow and deny rules in a fixed order. AcanUseToolcallback can decide per call. - Hooks: custom code at points in the agent lifecycle, such as
PreToolUse. Python 0.2.177 addedon_failure="block"onHookMatcherto block an action when a hook callback fails. - Subagents: specialised agents for subtasks, defined through
AgentDefinition, which gainedskills,memoryandmcpServersfields in Python 0.1.49. Depth, concurrency and spend can be capped. - MCP: external MCP servers through
mcpServers, and in-process SDK MCP servers throughcreateSdkMcpServerandtoolin TypeScript. - Sessions: keep context across exchanges, resume or fork later. A
SessionStoreadapter mirrors transcripts to durable storage, with reference adapters for S3, Redis and Postgres (Python 0.1.64). - Skills, commands, memory and plugins: loaded from
.claude/and~/.claude/as in Claude Code; plugins package skills, agents, hooks and MCP servers and load by local path (Python 0.1.5). - System prompt: minimal by default since 0.1.0; request Claude Code's prompt with
{"type": "preset", "preset": "claude_code"}or pass your own.
Supported IDEs and platforms
The SDK is a library that needs Python 3.10 or later or Node.js 18 or later; the bundled CLI needs no separate Node.js install. Some installs have no bundled binary, such as a Python source distribution on ARM64 Windows or an npm install that skips optional dependencies, and then Claude Code must be installed natively. The quickstart covers macOS, Linux and Windows PowerShell. Anthropic's hosting cookbook has deployable code for local Docker, Modal and Kubernetes, and the secure deployment guide lists Docker, gVisor and Firecracker as self-hosted isolation options. The hosting guide suggests 1 GiB RAM, 5 GiB disk and 1 CPU per agent as a starting point and outbound HTTPS to api.anthropic.com or the provider's regional endpoint.
| Session pattern (hosting guide) | How it works | Example workloads from the docs |
|---|---|---|
| Ephemeral | One container per task, destroyed on completion | Bug fixing, invoice extraction, translation |
| Long-running | Persistent containers, often several SDK processes each | Email triage agent, chat bot on a messaging platform |
| Hybrid | Ephemeral containers that hydrate from a SessionStore | Research that pauses and resumes, support with ticket history |
| Multi-agent container | Several SDK subprocesses in one container | Multi-agent simulations in a shared environment |
Enterprise and admin controls
The SDK has no admin console: organisation controls come from the Claude Console account or the cloud platform behind the credentials, and from Claude Code's settings layers, which the SDK loads. Recent TypeScript releases expose settings tooling for hosts, such as resolveSettings() with machine policy information and matchDeniedModels() for deniedModels lists, both marked alpha. Partners have branding rules: "Claude Agent" or "{YourAgentName} Powered by Claude" are allowed, while "Claude Code" or "Claude Code Agent" are not. For permissions, hooks, API keys and sandboxing in depth, see the Claude Agent SDK Security Guide.
Data handling and privacy
The hosting guide states that three kinds of agent state live on the container's filesystem by default and none survive a restart or a move to another node. The table summarises where data goes and how to control it.
| Item | Default | Control |
|---|---|---|
| Session transcripts (JSONL) | ~/.claude/projects/ on local disk | SessionStore adapter to mirror to durable storage; CLAUDE_CONFIG_DIR to relocate |
Filesystem settings and CLAUDE.md | User, project and local settings loaded | settingSources: [] or setting_sources=[] (Python 0.1.59 and earlier treated an empty list as omitted) |
| Auto memory | Loaded into the system prompt regardless of settingSources | CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 |
| OpenTelemetry export | Off until configured | CLAUDE_CODE_ENABLE_TELEMETRY=1 and OTEL variables; traces also need CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 |
| Prompt text and tool inputs in telemetry | Not included | Opt-in flags on the observability page |
For multi-tenant containers the hosting guide adds a per-tenant cwd, a per-tenant CLAUDE_CONFIG_DIR and per-tenant egress rules at the proxy. It warns that when the SDK cannot deliver a batch to the session store, it drops the batch and emits a mirror_error message. Model provider retention follows the terms of the API or cloud platform used.
Release history
Dates are GitHub tag dates for the Python repository, with changes taken from the Python changelog and migration guide, as of 15 November 2026.
| Date | Release | What changed |
|---|---|---|
| 21 Jul 2025 | Claude Code SDK 0.0.16 | ClaudeSDKClient for bidirectional streaming |
| 28 Sep 2025 | 0.1.0 | Renamed Claude Agent SDK; ClaudeAgentOptions; minimal system prompt by default |
| 24 Oct 2025 | 0.1.5 | Plugin support through the plugins option |
| 31 Oct 2025 | 0.1.6 | max_budget_usd spend cap |
| 20 Mar 2026 | 0.1.49 | skills, memory and mcpServers on AgentDefinition |
| 16 Apr 2026 | 0.1.60 | W3C trace context propagation; optional [otel] extra |
| 20 Apr 2026 | 0.1.64 | SessionStore support and reference adapters |
| 29 Apr 2026 | 0.1.71 | Domain allowlist fields in sandbox network configuration |
| 15 May 2026 | 0.2.82 | First 0.2.x tag; EffortLevel type export |
| 18 Aug 2026 | 0.2.140 | Minimum Python release the hosting guide names for CLAUDE_CODE_PROJECT_DIR_NAME |
| 3 Nov 2026 | 0.2.177 | on_failure option on HookMatcher |
| 13 Nov 2026 | 0.2.182 | Latest Python tag at the time of checking |
Release cadence: most Python patch releases update the bundled Claude CLI version, and TypeScript releases state parity with a Claude Code version (0.3.325 with v2.1.325). Because the binary is pinned to the SDK package, updating the SDK is how you update the CLI.
Limits and known constraints
- No top-level session timeout: the hosting guide says a session does not time out on its own; set
max_turnsormaxTurnsto bound tool-use round trips. - Memory grows with session length: cap session length or recycle subprocesses, and size hosts from measured peak memory rather than the 1 GiB starting point.
- No per-subagent wall-clock deadline: cap each subagent with
maxTurns;CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MSis a stall watchdog, not a runtime deadline. - Wide subagent fan-outs can hit rate limits: the docs suggest smaller batches.
- Local state is lost on restart: without a
SessionStore, transcripts disappear when a container stops, and the store does not mirrorCLAUDE.mdor working-directory files. - Cost fields can drift: per-step
output_tokensis a placeholder, and estimates can differ from billing when prices change or a model is unknown to the installed version.
Security guidance
This page covers what the SDK is, how it is versioned, hosted and paid for. Hardening is covered in the Claude Agent SDK Security Guide, which goes through permission modes, canUseTool, hooks, sandboxing and MCP. From the SDK's own hosting documentation, the most useful practices are to keep tool credentials out of the agent environment and inject them at an egress proxy, to put inbound authentication at a gateway in front of the agent container, to route outbound traffic through a proxy with domain allowlists and logging, and to isolate tenants with empty settingSources, disabled auto memory and per-tenant directories. The TypeScript 0.3.325 notes also record that sandboxed Bash commands are no longer auto-approved unless autoAllowBashIfSandboxed: true is set. Apply Anthropic SDK updates promptly. The wider discipline is covered in the Securing Agent Frameworks Guide and the Runtime Secrets Injection for AI Agents Without Prompt Exposure guide.
Practitioner checklist
- Replace any
claude-code-sdkor@anthropic-ai/claude-codedependency with the Agent SDK packages and renameClaudeCodeOptionstoClaudeAgentOptions. - Set the system prompt explicitly, either the
claude_codepreset or your own. - Pass empty
settingSourcesand setCLAUDE_CODE_DISABLE_AUTO_MEMORY=1in deployed and multi-tenant agents, on a Python release later than 0.1.59. - Use API key or cloud provider authentication, and supply keys from a secret manager or an injecting proxy.
- Bound every session with
max_turnsand a spend cap, and alert onmirror_errormessages if transcripts matter. - Reconcile spend from the Usage and Cost API, not from
total_cost_usd. - Take patch releases continuously and read the changelog before each minor, since each release also moves the bundled CLI.
- Confirm the licence that applies to each package with legal review, as Python and TypeScript differ.
Standards and references
- Anthropic: Agent SDK overview
- Anthropic: Agent SDK quickstart
- Anthropic: Hosting the Agent SDK
- Anthropic: Migrate to Claude Agent SDK
- Anthropic: Track cost and usage
- Anthropic: Agent SDK for Python changelog
- Anthropic: Agent SDK for TypeScript changelog
- Anthropic: Claude API pricing
Related NHI Mgmt Group resources: Claude Agent SDK Security Guide · Securing Agent Frameworks Guide · AI Agent Sandboxing and Code Execution Guide · Runtime Secrets Injection for AI Agents Without Prompt Exposure