Skip to main content

Claude Agent SDK for Python

Python SDK for Claude Agent. See the Claude Agent SDK documentation for more information.

Installation

pip install claude-agent-sdk

Prerequisites:

  • Python 3.10+

Note: The Claude Code CLI is automatically bundled with the package - no separate installation required! The SDK will use the bundled CLI by default. If you prefer to use a system-wide installation or a specific version, you can:

  • Install Claude Code separately: curl -fsSL https://claude.ai/install.sh | bash
  • Specify a custom path: ClaudeAgentOptions(cli_path="/path/to/claude")

Quick Start

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)

anyio.run(main)

Basic Usage: query()

query() is an async function for querying Claude Code. It returns an AsyncIterator of response messages. See src/claude_agent_sdk/query.py.

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

# Simple query
async for message in query(prompt="Hello Claude"):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)

# With options
options = ClaudeAgentOptions(
    system_prompt="You are a helpful assistant",
    max_turns=1
)

async for message in query(prompt="Tell me a joke", options=options):
    print(message)

Using Tools

By default, Claude has access to the full Claude Code toolset (Read, Write, Edit, Bash, and others). allowed_tools is a permission allowlist: listed tools are auto-approved, and unlisted tools fall through to permission_mode and can_use_tool for a decision. It does not remove tools from Claude's toolset. To block specific tools, use disallowed_tools. See the permissions guide for the full evaluation order.

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],  # auto-approve these tools
    permission_mode='acceptEdits'  # auto-accept file edits
)

async for message in query(
    prompt="Create a hello.py file",
    options=options
):
    # Process tool use and results
    pass

Working Directory

from pathlib import Path

options = ClaudeAgentOptions(
    cwd="/path/to/project"  # or Path("/path/to/project")
)

System Prompt

By default, Claude Code builds the system prompt on a session's first request, records it, and reuses it on every later request, including after you resume the session. A changed custom prompt, or changed append text on the claude_code preset, then has no effect until the session is compacted or you start a new session. To rebuild the prompt on every request instead, for example while you iterate on its wording, set snapshot to False in the {"type": "preset", ...} or {"type": "custom", ...} dict:

options = ClaudeAgentOptions(
    system_prompt={"type": "custom", "prompt": "You are a release bot.", "snapshot": False}
)

Requires Claude Code CLI 2.1.257 or later. Before 2.1.265, a session with an append or custom prompt recorded it only when snapshot was True. See Modifying system prompts for details.

ClaudeSDKClient

ClaudeSDKClient supports bidirectional, interactive conversations with Claude Code. See src/claude_agent_sdk/client.py.

Unlike query(), ClaudeSDKClient additionally enables custom tools and hooks, both of which can be defined as Python functions.

Custom Tools (as In-Process SDK MCP Servers)

A custom tool is a Python function that you can offer to Claude, for Claude to invoke as needed.

Custom tools are implemented in-process MCP servers that run directly within your Python application, eliminating the need for separate processes that regular MCP servers require.

For an end-to-end example, see MCP Calculator.

Creating a Simple Tool

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient

# Define a tool using the @tool decorator
@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {
        "content": [
            {"type": "text", "text": f"Hello, {args['name']}!"}
        ]
    }

# Create an SDK MCP server
server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user]
)

# Use it with Claude. allowed_tools pre-approves the tool so it runs
# without a permission prompt; it does not control tool availability.
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Greet Alice")

    # Extract and print response
    async for msg in client.receive_response():
        print(msg)

Benefits Over External MCP Servers

  • No subprocess management - Runs in the same process as your application
  • Better performance - No IPC overhead for tool calls
  • Simpler deployment - Single Python process instead of multiple
  • Easier debugging - All code runs in the same process
  • Type safety - Direct Python function calls with type hints

Migration from External Servers

# BEFORE: External MCP server (separate process)
options = ClaudeAgentOptions(
    mcp_servers={
        "calculator": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "calculator_server"]
        }
    }
)

# AFTER: SDK MCP server (in-process)
from my_tools import add, subtract  # Your tool functions

calculator = create_sdk_mcp_server(
    name="calculator",
    tools=[add, subtract]
)

options = ClaudeAgentOptions(
    mcp_servers={"calculator": calculator}
)

Mixed Server Support

You can use both SDK and external MCP servers together:

options = ClaudeAgentOptions(
    mcp_servers={
        "internal": sdk_server,      # In-process SDK server
        "external": {                # External subprocess server
            "type": "stdio",
            "command": "external-server"
        }
    }
)

Hooks

A hook is a Python function that the Claude Code application (not Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in Intercept and control agent behavior with hooks.

For more examples, see examples/hooks.py.

Example

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher

async def check_bash_command(input_data, tool_use_id, context):
    tool_name = input_data["tool_name"]
    tool_input = input_data["tool_input"]
    if tool_name != "Bash":
        return {}
    command = tool_input.get("command", "")
    block_patterns = ["foo.sh"]
    for pattern in block_patterns:
        if pattern in command:
            return {
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": f"Command contains invalid pattern: {pattern}",
                }
            }
    return {}

options = ClaudeAgentOptions(
    allowed_tools=["Bash"],
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="Bash", hooks=[check_bash_command]),
        ],
    }
)

async with ClaudeSDKClient(options=options) as client:
    # Test 1: Command with forbidden pattern (will be blocked)
    await client.query("Run the bash command: ./foo.sh --help")
    async for msg in client.receive_response():
        print(msg)

    print("\n" + "=" * 50 + "\n")

    # Test 2: Safe command that should work
    await client.query("Run the bash command: echo 'Hello from hooks example!'")
    async for msg in client.receive_response():
        print(msg)

Types

See src/claude_agent_sdk/types.py for complete type definitions:

  • ClaudeAgentOptions - Configuration options
  • AssistantMessage, UserMessage, SystemMessage, ResultMessage - Message types
  • TextBlock, ToolUseBlock, ToolResultBlock - Content blocks

Error Handling

from claude_agent_sdk import (
    ClaudeSDKError,      # Base error
    CLINotFoundError,    # Claude Code not installed
    CLIConnectionError,  # Connection issues
    ProcessError,        # Process failed
    ResultError,         # Run ended with an error result (subclass of ProcessError)
    CLIJSONDecodeError,  # JSON parsing issues
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("Please install Claude Code")
except ResultError as e:
    # The CLI reported a terminal error result (also yielded as the final
    # ResultMessage) and exited. Structured fields are on the exception.
    print(f"Run failed: {e.subtype=} {e.terminal_reason=} {e.api_error_status=}")
    print(e.result or e.errors)
except ProcessError as e:
    print(f"Process failed with exit code: {e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"Failed to parse response: {e}")

See src/claude_agent_sdk/_errors.py for all error types.

Available Tools

See the Claude Code documentation for a complete list of available tools.

Examples

See examples/quick_start.py for a complete working example.

See examples/streaming_mode.py for comprehensive examples involving ClaudeSDKClient. You can even run interactive examples in IPython from examples/streaming_mode_ipython.py.

Migrating from Claude Code SDK

If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the CHANGELOG.md for details on breaking changes and new features, including:

  • ClaudeCodeOptions → ClaudeAgentOptions rename
  • Merged system prompt configuration
  • Explicit settings control
  • New programmatic subagents and session forking features

Development

If you're contributing to this project, run the initial setup script to install git hooks:

./scripts/initial-setup.sh

This installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use git push --no-verify.

Building Wheels Locally

To build wheels with the bundled Claude Code CLI:

# Install build dependencies
pip install build twine

# Build wheel with bundled CLI
python scripts/build_wheel.py

# Build with specific version
python scripts/build_wheel.py --version 0.1.4

# Build with specific CLI version
python scripts/build_wheel.py --cli-version 2.0.0

# Clean bundled CLI after building
python scripts/build_wheel.py --clean

# Skip CLI download (use existing)
python scripts/build_wheel.py --skip-download

The build script:

  1. Downloads Claude Code CLI for your platform
  2. Bundles it in the wheel
  3. Builds both wheel and source distribution
  4. Checks the package with twine

See python scripts/build_wheel.py --help for all options.

Release Workflow

The package is published to PyPI via the GitHub Actions workflow in .github/workflows/publish.yml. To create a new release:

  1. Trigger the workflow manually from the Actions tab with two inputs:

    • version: The package version to publish (e.g., 0.1.5)
    • claude_code_version: The Claude Code CLI version to bundle (e.g., 2.0.0 or latest)
  2. The workflow will:

    • Build platform-specific wheels for macOS, Linux, and Windows
    • Bundle the specified Claude Code CLI version in each wheel
    • Build a source distribution
    • Publish all artifacts to PyPI
    • Create a release branch with version updates
    • Open a PR to main with:
      • Updated pyproject.toml version
      • Updated src/claude_agent_sdk/_version.py
      • Updated src/claude_agent_sdk/_cli_version.py with bundled CLI version
      • Auto-generated CHANGELOG.md entry
  3. Review and merge the release PR to update main with the new version information

The workflow tracks both the package version and the bundled CLI version separately, allowing you to release a new package version with an updated CLI without code changes.

License and terms

Use of this SDK is governed by Anthropic's Commercial Terms of Service, including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license as indicated in that component's LICENSE file.

Metadata

Release files for claude-agent-sdk 0.2.186

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for claude-agent-sdk 0.2.186
File Size Uploaded Provenance Actions
claude_agent_sdk-0.2.186.tar.gz 409.3 kB Without provenance Details for claude_agent_sdk-0.2.186.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for claude-agent-sdk 0.2.186
File Actions
claude_agent_sdk-0.2.186-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for claude_agent_sdk-0.2.186-py3-none-win_amd64.whl
claude_agent_sdk-0.2.186-py3-none-manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for claude_agent_sdk-0.2.186-py3-none-manylinux_2_17_x86_64.whl
claude_agent_sdk-0.2.186-py3-none-manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for claude_agent_sdk-0.2.186-py3-none-manylinux_2_17_aarch64.whl
claude_agent_sdk-0.2.186-py3-none-macosx_11_0_x86_64.whl Python 3 none macOS 11.0+ x86-64 Details for claude_agent_sdk-0.2.186-py3-none-macosx_11_0_x86_64.whl
claude_agent_sdk-0.2.186-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for claude_agent_sdk-0.2.186-py3-none-macosx_11_0_arm64.whl

Total release size: 817.9 MB

Release files / claude_agent_sdk-0.2.186.tar.gz

Download URL claude_agent_sdk-0.2.186.tar.gz
Size 409.3 kB
Tags Source
SHA-256 checksum
How to use checksums
16cb01af8309d371aae7c214b69d1a85f283a5aed06fc16054c1bc356c92f7a3
BLAKE2b-256 checksum
How to use checksums
77b5b7d8d7bfea2dbabb5720dea092fd26e1494daa4c8e7d4ce4f271287df14b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / claude_agent_sdk-0.2.186-py3-none-win_amd64.whl

Download URL claude_agent_sdk-0.2.186-py3-none-win_amd64.whl
Size 168.8 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
b68eefc87a966ec94d1d7d51ee97c01cd9849b8cef9da2e00066086a091c2716
BLAKE2b-256 checksum
How to use checksums
b0bb27cd01b7a9771d0db926fced99b2b88e7b35d26f6c832dd3aba5e7e1f6a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / claude_agent_sdk-0.2.186-py3-none-manylinux_2_17_x86_64.whl

Download URL claude_agent_sdk-0.2.186-py3-none-manylinux_2_17_x86_64.whl
Size 166.2 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
3aedbd01e5727283339362a544506f05cc19863a3b4c26bb9e1656d3e3940c3d
BLAKE2b-256 checksum
How to use checksums
86d83868ce79df74ee364fe9c6f560348f793ce89fef2d81347cdf0d4b8483c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / claude_agent_sdk-0.2.186-py3-none-manylinux_2_17_aarch64.whl

Download URL claude_agent_sdk-0.2.186-py3-none-manylinux_2_17_aarch64.whl
Size 165.6 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
2cffab71ff508634e2a6841edbcaf0d6ac3cd698e2378967ff4ffceba1d2f1bd
BLAKE2b-256 checksum
How to use checksums
3a535d7f6619453a06af77eab4f4ffa7c9d5de4ab77f3124186f6a35c94c8c63
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / claude_agent_sdk-0.2.186-py3-none-macosx_11_0_x86_64.whl

Download URL claude_agent_sdk-0.2.186-py3-none-macosx_11_0_x86_64.whl
Size 162.3 MB
Tags Python 3 macOS 11.0+ x86-64
SHA-256 checksum
How to use checksums
0099f4701569b7a625ef7a9c097577cf203671b5f793fec1697192d21c0be6f5
BLAKE2b-256 checksum
How to use checksums
aa9967caf906962bd7d3ecbe767cd058bb604bec10430a9eeba8c8a073f05a39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Release files / claude_agent_sdk-0.2.186-py3-none-macosx_11_0_arm64.whl

Download URL claude_agent_sdk-0.2.186-py3-none-macosx_11_0_arm64.whl
Size 154.6 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
4f98e05618a955fc49190465b4eb01cb3c2fca6e0b9319ee6e6c6dd042619bc6
BLAKE2b-256 checksum
How to use checksums
e423c4a6dc2ae62899dcd15e5ec54e9da65fc62a6f88a00b67620aa8096109a8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.12.16

Security for claude-agent-sdk 0.2.186

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.186 This release

6 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page