Agent SDK 核心概念

本页概览 Agent SDK 的核心概念。官方文档为每个主题都有专页和完整的 Python、TypeScript 代码示例，下面每节末尾点明了该读哪一页。

智能体循环

启动智能体时，SDK 运行的是驱动 Claude Code 的同一套执行循环：Claude 评估你的提示，调用工具采取行动，收到结果，重复直到任务完成。每个会话遵循同一个周期：

1. 接收提示：Claude 收到你的提示，连同系统提示、工具定义和对话历史；SDK 产出一条 subtype 为 "init"、含会话元数据的 SystemMessage
2. 评估并响应：Claude 评估当前状态，决定怎么继续：可能回复文字、请求一个或多个工具调用，或两者兼有；SDK 产出一个或多个 AssistantMessage
3. 执行工具：SDK 运行每个请求的工具并收集结果，每组结果反馈给 Claude 做下一次决定；你可以用 Hook 在工具运行前后拦截、修改或阻止调用
4. 重复：第 2 和 3 步重复，每个完整周期是一个回合（turn），直到 Claude 产出一个没有工具调用的回复
5. 返回结果：SDK 产出最终的 AssistantMessage，再跟一个含最终文本、token 用量、成本和会话 ID 的 ResultMessage

简单问题可能一两回合就够，复杂任务可能跨很多回合串起几十次工具调用。可以用 max_turns / maxTurns 限制循环（只计工具使用回合），或用 max_budget_usd / maxBudgetUsd 按花费封顶；对生产智能体，设一个预算是好的默认做法。消息有五种核心类型：SystemMessage（会话生命周期事件，如 init、compact_boundary）、AssistantMessage、UserMessage（工具结果）、StreamEvent（部分流式事件）和 ResultMessage。

会话

会话保存智能体的对话历史，让你能跨交流保持上下文，之后继续、恢复或分叉：继续（continue）接着最近的会话，恢复（resume）按会话 ID 回到特定会话，分叉（fork）从一个会话复制出新的分支。会话 ID 在每次运行的 ResultMessage 里返回；会话转录也可以镜像到你自己的对象存储或数据库。

权限

控制智能体怎么使用工具：用权限模式（default、acceptEdits、plan、auto、dontAsk、bypassPermissions）、Hook 和声明式的 allow/deny 规则，与 Claude Code 里的权限系统一致。需要把批准请求和澄清问题交给你的用户时，用 canUseTool 回调把决定返回给 SDK。

Hooks、MCP、子智能体、自定义工具

• Hooks：在智能体执行的关键点拦截并定制行为，与 Claude Code 的 Hook 事件对应
• MCP：配置 MCP 服务器扩展智能体，覆盖传输类型、面向大量工具的工具搜索等
• 子智能体：定义并调用子智能体，隔离上下文、并行运行并应用专门的指令
• 自定义工具：用 SDK 的进程内 MCP 服务器定义自定义工具，让 Claude 调用你的函数或你的 API
• 结构化输出：用 JSON Schema、Zod 或 Pydantic 从智能体工作流返回经过验证的 JSON

在生产中运行

主题还包括：流式输出与流式输入、Skill 和插件、成本与用量追踪、文件检查点、OpenTelemetry 可观测性、托管与安全部署（子进程架构、会话持久化、扩展、多租户和隔离、凭据管理）。官方 SDK 参考页（TypeScript 和 Python）列出了所有函数、类型和类。