跳到主要内容
投机取巧
← Harness

Claude Agent SDK

Anthropic
Python 开源 MIT 编程底座 CLI包装 hooks 权限链 仅Claude partial lifecycle: active 核验 2026-09-30

「Claude Code 的编程接口」 —— 不是自建 agent 框架，是把一个成熟的 coding CLI 变成 Python 可驱动的对象。

适合与不适合

适合：要一个已被打磨的 coding agent（工具集 + 权限链 + hooks + session fork 都在），团队用 Python，愿意把推理全权交给 Claude。 不适合：需要换模型或接自托管权重（直接排除）；要自定义 agent loop 形状（用 OpenAI Agents SDK 或 LangGraph）；要多 agent 编排。

固定坐标系

8 个维度，与同赛道其他对象逐项可比。

模型与开放条件
只支持 Claude。 README 全文没有 provider-agnostic 的表述， pyproject.toml 层面也没有 litellm / any-llm 之类的可选依赖。 ⚠ 这是它与其他九个对象最本质的差别：本站其他 harness 都能接自托管模型（Ollama / vLLM / llama.cpp）， 本 SDK 不能。模型层（models.specul.com）推荐的本地量化路线在这里走不通。
运行位置
它是「你运营 Python 进程 + 它驱动一个 CLI 子进程」的双层结构。 README 明说CLI 随 wheel 捆绑（核验：_cli_version.py 里 __cli_version__ = "2.1.286"）， 默认用捆绑版；也可指向系统安装（ClaudeAgentOptions(cli_path="/path/to/claude")）。 实际形态：pip 包 → 内含 Claude Code CLI → CLI 连 Anthropic API。 换句话说这不是「库」，是「带 CLI 的库」。
本地文件
默认就是全套文件工具，且是全权限起步。 README 原文： 「By default, Claude has access to the full Claude Code toolset (Read, Write, Edit, Bash, and others)」。 工作目录用 ClaudeAgentOptions(cwd="/path/to/project") 指定。 这是与本站其他对象最大的风险差异 —— 默认就能读文件、改文件、跑 Bash。
关机后的任务
进程关了就停，但会话可续。 错误类型里 CLIConnectionError / CLINotFoundError / ProcessError / ResultError 揭示了进程依赖结构。 会话持久化有官方支撑：README 提到「records it, and reuses it on every later request, including after you resume the session」，以及 CHANGELOG 的 「session forking features」—— 即 resume + fork 是一等能力。 具体存储位置本次未核验。
工具与扩展
两个入口，能力不同（这是很关键的设计细节）： query() 是单向提问，只能用 CLI 自带工具集； ClaudeSDKClient 是双向会话，额外解锁 custom tools 与 hooks。 custom tools 是「进程内 MCP server」：README 说它们是 「in-process MCP servers that run directly within your Python application」， 官方列的收益是 no subprocess management / no IPC overhead / 单进程部署 / 更好调试 / 类型安全。 外部 MCP server 也支持，且两者可混用（mcp_servers 可同时放 SDK server 与 stdio 外部 server）。
上下文与记忆
有一个本站很关注、但容易被忽略的机制：system prompt 的 snapshot 语义。 README 原文：Claude Code 会在会话首次请求时构建并记录 system prompt， 之后每次请求（含恢复会话后）都复用它； 改了自定义 prompt 或 claude_code preset 的 append 文本， 要等到会话被compact 或开了新会话才生效—— 除非把 snapshot 设为 False（需要 CLI 2.1.257+）。 这实质上是「上下文快照不可变」的设计，与本站「状态 ≠ 上下文」的讨论直接相关： 它保证了 prompt 的确定性，代价是改动生效有延迟。
权限与限制
官方给了完整的权限求值链，这是本站目前见到的最详细的一份。 README 原文： 「allowed_tools is a permission allowlist: listed tools are auto-approved, and unlisted tools fall through to permission_mode and can_use_tool for a decision. It does not remove tools from Claude's toolset. To block specific tools, use disallowed_tools.」 翻译：allowed_tools 是准入白名单（列进去=自动批准）， 未列的走 permission_mode 与 can_use_tool 判定； 它不会把工具从工具集里移除 —— 要真正禁用得用 disallowed_tools。 hooks 提供确定性拦截：README 说 hooks 是「Python 函数，由 Claude Code *应用*（不是 Claude）调用」， 可在 PreToolUse 返回 permissionDecision: "deny" + 理由，示例就是拦 Bash 命令。 ⚠ 默认起步是全工具 + 无沙箱，想收紧必须主动配置。
适合什么任务
适合：想要一个已经被打磨过的 coding agent（工具集、权限链、hooks、session fork 都在） 并且团队用 Python；愿意把推理完全交给 Claude。 不适合：需要换模型 / 接自托管权重（直接排除）； 需要框架级的自定义 agent loop（它是 CLI 的接口，loop 形状由 Claude Code 决定）； 需要多agent 编排（它没有 agents-as-tools 那种一等委派机制）。

头号误解

  • 以为它是「Anthropic 版的 OpenAI Agents SDK」—— 不是。它是 Claude Code CLI 的 SDK，能力来自那个 CLI，不是框架自带
  • 以为 allowed_tools 能限制工具集 —— 官方明确「It does not remove tools from Claude's toolset」，禁用要用 disallowed_tools
  • 以为默认是安全的 —— 默认是 full toolset（Read/Write/Edit/Bash），且没有沙箱层
  • 以为改了 system prompt 立刻生效 —— 会被 snapshot 冻结，要compact 或新会话才生效（除非 snapshot=False）
  • 以为 MIT = 无附加条款 —— 受 Anthropic 商业条款约束（见正文）
  • 以为 TS 版授权与 Python 版一致 —— 核验发现 TS 版无 LICENSE 文件、license API 返回 null，授权状态不明（核验 2026-09-30）

价格

月度入口库免费（MIT）· 模型按 Claude API 计费（无法预置月费）
额度说明这是本站十对象里唯一不支持换provider 的编程底座。 SDK 只包装 Claude Code CLI，agent 的推理全部走 Anthropic API，没有 litellm / any-llm 这类旁路。 换模型 = 换方案，不是换配置。

不同币种不做折算。优惠、地区、税费与登录后报价可能变化，购买前请到官方页面确认。

未知项清单

  • Anthropic 商业条款的具体约束（尤其面向客户的场景）
  • TypeScript 版的授权状态
  • 会话持久化的存储位置与多进程并发语义
  • session forking 的具体形态与限制
  • permission_mode 全部取值与 can_use_tool 的优先级细节
  • 捆绑 CLI 版本与系统安装版本的兼容差异

证据来源

判断可回到以下一手源复核。本站核验日 2026-09-30，内容更新日 2026-09-30。

类型名称链接
repoClaude Agent SDK for Python · 仓库https://github.com/anthropics/claude-agent-sdk-python
docs官方文档（Python）https://platform.claude.com/docs/en/agent-sdk/python
docs权限指南（求值顺序的权威说明）https://platform.claude.com/docs/en/agent-sdk/permissions
docsHooks（官方专章）https://platform.claude.com/docs/en/agent-sdk/hooks
docsClaude Code 工具集清单（tools available to Claude）https://code.claude.com/docs/en/settings#tools-available-to-claude
docs修改 system prompts（snapshot 语义的权威说明）https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts
docsAnthropic 商业条款（README 末节指向，授权关键）https://www.anthropic.com/legal/commercial-terms
changelogReleases（0.2.163 @ 2026-09-30）https://github.com/anthropics/claude-agent-sdk-python/releases
changelogCHANGELOG（Claude Code SDK <0.1.0 的破坏性变更）https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md

实测记录

本站尚未完成实测。测试协议见 tasks/_protocol.md。 实测建议： | # | 测什么 | 为什么值得测 | |:--:|---|---| | 1 | pip 装完到底拉了多少东西（含捆绑 CLI 的体积） | CLI 随包捆绑，部署体积影响未知 | | 2 | 默认配置下agent 实际能碰到哪些目录 | 默认 full toolset 且无沙箱，边界要实测 | | 3 | disallowed_tools 与 hooks 哪条先生效 | README 只说求值顺序概述，实测才知道 | | 4 | resume 会话后状态恢复到什么粒度 | 本站最关心的「可靠长期运行」 | | 5 | 改system prompt 后多久生效（测compact 触发条件） | snapshot 语义的边界 |

相关条目

  • OpenAI Agents SDK本站最该对照的一对：同样是模型厂商出品、同为「编程底座」档。OpenAI 侧是自建 loop 的框架 + provider-agnostic；Anthropic 侧是 CLI 的 SDK + 仅 Claude。
  • Codex SDK第三家厂商的同档选择。三家是同一个问题的三种答案：自建框架 / 包装 CLI / 包装 CLI。
  • Deep Agents权限哲学的对照：「信任 LLM」vs「应用层确定性拦截」
  • Hermes Agent路线相反、厂商不同（本站前者 Anthropic、后者 Nous Research）：那个是自托管优先的通用 harness，本条只包 Anthropic 自家的 CLI。

本页由 ai-agent-guide 数据层生成（CC BY 4.0）。 方法论与坐标系定义见仓库内 METHODOLOGY.md。