# Claude Agent SDK for Python

> Python SDK for building agents on Claude Code, with streaming queries, custom in-process MCP tools, and hooks.

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.

## 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

## Integrations
Claude Code, Model Context Protocol (MCP), PyPI

## Platforms
WINDOWS, MACOS, LINUX, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.2.174

## Links
- Website: https://github.com/anthropics/claude-agent-sdk-python
- Documentation: https://platform.claude.com/docs/en/agent-sdk/python
- Repository: https://github.com/anthropics/claude-agent-sdk-python
- EveryDev.ai: https://www.everydev.ai/tools/claude-agent-sdk-python