claude-agent-sdk

Claude Agent SDK

状态：生产就绪 最后更新：2025-11-21 依赖项：@anthropic-ai/claude-code，zod 最新版本：@anthropic-ai/[email protected]+，[email protected]+

---

快速入门（5 分钟）

1. 安装 SDK

bun add @anthropic-ai/claude-agent-sdk zod

为什么需要这些软件包：

• @anthropic-ai/claude-agent-sdk - 主要的 Agent SDK
• zod - 用于工具的类型安全架构验证

2. 设置 API 密钥

export ANTHROPIC_API_KEY="sk-ant-..."

重要：

• 所有 Agent 操作都需要 API 密钥
• 切勿将 API 密钥提交到版本控制系统
• 使用环境变量

3. 基本查询

import { query } from "@anthropic-ai/claude-agent-sdk";

const response = query({
  prompt: "Analyze the codebase and suggest improvements",
  options: {
    model: "claude-sonnet-4-5",
    workingDirectory: process.cwd(),
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

for await (const message of response) {
  if (message.type === 'assistant') {
    console.log(message.content);
  }
}

---

安全安装

Agent SDK 软件包提供系统级功能——请在安装前进行验证，以防止未经授权的 Agent 访问。遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审查新版本的软件包
• 安装前审计 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

Claude Agent SDK 完整参考

目录

1. 核心查询 API
2. 工具集成
3. MCP 服务
4. 子 Agent 编排
5. 会话管理
6. 权限控制
7. 文件系统设置
8. 消息类型与流式传输
9. 错误处理
10. 已知问题

---

何时加载参考资料

该技能包含全面的参考文件，供深入了解。请在需要时加载：

• references/query-api-reference.md - 配置 query() 选项、处理消息类型、了解文件系统设置或调试 API 行为时加载
• references/mcp-servers-guide.md - 创建自定义工具、集成外部 MCP 服务或调试服务连接时加载
• references/subagents-patterns.md - 设计多 Agent 系统、编排专用 Agent 或优化 Agent 工作流时加载
• references/session-management.md - 实现持久对话、分叉会话或管理长期交互时加载
• references/permissions-guide.md - 实现自定义权限逻辑、保护 Agent 功能或控制工具访问权限时加载
• references/top-errors.md - 遇到错误、调试问题或实现错误处理时加载

---

核心查询 API

query() 函数是以编程方式与 Claude Code CLI 交互的主要接口。它会返回一个 AsyncGenerator，在 Agent 工作时流式传输消息。

完整的 API 详情、选项和高级模式：配置高级设置、处理消息流式传输或文件系统设置时，加载 references/query-api-reference.md。

基本用法

import { query } from "@anthropic-ai/claude-agent-sdk";

const response = query({
  prompt: "Review this code for bugs",
  options: {
    model: "claude-sonnet-4-5",        // or "haiku", "opus"
    workingDirectory: "/path/to/project",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "default"
  }
});

for await (const message of response) {
  // Process streaming messages
}

模型选择

模型	ID	适用场景	速度	能力
Haiku	"haiku"	快速任务、监控	最快	基础
Sonnet	"sonnet" 或 "claude-sonnet-4-5"	均衡	中等	高
Opus	"opus"	复杂推理	最慢	最高

---

工具集成（内置 + 自定义）

Claude Code 提供内置工具（Read、Write、Edit、Bash、Grep、Glob、WebSearch、WebFetch、Task），可通过 allowedTools 和 disallowedTools 选项进行控制。

完整的工具配置、自定义监控和高级模式：实现工具限制或监控时，加载 references/query-api-reference.md。

允许/禁止工具

// Whitelist approach (recommended)
const response = query({
  prompt: "Analyze code but don't modify anything",
  options: {
    allowedTools: ["Read", "Grep", "Glob"]
    // ONLY these tools can be used
  }
});

// Blacklist approach
const response = query({
  prompt: "Review and fix issues",
  options: {
    disallowedTools: ["Bash"]
    // Everything except Bash allowed
  }
});

重要：allowedTools = 白名单（仅限这些工具），disallowedTools = 黑名单（除这些工具外的所有工具）。如果两者都指定，则以 allowedTools 为准。

---

MCP 服务（Model Context Protocol）

MCP 服务通过 createSdkMcpServer()（进程内）或外部服务（stdio、HTTP、SSE），使用自定义工具扩展 Agent 的能力。

完整的 MCP 服务实现指南：创建自定义工具或集成 MCP 服务时，请加载 references/mcp-servers-guide.md。

快速示例：使用 tool(name, description, zodSchema, handler) 创建服务，通过 mcpServers 选项和 allowedTools: ["mcp__<server>__<tool>"] 使用

---

子 Agent 编排

具备专业技能的 Agent，可使用自定义工具、不同模型和专用提示词，适用于多 Agent 工作流。

完整的子 Agent 模式和编排策略：设计多 Agent 系统时，请加载 references/subagents-patterns.md。

AgentDefinition：使用 agents 选项，传入包含 description、prompt、tools（可选）和 model（可选）的对象

---

会话管理

会话支持持久对话、上下文保留和备选探索路径（分叉）。

完整的会话模式和工作流：实现持久对话时，请加载 references/session-management.md。

用法：从 system 初始化消息中获取 session_id，使用 resume: sessionId 选项恢复会话，使用 forkSession: true 创建分叉

---

权限控制

使用权限模式控制 Agent 的能力："default"（标准检查）、"acceptEdits"（自动批准编辑）、"bypassPermissions"（跳过所有检查——请谨慎使用）。

完整的权限模式和安全策略：实现自定义权限逻辑时，请加载 references/permissions-guide.md。

自定义逻辑：使用 canUseTool: async (toolName, input) => ({ behavior: "allow" | "deny" | "ask", message?: string }) 回调

---

文件系统设置

通过 settingSources 数组控制加载哪些设置文件："user"（~/.claude/settings.json）、"project"（.claude/settings.json）、"local"（.claude/settings.local.json）。

完整的配置和优先级规则：配置设置源时，请加载 references/query-api-reference.md。

默认值：[]（不加载任何设置）。优先级：程序化设置 > 本地 > 项目 > 用户

---

消息类型与流式处理

SDK 会流式传输消息：system（初始化/完成）、assistant（响应）、tool_call（工具请求）、tool_result（工具输出）、error（故障）。

完整的消息类型参考和流式处理模式：实现高级消息处理时，请加载 references/query-api-reference.md。

用法：在 for await (const message of response) 循环中处理消息，根据 message.type 进行分支判断

---

错误处理

常见错误：CLI_NOT_FOUND、AUTHENTICATION_FAILED、RATE_LIMIT_EXCEEDED、CONTEXT_LENGTH_EXCEEDED、PERMISSION_DENIED。

完整的错误目录及解决方案：遇到错误或实现错误处理时，请加载 references/top-errors.md。

模式：使用 try/catch 包裹查询，检查 error.code，在流式循环中处理 message.type === 'error'

---

已知问题预防

此技能可预防已记录的 12 个问题。最常见的 3 个问题：

问题 #1：未找到 CLI 错误

错误："Claude Code CLI not installed" 预防措施：使用 SDK 前先安装：bun add -g @anthropic-ai/claude-code

问题 #2：身份验证失败

错误："Invalid API key" 预防措施：始终设置 export ANTHROPIC_API_KEY="sk-ant-..."

问题 #3：权限被拒绝错误

错误：工具执行被阻止 预防措施：使用 allowedTools 或自定义 canUseTool 回调

所有 12 个错误的完整解决方案：调试或实现错误预防时，请加载 references/top-errors.md。

---

关键规则

始终要做

✅ 使用 SDK 前安装 Claude Code CLI ✅ 设置 ANTHROPIC_API_KEY 环境变量 ✅ 从 system 消息中捕获 session_id，以便恢复会话 ✅ 使用 allowedTools 限制 Agent 的能力 ✅ 实现 canUseTool，用于自定义权限逻辑 ✅ 在流式处理循环中处理所有消息类型 ✅ 使用 Zod 模式验证工具输入 ✅ 在多项目环境中设置 workingDirectory ✅ 在集成前单独测试 MCP 服务 ✅ 在 CI/CD 中使用 settingSources: ["project"] ✅ 通过 tool_call 消息监控工具执行情况 ✅ 为所有查询实现错误处理

绝不要做

❌ 将 API 密钥提交到版本控制中 ❌ 在生产环境中使用 bypassPermissions（除非在沙箱中运行） ❌ 假定工具已执行（检查 tool_result 消息） ❌ 忽略流中的错误消息 ❌ 如果计划恢复会话，不要跳过会话 ID 捕获 ❌ 不要在不同 MCP 服务之间使用重复的工具名称 ❌ 不要在没有 canUseTool 的情况下允许不受限制的 Bash 访问 ❌ 不要在 CI/CD 中从用户加载设置（settingSources: ["user"]） ❌ 不要未经验证就信任工具结果 ❌ 不要对文件路径进行硬编码（使用 workingDirectory） ❌ 不要对不可信的提示词使用 acceptEdits 模式 ❌ 不要跳过对工具输入的 Zod 验证

---

依赖项

必需：

• @anthropic-ai/[email protected]+ - Agent SDK
• [email protected]+ - 模式验证

可选：

• @types/[email protected]+ - TypeScript 类型
• @modelcontextprotocol/sdk@latest - MCP 服务开发

系统要求：

• Node.js 18.0.0+
• Claude Code CLI（安装：bun add -g @anthropic-ai/claude-code）
• 有效的 ANTHROPIC_API_KEY

---

官方文档

• Agent SDK 概览：https://docs.claude.com/en/api/agent-sdk/overview
• TypeScript API：https://docs.claude.com/en/api/agent-sdk/typescript
• Python API：https://docs.claude.com/en/api/agent-sdk/python
• Model Context Protocol：https://modelcontextprotocol.io/
• GitHub（TypeScript）：https://github.com/anthropics/claude-agent-sdk-typescript
• GitHub（Python）：https://github.com/anthropics/claude-agent-sdk-python
• Context7 库 ID：/anthropics/claude-agent-sdk-typescript

---

软件包版本（已于 2025-10-25 验证）

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
    "zod": "^3.23.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.3.0"
  }
}

---

生产环境示例

此技能基于 Anthropic 官方文档和 SDK 模式：

• 文档：https://docs.claude.com/en/api/agent-sdk/
• 验证：✅ 已使用 SDK 0.1.0+ 测试所有模式
• 用例：编码 Agent、SRE 系统、安全审计工具、CI/CD 自动化
• 平台支持：Node.js 18+、TypeScript 5.3+

---

完整设置清单

• 已安装 Node.js 18.0.0+
• 已安装 Claude Code CLI（bun add -g @anthropic-ai/claude-code）
• 已安装 SDK（bun add @anthropic-ai/claude-agent-sdk zod）
• 已设置 ANTHROPIC_API_KEY 环境变量
• 已为项目设置 workingDirectory
• 已配置 allowedTools（或使用默认值）
• 已选择 permissionMode（推荐使用默认值）
• 已实现错误处理
• 已设置会话管理（如有需要）
• 已配置 MCP 服务（如使用自定义工具）
• 已定义子 Agent（如有需要）

---

有疑问？遇到问题？

1. 查看 references/query-api-reference.md，了解完整的 API 详情
2. 查看 references/mcp-servers-guide.md，了解自定义工具
3. 查看 references/subagents-patterns.md，了解编排模式
4. 查看 references/session-management.md，了解持久化对话
5. 查看 references/permissions-guide.md，了解安全策略
6. 查看 references/top-errors.md，了解常见问题
7. 参阅官方文档：https://docs.claude.com/en/api/agent-sdk/

---

Token 效率：与手动集成 Agent SDK 相比，预计节省约 65% 错误预防：100%（可避免所有 12 个已记录的问题） 开发时间：使用技能仅需 30 分钟，手动开发则需 3–4 小时