Claude Code SDK Python 使用指南：从基础安装到自定义工具开发

要使用 Claude 的内置工具，需要在选项中指定允许的工具：

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode='acceptEdits' # 自动接受文件编辑
)

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

工具权限控制

您可以通过钩子（Hooks）实现对工具使用的细粒度控制，例如阻止特定命令执行：

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]),
        ],
    }
)

自定义工具开发

工具开发概述

claude-code-sdk-python 允许您创建自定义工具，这些工具作为进程内 MCP 服务器运行，无需单独的进程。这提供了更好的性能和更简单的部署方式。

创建简单工具

以下是创建自定义工具的基本步骤：

1. 使用 @tool 装饰器定义工具函数
2. 使用 create_sdk_mcp_server 创建 MCP 服务器
3. 在客户端中使用自定义工具

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]
)

# 在客户端中使用
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)

开发计算器工具示例

下面是一个完整的计算器工具集实现，包含加、减、乘、除等基本运算：

# 定义计算器工具
@tool("add", "Add two numbers", {"a": float, "b": float})
async def add_numbers(args: dict[str, Any]) -> dict[str, Any]:
    result = args["a"] + args["b"]
    return {
        "content": [{"type": "text", "text": f"{args['a']} + {args['b']} = {result}"}]
    }

@tool("subtract", "Subtract one number from another", {"a": float, "b": float})
async def subtract_numbers(args: dict[str, Any]) -> dict[str, Any]:
    result = args["a"] - args["b"]
    return {
        "content": [{"type": "text", "text": f"{args['a']} - {args['b']} = {result}"}]
    }

# 更多工具定义...
# 创建计算器服务器
calculator = create_sdk_mcp_server(
    name="calculator",
    tools=[add_numbers, subtract_numbers, multiply_numbers, divide_numbers, square_root, power]
)

# 使用计算器工具
options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=[
        "mcp__calc__add",
        "mcp__calc__subtract",
        "mcp__calc__multiply",
        "mcp__calc__divide",
        "mcp__calc__sqrt",
        "mcp__calc__power",
    ],
)

错误处理

SDK 提供了多种异常类型，帮助您处理不同的错误场景：

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("Please install Claude Code")
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}")

高级功能

流模式

SDK 支持流模式，允许您实时处理 Claude 的响应：

async with ClaudeSDKClient(options=options) as client:
    await client.query("Tell me a story")
    async for message in client.receive_response():
        # 实时处理消息
        print(message)

混合 MCP 服务器

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

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

类型定义

SDK 提供了完整的类型定义，帮助您编写类型安全的代码。主要类型包括：

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

从旧版迁移

如果您正在从 Claude Code SDK（版本<0.1.0）升级，请参考 CHANGELOG.md 了解重大变更和新功能，包括：

• ClaudeCodeOptions 重命名为 ClaudeAgentOptions
• 合并的系统提示配置
• 设置隔离和显式控制
• 新的编程式子代理和会话分支功能

总结

claude-code-sdk-python 为开发者提供了与 Claude AI 助手交互的强大工具。通过本指南，您已经了解了从基础安装到高级自定义工具开发的全部内容。无论是构建简单的查询应用，还是开发复杂的自定义工具，claude-code-sdk-python 都能满足您的需求。