Agent SDK 概览
把 Claude Code 当作库来构建生产级 AI 智能体：与 CLI、Client SDK、Managed Agents 的区别，以及内置的能力。
智能体是通过规划自己的步骤、并调用读文件、运行命令或编辑代码的工具来完成任务的应用。Agent SDK 把驱动 Claude Code 的同一套工具、智能体循环和上下文管理，以 Python 和 TypeScript 库的形式交给你，让你把这样的智能体嵌入自己的应用。
和其他 Claude 工具对比
| 你想要 | 用 | 你得到什么 |
|---|---|---|
| 把 Claude Code 的智能体嵌进你自己的 Python 或 TypeScript 应用，在你运营的进程里运行 | Agent SDK | 一个运行 Claude Code 二进制的库，带有 Claude Code 的能力（内置工具、Hook、子智能体、MCP、权限、会话等） |
| 在终端里做交互式开发或一次性任务 | Claude Code CLI | 为日常交互使用构建的终端界面 |
| 从自己的代码直接调用 Claude API | Client SDK | 直接访问 Claude API，由你自己写工具循环 |
| 让 Anthropic 托管智能体，通过 Claude API 配置 | Managed Agents | 托管的智能体运行环境，会话保存在 Anthropic 的基础设施里 |
想从 Python 或 TypeScript 之外的语言驱动同一个智能体循环，可以用 -p 标志和 --output-format json 把 CLI 作为子进程运行。
SDK 里有哪些能力
| 能力 | 作用 |
|---|---|
| 内置工具 | 读、写、编辑文件，运行命令，搜索网络 |
| Hooks | 在智能体生命周期的关键节点运行自定义代码 |
| 子智能体 | 为聚焦的子任务派生专门的智能体 |
| MCP | 通过 Model Context Protocol 连接外部工具和数据源 |
| 权限 | 控制哪些工具自动运行、哪些需要批准 |
| 会话 | 跨交流保持上下文，之后恢复或分叉 |
| Skill、命令和记忆 | 与 Claude Code 一样，从项目的 .claude/ 和 ~/.claude/ 自动加载 |
| 插件 | 打包 Skill、智能体、Hook 和 MCP 服务器，并按本地路径加载 |
注意事项
- 除非事先获得批准，Anthropic 不允许第三方开发者为其产品（包括基于 Claude Agent SDK 构建的智能体）提供 claude.ai 登录或其速率限制；请使用 API Key 认证（或支持的云厂商认证）
- 品牌使用：集成 SDK 的合作伙伴使用 Claude 品牌是可选的。允许的叫法包括「Claude Agent」「{你的智能体名} Powered by Claude」；不允许使用「Claude Code」或「Claude Code Agent」，也不能使用模仿 Claude Code 的 ASCII 图案或视觉元素，你的产品要保持自己的品牌
- 使用受 Anthropic 商业服务条款约束
In this section
- 快速上手安装 Agent SDK、设置 API Key（或第三方提供商），写一个会自己找 bug 并修复的智能体（Python 或 TypeScript），运行、换提示词、定制工具与系统提示。
- 核心概念智能体循环与消息类型、会话（继续、恢复、分叉）、权限模式、Hook、MCP、子智能体、自定义工具和结构化输出等主题的概览。
- 托管 Agent SDK在生产环境部署 Agent SDK：子进程架构、本地磁盘上的状态、四种会话模式（临时、长时间运行、混合、多智能体容器）、容器供给（沙盒、运行时依赖、资源、网络）、会话持久化、可观测性、认证与密钥、扩展与并发、成本、多租户隔离、已知限制与部署排障。
- 安全部署 AI 智能体用隔离、凭据管理和网络控制保护 Claude Code 与 Agent SDK 部署：威胁模型、内置安全特性、安全原则、隔离技术（沙盒运行时、容器、gVisor、虚拟机、云部署）、凭据代理模式、文件系统配置。
- 用 hooks 拦截和控制智能体行为在 Agent SDK 里用回调函数拦截智能体事件：hooks 的工作方式、全部可用事件（Python/TypeScript 支持情况）、配置与匹配器、回调输入输出、异步输出，以及修改输入、阻止工具、自动批准、多 hook、子智能体跟踪、HTTP 请求、Slack 通知等示例与常见问题。
- SDK 里的子智能体在 Agent SDK 里定义和调用子智能体：编程方式与文件系统方式、AgentDefinition 字段、子智能体继承什么、自动与显式调用、动态配置、检测调用、恢复子智能体、工具限制、限制深度并发与花费、动态工作流和排障。
- 从智能体获取结构化输出用 JSON Schema、Zod 或 Pydantic 从智能体工作流返回经过验证的 JSON：outputFormat 配置、类型安全的 schema、TODO 跟踪示例、错误处理（error_max_structured_output_retries）与避免错误的建议。
- 给 Claude 自定义工具用 Agent SDK 的进程内 MCP 服务器定义自定义工具：快速参考、创建与调用工具、添加更多工具、工具注解、控制工具访问、错误处理、返回图片与资源、返回结构化数据，以及单位转换器完整示例。
- 用 MCP 连接外部工具在 Agent SDK 里配置 MCP 服务器：快速开始、在代码里或配置文件里添加、连接时序、允许 MCP 工具、传输类型（stdio、HTTP/SSE、SDK）、工具搜索、认证（环境变量、HTTP 头、OAuth2）、示例与错误处理、排障。
- 跟踪成本与用量在 Agent SDK 里跟踪 token 用量、估算成本并配置提示缓存：用量范围（query 调用、步骤、会话）、流式输入模式、总成本、按步骤和按模型的用量、跨调用累计、失败与崩溃后的恢复、缓存 token 与一小时 TTL。
- 实时流式输出响应在 Agent SDK 里启用部分消息流：StreamEvent 参考、消息流转顺序、流式工具调用、构建流式 UI 示例与已知限制。
- 把会话持久化到外部存储用 SessionStore 适配器把 Agent SDK 的会话记录镜像到你自己的对象存储、键值存储或数据库：SessionStore 接口、快速开始、编写适配器、参考实现与一致性测试、双写架构、从存储恢复、尽力而为的镜像写入、保留与支持范围。
- TypeScript SDK 参考：安装与函数Agent SDK TypeScript 的安装、编译为单文件可执行、/core 入口，以及 query、startup、prewarm、tool、createSdkMcpServer、会话函数、resolveSettings 的完整签名、参数与返回值。
- TypeScript SDK 参考：选项与类型Agent SDK TypeScript 的 Options 全部字段、Query 对象的方法、applyFlagSettings 与 updateSettings、WarmQuery、SpareProcess、各 SDKControl 响应类型、AgentDefinition、SettingSource、PermissionMode、CanUseTool、PermissionResult、ToolConfig、McpServerConfig、SdkPluginConfig。
- TypeScript SDK 参考：消息类型Agent SDK TypeScript 的 SDKMessage 联合类型及 SDKAssistantMessage、SDKUserMessage、SDKResultMessage（含诊断字段、user_message_uuid、startup_failure_reason）、SDKSystemMessage、权限拒绝、上下文用量、消息来源 origin 等的字段说明。
- TypeScript SDK 参考：Hook 类型Agent SDK TypeScript 的 HookEvent、HookCallback、HookCallbackMatcher，每个事件的输入类型（PreToolUse、PostToolUse、Stop、SessionStart、PreModelSwitch 等）以及 HookJSONOutput 的同步与异步输出形状。
- TypeScript SDK 参考：工具与权限类型Agent SDK TypeScript 导出的内置工具输入类型（Agent、Bash、Read、Edit、Grep、Workflow、Task* 等）、工具输出类型，以及 PermissionUpdate、PermissionBehavior、PermissionUpdateDestination、PermissionRuleValue。
- TypeScript SDK 参考：其他类型与沙盒配置Agent SDK TypeScript 的 ModelInfo、McpServerStatus、ModelUsage、Usage、ThinkingConfig、SpawnOptions、各类系统消息（任务、hook 进度、速率限制等）、AbortError，以及 SandboxSettings、网络与文件系统沙盒配置。
- Python SDK 参考：安装、函数与 ClaudeSDKClientAgent SDK Python 的安装、query() 与 ClaudeSDKClient 的选择，query、tool、create_sdk_mcp_server、会话函数的完整签名，以及 ClaudeSDKClient 类的方法与示例（继续对话、流式输入、中断、权限控制）。
- Python SDK 参考：选项与类型Agent SDK Python 的 ClaudeAgentOptions 全部字段、Transport、SdkMcpTool、系统提示类型、SettingSource、AgentDefinition、PermissionMode、EffortLevel、CanUseTool 与权限结果类型、ThinkingConfig、MCP 配置与状态类型、ContextUsageResponse、SdkPluginConfig。
- Python SDK 参考：消息、内容块与错误Agent SDK Python 的 Message 联合类型、UserMessage、AssistantMessage、ResultMessage（含 usage、model_usage 字段）、StreamEvent、RateLimitEvent、后台任务消息、内容块类型以及错误类型（ClaudeSDKError、ProcessError、ResultError 等）。
- Python SDK 参考：Hook 类型Agent SDK Python 的 HookEvent、HookCallback、HookContext、HookMatcher、各事件的 HookInput 类型（PreToolUse、PostToolUse、Stop、PermissionRequest 等）、HookJSONOutput 同步与异步输出，以及完整使用示例。
- Python SDK 参考：工具输入输出、示例与沙盒Agent SDK Python 里内置工具（Agent、Bash、Read、Edit、Grep、Task* 等）的输入输出结构、持续对话界面示例、错误处理示例，以及 SandboxSettings、SandboxNetworkConfig、SandboxIgnoreViolations 与对未沙盒命令的权限回退。