Skip to content

Anthropic Claude Agent SDK (Python)

Claude Code as a Python library — built-in tools, MCP, subagents, hooks, permissions and resumable sessions.

GroupModel-Specific
Current versionv0.2.183
Bonds withPy

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

Terminal window
pip install claude-agent-sdk==0.2.183

Version

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:

  • 0.2.170 — get_session_messages() returns every branch of parallel tool calls.
  • 0.2.166 — typed hook outputs and SystemInitData; SandboxSettings.ignoreViolations is now a dict[str, list[str]].
  • 0.2.158 — verbatim_prompts option: prompts are delivered literally, with no @file expansion or slash commands.
  • 0.2.140 — ResultError with structured failure details; can_use_tool works with query(); forward_subagent_text; mcp 2.x support.
  • 0.2.137 — ConversationResetMessage; message origin; resume_session_at / resume_drops_turn.
  • 0.2.129 — skill names are validated (breaking for skills=["*"]; use skills="all").
  • 0.2.126 — 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 asyncio
from 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 asyncio
from 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 →


DateVersionSummary
2026-11-170.2.183Bumped 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-250.2.174Bumped 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-250.2.170Audit 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-210.2.170Failure 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-210.2.170Guide 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-190.2.820.1.x → 0.2.x series.
2026-04-160.1.60Thinking configuration and file checkpointing documented.
20250.1.0Renamed from Claude Code SDK to Claude Agent SDK.

Note: the TypeScript package has its own guide: Claude Agent SDK (TypeScript).