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 解析失败，需手动转义。