框架可以把工作委派给子智能体。对前端而言,这一切以一条事件流到达;没有额外信息就无法分辨谁产生了哪条消息。子智能体支持解决这一点:把事件归因到产生它的调用,并报告调用何时开始与停止。它不编排、调度或定义子智能体——那属于框架。
完整的概念说明、示例与兼容性讨论见子智能体(概念)。本页给出规范层面的规则。
subagentRunId
subagentRunId是子智能体一次调用的不透明句柄,不是可复用的定义名,也不是名称。同一子智能体的两次调用携带两个不同的值。- 与顶层的对称:
agentId对应子智能体的name(可复用类型);runId对应subagentRunId(一次调用的生命周期)。 - 按
subagentRunId键控临时 UI 状态(可折叠分组、加载指示、进度行)。不要按它持久化并期望在后续运行中有意义。 - 唯一例外:以
outcome: { type: "suspended" }结束的子智能体 MAY 在恢复运行时复用其 id;客户端 MUST 把后续SUBAGENT_STARTED视为延续,绝不渲染重复项。
生命周期事件
SUBAGENT_STARTED
| 属性 | 说明 |
|---|---|
subagentRunId |
本次调用的不透明 id。必填 |
name |
子智能体声明的类型或名称,用于显示。必填 |
description |
可选的人类可读描述 |
parentSubagentRunId |
可选——嵌套时的外层子智能体 |
parentToolCallId |
可选——生成该子智能体的工具调用 |
parentMessageId |
可选——持有该工具调用的消息 |
parentToolCallId 与 parentMessageId 服务于 agents-as-tools 模式,使客户端无需检查 rawEvent 就能把子智能体输出渲染在工具调用卡片内。
SUBAGENT_FINISHED
| 属性 | 说明 |
|---|---|
subagentRunId |
与开启时一致。必填 |
result |
可选的完成载荷,镜像 RunFinished.result |
outcome |
可选类型化结果:{ type: "success" } 或 { type: "suspended", interruptIds?: [...] }。省略表示成功 |
挂起(Suspension):子智能体可在任务中途暂停等待外部输入。此时运行以中断结果结束;由于每个已启动的子智能体都必须在 RunFinished 前关闭,暂停的子智能体仍发射 SUBAGENT_FINISHED,但带 outcome: { type: "suspended" },让 UI 渲染“等待中”。interruptIds 命名该子智能体直接拥有的运行级中断;当祖先因子孙中断而挂起时可为空或省略。
挂起是 subagentRunId 唯一可能有意跨运行的情形:
- 客户端 MUST 接受后续运行复用挂起调用 id 的
SubagentStarted,视为延续(waiting → running),绝不渲染重复。 - 生产者 SHOULD 在能关联时复用 id(LangGraph 集成从 checkpoint 任务身份派生 id,可跨越暂停)。
- 无法关联的生产者生成新 id,这是合法的;客户端的等待状态通过挂起结果的
interruptIds与它自己发送的 resume 条目解除。
SUBAGENT_ERROR
| 属性 | 说明 |
|---|---|
subagentRunId |
与开启时一致。必填 |
message |
人类可读错误信息。必填 |
code |
可选错误码 |
归因
大多数事件可携带可选的 subagentRunId 表示谁产生了它。没有该字段的事件属于父智能体。归因是增量式的:从不设置该字段的流与子智能体出现之前完全一样。
归因可独立存在:生产者可以只给事件打标签而从不发射生命周期事件。客户端必须接受从未被宣告过的标识符。
可携带归因:文本消息族、工具调用族、活动事件、推理族、步骤事件、状态事件、RAW/CUSTOM。
不能携带:RUN_STARTED、RUN_FINISHED、RUN_ERROR(描述整个运行),以及 MESSAGES_SNAPSHOT(改为在每条消息上携带归因)。
归因是来源,不是所有权
STATE_SNAPSHOT/STATE_DELTA 上的归因记录哪个子智能体产生了更新,并不意味着子智能体拥有自己的状态。AG-UI 状态是运行作用域的:一次运行只有一份状态文档,带归因的快照或增量仍应用于该文档。
不存在按子智能体划分的状态。 若给快照加归因并期望父状态不受影响,它不会——快照会像任何快照一样替换运行状态。需要隔离时,在运行状态内使用不同的 key。
生产者没有义务归因状态;LangGraph 集成在子智能体活动期间不发射状态,因为其状态是一份共享文档,委派中途的快照会携带部分视图。这是合理的生产者侧选择。
归因转移到消息
当归因事件创建消息时,subagentRunId 转移到该消息上,使渲染层无需回放事件流就能按子智能体分组会话,并在轮次与快照之间保持。
工具结果携带自己的归因
TOOL_CALL_RESULT 独立于它所回应的调用进行归因:执行工具调用的一方可能与请求它的子智能体不同。前端执行的工具、或主管代表子智能体执行的调用,都会产生归属不同于调用方的结果。继承调用方归因会误报这些情况。
嵌套与并发
parentSubagentRunId把子级链接到外层子智能体;没有父链接的子智能体直接属于该运行。- 子智能体并发运行,事件会交错,归因是唯一区分手段。
- 两个子智能体可能同时拥有打开的文本消息;客户端必须独立跟踪每条。
- 子智能体的
SUBAGENT_FINISHED只关闭该子智能体自己的开放流,绝不关闭兄弟或父级的。 - 父级可能先于子级完成;
parentSubagentRunId因而可能指向已完成的子智能体,这是合法的。
并发与 chunk 简写
TextMessageChunk/ToolCallChunk/ReasoningMessageChunk 中省略 id 的 chunk 表示“与上一个相同”;在并发下,“上一个”只在每个子智能体内有意义。既无 id 也无 subagentRunId 的 chunk,若父级有该类型的开放流则解析到父级流,否则解析到该类型唯一的开放流。多个子智能体的流都可能认领且无一是父级时,客户端 MUST 以歧义拒绝。
并发流式输出时,为每个 chunk 添加归因,或重复 id。
客户端执行的规则
SUBAGENT_FINISHED/SUBAGENT_ERROR必须命名当前活跃的子智能体;同一运行内子智能体不会被启动两次。生命周期事件携带 schema 必填字段(三者都有subagentRunId,SUBAGENT_STARTED有name,SUBAGENT_ERROR有message)。- 延续与关闭事件必须与其实体创建时的所有者一致:一个子智能体打开的文本消息不能由另一个子智能体继续。
- 所有权也由回放历史确立:
MESSAGES_SNAPSHOT中的消息归其subagentRunId所有(缺省表示父级);后续事件以不同所有者重开该 id 会被拒绝。 - 工具调用属于其
parentMessageId命名的助手消息;ToolCall本身不携带归因字段,因此TOOL_CALL_START的显式归因与消息所有者不一致时会被拒绝;未打标签的工具调用继承父消息所有者。 - 步骤作用域限于打开它的智能体:子智能体不能关闭父级或兄弟的步骤。
- 每个已启动的子智能体都在
RUN_FINISHED前关闭。
有意不强制:
- 用于归因的
subagentRunId不必已被启动(无生命周期事件归因是受支持模式)。 parentSubagentRunId只需命名已启动的子智能体,不必仍活跃。- 归因到已完成子智能体的事件会被接受。
- 关闭只需在
RUN_FINISHED前,而非RUN_ERROR前——未关闭的子智能体是中止运行的预期形态。 - 带归因的状态事件会被接受。
兼容性
旧客户端会直接拒绝生命周期事件:
subagentRunId是未知字段(可容忍),但SUBAGENT_STARTED/FINISHED/ERROR是未知事件类型,早于子智能体支持的客户端会在解码时失败。若部分消费者较旧,生产者不得向它们发射生命周期事件。
新智能体 → 旧客户端:发射生命周期事件必须是生产者侧可选开启,默认关闭。LangGraph 集成的开关是 subagent_visibility:"inline"(默认,无生命周期、无 subagentRunId)、"attributed"(完整表面)、"hidden"(完全抑制子智能体内部流)。仅归因是更安全的中间步骤。
新客户端 → 旧智能体:TypeScript 客户端基于智能体报告的版本插入 shim,双向生效——从出站输入剥离 subagentRunId,并从入站流丢弃子智能体事件与归因。位于 shim 之后的消费者会看到扁平化、无归因的流。
SDK 支持
| SDK | 状态 |
|---|---|
| TypeScript | 事件、归因、验证、订阅者 hook、protobuf |
| Python | 事件与归因 |
| .NET | 事件、归因、验证、protobuf |
已知限制:protobuf 只覆盖 36 种事件类型中的 19 种,若干携带归因的类型(TOOL_CALL_RESULT、推理族、活动事件)与 chunk 简写无法编码;.NET 在来自不同子智能体的并行工具调用上会丢失第二个所有者。