Claude Agent SDK 是用于构建自主 AI 智能体的开发工具包，包名为 @anthropic-ai/claude-agent-sdk@0.2.12。资料中明确列出若干破坏性变更：v0.1.45 引入结构化输出（2025 年 11 月），v0.1.0 起不再提供默认 system prompt，且需要设置 settingSources。
【结构化输出】v0.1.45（2025-11-14）引入。提供 JSON schema 校验，保证响应严格匹配指定 schema；通过 outputFormat 参数以 JSON schema 或 Zod 定义输出结构；校验结果通过 message.structured_output 获取；需要 beta 头 structured-outputs-2025-11-13；支持基于 Zod schema 的完整 TypeScript 类型推断。使用上需引入 query 与 zod、zod-to-json-schema，定义 schema 后在 options.outputFormat 中设置 type 为 json_schema、name、strict 及 schema，再遍历响应的 message，在 type 为 result 且存在 structured_output 时用 schema.parse 解析。Zod 兼容性方面，v0.1.71+ 起同时支持 Zod v3.24.1+ 与 v4.0.0+ 作为 peer 依赖，导入方式均为 import { z } from "zod"。官方文档地址为 https://platform.claude.com/docs/en/agent-sdk/structured-outputs。
【插件系统】v0.1.27 引入。通过 plugins 数组加载本地插件路径，支持自定义插件以扩展智能体能力。
【Hooks 系统】v0.1.0+ 引入，包含 12 个 Hook 事件：PreToolUse（工具执行前，用于校验、修改或阻止工具调用）、PostToolUse（工具执行后，记录结果或触发副作用）、Notification（智能体通知，展示状态更新）、UserPromptSubmit（收到用户提示，预处理或校验输入）、SubagentStart（派生子智能体，追踪委派）、SubagentStop（子智能体完成，聚合结果与清理）、PreCompact（上下文压缩前，截断前保存状态）、PermissionRequest（需要权限，自定义审批流程）、Stop（智能体停止，清理与最终日志）、SessionStart（会话开始，初始化状态）、SessionEnd（会话结束，持久化状态与清理）、Error（发生错误，自定义错误处理）。Hooks 在 query 的 options.hooks 中配置，如 PreToolUse 返回 { allow: true } 或 { allow: false, message: "..." }。
【其他选项】fallbackModel（失败时自动回退模型）、maxThinkingTokens（控制扩展思考预算）、strictMcpConfig（严格 MCP 配置校验）、continue（以新提示继续，区别于 resume）、permissionMode: 'plan'（用于规划工作流的新权限模式）。
【核心 Query API】签名：query(prompt: string | AsyncIterable<SDKUserMessage>, options?: Options) -> AsyncGenerator<SDKMessage>。关键选项包括 outputFormat、settingSources（'user'|'project'|'local'）、canUseTool、agents、mcpServers、permissionMode（'default'|'acceptEdits'|'bypassPermissions'|'plan'）、betas、sandbox、enableFileCheckpointing、systemPrompt。扩展上下文（100 万 token）通过 betas: ['context-1m-2025-08-07'] 启用。systemPrompt 支持两种形式：简单字符串，或带 preset 的对象（type: 'preset'，preset: 'claude_code'，append 追加内容），后者在保留 Claude Code 默认行为基础上追加自定义内容。
【工具集成与 MCP】工具控制包括 allowedTools（白名单，优先）、disallowedTools（黑名单）、canUseTool（自定义权限回调）。内置工具：Read、Write、Edit、Bash、Grep、Glob、WebSearch、WebFetch、Task、NotebookEdit、BashOutput、KillBash、ListMcpResources、ReadMcpResource、AskUserQuestion。AskUserQuestion（v0.1.71+）用于执行期间与用户交互，在消息流中以 tool_call 形式出现，可用于澄清需求、破坏性操作前获取批准、呈现选项供选择。工具配置（v0.1.57+）支持三种形式：字符串数组精确白名单、空数组禁用全部工具、对象形式 preset（claude_code）。MCP 服务器支持进程内（createSdkMcpServer() 与 tool() 定义）与外部（stdio、HTTP、SSE 传输）。工具定义签名为 tool(name, description, zodSchema, handler)，handler 返回 { content: [{ type: "text", text: "..." }], isError?: boolean }。stdio 外部服务器通过 command、args、env 配置；HTTP/SSE 通过 url 与 headers 配置。MCP 工具命名约定为 mcp__<server-name>__<tool-name>，服务器名与工具名必须匹配配置，使用双下划线分隔，并需包含在 allowedTools 中。
【子智能体编排】AgentDefinition 类型包含：description（何时使用该智能体）、prompt（系统提示）、tools（可选允许工具，省略则继承主智能体）、model（'sonnet'|'opus'|'haiku'|'inherit'）、skills（v0.2.10+ 加载的技能）、maxTurns（v0.2.10+ 最大轮数）。使用示例如定义 security-checker，配置 description、prompt、tools、model、skills 与 maxTurns。资料标注已知问题（Issue #132）：父智能体停止时子智能体不会停止，会作为孤儿进程继续运行，可能导致资源泄漏、父停止后继续执行工具、递归场景下 RAM 内存溢出（Claude Code Issue #4850）。规避方式是在 Stop 钩子中实现清理。增强跟踪方面 Issue #142 提议自动终止。
【会话管理】选项包括 resume（sessionId 继续先前会话）、forkSession: true（从会话创建新分支）、continue（以新提示恢复，区别于 resume）。会话分叉可在不修改原会话的情况下探索替代方案。会话 ID 可从响应中 type 为 system 且 subtype 为 init 的 message.session_id 捕获。V2 会话 API（预览，v0.1.54+）提供更简单的多轮对话模式，导入 unstable_v2_createSession、unstable_v2_resumeSession、unstable_v2_prompt；注意 V2 API 带 unstable_ 前缀，.receive() 方法在 v0.1.72 更名为 .stream()。
【权限控制】权限模式类型为 "default"|"acceptEdits"|"bypassPermissions"|"plan"：default 为标准检查，acceptEdits 自动批准文件编辑，bypassPermissions 跳过所有检查（仅限 CI/CD），plan 为规划模式（v0.1.45+）。canUseTool 回调签名 (toolName, input) => Promise<PermissionDecision>，决策为 { behavior: "allow" }、{ behavior: "deny"; message? } 或 { behavior: "ask"; message? }。示例包括阻止文件写入、对敏感路径要求确认、记录所有工具使用等。
【沙箱设置】SandboxSettings 类型包含 enabled、autoAllowBashIfSandboxed（默认 false）、excludedCommands、allowUnsandboxedCommands（默认 false）、network（NetworkSandboxSettings，含 enabled 与 proxyUrl）、ignoreViolations。用于为 Bash 命令提供沙箱化执行。资料建议在生产环境处理不可信输入的智能体中使用沙箱。
【文件检查点】通过 enableFileCheckpointing: true 启用文件状态快照，可从响应中 user 类型且带 uuid 的消息获取用户消息 UUID，并在 Query 对象上调用 rewindFiles(userMessageUuid) 回滚文件改动。资料列举的用例包括撤销失败的重构、A/B 测试代码更改、安全探索替代方案（该段资料文本在此处截断）。