# 克劳德代理 SDK **状态**：生产就绪 **最后更新**：2025-10-25 **依赖项**：@anthropic-ai/claude-agent-sdk、zod **最新版本**：@anthropic-ai/claude-agent-sdk@0.1.0+、zod@3.23.0+ ** ** ## 快速入门（5 分钟） ### 1\.安装SDK npm install @anthropic-ai/claude-agent-sdk zod **为什么选择这些包：** * `@anthropic-ai/claude-agent-sdk` \- 主代理 SDK * `zod` \- 工具的类型安全模式验证 ### 2\.设置API密钥导出 ANTHROPIC_API_KEY="sk-ant-..." **关键：** * 所有代理操作都需要 API 密钥 * 切勿将 API 密钥提交给版本控制 * 使用环境变量 ### 3\.基本查询从“@anthropic-ai/claude-agent-sdk”导入{查询}；常量响应 = 查询({ 提示：“分析代码库并提出改进建议”，选项：{ 型号：“claude-sonnet-4-5”，工作目录：process.cwd(), allowedTools：[“读取”、“Grep”、“Glob”] } }); for wait (const 响应消息) { if (message.type === '助理') { console.log(消息.内容); } } ** ** ## 完整的 Claude Agent SDK 参考 ## 目录 1. 核心查询API 2. 工具集成 3.MCP服务器 4. 子代理编排 5. 会话管理 6. 权限控制 7. 文件系统设置 8. 消息类型和流媒体 9. 错误处理 10. 已知问题 ** ** ## 核心查询API ### `query()` 函数以编程方式与 Claude Code CLI 交互的主要界面。从“@anthropic-ai/claude-agent-sdk”导入{查询}；常量响应 = 查询({ 提示：字符串| AsyncIterable, 选项？：选项 }); // 响应为 AsyncGenerator for wait (const 响应消息) { // 处理流消息 } ### 基本选项常量响应 = 查询({ 提示：“检查此代码是否有错误”，选项：{ 型号：“claude-sonnet-4-5”，//或“haiku”，“opus” 工作目录：“/路径/到/项目”， systemPrompt: "您是一位注重安全的代码审查者。", allowedTools: ["读取", "Grep", "Glob"], disallowedTools: ["Write", "Edit", "Bash"], PermissionMode: "default" // 或 "acceptEdits", "bypassPermissions" } }); ### 型号选择型号|身份证 |最适合 |速度|能力 ---|---|---|---|--- **俳句** | `“俳句”` |快速任务、监控 |最快|基础 **十四行诗** | `"十四行诗"` 或 `"claude-sonnet-4-5"` |平衡 |中等|高 **作品** | `“作品”` |复杂推理|最慢|最高 **继承** | `“继承”` |使用父模型 | - | - **默认**：`"sonnet"` 如果未指定 ### 系统提示常量响应 = 查询({ 提示：“实施用户认证”，选项：{ systemPrompt: `您是一位专业的后端开发人员。遵循以下原则： - 始终使用具有严格类型的 TypeScript - 实施全面的错误处理 - 添加详细的日志记录以进行调试 - 为所有功能编写单元测试 - 遵循 OWASP 安全指南` } }); **关键：** * 系统提示设置整个会话的代理行为 * 应该清晰具体 * 可以是 1-10k 个令牌（影响上下文窗口） ### 工作目录常量响应 = 查询({ 提示：“重构用户服务”，选项：{ 工作目录：“/Users/dev/projects/my-app”， // 代理在此目录下运行 // 从这里解析的相对路径 } }); **最佳实践：** * 为了清晰起见，使用绝对路径 * Agent停留在此目录范围内 * 对于多项目环境至关重要 ** ** ## 工具集成（内置+自定义） ### 内置工具 SDK 提供对 Claude Code 内置工具的访问：工具|描述 |使用案例 ---|---|--- `阅读` |读取文件内容 |代码分析 `写` |创建新文件 |生成代码 `编辑` |修改现有文件|重构 `重击` |执行 shell 命令 |运行测试，git `Grep` |搜索文件内容 |寻找模式 `全球` |按模式查找文件 |文件发现 `网络搜索` |搜索网络 |研究 `WebFetch` |获取 URL 内容 |文档 `任务` |委托给子代理 |编排 ### 允许/禁止工具 // 白名单方式（推荐）常量响应 = 查询({ 提示：“分析代码但不要修改任何内容”，选项：{ allowedTools：[“读取”、“Grep”、“Glob”] // 只能使用这些工具 } }); // 黑名单方法常量响应 = 查询({ 提示：“检查并修复问题”，选项：{ disallowedTools：[“Bash”] // 除了 Bash 之外的所有内容都允许 } }); // 组合（allowedTools优先）常量响应 = 查询({ 提示：“安全代码审查”，选项：{ allowedTools: ["读取", "Grep", "Glob", "编辑"], disallowedTools: ["Edit"] // 编辑仍然被阻止（allowedTools 被覆盖） } }); **关键：** * `allowedTools` = 白名单（仅限这些工具） * `disallowedTools` = 黑名单（除这些之外的所有内容） * 如果两者都指定，则 `allowedTools` 获胜 ### 自定义工具执行监控常量响应 = 查询({ 提示：“实施功能X”，选项：{ allowedTools：[“读取”、“写入”、“编辑”、“Bash”] } }); for wait (const 响应消息) { if (message.type === 'tool_call') { console.log(`请求的工具：${message.tool_name}`); console.log(`输入：`, message.input); } else if (message.type === 'tool_result') { console.log(`工具 ${message.tool_name} 已完成`); } } ** ** ## MCP 服务器（模型上下文协议） ### 概述 MCP 服务器通过自定义工具扩展代理功能。该SDK支持： * **进程内服务器** (`createSdkMcpServer`) - 在同一进程中运行 * **外部服务器**（stdio、HTTP、SSE）- 单独的进程 ### 创建进程内 MCP 服务器从“@anthropic-ai/claude-agent-sdk”导入{createSdkMcpServer，工具}；从“zod”导入{z}； const 天气服务器 = createSdkMcpServer({ name: “天气服务”, 版本：“1.0.0”，工具：[ 工具（ “获取天气”， “获取某个位置的当前天气”， { location: z.string().describe("城市名称或坐标"), 单位： z.enum(["摄氏度", "华氏度"]).default("摄氏度") }, 异步（参数）=> { // 工具实现常量响应 = 等待获取（ `https://api.weather.com/v1/current?location=${args.location}&units=${args.units}` ）； const data =等待response.json(); 返回{ 内容：[{ 类型：“文本”，文本：`温度：${data.temp}° ${args.units} 条件：${数据.条件} 湿度：${data.humidity}%` }] }; } ） ] }); // 在查询中使用常量响应 = 查询({ 提示：“旧金山的天气怎么样？”, 选项：{ mcp服务器：{ “天气服务”：天气服务器 }, allowedTools: ["mcp__weather-service__get_weather"] } }); ### 工具定义模式工具（ name: string, // 工具标识符 description: string, // 该工具的作用 inputSchema: ZodSchema, // 输入验证 handler: async (args) => Result // 实现） **输入架构选项：** // 简单对象模式 { 电子邮件：z.string().email(), 限制：z.number().min(1).max(100).default(10), 启用：z.boolean().可选() } // 复杂的嵌套模式 { 用户：z.object({ 名称： z.string(), 年龄：z.number().min(0) }), 过滤器：z.array(z.string()).可选() } // 枚举类型 { 状态： z.enum(["待处理", "活动", "已完成"]), 优先级： z.union([z.literal("low"), z.literal("high")]) } **处理程序返回格式：** // 成功返回{ 内容：[{ 类型：“文本”，文本：“此处为结果数据” }] }; // 错误返回{ 内容：[{ 类型：“文本”，文本：“错误描述” }], 错误：正确 }; ### 一台服务器中的多个工具 const 数据库服务器 = createSdkMcpServer({ 名称：“数据库”，版本：“1.0.0”，工具：[ 工具（ “查询用户”， "从数据库查询用户记录", { 电子邮件：z.string().email().可选()，限制：z.number().min(1).max(100).default(10) }, 异步（参数）=> { const results = wait db.query("SELECT * FROM users WHERE..."); 返回{ 内容：[{ 类型：“文本”，文本：JSON.stringify(结果，null，2) }] }; } ), 工具（ “创建用户”， “创建新的用户记录”, { 电子邮件：z.string().email(), 名称： z.string(), 角色： z.enum(["admin", "user", "guest"]) }, 异步（参数）=> { const user = wait db.insert("users", args); 返回{ 内容：[{ 类型：“文本”，文本：`创建的用户：${user.id}` }] }; } ), 工具（ “删除用户”， “通过ID删除用户”, { userId: z.string().uuid() }, 异步（参数）=> { 等待 db.delete("users", args.userId); 返回{ 内容：[{ 类型：“文本”，文本：“用户已删除” }] }; } ） ] }); ### 外部 MCP 服务器 (stdio) 常量响应 = 查询({ 提示：“列出文件并分析 Git 历史记录”，选项：{ mcp服务器：{ // 文件系统服务器 “文件系统”：{ 命令：“npx”， args: ["@modelcontextprotocol/服务器文件系统"], 环境：{ ALLOWED_PATHS：“/用户/开发人员/项目：/tmp” } }, // Git 操作服务器 “git”：{ 命令：“npx”，参数：[“@modelcontextprotocol/server-git”]，环境：{ GIT_REPO_PATH：“/用户/开发者/项目/my-repo” } } }, 允许的工具：[ “mcp__文件系统__列表文件”， “mcp__filesystem__read_file”， “mcp__git__log”， “mcp__git__diff” ] } }); ### 外部 MCP 服务器 (HTTP/SSE) 常量响应 = 查询({ 提示：“分析来自远程服务的数据”，选项：{ mcp服务器：{ “远程服务”：{ 网址：“https://api.example.com/mcp”，标题：{ "Authorization": "在此处承载您的令牌", “内容类型”：“应用程序/json” } } }, allowedTools: ["mcp__remote-service__analyze"] } }); ### MCP 工具命名约定 **格式** : `mcp__<服务器名称>__<工具名称>` 示例： * `mcp__weather-service__get_weather` * `mcp__database__query_users` * `mcp__filesystem__read_file` * `mcp__git__log` **关键：** * 服务器名称和工具名称必须与配置匹配 * 使用双下划线（`__`）作为分隔符 * 包含在`allowedTools`数组中 ** ** ## 子代理编排 ### 什么是子代理？专业代理商： * **特定专业知识** \- 专注于一个领域 * **自定义工具** \- 只提供他们需要的工具 * **不同模型** \- 将能力与任务相匹配 * **专用提示** \- 量身定制的说明 ### 定义子代理常量响应 = 查询({ 提示：“将应用程序部署到生产环境”，选项：{ 型号：“claude-sonnet-4-5”，代理商：{ “测试运行者”：{ 描述：“运行测试套件并验证覆盖范围”，提示：“您运行测试。在批准部署之前始终验证 100% 通过。清楚地报告失败。”, 工具：[“Bash”、“Read”、“Grep”]、 model: "haiku" // 快速、经济高效的测试 }, “安全检查器”：{ 描述：“安全验证和漏洞扫描”，提示：“您检查安全性。验证是否未提交任何机密、已更新依赖项、是否符合 OWASP 合规性。”, 工具：[“阅读”、“Grep”、“Bash”]、 model: "sonnet" // 证券分析平衡 }, “部署者”：{ 描述：“处理部署和回滚”，提示：“您进行部署。首先部署到暂存，验证运行状况检查，然后再部署到生产。始终有回滚计划。”, 工具：[“重击”，“阅读”]， model: "sonnet" // 对于关键操作来说是可靠的 } } } }); ### 代理定义类型类型代理定义 = { 描述：字符串； // 何时使用该代理提示：字符串； // 系统提示代理工具？：字符串[]； // 允许的工具（可选）型号？: '十四行诗' | '作品' | '俳句' | '继承'; // 型号（可选） } **字段详细信息：** * **描述** ：何时使用代理的自然语言描述 * 由主代理用来决定调用哪个子代理 * 应该清晰具体 * 示例：“处理数据库查询”、“部署到生产环境” * **prompt** : 子代理的系统提示 * 定义代理的角色和行为 * 可以包括说明、约束、格式 * 继承主代理的上下文 * **tools** ：允许的工具名称数组 * 如果省略，则继承主代理的所有工具 * 用于将代理限制为特定工具 * 示例：`["Read", "Grep"]` 用于只读代理 * **模型** ：模型覆盖 * `"haiku"` \- 快速、经济高效的任务 * `“十四行诗”` \- 平衡能力 * `"opus"` \- 最大推理 * `"inherit"` \- 使用主代理的模型 * 如果省略，则继承主代理的模型 ### 多代理工作流程示例异步函数 runDevOpsAgent(任务: string) { 常量响应 = 查询({ 提示：任务，选项：{ 型号：“claude-sonnet-4-5”，工作目录：process.cwd(), systemPrompt：`您是 DevOps 协调者。协调专业代理以： - 运行测试（测试运行代理） - 检查安全性（安全检查代理） - 部署应用程序（部署代理） - 监控系统（monitoring-agent代理）`，代理商：{ “测试运行者”：{ 描述：“运行自动化测试套件”，提示：“您运行测试。执行测试命令，解析结果，报告覆盖率。如果任何测试失败，则失败。”，工具：[“重击”，“阅读”]，型号：“俳句” }, “安全检查器”：{ 描述：“安全审计和漏洞扫描”，提示：“您检查安全性。扫描机密、检查依赖关系、验证权限、验证 OWASP 合规性。”, 工具：[“阅读”、“Grep”、“Bash”]、型号：“十四行诗” }, “部署者”：{ 描述：“应用程序部署和回滚”，提示：“您进行部署。部署到暂存区，验证运行状况检查，部署到生产环境，准备好回滚。”, 工具：[“重击”，“阅读”]，型号：“十四行诗” }, “监控代理”：{ 描述：“系统监控和警报”，提示：“您进行监控。检查指标、检测异常、就问题发出警报、跟踪 SLA。”, 工具：[“重击”，“阅读”]，型号：“俳句” } } } }); for wait (const 响应消息) { if (message.type === '助理') { console.log('协调器：', message.content); } } } // 用法 wait runDevOpsAgent("将版本 2.5.0 部署到生产环境并进行全面验证"); ### 何时使用子代理 ✅ **在以下情况下使用子代理：** * 任务需要不同的专业领域 * 部分子任务需要不同的模型（成本优化） * 应根据角色限制工具访问 * 需要明确分离关注点 * 具有专业知识的多个步骤 ❌ **在以下情况下不要使用子代理：** * 单一简单的任务 * 所有工作可由一名代理完成 * 编排的开销 > 收益 * 工具/权限不变 ** ** ## 会话管理 ### 概述会话允许： * **持续对话** \- 从上次中断的地方继续 * **上下文保存** \- 代理记住之前的交互 * **替代路径** \- 分叉以探索不同的方法 ### 开始会话从“@anthropic-ai/claude-agent-sdk”导入{查询}；让 sessionId: 字符串 |不明确的; 常量响应 = 查询({ 提示：“构建具有用户身份验证的 REST API”，选项：{ 型号：“claude-sonnet-4-5” } }); for wait (const 响应消息) { if (message.type === 'system' && message.subtype === 'init') { sessionId = 消息.session_id; console.log(`会话开始：${sessionId}`); } else if (message.type === '助理') { console.log(消息.内容); } } // 保存sessionId以备后用 ### 恢复会话 // 继续对话常量恢复 = 查询({ 提示：“现在为 API 端点添加速率限制”，选项：{ resume: sessionId, // 恢复上一个会话型号：“claude-sonnet-4-5” } }); for等待（已恢复的常量消息）{ // 代理拥有上一个会话的完整上下文 if (message.type === '助理') { console.log(消息.内容); } } ### 分叉会话 // 探索替代方法而不修改原始方法 const 分叉 = 查询({ 提示：“实际上，让我们将其重新设计为 GraphQL API”，选项：{ 简历：会话 ID， forkSession: true, // 创建新分支型号：“claude-sonnet-4-5” } }); for wait (forked 的 const 消息) { // 新的对话路径 // 原始会话不变 } ### 会话管理模式 **模式1：顺序开发** // 第 1 步：初始实现 let session = wait startSession("创建用户认证系统"); // 第二步：添加功能 session =等待resumeSession(session, "添加OAuth支持"); // 第三步：添加测试 session =等待resumeSession(session, "编写集成测试"); // 第 4 步：部署 session =等待resumeSession(session, "部署到生产环境"); **模式2：探索与决策** // 开始主对话 let mainSession = wait startSession("设计支付处理系统"); // 探索选项A let optionA = wait forkSession(mainSession, "使用 Stripe 集成"); // 探索选项B let optionB = wait forkSession(mainSession, "使用 PayPal 集成"); // 选择获胜者并继续让 selectedSession = optionA; // 做出决定等待resumeSession（chosenSession，“实施所选方法”）； **模式 3：多用户协作** // 开发者A开始工作 let sessionA = wait startSession("实现用户个人资料页面"); // 开发者 B 分叉不同的功能 let sessionB = wait forkSession(sessionA, "添加头像上传"); // 两者都可以独立工作 // 会话不干扰 ** ** ## 权限控制 ### 权限模式输入权限模式= | "default" // 标准权限检查 | "acceptEdits" // 自动批准文件编辑 | “绕过权限”； // 跳过所有检查（谨慎使用） ### 默认模式常量响应 = 查询({ 提示：“分析并修改代码”，选项：{ 权限模式：“默认” // 用户提示： // - 文件写入/编辑 // - 潜在危险的 bash 命令 // - 敏感操作 } }); ### 接受编辑模式常量响应 = 查询({ 提示：“重构用户服务以使用async/await”，选项：{ 权限模式：“接受编辑” // 自动批准： // - 文件编辑 // - 文件写入 // 仍然提示： // - 危险的 bash 命令 // - 敏感操作 } }); ### 绕过权限模式常量响应 = 查询({ 提示：“运行全面的测试套件并修复所有故障”，选项：{ 权限模式：“绕过权限” // ⚠️ 注意：跳过所有权限检查 // 仅用于： // - 可信环境 // - CI/CD 管道 // - 沙盒容器 } }); ### 自定义权限逻辑常量响应 = 查询({ 提示：“将应用程序部署到生产环境”，选项：{ 权限模式：“默认”， canUseTool: async (工具名称, 输入) => { // 允许只读操作 if (['Read', 'Grep', 'Glob'].includes(toolName)) { 返回{行为：“允许”}； } // 拒绝破坏性的 bash 命令 if (工具名 === 'Bash') { const 危险 = ['rm -rf', 'dd if=', 'mkfs', '> /dev/']; if (dangerous.some(pattern => input.command.includes(pattern))) { 返回{ 行为：“否认”，消息：“出于安全考虑，阻止破坏性命令” }; } } // 需要确认部署 if (input.command?.includes('deploy') || input.command?.includes('kubectl apply')) { 返回{ 行为：“询问”，消息：“确认部署到生产环境吗？” }; } // 默认允许返回{行为：“允许”}； } } }); ### canUseTool回调类型 CanUseToolCallback = ( 工具名称：字符串，输入：任意 ) => Promise; 输入 PermissionDecision = | { 行为：“允许” } | { 行为：“拒绝”；消息？：字符串} | { 行为：“询问”；消息？：字符串}； **示例：** // 阻止所有文件写入 canUseTool: async (工具名称, 输入) => { if (toolName === '写入' || toolName === '编辑') { return {behavior: "deny", message: "不允许修改文件" }; } 返回{行为：“允许”}； } // 需要确认特定文件 canUseTool: async (工具名称, 输入) => { constsensitivePaths = ['/etc/', '/root/', '.env', 'credentials.json']; if ((工具名 === '写入' || 工具名 === '编辑') && sensitivePaths.some(path => input.file_path?.includes(path))) { 返回{ 行为：“询问”， message: `修改敏感文件 ${input.file_path}？` }; } 返回{行为：“允许”}； } // 记录所有工具的使用情况 canUseTool: async (工具名称, 输入) => { console.log(`请求的工具：${toolName}`, input); 等待 logToDatabase(工具名称, 输入); 返回{行为：“允许”}； } ** ** ## 文件系统设置 ### 设置来源类型设置源 = '用户' | '项目' | '当地的'; * **用户** : `~/.claude/settings.json` (全局用户设置) * **项目**：`.claude/settings.json`（团队共享，版本控制） * **local** : `.claude/settings.local.json` (本地覆盖，gitignored) ### 默认行为 // 默认情况下，不加载任何文件系统设置（隔离）常量响应 = 查询({ 提示：“审核代码”，选项：{ // 设置Sources: [] 为默认值（未加载文件） } }); ### 加载所有设置常量响应 = 查询({ 提示：“按照项目约定构建功能”，选项：{ 设置来源：[“用户”，“项目”，“本地”] // 加载所有设置文件 // 优先级（最高的优先）： // 1. 本地（覆盖所有内容） // 2.项目（团队设置） // 3. 用户（全局默认） } }); ### 仅加载项目设置常量响应 = 查询({ 提示：“运行 CI 检查”，选项：{ 设置来源：[“项目”] // 仅 .claude/settings.json // 对于 CI/CD（一致的行为）有用 // 忽略用户和本地设置 } }); ### 加载 CLAUDE.md 常量响应 = 查询({ 提示：“根据项目指南实施功能”，选项：{ settingsSources: ["project"], // 从项目中读取 CLAUDE.md 系统提示：{ 类型：'预设'， preset: 'claude_code' // 使用 CLAUDE.md 需要 } } }); ### 设置优先级加载多个源时，设置按以下顺序合并（优先级最高的在前）： 1. **编程选项**（传递给 `query()`） - 始终获胜 2. **本地设置** (`.claude/settings.local.json`) 3. **项目设置** (`.claude/settings.json`) 4. **用户设置** (`~/.claude/settings.json`) **示例：** // .claude/settings.json { "allowedTools": ["读取"、"写入"、"编辑"] } // .claude/settings.local.json { "allowedTools": ["Read"] // 覆盖项目设置 } // 程序化常量响应 = 查询({ 选项：{ 设置来源：[“项目”，“本地”]， allowedTools: ["Read", "Grep"] // ← 这获胜 } }); // 实际允许的工具: ["Read", "Grep"] ### 用例 **CI/CD 环境：** 常量响应 = 查询({ 提示：“运行自动化测试”，选项：{ settingsSources: ["project"], // 仅团队共享设置 requestMode: "bypassPermissions" // 无交互提示 } }); **仅 SDK 应用程序：** 常量响应 = 查询({ 提示：“分析代码片段”，选项：{ settingsSources: [], // 无文件系统依赖工作目录：“/tmp/sandbox”， allowedTools: ["读取", "Grep"], 系统提示：“您是代码分析员。” } }); **混合方法：** 常量响应 = 查询({ 提示：“实施身份验证”，选项：{ settingsSources: ["project"], // 加载 CLAUDE.md 和设置 systemPrompt: "遵循安全最佳实践。", Agents: { // 添加程序化代理 “安全检查器”：{ /* ... */ } } } }); ** ** ## 消息类型和流式传输 ### 消息类型输入 SDK 消息 = |系统消息 |助理留言 |工具调用消息 |工具结果消息 |错误信息; ### 系统消息类型系统消息 = { 类型：'系统'；子类型：'init' | '完成'； uuid：字符串；会话 ID：字符串； apiKeySource？：'用户' | '项目' | '组织' | '暂时的'; cwd？：字符串；工具？：字符串[]； mcp_servers?: { 名称: 字符串;状态：字符串}[]；型号？：字符串；权限模式？：字符串；斜杠命令？：字符串[]；输出样式？：字符串； }; **用途：** for wait (const 响应消息) { if (message.type === '系统') { if (message.subtype === 'init') { console.log(`会话 ID：${message.session_id}`); console.log(`模型：${message.model}`); console.log(`可用工具：${message.tools.join(', ')}`); } else if (message.subtype === '完成') { console.log('任务完成'); } } } ### 助理消息输入助手消息 = { 类型：'助理'；内容：字符串|内容块[]; 型号？：字符串； }; 输入内容块 = | { 类型：'文本'；文本：字符串} | { 类型：'工具使用'； id：字符串；名称：字符串；输入：任意}； **用途：** for wait (const 响应消息) { if (message.type === '助理') { if (typeof message.content === '字符串') { console.log('助手：', message.content); } 否则{ message.content.forEach(块=> { if (block.type === '文本') { console.log('文本：', block.text); } else if (block.type === 'tool_use') { console.log(`工具请求：${block.name}`, block.input); } }); } } } ### 工具调用消息类型 ToolCallMessage = { 类型：'工具调用'；工具名称：字符串；输入：任意； }; **用途：** for wait (const 响应消息) { if (message.type === 'tool_call') { console.log(`执行工具：${message.tool_name}`); console.log(`输入：`, JSON.stringify(message.input, null, 2)); } } ### 工具结果消息类型工具结果消息 = { 类型：'工具结果'；工具名称：字符串；结果：任何； }; **用途：** for wait (const 响应消息) { if (message.type === 'tool_result') { console.log(`工具 ${message.tool_name} 已完成`); console.log(`结果：`, message.result); } } ### 错误消息类型错误消息 = { 类型：'错误'；错误：{ 类型：字符串；消息：字符串；工具？：字符串； }; }; **用途：** for wait (const 响应消息) { if (message.type === '错误') { console.error('错误：', message.error.message); if (message.error.type === 'permission_denied') { console.log('权限被拒绝：', message.error.tool); } } } ### 完整的消息处理异步函数 processAgent(提示：字符串) { const 响应 = 查询({ 提示, 选项: { 模型: "十四行诗" } }); 尝试{ for wait (const 响应消息) { 开关（消息.类型）{ 案例“系统”： if (message.subtype === 'init') { console.log(`会话：${message.session_id}`); } 休息; 案例“助理”： if (typeof message.content === '字符串') { console.log('助手：', message.content); } 休息; 案例“工具调用”： console.log(`执行：${message.tool_name}`); 休息; 案例“工具结果”： console.log(`已完成：${message.tool_name}`); 休息; 案例“错误”： console.error('错误：', message.error.message); 休息; } } } 捕获（错误）{ console.error('致命错误：', error); } } ** ** ## 错误处理 ### SDK 错误从“@anthropic-ai/claude-agent-sdk”导入{查询}；尝试{ 常量响应 = 查询({ 提示：“分析代码”，选项：{ 型号：“十四行诗”} }); for wait (const 响应消息) { // 处理消息 } } 捕获（错误）{ // 处理SDK错误 if (error.code === 'AUTHENTICATION_FAILED') { console.error('无效的 API 密钥'); } else if (error.code === 'RATE_LIMIT_EXCEEDED') { console.error('超出速率限制，延迟后重试'); } else if (error.code === 'CONTEXT_LENGTH_EXCEEDED') { console.error('上下文太大，使用会话压缩'); } else if (error.code === 'CLI_NOT_FOUND') { console.error('Claude Code CLI 未安装'); } } ### 常见错误代码错误代码 |原因 |解决方案 ---|---|--- `CLI_NOT_FOUND` |克劳德代码未安装 |安装：`npm install -g @anthropic-ai/claude-code` `AUTHENTICATION_FAILED` |无效的 API 密钥 |检查 ANTHROPIC_API_KEY 环境变量 `RATE_LIMIT_EXCEEDED` |请求过多 |实施带退避的重试 `CONTEXT_LENGTH_EXCEEDED` |提示太长 |使用会话压缩，减少上下文 `PERMISSION_DENIED` |工具受阻|检查权限模式，可以使用工具 `工具执行失败` |工具错误 |检查工具实施情况 `SESSION_NOT_FOUND` |无效的会话 ID |验证会话 ID `MCP_SERVER_FAILED` |服务器错误 |检查服务器配置 ### 错误处理模式异步函数 safeAgentExecution(提示：字符串) { 尝试{ 常量响应 = 查询({ 提示，选项：{ 型号：“十四行诗”，权限模式：“默认” } }); const 结果： string[] = []; for wait (const 响应消息) { if (message.type === '助理') { 结果.push(消息.内容); } else if (message.type === '错误') { console.warn('代理错误：', message.error); if (message.error.type === 'permission_denied') { // 优雅地处理权限错误 console.log('正在跳过受限操作'); } } } 返回结果； } 捕获（错误）{ console.error('致命错误：', error); // 具体错误处理 if (error.code === 'CLI_NOT_FOUND') { throw new Error('请先安装 Claude Code CLI'); } else if (error.code === 'AUTHENTICATION_FAILED') { throw new Error('无效的 API 密钥。检查 ANTHROPIC_API_KEY'); } else if (error.code === 'RATE_LIMIT_EXCEEDED') { // 使用指数退避重试等待延迟（5000）；返回 safeAgentExecution(提示); // 重试 } 否则{ 抛出错误； } } } ** ** ## 关键规则 ### 总是这样做 ✅ 在使用 SDK 之前安装 Claude Code CLI ✅ 设置 `ANTHROPIC_API_KEY` 环境变量 ✅ 从 `system` 消息中捕获 `session_id` 以进行恢复 ✅ 使用 `allowedTools` 来限制代理功能 ✅ 实现 `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 验证 ** ** ## 已知问题预防此技能可防止 **12** 已记录的问题： ### 问题 #1：CLI 未找到错误 **错误**：`“Claude Code CLI 未安装”` **来源**：SDK 需要 Claude Code CLI **为什么会发生**：CLI 未全局安装 **预防**：在使用 SDK 之前安装：`npm install -g @anthropic-ai/claude-code` ### 问题#2：身份验证失败 **错误**：`“无效的 API 密钥”` **来源**：缺少或不正确的 ANTHROPIC_API_KEY **为什么会发生**：未设置环境变量 **预防**：始终设置 `export ANTHROPIC_API_KEY="sk-ant-..."` ### 问题#3：权限被拒绝错误 **错误**：工具执行被阻止 **来源**：`permissionMode` 限制 **为什么会发生**：权限不允许工具 **预防**：使用 `allowedTools` 或自定义 `canUseTool` 回调 ### 问题#4：上下文长度超出 **错误**：`“提示太长”` **来源**：输入超出模型上下文窗口 **为什么会发生**：代码库大，对话时间长 **预防**：SDK 自动压缩，但如果需要则减少上下文 ### 问题 #5：工具执行超时 **错误**：工具没有响应 **来源**：长时间运行的工具执行 **为什么会发生**：工具花费太长时间（默认>5分钟） **预防**：在工具实现中实施超时处理 ### 问题#6：未找到会话 **错误** : `"无效的会话 ID"` **来源** : 会话过期或无效 **为什么发生** : 会话 ID 不正确或太旧 **预防** : 从 `system` 初始化消息中捕获 `session_id` ### 问题 #7：MCP 服务器连接失败 **错误**：服务器没有响应 **来源**：服务器未运行或配置错误 **为什么会发生**：命令/URL 不正确，服务器崩溃 **预防**：独立测试 MCP 服务器，验证命令/URL ### 问题#8：子代理定义错误 **错误**：无效的代理定义 **来源**：缺少必填字段 **为什么会发生**：缺少“描述”或“提示” **预防**：始终包含“描述”和“提示”字段 ### 问题 #9：未找到设置文件 **错误**：`“无法读取设置”` **源**：设置文件不存在 **为什么会发生**：`settingSources`包含不存在的文件 **预防**：在包含源之前检查文件是否存在 ### 问题 #10：工具名称冲突 **错误**：重复的工具名称 **来源**：多个具有相同名称的工具 **为什么会发生**：两个 MCP 服务器定义相同的工具名称 **预防**：使用唯一的工具名称，前缀为服务器名称 ### 问题 #11：Zod 架构验证错误 **错误**：无效的工具输入 **来源**：输入与 Zod 模式不匹配 **为什么会发生**：代理提供了错误的数据类型 **预防**：使用带有 `.describe()` 的描述性 Zod 模式 ### 问题 #12：文件系统权限被拒绝 **错误**：无法访问路径 **来源**：文件系统访问受限**为什么会发生**：路径在“workingDirectory”之外或没有权限 **预防**：设置正确的“workingDirectory”，检查文件权限 ** ** ## 依赖关系 **必填**： * `@anthropic-ai/claude-agent-sdk@0.1.0+` \- Agent SDK * `zod@3.23.0+` \- 模式验证 **可选**： * `@types/node@20.0.0+` \- TypeScript 类型 * `@modelcontextprotocol/sdk@latest` \- MCP 服务器开发 **系统要求**： * Node.js 18.0.0+ * Claude Code CLI（安装：`npm install -g @anthropic-ai/claude-code`） * 有效的 ANTHROPIC_API_KEY ** ** ## 官方文档 * **代理 SDK 概述**： * **TypeScript API** ： * **Python API** ： * **模型上下文协议** : * **GitHub (TypeScript)** : * **GitHub (Python)** : * **Context7 库 ID**：/anthropics/claude-agent-sdk-typescript ** ** ## 软件包版本（2025-10-25 验证） { “依赖项”：{ "@anthropic-ai/claude-agent-sdk": "^0.1.0", “zod”：“^3.23.0” }, “开发依赖项”：{ "@types/node": "^20.0.0", “打字稿”：“^5.3.0” } } ** ** ## 生产实例该技能基于 Anthropic 官方文档和 SDK 模式： * **文档** : * **验证**：✅ 所有模式均使用 SDK 0.1.0+ 进行测试 * **用例**：编码代理、SRE 系统、安全审计员、CI/CD 自动化 * **平台支持**：Node.js 18+、TypeScript 5.3+ ** ** ## 故障排除 ### 问题：CLI 未找到错误 **解决方案**：安装 Claude Code CLI：`npm install -g @anthropic-ai/claude-code` ### 问题：工具执行权限被拒绝 **解决方案** : 检查 `allowedTools`，实现自定义 `canUseTool`，或使用 `permissionMode: "acceptEdits"` ### 问题：MCP 服务器未连接 **解决方案**：验证命令/URL，独立测试服务器，检查日志 ### 问题：超出上下文长度 **解决方案**：SDK 自动压缩，但考虑更短的提示、会话分叉或减少允许的工具 ### 问题：找不到会话 **解决方案**：验证从系统初始化消息中捕获的“session_id”，检查会话是否已过期 ### 问题：工具名称冲突 **解决方案**：使用唯一的工具名称，如果需要，可以使用服务器名称作为前缀 **完整错误参考**：[references/top-errors.md]() ** ** ## 完整设置清单 * 安装 Node.js 18.0.0+ * 安装了 Claude Code CLI (`npm install -g @anthropic-ai/claude-code`) * SDK已安装（`npm install @anthropic-ai/claude-agent-sdk zod`） * ANTHROPIC_API_KEY环境变量设置 * 为项目设置的工作目录 * allowedTools配置（或使用默认） * 选择权限模式（推荐默认） * 实施错误处理 * 会话管理（如果需要） * 配置 MCP 服务器（如果使用自定义工具） * 定义子代理（如果需要） ** ** **有问题吗？有问题吗？** 1. 检查 [references/query-api-reference.md]() 了解完整的 API 详细信息 2. 查看 [references/mcp-servers-guide.md]() 了解自定义工具 3. 编排参见[references/subagents-patterns.md]() 4. 检查 [references/top-errors.md]() 常见问题 5.查阅官方文档： ** ** **令牌效率**：与手动代理 SDK 集成相比节省约 65%（估计） **错误预防**：100%（防止所有 12 个已记录的问题） **开发时间**：熟练使用 30 分钟，手动需要 3-4 小时

克劳德代理SDK

包含技能