项目概述

该项目是 Anthropic 官方提供的 Claude Agent SDK for Python。它是一个软件开发工具包，允许开发者通过 Python 代码与 Claude Code（一个专为编码和智能体任务设计的 Claude 应用程序）进行交互、集成和扩展，从而构建强大的、由 Claude 驱动的AI智能体（Agent）。

核心功能与特性

1. 两种主要交互模式：

· query() 函数：一个简单、高级的接口，用于执行单次查询并获取流式响应。适合快速、简单的交互。

· ClaudeSDKClient 类：一个功能更全面、低级别的客户端，支持双向、交互式对话。这是构建复杂应用的基础，支持自定义工具（Tools） 和钩子（Hooks）。

2. 自定义工具（In-Process MCP Servers）：

· 核心创新：允许开发者将Python函数直接定义为工具供Claude调用，无需运行独立的MCP（Model Context Protocol）服务器进程。

· 实现方式：使用 @tool 装饰器定义函数，然后使用 create_sdk_mcp_server() 将其打包成一个SDK MCP服务器，最后通过 ClaudeAgentOptions 提供给Claude。

· 优势：

· 无需子进程管理：工具运行在与应用相同的Python进程中。

· 性能更好：避免了进程间通信（IPC）的开销。

· 部署更简单：只需管理一个Python进程。

· 调试更容易：所有代码在同一进程，便于跟踪和调试。

· 类型安全：直接使用Python函数，支持类型提示。

· 兼容性：支持同时使用SDK MCP服务器（内部）和外部MCP服务器（子进程）。

3. 钩子（Hooks）：

· 功能：允许开发者在Claude智能体循环的特定时间点（如 PreToolUse）注入自定义Python逻辑。

· 用途：提供确定性处理和自动化反馈，例如实现安全策略（如拦截危险的Bash命令）、自动批准/拒绝工具使用、记录日志等。

· 实现：通过 HookMatcher 将钩子函数与特定的工具或事件进行匹配，并在 ClaudeAgentOptions 中配置。

4. 工作目录控制：

· 可以通过 ClaudeAgentOptions(cwd=…) 设置Claude操作的文件系统上下文，使其能够在指定的项目目录中读写文件、执行命令。

5. 丰富的消息和内容类型：

· SDK定义了清晰的消息类型（AssistantMessage, UserMessage, SystemMessage, ResultMessage）和内容块类型（TextBlock, ToolUseBlock, ToolResultBlock），方便开发者结构化地处理输入和输出。

6. 全面的错误处理：

· 提供了多种特定的异常类（如 CLINotFoundError, CLIConnectionError, ProcessError等），帮助开发者精准地捕获和处理各种错误场景。

技术栈与要求

· 语言：Python

· Python版本：3.10+

· 必需组件：

· pip install claude-agent-sdk

· Claude Code 应用程序：需要通过 npm install -g @anthropic-ai/claude-code 单独安装。SDK通过CLI与它通信。

应用场景

· 构建自动化编码助手和智能体。

· 创建自定义的AI工作流程，将Claude与内部工具和API集成。

· 实现复杂的、多步骤的任务自动化（如代码库分析、重构、文件操作等）。

· 为Claude的使用添加安全层和审计功能（通过Hooks）。

迁移说明

· 该项目是旧版 “Claude Code SDK” 的演进版本。

· 存在一些破坏性变更，例如将 ClaudeCodeOptions 重命名为 ClaudeAgentOptions。

· 建议从旧版本迁移的用户详细阅读 CHANGELOG.md 文件。

许可证

· 项目采用 MIT 许可证，这是一个非常宽松的开源许可证。

总结：claude-agent-sdk-python 是一个功能强大且灵活的官方SDK，它极大地降低了将Claude Code集成到Python应用程序中的复杂度。其最大的亮点在于引入了进程内自定义工具的概念，避免了管理外部MCP服务器的麻烦，同时通过钩子机制提供了深度的控制和定制能力，是开发者构建下一代AI驱动应用的重要工具。