Claude Agent SDK for Python
在 Python 程序中调用 Claude Code，构建可交互并可扩展工具的代理工作流。
- Star 数
- ★ 8.3k
- 最近更新
- 今天
- License
- MIT
- 主语言
- Python
- FA 评分
- 57/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用Claude CodeClaude API（部分支持）
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- Python 应用开发者希望把 Claude Code 的异步问答接入现有应用时。
- 不适合
- 需要模型供应商无关 SDK 的团队
- 需要在不使用 Claude Code CLI 的环境中运行的团队
- 源码审查
- 57/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
这是一个面向 Python 3.10+ 的 SDK，通过异步 Python API 调用 Claude Code。query() 返回异步消息迭代器，适合一次性请求；ClaudeSDKClient 支持双向交互，并可配置 Python 自定义工具和 hooks。包默认捆绑 Claude Code CLI，也可指定系统安装或自定义路径。Claude 可使用 Claude Code 工具集，调用结果以消息和内容块形式提供给程序处理。该 SDK 依赖 Claude Code 生态；README 未说明模型调用价格或凭据要求。
安装 claude-agent-sdk 后，Python 程序可用 query(prompt=...) 向 Claude Code 发送提示，并异步读取响应消息。通过 ClaudeAgentOptions，调用方可设置工作目录、系统提示、轮数、工具许可和权限模式。对交互式会话，可用 ClaudeSDKClient 发送查询并接收响应；还可通过 @tool、create_sdk_mcp_server 注册进程内 Python 工具，并设置 hooks 在代理循环的特定阶段执行确定性处理。程序可检查 AssistantMessage、TextBlock 等类型，并捕获 CLI 连接、进程、结果或 JSON 解码错误。
- Python 应用开发者希望把 Claude Code 的异步问答接入现有应用时。
- 需要在交互式 Claude Code 会话中逐条处理响应消息的开发团队。
- 希望将现有 Python 函数作为进程内 MCP 工具交给 Claude 调用的团队。
- 需要在 Bash 等工具使用前设置确定性检查或拦截逻辑的工程团队。
如何安装或部署这个 Agent？
需要 Python 3.10+。安装包会自动捆绑 Claude Code CLI；如偏好系统安装或指定版本，可另行安装 CLI，或通过 ClaudeAgentOptions(cli_path=...) 配置路径。
如何使用这个 Agent？
最小异步调用示例：
pip install claude-agent-sdkimport 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)这个 Agent 有哪些优点和局限？
query()提供简单的异步消息流接口，适合嵌入 Python 程序。ClaudeSDKClient支持双向交互，并可使用 Python 函数定义自定义工具和 hooks。- Claude Code CLI 默认随包捆绑，也支持指定自定义 CLI 路径。
- 核心调用依赖 Claude Code CLI 和 Claude Code 产品生态，供应商可移植性有限。
- 需要 Python 3.10 或更高版本。
- README 未说明模型调用费用、所需凭据或离线运行能力，采用前需另行确认这些条件。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Claude Agent SDK for Python 当前 | 57 · 缺口较多 | 代码库 / SDK | ★ 8.3k | 今天 | Python | Claude Code |
| Agno Agent Platform | 41 · 缺口较多 | 开发框架免费 + 模型费 | ★ 43k | 今天 | Python | — |
| OpenAI Agents SDK | 64 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 30k | 今天 | Python | OpenAI API |
| Agently AI 应用运行时 | 63 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 1.7k | 7 天前 | Python | OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
README 说明 allowed_tools 会自动批准列出的工具、permission_mode 和 can_use_tool 负责其余决策，并介绍 disallowed_tools 与 hooks；但默认拥有完整 Claude Code 工具集，且示例设置 acceptEdits 并预先批准 Bash，缺少默认逐次确认保证，因此最小权限与确认仅部分处理。数据经 Python SDK、Claude Code CLI、Claude 服务及可选外部 MCP 子进程流转，README 对架构有所说明，但未见敏感数据保留、脱敏或访问控制细节，故数据透明度与敏感数据处理偏薄。发布工作流采用哈希锁定构建依赖、PyPI trusted publishing，并隔离无发布凭据的 changelog 作业，支持依赖安全得 2；然而工具可写文件、运行 Bash、访问 MCP 服务，静态材料没有通用撤销或恢复措施，外部影响与回滚仅部分说明。README、包元数据、许可证及发布工作流清楚标示 Anthropic 项目和更新路径，来源归属较充分。
README、pyproject 和测试配置在包名、Python 版本、异步接口及依赖范围上大体一致；测试文件展示了构建、发布工具和 changelog 的检查，但静态审阅不能证明测试运行结果，因此自洽性得 2。基础依赖有版本下限/上限，CLI 随 wheel 捆绑且可指定路径，降低常见安装阻塞；仍依赖网络服务、平台构建和外部 MCP，故可用性并非完整保证。README 列出结构化异常类型与示例处理，错误消息处理充分但未显示所有运行时失败路径。
面向 Python 开发者的 SDK，README 覆盖简单查询、交互客户端、工具、hooks、工作目录、提示配置与外部/内置 MCP 场景；支持 Python 3.10–3.13，配置 CLI 路径、权限 allowlist 和 hooks，能力边界及常见触发场景清晰。对运行环境的支持说明较好，但具体 CLI 版本兼容要求只在部分功能处出现，故各项均为充分而非全面。
README 按安装、快速开始、功能、类型、错误处理和开发发布组织，安装前置条件清晰，示例覆盖多种主要用法；FAQ 和限制说明有限，尤其数据治理及风险边界未详述。名称、包元数据与代码导出概念一致，MIT 许可证文本完整得满分。版本号及双独立 CLI/SDK 版本发布流程清楚，CHANGELOG 与自动发布路径存在；维护责任可从 Anthropic 作者、仓库和发布工作流辨认，但没有更细的维护承诺，故未给满分。
SDK 提供异步消息流、交互会话、自定义工具与 hooks，输出可由调用方消费，且相对直接调用 CLI 有集成价值；README 的示例和错误类型提升可用性。边际价值由功能说明支持，但成本收益没有量化，且 CLI 体积、网络/API 使用和部署成本未充分展开，故成本效益只得 1。
README 的主要接口说明链接到对应源文件，配置、依赖、许可证和发布流程可在多个文件中相互印证。测试源码提供构建与版本约束的可检查断言，但本审阅不推断其已运行或通过。材料通常区分功能事实与示例说明；对性能和部署收益的表述仍是文档主张，未见独立佐证，因此各项得 2 而非满分。
- 默认工具集包含文件写入和 Bash；调用方应明确配置工具权限与审批策略，并审查自定义工具及 MCP 服务的访问范围。
- 材料没有说明敏感提示词或代码的保留、脱敏和数据访问控制；使用前需结合适用的 Anthropic 服务条款及自身数据要求评估。
- 静态审阅未执行代码或测试，也未验证发布产物、运行时行为或外部服务可用性。
常见问题
需要单独安装 Claude Code CLI 吗？
ClaudeAgentOptions(cli_path=...) 指定路径。query() 和 ClaudeSDKClient 有什么区别？
query() 返回异步响应消息迭代器；ClaudeSDKClient 支持双向交互，并提供自定义工具和 hooks 能力。如何控制 Claude 使用哪些工具？
allowed_tools 会自动批准列出的工具，不会从工具集中移除其他工具；未列出的工具由 permission_mode 和 can_use_tool 决定。要阻止特定工具，可使用 disallowed_tools。运行出错时可以捕获哪些错误？
CLINotFoundError、CLIConnectionError、ProcessError、ResultError 和 CLIJSONDecodeError 等错误类型。