Claude Agent SDK for Python
Python SDK for building agents on Claude Code, with streaming queries, custom in-process MCP tools, and hooks.
At a Glance
About Claude Agent SDK for Python
Claude Agent SDK for Python is Anthropic's Python SDK for programmatically driving Claude Code. It is installed with pip, requires Python 3.10+, and bundles the Claude Code CLI by default. The repository is MIT-licensed, and the latest listed release is v0.2.174.
What It Is
The SDK lets Python applications send prompts to Claude and receive streamed response messages. Developers use the async query() function for one-off requests, or ClaudeSDKClient for bidirectional, interactive conversations. By default Claude has access to the Claude Code toolset (Read, Write, Edit, Bash, and others), and options control permissions, working directory, system prompt and turn limits.
Custom Tools and Hooks
With ClaudeSDKClient, developers can define custom tools as Python functions using the @tool decorator and expose them through in-process SDK MCP servers. These run inside the application without separate subprocesses, and can be mixed with external stdio MCP servers. Hooks are Python functions invoked by the Claude Code application at points in the agent loop, such as PreToolUse, and can allow or deny actions like specific Bash commands.
Permissions and Configuration
allowed_tools pre-approves tools, disallowed_tools blocks them, and permission_mode and can_use_tool decide the rest. The system prompt can be customized, with a snapshot setting that controls whether it is rebuilt on every request (requires a recent Claude Code CLI). A custom CLI path can be set to use a system-wide installation.
Errors and Migration
The SDK provides typed errors such as CLINotFoundError, ProcessError, ResultError and CLIJSONDecodeError. Users of the earlier Claude Code SDK can follow the changelog for the rename from ClaudeCodeOptions to ClaudeAgentOptions. Use is governed by Anthropic's Commercial Terms of Service.
Community Discussions
Be the first to start a conversation about Claude Agent SDK for Python
Share your experience with Claude Agent SDK for Python, ask questions, or help others learn from your insights.
Pricing
Open Source (MIT)
Claude Agent SDK for Python, licensed under the MIT License. Use is also governed by Anthropic's Commercial Terms of Service; the SDK calls Claude, so API usage costs are external.
- MIT License declared in repository and LICENSE file
- Python 3.10+
- Bundles the Claude Code CLI
- README states use is governed by Anthropic's Commercial Terms of Service except for components covered by a different LICENSE file
Capabilities
Key Features
- Async query() function streaming response messages
- ClaudeSDKClient for bidirectional interactive conversations
- Custom tools as in-process SDK MCP servers
- Mixed SDK and external MCP server support
- Python hooks such as PreToolUse for deterministic control
- Tool permission controls (allowed_tools, disallowed_tools, permission_mode)
- Configurable system prompt and working directory
- Bundled Claude Code CLI with optional custom path
- Typed error classes for CLI and process failures
- Programmatic subagents and session forking
