The Claude Agent SDK for Python is the official Python SDK released by Anthropic for building production-grade AI agents based on Claude. Its repository name is claude-agent-sdk-python, and the corresponding documentation title is "Claude Agent SDK for Python".
Purpose The SDK queries Claude Code through Python. The SDK automatically bundles the Claude Code CLI, so no separate installation is required; if you need to use a system-level installation or specify a version, you can install Claude Code separately (curl -fsSL https://claude.ai/install.sh | bash), or specify a custom path via ClaudeAgentOptions(cli_path="/path/to/claude").
Main capabilities
- query(): An asynchronous function used to query Claude Code, returning an AsyncIterator of response messages (see src/claude_agent_sdk/query.py). By default, Claude can use the full Claude Code toolset (Read, Write, Edit, Bash, etc.). allowed_tools is a permission allowlist: tools that are listed are automatically approved, and tools that are not listed are left to permission_mode and can_use_tool for a decision, rather than being removed from the toolset; to block specific tools, use disallowed_tools.
- Working directory and system prompt: By default, Claude Code builds and records the system prompt on the session's first request, and then reuses it for every subsequent request (including after resuming a session), so changes to custom prompts or the appended text of the claude_code preset will not take effect until the session is compacted or a new session starts. To rebuild the prompt on every request, set snapshot to False in the {"type": "preset", ...} or {"type": "custom", ...} dictionary. This feature requires Claude Code CLI 2.1.257 or later; before 2.1.265, sessions with appended or custom prompts are only recorded when snapshot is True.
- ClaudeSDKClient: Supports bidirectional interactive conversation with Claude Code (see src/claude_agent_sdk/client.py). Unlike query(), it also supports custom tools and hooks, both of which can be defined as Python functions.
- Custom tools (as in-process SDK MCP servers): Custom tools are Python functions that can be provided to Claude and called on demand. They run directly in the Python application as in-process MCP servers, without the separate process required by ordinary MCP servers. Advantages include: no subprocess management (running in the same process as the application), better performance (tool calls without IPC overhead), simpler deployment (a single Python process), easier debugging (all code in the same process), and type safety (direct Python function calls with type hints). The SDK and external MCP servers can be used simultaneously.
- Hooks: Hooks are Python functions invoked by the Claude Code application (not Claude) at specific points in the Claude agent loop, providing Claude with deterministic handling and automatic feedback.
Types and Errors For complete type definitions, see src/claude_agent_sdk/types.py, including ClaudeAgentOptions (configuration options), AssistantMessage, UserMessage, SystemMessage, ResultMessage (message types), TextBlock, ToolUseBlock, ToolResultBlock (content blocks). For all error types, see src/claude_agent_sdk/_errors.py. For a complete list of available tools, see the Claude Code documentation.
Usage and Examples
- Basic usage: query().
- For complete runnable examples, see examples/quick_start.py.
- For a comprehensive example of ClaudeSDKClient, see examples/streaming_mode.py; you can run the interactive example examples/streaming_mode_ipython.py in IPython.
- For an end-to-end example of custom tools, see MCP Calculator.
- For more hook examples, see examples/hooks.py.
Migrating from the Claude Code SDK If you are upgrading from the Claude Code SDK (version < 0.1.0), please refer to CHANGELOG.md for breaking changes and new features, including: ClaudeCodeOptions renamed to ClaudeAgentOptions, merged system prompt configuration, settings isolation and explicit control, and new programmatic subagents and session forking features.
Contributing and Building Contributors need to run the initial setup script to install git hooks; it installs a pre-push hook that runs lint checks before pushing to match the CI workflow; temporaryTo skip, you can use git push --no-verify. To build a wheel locally (with the built-in Claude Code CLI), use python scripts/build_wheel.py (see --help for all options); the build script downloads the Claude Code CLI for the current platform, packages it into the wheel, builds the wheel and source distribution, and checks them with twine. The release workflow publishes the package to PyPI via .github/workflows/publish.yml: manually trigger it on the Actions tab, entering version (the package version, e.g., 0.1.5) and claude_code_version (the version of the Claude Code CLI to bundle, e.g., 2.0.0 or latest). The workflow builds platform-specific wheels for macOS, Linux, and Windows, bundles the specified CLI version in each wheel, builds the source distribution, publishes all artifacts to PyPI, creates a release branch with the version update, and opens a PR containing the updated pyproject.toml version, src/claude_agent_sdk/_version.py, src/claude_agent_sdk/_cli_version.py (the bundled CLI version), and an automatically generated CHANGELOG.md entry. The workflow tracks the package version and the bundled CLI version separately, allowing a new package version with an updated CLI to be released without code changes.
Use Cases Suitable for developers who need to build Claude-based agents in Python, need interactive sessions, custom tools or hooks, and want to integrate tools in-process.
Limitations The official materials do not clearly state the SDK's fees, pricing, or commercial terms details; they only state that use is subject to Anthropic's Commercial Terms of Service; specific pricing and billing methods are not currently provided.
