⚡

ClaudeAgentSDK claude-agent-sdk

Claude Agent SDK 是一个用于构建和部署自主AI代理的软件开发工具包，支持工具集成、MCP服务器、多代理编排和会话管理，适用于自动化工作流、代码分析、系统监控等场景。关键词：Claude Agent SDK, AI智能体, 工具编排, MCP协议, 自主代理。

AI智能体 0 次安装 0 次浏览 更新于 3/8/2026

名称: claude-agent-sdk 描述: Anthropic Claude Agent SDK 用于自主代理和多步工作流。适用于子代理、工具编排、MCP服务器，或解决CLI未找到、上下文长度超出错误。

关键词: claude agent sdk, @anthropic-ai/claude-agent-sdk, query(), createSdkMcpServer, AgentDefinition, tool(), claude subagents, mcp servers, autonomous agents, agentic loops, session management, permissionMode, canUseTool, multi-agent orchestration, settingSources, CLI not found, context length exceeded 许可证: MIT

Claude Agent SDK

状态: 生产就绪 最后更新: 2025-11-21 依赖项: @anthropic-ai/claude-code, zod 最新版本: @anthropic-ai/claude-code@2.0.49+, zod@3.23.0+

快速开始（5分钟）

1. 安装SDK

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

为什么需要这些包:

  • @anthropic-ai/claude-agent-sdk - 主要代理SDK
  • zod - 类型安全的工具模式验证

2. 设置API密钥

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

关键:

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

3. 基本查询

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

const response = query({
  prompt: "分析代码库并提出改进建议",
  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);
  }
}

完整的Claude Agent SDK参考

目录

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

何时加载参考文件

技能包含全面的参考文件，用于深入探索。需要时加载：

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

核心查询API

query()函数是与Claude Code CLI编程交互的主要接口，返回一个AsyncGenerator流式传输消息。

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

基本用法

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

const response = query({
  prompt: "审查此代码中的错误",
  options: {
    model: "claude-sonnet-4-5",        // 或 "haiku", "opus"
    workingDirectory: "/path/to/project",
    allowedTools: ["Read", "Grep", "Glob"],
    permissionMode: "default"
  }
});

for await (const message of response) {
  // 处理流式消息
}

模型选择

模型 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。

允许/禁止工具

// 白名单方法（推荐）
const response = query({
  prompt: "分析代码但不修改任何内容",
  options: {
    allowedTools: ["Read", "Grep", "Glob"]
    // 仅这些工具可用
  }
});

// 黑名单方法
const response = query({
  prompt: "审查并修复问题",
  options: {
    disallowedTools: ["Bash"]
    // 除Bash外所有工具允许
  }
});

关键: allowedTools = 白名单（仅这些工具），disallowedTools = 黑名单（除这些外所有工具）。如果同时指定，allowedTools优先。

MCP服务器（模型上下文协议）

MCP服务器通过createSdkMcpServer()（进程内）或外部服务器（stdio, HTTP, SSE）扩展代理能力。

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

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

子代理编排

专业代理，具有专注专长、自定义工具、不同模型和专用提示，用于多代理工作流。

完整子代理模式和编排策略: 设计多代理系统时加载references/subagents-patterns.md。

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

会话管理

会话支持持久对话、上下文保存和替代探索路径（分叉）。

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

用法: 从系统初始化消息捕获session_id，通过resume: sessionId选项恢复，通过forkSession: true分叉

权限控制

控制代理能力：权限模式："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包装query，检查error.code，在流式循环中处理message.type === 'error'

已知问题预防

此技能预防12个文档化问题。最常见3个：

问题 #1: CLI未找到错误

错误: "Claude Code CLI未安装" 预防: 使用前安装：bun add -g @anthropic-ai/claude-code

问题 #2: 认证失败

错误: "无效API密钥" 预防: 始终设置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限制代理能力 ✅ 实现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/claude-agent-sdk@0.1.0+ - 代理SDK
  • zod@3.23.0+ - 模式验证

可选:

  • @types/node@20.0.0+ - TypeScript类型
  • @modelcontextprotocol/sdk@latest - MCP服务器开发

系统要求:

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

官方文档

包版本（已验证 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+测试
  • 使用案例: 编码代理、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服务器已配置（如使用自定义工具）
  • [ ] 子代理已定义（如需要）

问题？问题？

  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/

令牌效率: ~65% 节省 vs 手动Agent SDK集成（估计） 错误预防: 100%（所有12个文档化问题已预防） 开发时间: 30分钟使用技能 vs 3-4小时手动