Claude Agent SDK for Python 是 Anthropic 官方发布的 Python SDK，用于基于 Claude 构建生产级 AI 智能体。其仓库名称为 claude-agent-sdk-python，对应文档标题为 “Claude Agent SDK for Python”。
用途 该 SDK 通过 Python 查询 Claude Code。SDK 会自动打包 Claude Code CLI，无需单独安装；如需使用系统级安装或指定版本，可单独安装 Claude Code（curl -fsSL https://claude.ai/install.sh | bash），或通过 ClaudeAgentOptions(cli_path="/path/to/claude") 指定自定义路径。
主要能力
- query()：异步函数，用于查询 Claude Code，返回响应消息的 AsyncIterator（见 src/claude_agent_sdk/query.py）。默认情况下 Claude 可使用完整的 Claude Code 工具集（Read、Write、Edit、Bash 等）。allowed_tools 是权限允许列表：列出工具自动批准，未列出工具交由 permission_mode 与 can_use_tool 决策，而不会从工具集中移除工具；如需屏蔽特定工具，应使用 disallowed_tools。
- 工作目录与系统提示：默认情况下，Claude Code 在会话首次请求时构建系统提示并记录，之后每次请求（包括恢复会话后）复用，因此修改自定义提示或 claude_code 预设的追加文本不会生效，直到会话被压缩或开始新会话。若要在每次请求时重建提示，可在 {"type": "preset", ...} 或 {"type": "custom", ...} 字典中将 snapshot 设为 False。此功能需要 Claude Code CLI 2.1.257 或更高版本；2.1.265 之前，带追加或自定义提示的会话仅在 snapshot 为 True 时记录。
- ClaudeSDKClient：支持与 Claude Code 进行双向交互式对话（见 src/claude_agent_sdk/client.py）。与 query() 不同，它还支持自定义工具与钩子，二者均可定义为 Python 函数。
- 自定义工具（作为进程内 SDK MCP 服务器）：自定义工具是可以提供给 Claude 并按需调用的 Python 函数。它们以进程内 MCP 服务器形式直接运行在 Python 应用中，无需普通 MCP 服务器所需的独立进程。优势包括：无需子进程管理（与应用程序同进程运行）、更好性能（工具调用无 IPC 开销）、更简单部署（单个 Python 进程）、更易调试（所有代码在同一进程）、类型安全（带类型提示的直接 Python 函数调用）。SDK 与外部 MCP 服务器可同时使用。
- 钩子：钩子是 Claude Code 应用（不是 Claude）在 Claude 智能体循环的特定节点调用的 Python 函数，可为 Claude 提供确定性处理与自动反馈。
类型与错误 完整类型定义见 src/claude_agent_sdk/types.py，包括 ClaudeAgentOptions（配置选项）、AssistantMessage、UserMessage、SystemMessage、ResultMessage（消息类型）、TextBlock、ToolUseBlock、ToolResultBlock（内容块）。所有错误类型见 src/claude_agent_sdk/_errors.py。可用工具完整列表见 Claude Code 文档。
使用方式与示例
- 基础用法：query()。
- 完整可运行示例见 examples/quick_start.py。
- ClaudeSDKClient 的综合示例见 examples/streaming_mode.py；可在 IPython 中运行交互式示例 examples/streaming_mode_ipython.py。
- 自定义工具端到端示例见 MCP Calculator。
- 钩子更多示例见 examples/hooks.py。
从 Claude Code SDK 迁移 若从 Claude Code SDK（版本 < 0.1.0）升级，请参阅 CHANGELOG.md 了解破坏性变更与新功能，包括：ClaudeCodeOptions 更名为 ClaudeAgentOptions、合并的系统提示配置、设置隔离与显式控制、新的编程式子智能体与会话分叉功能。
贡献与构建 贡献者需运行初始安装脚本以安装 git 钩子，会安装一个 pre-push 钩子，在推送前运行 lint 检查以匹配 CI 工作流；临时跳过可使用 git push --no-verify。本地构建 wheel（内置 Claude Code CLI）可通过 python scripts/build_wheel.py（--help 查看全部选项）；构建脚本会为当前平台下载 Claude Code CLI、将其打包进 wheel、构建 wheel 与源码分发并用 twine 检查。发布工作流通过 .github/workflows/publish.yml 将包发布到 PyPI：在 Actions 标签页手动触发，输入 version（包版本，例如 0.1.5）与 claude_code_version（要内置的 Claude Code CLI 版本，例如 2.0.0 或 latest）。工作流将为 macOS、Linux、Windows 构建平台特定 wheel，在各 wheel 中内置指定 CLI 版本，构建源码分发，发布全部产物到 PyPI，创建带版本更新的发布分支，并打开一个包含更新后的 pyproject.toml 版本、src/claude_agent_sdk/_version.py、src/claude_agent_sdk/_cli_version.py（内置 CLI 版本）及自动生成的 CHANGELOG.md 条目的 PR。工作流分别跟踪包版本与内置 CLI 版本，允许在不改代码的情况下发布带更新 CLI 的新包版本。
适用场景 适用于需要以 Python 构建基于 Claude 的智能体、需要交互式会话、自定义工具或钩子、并希望以进程内方式集成工具的开发者。
限制 官方资料未明确说明该 SDK 的收费、价格或商业条款细节，仅说明使用受 Anthropic 商业服务条款约束；具体价格与计费方式暂未提供。
