使用 Agent SDK

Agent SDK 不是“在代码里调用一次模型”，而是把 Claude Code 的 agent loop、工具执行、上下文管理和权限机制放进你的程序。日常写代码用 CLI；要做产品、服务、CI agent 或内部平台，才进入 SDK。——翔宇

1. 先改名：Claude Code SDK 已更名为 Claude Agent SDK

官方文档已经明确：旧的 Claude Code SDK 更名为 Claude Agent SDK。

当前包名：

npm install @anthropic-ai/claude-agent-sdk

pip install claude-agent-sdk

TypeScript SDK 会通过 optional dependency 带平台对应的 Claude Code native binary，所以不一定需要另装 Claude Code CLI。

2. Agent SDK 解决什么问题

普通 Anthropic Client SDK 是你自己实现 tool loop：

• 发送 prompt。
• 模型返回 tool use。
• 你执行工具。
• 再把 tool result 发回模型。
• 循环直到完成。

Agent SDK 是 Claude Code 替你跑 agent loop：

• Claude 自主读文件。
• 搜索代码。
• 执行命令。
• 编辑文件。
• 调用 MCP。
• 使用 Hooks、Skills、Subagents。
• 管理上下文和 sessions。
• 流式返回消息、工具调用和结果。

flowchart TD
    Prompt["你的程序发送任务"]
    Loop["Agent SDK agent loop"]
    Decide["Claude 决定下一步"]
    Tools["读文件 / 搜索 / Bash / Edit / MCP"]
    Observe["观察工具结果"]
    Done["返回结果或结构化输出"]

    Prompt --> Loop
    Loop --> Decide
    Decide --> Tools
    Tools --> Observe
    Observe --> Decide
    Decide --> Done

    style Loop fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Tools fill:#e0f2fe,stroke:#0284c7,stroke-width:2px

3. 什么时候用 SDK，什么时候不用

用 Claude Code CLI：

• 日常写代码。
• 一次性调试。
• 交互式重构。
• 需要你边看边确认。
• 还没跑稳的工作流。

用 Agent SDK：

• CI / CD 自动修复。
• 后台 worker。
• 内部代码平台。
• Web app 里的 coding agent。
• 需要程序化审批、日志、计费、会话管理。
• 需要把 Claude Code 的工具能力接进自己的系统。

用 Managed Agents：

• 你不想维护 agent 运行环境和 sandbox。
• 需要托管事件流、长任务、异步 session。
• 生产级 agent 更适合交给 Anthropic 管执行环境。

4. 安装和认证

TypeScript：

npm install @anthropic-ai/claude-agent-sdk

Python：

pip install claude-agent-sdk

基础认证是 API key：

export ANTHROPIC_API_KEY=your-api-key

也支持第三方 provider：

• Amazon Bedrock：设置 CLAUDE_CODE_USE_BEDROCK=1 并配置 AWS credentials。
• Google Vertex AI：设置 CLAUDE_CODE_USE_VERTEX=1 并配置 Google Cloud credentials。
• Microsoft Azure AI Foundry：设置 CLAUDE_CODE_USE_FOUNDRY=1 并配置 Azure credentials。

官方同时说明：除非事先获批，第三方开发者不能把 claude.ai 登录或 claude.ai rate limits 提供给自己的产品用户。对外产品应使用 API key 认证方式。

5. 最小 Python 示例

from claude_agent_sdk import ClaudeAgentOptions, query
from asyncio import run


async def main():
    async for message in query(
        prompt="What files are in this directory?",
        options=ClaudeAgentOptions(
            allowed_tools=["Bash", "Glob"],
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


run(main())

这里的重点：

• prompt 是任务。
• ClaudeAgentOptions 控制工具、权限、MCP、系统提示词等。
• async for 会持续接收 agent 思考、工具调用、结果消息。
• allowed_tools 预批准工具，不等于禁用其他工具。

6. 最小 TypeScript 示例

const { query } = await import("@anthropic-ai/claude-agent-sdk");

for await (const message of query({
  prompt: "Find all places that import the auth module.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

TypeScript 和 Python 的概念一致，但字段命名不同：

• Python：allowed_tools、permission_mode、setting_sources、output_format
• TypeScript：allowedTools、permissionMode、settingSources、outputFormat

7. 内置工具能力

Agent SDK 带 Claude Code 的常用工具。

• Read：读取文件。
• Write：创建文件。
• Edit：精确修改文件。
• Bash：运行 shell 命令、脚本、git 操作。
• Monitor：监听后台脚本输出并按事件处理。
• Glob：按 pattern 找文件。
• Grep：用 regex 搜索文件内容。
• WebSearch：搜索网页。
• WebFetch：读取网页内容。
• AskUserQuestion：向用户提问。

最容易犯的错是直接给全工具：

ClaudeAgentOptions(
    permission_mode="bypassPermissions",
)

这会让 agent 在你的进程环境里拥有极大能力。生产环境应该从最小工具面开始。

8. Permissions：SDK 里的安全链路

SDK 权限评估顺序官方写得很清楚：

1. Hooks 先运行。
2. Deny rules 先检查，包括 disallowed_tools 和 settings deny。
3. Permission mode 生效。
4. Allow rules 检查，包括 allowed_tools 和 settings allow。
5. 还没决定时调用 canUseTool callback。

常见模式：

ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],
    permission_mode="dontAsk",
)

这会构成一个比较干净的只读 agent：

• Read、Glob、Grep 被批准。
• 其他工具不会弹窗，而是直接拒绝。

要阻止工具，用 disallowed_tools：

ClaudeAgentOptions(
    disallowed_tools=["Bash", "Write", "Edit"],
)

9. Permission modes 怎么选

SDK 支持的主要模式：

• default：标准权限行为，未匹配工具会走 canUseTool。
• dontAsk：未预批准工具直接拒绝。
• acceptEdits：自动接受文件编辑和常见文件系统操作。
• bypassPermissions：绕过大多数权限提示，风险极高。
• plan：规划模式，不执行工具。
• auto：TypeScript 支持，模型分类器审批工具调用。

选择建议：

• 只读分析：allowed_tools=["Read", "Glob", "Grep"] + dontAsk。
• 原型期自动改代码：acceptEdits，但只在隔离目录或临时分支。
• 生产后台 agent：避免 bypassPermissions，显式 allow / deny。
• 用户要先批准方案：先 plan，确认后再切到执行模式。

SDK 支持运行中改模式：

await q.set_permission_mode("acceptEdits")

10. Settings 和项目配置

Agent SDK 可以读取 Claude Code 的 filesystem-based configuration。

默认 query() 会读取：

• 当前 working directory 里的 .claude/
• 用户目录里的 ~/.claude/

它能用到：

• Skills：.claude/skills/*/SKILL.md
• Custom commands：.claude/commands/*.md
• Memory：CLAUDE.md 或 .claude/CLAUDE.md
• Plugins：通过 options 程序化传入
• Project settings：例如 permissions、hooks、MCP 等

如果你想限制来源，设置：

• Python：setting_sources
• TypeScript：settingSources

11. Sessions：继续、恢复和 fork

Session 是 agent 工作时累积的会话历史，包含：

• prompt。
• tool calls。
• tool results。
• Claude responses。
• agent 做过的分析。

Session 会自动写到磁盘。恢复 session 意味着 agent 拿回之前完整上下文。

三种常见方式：

• Continue：继续当前目录最近 session。
• Resume：用 session ID 恢复指定 session。
• Fork：复制一个 session 的历史，开一个新分支尝试不同方向。

重要边界：

• Session 保存对话历史，不保存文件系统快照。
• 要撤销文件变更，用 checkpointing，不是 session resume。
• 多用户产品里不要只用“最近 session”，要按用户或任务保存 session ID。

12. Streaming：不要只等最终文本

SDK 是流式的。你可以在 agent 工作过程中收到：

• system init。
• assistant message。
• tool use。
• tool result。
• permission request。
• result message。
• usage / cost 信息。

这对产品化很关键：

• UI 可以展示 agent 当前在做什么。
• 后端可以实时记录工具调用。
• 用户可以在中途批准或拒绝。
• 失败时可以定位卡在哪一步。

13. 结构化输出

自由文本适合聊天，不适合程序使用。

SDK 支持结构化输出：

• TypeScript：outputFormat
• Python：output_format

你定义 JSON Schema，agent 可以先多轮工具调用，最后返回经过验证的 JSON。

TypeScript 示例：

const { query } = await import("@anthropic-ai/claude-agent-sdk");

const schema = {
  type: "object",
  properties: {
    summary: { type: "string" },
    risk_level: { enum: ["low", "medium", "high"] },
    files: {
      type: "array",
      items: { type: "string" },
    },
  },
  required: ["summary", "risk_level"],
};

for await (const message of query({
  prompt: "Review the current changes and return a risk summary.",
  options: {
    outputFormat: {
      type: "json_schema",
      schema,
    },
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.structured_output);
  }
}

官方说明：如果校验失败，SDK 会重试；重试后仍失败，会返回错误 subtype，而不是伪造结构化数据。

14. 自定义工具和 MCP

Agent SDK 有两种扩展工具的方式。

第一种：MCP server。

ClaudeAgentOptions(
    mcp_servers={
        "playwright": {
            "command": "npx",
            "args": ["@playwright/mcp@latest"],
        }
    }
)

适合：

• 数据库。
• 浏览器自动化。
• 外部 API。
• 组织内工具。
• 已经有 MCP server 的系统。

第二种：SDK in-process MCP server。

你可以把自己程序里的函数定义成 tool，再传给 agent。官方把这称为 custom tools，通过 SDK 的 in-process MCP server 暴露。

适合：

• 应用内部函数。
• 受控业务 API。
• 不想启动额外进程的工具。
• 需要类型化输入 schema 的能力。

15. Subagents in SDK

SDK 可以定义和调用 Subagents。

Python 示例概念：

from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep", "Agent"],
    agents={
        "code-reviewer": AgentDefinition(
            description="Reviews code quality, security risks, and missing tests.",
            prompt="Analyze code quality and return findings ordered by severity.",
            tools=["Read", "Glob", "Grep"],
        )
    },
)

关键点：

• 要让主 agent spawn subagents，需要把 Agent 加进 allowed_tools / allowedTools。
• Subagent 有自己的工具边界。
• Subagent 消息里会有 parent_tool_use_id，方便追踪属于哪次 subagent 调用。
• Subagents 不会自动继承父 agent 的所有权限。

16. Hooks in SDK

SDK hooks 可以用 callback 函数控制 agent 生命周期。

常见用途：

• 记录文件修改。
• 阻止危险 Bash。
• 审计 tool use。
• 在 Stop 前检查结果。
• 对 permission request 做程序化审批。

Python 里可用 hook events 和 TypeScript 不完全一样。官方说明 TypeScript 支持更多事件，例如 SessionStart、SessionEnd、Setup、ConfigChange、WorktreeCreate、WorktreeRemove、PostToolBatch 等；Python 当前支持核心事件集合。

17. Skills、Slash commands 和 Plugins

SDK 可以使用 Claude Code 的一些扩展能力：

• Skills：Markdown 定义的专用能力。
• Slash commands：自定义 command。
• Plugins：通过 options 程序化接入。

边界：

• SKILL.md 里的 allowed-tools frontmatter 只在 Claude Code CLI 直接使用 Skills 时支持；SDK 里应通过主 options 控制 tools。
• 不要把 SDK 产品的安全边界放到 Skill frontmatter 里。
• Plugins 适合复用扩展，但生产服务要固定版本和来源。

18. AskUserQuestion 和审批

SDK 里的 agent 可能需要用户输入：

• 澄清需求。
• 审批工具调用。
• 选择方案。
• 确认风险。

Claude Code 提供 AskUserQuestion 工具，SDK 也有处理 approvals 和 user input 的机制。

产品设计上不要让 agent 卡死在“需要人类批准”：

• UI 要展示等待状态。
• 后端要能超时。
• 权限请求要记录。
• 多用户场景要把请求路由给正确用户。
• 无人值守任务用 dontAsk，让未批准工具直接拒绝。

19. Observability 和成本

生产 agent 必须可观测。

至少记录：

• session ID。
• 用户或任务 ID。
• prompt 摘要。
• tool calls。
• permission decisions。
• structured output 是否成功。
• error subtype。
• usage / cost。
• latency。

Agent SDK 官方提供 usage / cost tracking 和 OpenTelemetry 相关文档。不要等线上出问题才补日志。

20. Checkpointing 和文件安全

Session 不是文件快照。Agent 改文件后，如果你需要可回滚能力，要用 checkpointing 或自己在运行环境外做版本控制。

最低要求：

• 每个任务独立工作目录。
• 运行前记录 git status。
• 改完后保存 diff。
• 跑测试。
• 审批后再合并。
• 出错可清理临时目录。

对后台服务，推荐用：

• 临时 clone。
• 临时 branch。
• git worktree。
• 容器或 sandbox。
• 最小权限 token。

21. 部署边界

SDK agent 运行在你的进程和基础设施里，所以你负责：

• API key 管理。
• 文件系统隔离。
• 网络访问策略。
• shell 命令边界。
• 多租户隔离。
• 日志脱敏。
• 成本限制。
• 超时和重试。
• worker 队列。
• sandbox 或容器。
• 版本升级。

Managed Agents 则是 Anthropic 托管 agent 和 sandbox。官方 overview 里也建议：一个常见路径是先用 Agent SDK 本地原型验证，再迁到 Managed Agents 做生产托管。

22. 品牌和合规边界

官方 branding guidance 里提到，集成 Claude Agent SDK 时可以用：

• “Claude Agent”
• “Claude”
• “Powered by Claude”

不应使用：

• “Claude Code”
• “Claude Code Agent”
• 模仿 Claude Code 的品牌视觉或 ASCII art。

这对公开产品、客户界面、菜单命名都重要。

23. 推荐落地顺序

不要一上来就写生产 agent。按这个顺序：

1. 在 Claude Code CLI 里跑通流程。
2. 收敛工具和权限边界。
3. 写最小 SDK demo，只给只读工具。
4. 加 session ID 和日志。
5. 加审批或 dontAsk。
6. 加结构化输出。
7. 接 MCP 或 custom tools。
8. 加 Hooks 做审计和阻断。
9. 用隔离工作区处理文件修改。
10. 加成本、超时、重试和队列。
11. 再考虑对外产品或 Managed Agents。

24. 常见故障：SDK 跑不起来

排查顺序：

1. 确认包名是 claude-agent-sdk 或 @anthropic-ai/claude-agent-sdk。
2. 确认 ANTHROPIC_API_KEY 已设置。
3. 如果用 Bedrock / Vertex / Foundry，确认环境变量和云凭据。
4. TypeScript 场景检查 optional native binary 是否安装成功。
5. 确认 Python / Node 版本符合项目要求。
6. 先跑官方最小 query 示例，不要一开始接 MCP 和 Hooks。
7. 打开 debug log，看 API error、权限 error、工具 error 属于哪类。

25. 常见故障：权限行为和预期不同

常见原因：

• 以为 allowed_tools 会限制所有工具。
• 同时用了 allowed_tools 和 bypassPermissions。
• 没有设置 dontAsk，导致未匹配工具进入 canUseTool。
• setting_sources 排除了 project，项目 .claude/settings.json 没加载。
• Subagent 继承了父会话危险 permission mode。
• Hook 在权限链前面已经 allow / deny 了。

处理：

• 明确使用 disallowed_tools。
• 锁定工具面时用 permission_mode="dontAsk"。
• 避免生产使用 bypassPermissions。
• 检查 setting sources。
• 给 subagents 单独工具边界。
• 记录 permission decision。

26. 常见故障：结果不能给程序用

表现：

• 输出是自然语言，程序解析不稳定。
• 字段缺失。
• JSON 格式偶发错误。
• 长任务后只返回总结，没有结构化字段。

处理：

• 使用 structured outputs。
• 缩小 schema。
• 把可选字段设 optional。
• 在 prompt 里说明任务目标和数据来源。
• 检查 error_max_structured_output_retries。
• 不要手写正则解析自然语言输出。

27. 自检清单

学完这一章，你应该能做到：

• 我知道 Claude Code SDK 已更名为 Claude Agent SDK。
• 我能解释 Agent SDK、Client SDK、Claude Code CLI、Managed Agents 的区别。
• 我知道什么时候该先用 CLI，而不是直接 SDK。
• 我能写出最小 Python 或 TypeScript query 示例。
• 我知道 API key、Bedrock、Vertex、Foundry 的认证入口。
• 我知道 allowed_tools 是预批准，不是限制。
• 我知道 dontAsk、acceptEdits、bypassPermissions、plan 的取舍。
• 我知道 session 保存对话历史，不保存文件快照。
• 我知道 structured outputs 适合程序化结果。
• 我知道 SDK 可以接 MCP、自定义 tools、Hooks、Subagents、Skills。
• 我知道生产 SDK agent 要有日志、成本、隔离、审批和回滚。

28. 术语速查

• Claude Agent SDK：把 Claude Code agent loop 作为 Python / TypeScript 库使用的 SDK。
• query()：启动一次 agent 任务的核心接口。
• ClaudeAgentOptions：Python SDK 的配置对象。
• Options：TypeScript SDK 的配置对象。
• allowed_tools / allowedTools：预批准工具列表。
• disallowed_tools / disallowedTools：拒绝工具列表。
• permission_mode / permissionMode：工具权限模式。
• canUseTool：运行时审批工具调用的 callback。
• session：SDK 保存的 agent 会话历史。
• resume：用 session ID 恢复指定会话。
• continue：继续当前目录最近会话。
• fork：从已有 session 历史复制出新分支。
• output_format / outputFormat：结构化输出配置。
• structured_output：校验通过后的结构化结果。
• mcp_servers / mcpServers：接入 MCP server 的配置。
• AgentDefinition：SDK 中定义 subagent 的结构。
• setting_sources / settingSources：限制 SDK 加载哪些 filesystem settings。
• OpenTelemetry：生产观测和 tracing 体系。
• Managed Agents：Anthropic 托管 agent 和 sandbox 的产品形态。

29. 官方资料

• Agent SDK overview
• Quickstart
• How the agent loop works
• Use Claude Code features in the SDK
• Configure permissions
• Work with sessions
• Get structured output from agents
• Give Claude custom tools
• Hosting the Agent SDK