Install
pip install claude-agent-sdk==0.2.183Claude Code as a Python library — built-in tools, MCP, subagents, hooks, permissions and resumable sessions.
Claude Code as a library. The Agent SDK gives Python code the same agent loop, built-in tools, permission system and sessions that power Claude Code, plus in-process custom tools via MCP.
Install
pip install claude-agent-sdk==0.2.183Version
Current release: claude-agent-sdk 0.2.183 · Python 3.10+ · checked 2026-11-19
Best for
Agents that read and change files, run commands and call tools on your own infrastructure.
Most releases only update the bundled Claude Code CLI. The ones that change the API:
get_session_messages() returns every branch of parallel tool calls.SystemInitData; SandboxSettings.ignoreViolations is now a dict[str, list[str]].verbatim_prompts option: prompts are delivered literally, with no @file expansion or slash commands.ResultError with structured failure details; can_use_tool works with query(); forward_subagent_text; mcp 2.x support.ConversationResetMessage; message origin; resume_session_at / resume_drops_turn.skills=["*"]; use skills="all").ResultMessage.terminal_reason; typed model_usage.See the migration guide for what to change, and the upstream CHANGELOG for everything else.
The SDK has two entry points: query() for one-shot tasks and ClaudeSDKClient for conversations. There is no Agent class.
import asynciofrom claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
async def main(): options = ClaudeAgentOptions( model="claude-opus-5-5", system_prompt="You are a helpful assistant.", ) async for message in query(prompt="What is 15 + 27?", options=options): if isinstance(message, ResultMessage): print(message.result)
asyncio.run(main())import asynciofrom claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock
async def main(): options = ClaudeAgentOptions(system_prompt="You are a helpful assistant.") async with ClaudeSDKClient(options=options) as client: await client.query("What is 15 + 27?") async for message in client.receive_response(): if isinstance(message, AssistantMessage): for block in message.content: if isinstance(block, TextBlock): print(block.text)
asyncio.run(main())Ready? Start Zero → Hero step 1 →
| Date | Version | Summary |
|---|---|---|
| 2026-11-17 | 0.2.183 | Bumped from 0.2.180 (0.2.181 to 0.2.183; bundled Claude CLI updates only, no API changes). Clarified that autoAllowBashIfSandboxed must be set for sandboxed Bash to skip approval. |
| 2026-10-25 | 0.2.174 | Bumped from 0.2.170 (0.2.171 to 0.2.174, released 2026-10-21 to 2026-10-24). The Python sources are unchanged; only the bundled Claude Code CLI moved (2.1.306 to 2.1.310). Re-ran the guide’s imports against the installed package and the offline stub-CLI test from the recipes (success and ResultError paths): both pass. No API changes to document. |
| 2026-10-25 | 0.2.170 | Audit against the installed package: added hook patterns (input rewriting, prompt screening, Stop hook) and a skills, slash commands and plugins section; autoCompactThreshold read with .get() because the key is optional. |
| 2026-10-21 | 0.2.170 | Failure handling corrected: the SDK yields the error ResultMessage before raising ResultError, so the retry helpers now keep reading and decide from subtype / api_error_status (tested against a stub CLI). Corrected the setting_sources default (all sources), hooks vs pre-approved tools, load_timeout_ms, usage vs model_usage; replaced TodoWrite with the Task tools. Added user input and approvals, image prompts, a SQLite SessionStore with its conformance test, a stub-CLI testing recipe and a FastAPI SSE recipe; rewrote the diagrams page. |
| 2026-10-21 | 0.2.170 | Guide rewritten as Python-only and re-verified against the installed package: removed TypeScript duplicates and invented options (api_provider, checkpoint_dir, enable_subagents, temperature, permission_prompt_tool_callback), fixed query() keyword-only usage and isinstance-based message handling, added permissions, hooks, structured output, session stores and file checkpointing, updated models to the Claude 5 family. |
| 2026-05-19 | 0.2.82 | 0.1.x → 0.2.x series. |
| 2026-04-16 | 0.1.60 | Thinking configuration and file checkpointing documented. |
| 2025 | 0.1.0 | Renamed from Claude Code SDK to Claude Agent SDK. |
Note: the TypeScript package has its own guide: Claude Agent SDK (TypeScript).