claude-agent-sdk

核心用法

Claude Agent SDK 是 Anthropic 推出的 TypeScript 开发工具包，专用于构建自主 AI 智能体。其核心 API 为 query() 函数，采用异步生成器模式处理流式消息。开发者可通过 outputFormat 参数实现 JSON Schema 结构化输出验证，利用 agents 配置实现多层级子代理编排，或通过 mcpServers 集成外部 MCP 服务。SDK 提供 12 种生命周期钩子（Hooks）支持事件驱动编程，具备会话管理（resume/forkSession）、文件检查点（checkpointing）和沙盒执行等高级功能。

显著优点

类型安全与结构化输出是最大亮点，v0.1.45+ 版本支持 Zod 和 JSON Schema 验证，确保 AI 输出 100% 符合预期格式。安全架构完善，提供沙盒执行环境（Sandbox）、细粒度权限控制（canUseTool 回调）和四种权限模式（包括 plan 模式）。错误预防机制全面，文档详细列出 14 种常见错误及其解决方案，涵盖上下文长度管理、MCP 配置陷阱等。生态系统集成能力强，原生支持 MCP 协议，可无缝连接文件系统、Git 等外部服务，支持百万级 Token 长上下文。

潜在缺点与局限性

存在子代理资源泄漏风险（Issue #132），父代理停止时子代理可能继续运行导致内存泄漏；会话上下文硬限制，一旦触发 "Prompt too long" 错误，会话将永久损坏且无法通过 compact 恢复；T3 来源风险，技能由社区开发者维护而非 Anthropic 官方直接发布；学习曲线陡峭，涉及 Hooks、MCP、Sandbox 等多个复杂概念，初学者需要较长时间掌握。

适合的目标群体

主要面向企业级 AI 应用开发者、SRE 和运维自动化工程师、安全审计工具开发者以及需要构建多代理系统的架构师。特别适合需要强类型安全、严格权限控制和错误恢复机制的关键业务场景。对于快速原型开发或个人脚本编写，可能显得过于重量级。

使用风险

使用时需特别注意会话管理风险：长时间运行会话（超过 80 分钟）或上下文过大可能导致不可恢复的崩溃，建议实施主动会话轮换策略。子代理清理风险：默认情况下子代理不会随父代理终止而停止，必须在 Stop 钩子中手动实现清理逻辑。MCP 配置陷阱：URL 类型的 MCP 服务器必须显式声明 type 字段，否则会导致进程崩溃。Unicode 处理风险：MCP 工具返回结果中的 U+2028/U+2029 字符可能导致 JSON 解析失败，需手动转义。

核心用法

Claude Agent SDK 是 Anthropic 官方推出的 TypeScript SDK，用于构建自主 AI Agent。核心 API 为 query() 函数，返回异步生成器供流式处理消息。

关键特性：

• 结构化输出（v0.1.45+）：通过 outputFormat 参数实现 JSON Schema 验证，支持 Zod 类型推断
• 插件系统（v0.1.27+）：通过 plugins 数组加载本地插件扩展能力
• Hooks 系统（12个事件）：包括 PreToolUse、PostToolUse、SubagentStart/Stop、PreCompact 等，支持事件驱动工作流
• MCP 服务器：支持进程内（createSdkMcpServer）、stdio、HTTP/SSE 三种模式
• 子代理编排：通过 agents 参数定义子代理，支持 maxTurns 限制和技能加载
• 会话管理：支持 resume 恢复、forkSession 分支、continue 续接
• 权限控制：四种模式（default/acceptEdits/bypassPermissions/plan）+ canUseTool 自定义回调
• 沙箱设置：隔离 Bash 执行，支持网络代理和命令白名单
• 文件检查点：enableFileCheckpointing 实现状态快照与回滚

显著优点

1. 生产级安全：沙箱隔离、细粒度权限回调、敏感路径拦截
2. 类型安全：完整 TypeScript 支持，Zod v3/v4 双版本兼容
3. 灵活扩展：插件+Hooks+MCP 三层扩展架构
4. 错误预防：文档明确列出14个已知问题及解决方案
5. 官方维护：Anthropic 直接维护，API 与 Claude Code 同步更新

潜在缺点/局限性

1. 依赖 Claude Code CLI：必须全局安装 @anthropic-ai/claude-code
2. 会话易碎性：上下文超限后会话永久损坏，无法通过 /compact 恢复
3. 子代理孤儿进程：父代理停止后子代理继续运行（Issue #132）
4. MCP 配置陷阱：URL 服务器必须显式声明 type 字段，否则报 cryptic 错误
5. Unicode 陷阱：U+2028/U+2029 字符导致 JSON 解析失败
6. V2 API 不稳定：带 unstable_ 前缀，API 可能变动

适合人群

• SRE/DevOps：构建自动化运维、部署流水线 Agent
• 安全工程师：开发代码审计、漏洞扫描 Agent
• 平台工程师：搭建内部 AI 开发工具链
• 研究/原型开发：快速验证多 Agent 协作架构

常规风险

• 权限绕过误用：bypassPermissions 模式若用于生产可导致任意代码执行
• 沙箱逃逸：allowUnsandboxedCommands: true 或危险命令未列入 excludedCommands
• 敏感信息泄露：MCP 工具可能返回含密钥的日志未做脱敏
• 资源耗尽：子代理未清理导致的内存泄漏（递归场景 OOM）