Claude Agent SDK for Python

Claude Agent 的 Python SDK。更多信息请参阅 Claude Agent SDK 文档。

安装

pip install claude-agent-sdk

前置要求：

• Python 3.10+

注意： Claude Code CLI 已自动捆绑在包中 - 无需单独安装！SDK 默认使用捆绑的 CLI。如需使用全局安装或特定版本，可以：

• 单独安装 Claude Code：curl -fsSL https://claude.ai/install.sh | bash
• 指定自定义路径：ClaudeAgentOptions(cli_path="/path/to/claude")

快速开始

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)

基本用法：query()

query() 是用于查询 Claude Code 的异步函数（async function）。它返回响应消息的 AsyncIterator（异步迭代器）。详见 src/claude_agent_sdk/query.py。

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

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

# 使用选项
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)

使用工具

默认情况下，Claude 可以访问完整的 Claude Code 工具集（读取、写入、编辑、Bash 等）。allowed_tools 是权限白名单：列出的工具会自动批准，未列出的工具会根据 permission_mode 和 can_use_tool 决定是否允许。这不会从 Claude 工具集中移除工具。要阻止特定工具，请使用 disallowed_tools。完整的评估顺序请参阅权限指南。

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],  # 自动批准这些工具
    permission_mode='acceptEdits'  # 自动接受文件修改
)

async for message in query(
    prompt="Create a hello.py file",
    options=options
):
    # 处理工具调用和结果
    pass

工作目录

from pathlib import Path

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

ClaudeSDKClient

ClaudeSDKClient 支持与 Claude Code 进行双向交互式对话。详见 src/claude_agent_sdk/client.py。

与 query() 不同，ClaudeSDKClient 还支持 自定义工具 和 钩子，两者都可以定义为 Python 函数。

自定义工具（作为进程内 SDK MCP 服务器）

自定义工具 是您可以通过 Python 函数实现并提供给 Claude 调用的工具。

自定义工具通过进程内 MCP 服务器实现，直接在您的 Python 应用程序中运行，无需常规 MCP 服务器所需的独立进程。

完整示例请参见 MCP 计算器。

创建简单工具

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient

# 使用 @tool 装饰器定义工具
@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {
        "content": [
            {"type": "text", "text": f"Hello, {args['name']}!"}
        ]
    }

# 创建 SDK MCP 服务器
server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user]
)

# 与 Claude 一起使用。allowed_tools 预批准该工具使其无需权限提示运行
# 但不控制工具可用性
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

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

    # 提取并打印响应
    async for msg in client.receive_response():
        print(msg)

相比外部 MCP 服务器的优势

• 无需子进程管理 - 与您的应用程序运行在同一个进程中
• 更好性能 - 工具调用无 IPC 开销
• 更简单部署 - 单一 Python 进程而非多个
• 更容易调试 - 所有代码运行在同一个进程中
• 类型安全 - 直接的 Python 函数调用和类型提示

从外部服务器迁移

# 之前：外部 MCP 服务器（独立进程）
options = ClaudeAgentOptions(
    mcp_servers={
        "calculator": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "calculator_server"]
        }
    }
)

# 之后：SDK MCP 服务器（进程内）
from my_tools import add, subtract  # 您的工具函数

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

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

混合服务器支持

您可以同时使用 SDK 和外部 MCP 服务器：

options = ClaudeAgentOptions(
    mcp_servers={
        "internal": sdk_server,      # 进程内 SDK 服务器
        "external": {                # 外部子进程服务器
            "type": "stdio",
            "command": "external-server"
        }
    }
)

钩子（Hooks）

钩子（hook） 是由 Claude Code 应用程序（而非 Claude）在 Claude 代理循环的特定节点调用的 Python 函数。钩子可以为 Claude 提供确定性处理和自动化反馈。详见 使用钩子拦截和控制代理行为。

更多示例请查看 examples/hooks.py。

示例

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"命令包含非法模式: {pattern}",
                }
            }
    return {}

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

async with ClaudeSDKClient(options=options) as client:
    # 测试1: 包含禁止模式的命令（将被拦截）
    await client.query("运行bash命令: ./foo.sh --help")
    async for msg in client.receive_response():
        print(msg)

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

    # 测试2: 可正常执行的安全命令
    await client.query("运行bash命令: echo 'Hello from hooks example!'")
    async for msg in client.receive_response():
        print(msg)

类型定义

完整类型定义请查看 src/claude_agent_sdk/types.py：

• ClaudeAgentOptions - 配置选项
• AssistantMessage, UserMessage, SystemMessage, ResultMessage - 消息类型
• TextBlock, ToolUseBlock, ToolResultBlock - 内容块类型

错误处理

from claude_agent_sdk import (
    ClaudeSDKError,      # 基类错误
    CLINotFoundError,    # 未安装Claude Code
    CLIConnectionError,  # 连接问题
    ProcessError,        # 进程失败
    CLIJSONDecodeError,  # JSON解析问题
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("请安装Claude Code")
except ProcessError as e:
    print(f"进程失败，退出码: {e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"响应解析失败: {e}")

所有错误类型定义请查看 src/claude_agent_sdk/_errors.py。

可用工具

完整可用工具列表请查看 Claude Code 文档。

示例

完整工作示例请查看 examples/quick_start.py。

包含 ClaudeSDKClient 的综合示例请查看 examples/streaming_mode.py。您还可以在 IPython 中运行交互式示例 examples/streaming_mode_ipython.py。

从Claude Code SDK迁移

如果您正在升级自Claude Code SDK（版本<0.1.0），请查看 CHANGELOG.md 中的破坏性变更和新特性说明，包括：

• ClaudeCodeOptions → ClaudeAgentOptions 重命名
• 系统提示配置合并
• 设置隔离和显式控制
• 新的程序化子代理和会话分叉特性

开发

如需贡献代码，请运行初始化脚本安装git钩子：

./scripts/initial-setup.sh

该脚本会安装预推送钩子，在推送前运行代码检查，与CI流程保持一致。临时跳过钩子可使用 git push --no-verify。

本地构建wheel包

构建包含Claude Code CLI的wheel包：

# 安装构建依赖
pip install build twine

# 构建wheel包
python scripts/build_wheel.py

# 指定版本构建
python scripts/build_wheel.py --version 0.1.4

# 指定CLI版本构建
python scripts/build_wheel.py --cli-version 2.0.0

# 构建后清理CLI文件
python scripts/build_wheel.py --clean

# 跳过CLI下载（使用现有文件）
python scripts/build_wheel.py --skip-download

构建脚本会执行以下步骤：

1. 下载适用于您平台的Claude Code CLI
2. 将其打包进wheel
3. 构建wheel和源码分发包
4. 使用twine验证包

完整选项请查看 python scripts/build_wheel.py --help。

发布流程

包通过 .github/workflows/publish.yml 中的GitHub Actions工作流发布到PyPI。创建新版本需：

1. 手动触发工作流（在Actions标签页）并提供两个输入：

   • version: 要发布的包版本（如 0.1.5）
   • claude_code_version: 要打包的Claude Code CLI版本（如 2.0.0 或 latest）

2. 工作流将：

   • 为macOS、Linux和Windows构建平台特定的wheel包
   • 在每个wheel中打包指定版本的Claude Code CLI
   • 构建源码分发包
   • 将所有制品发布到PyPI
   • 创建包含版本更新的发布分支
   • 提交PR合并到main分支，包含：
     • 更新 pyproject.toml 版本
     • 更新 src/claude_agent_sdk/_version.py
     • 更新 src/claude_agent_sdk/_cli_version.py 中的CLI版本
     • 自动生成的 CHANGELOG.md 条目

3. 审核并合并 发布PR以更新main分支的版本信息

工作流分别跟踪包版本和CLI版本，允许您在不修改代码的情况下发布包含更新CLI的新版本。

许可协议

本SDK的使用受Anthropic 商业服务条款 约束，包括您使用其为自有客户提供产品和服务的场景，除非特定组件或依赖项另有许可协议（详见对应组件的LICENSE文件）。

Claude Agent SDK Python 快速上手指南

环境准备

• 系统要求：Python 3.10 或更高版本
• 前置依赖：

  # 建议使用国内镜像加速安装
  pip install --upgrade pip
  

安装步骤

# 推荐使用清华源加速安装
pip install claude-agent-sdk -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

最简示例

1. 创建 main.py 文件，内容如下：

   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)
   

2. 运行示例：

   python main.py
   

进阶用法（可选）

• 自定义系统提示：

  from claude_agent_sdk import ClaudeAgentOptions
  
  options = ClaudeAgentOptions(
      system_prompt="You are a helpful assistant",
      max_turns=1
  )
  

• 指定工作目录：

  from pathlib import Path
  
  options = ClaudeAgentOptions(
      cwd=Path("/path/to/project")
  )
  

提示：完整工具集使用、自定义工具开发等内容请参考官方文档的工具使用和自定义工具章节。