许多智能体框架允许智能体把工作委派给子智能体——主管分派研究任务、agents-as-tools 模式中工具调用本身就是嵌套智能体、规划器并行分发子任务。
对前端而言,这一切都以一条事件流到达。没有额外信息时,无法分辨某条消息由哪个子智能体产生,于是三个并发研究者会渲染成一堵无差别的文本墙。
AG-UI 的子智能体支持恰好解决这个问题,且不多做:它把每个事件归因(attribute)到产生它的子智能体,并报告子智能体何时开始与停止。它不负责编排、调度或定义子智能体——那完全属于框架。
subagentRunId 标识一次调用,而非一个定义
这是最重要、也最容易搞错的一点。
subagentRunId 是子智能体一次调用的不透明句柄。同一个子智能体运行两次会得到两个不同的值。它不是可复用子智能体定义的稳定标识,也不是名称。
与顶层运行的对称性有助于理解:
| 顶层 | 子智能体 |
|---|---|
agentId —— 已配置、可复用的智能体 |
子智能体的 name —— 可复用的子智能体类型 |
runId —— 一次调用的生命周期 |
subagentRunId —— 一次嵌套调用的生命周期 |
因此:
- 应该用
subagentRunId作为临时 UI 状态的 key——可折叠分组、加载指示器、进度行 - 不要按
subagentRunId持久化任何内容并期望它在后续运行中仍有意义,也不要把同一子智能体的两次调用视为共享值。表示“这是哪类子智能体”时使用name - 一个例外:以
outcome: { type: "suspended" }结束的子智能体可能在恢复运行时复用其 id。能关联恢复工作与挂起调用的生产者应这样做,客户端必须把后续SubagentStarted视为延续(waiting → running),而不是重复
该字段在预发布版本中叫
subagentId。重命名是因为旧名暗示了可复用定义。若你在仍使用subagentId的 canary 构建上,值含义相同——只是名称变了。
生命周期事件
三个事件界定子智能体的活动。
Agent → Client: SUBAGENT_STARTED
Agent → Client: TEXT_MESSAGE_* / TOOL_CALL_*(带归因)
alt 成功
Agent → Client: SUBAGENT_FINISHED
else 失败
Agent → Client: SUBAGENT_ERROR
endSUBAGENT_STARTED
宣告新的子智能体调用,并给出 UI 可显示的名称。
| 属性 | 说明 |
|---|---|
subagentRunId |
本次调用的不透明 id。必填 |
name |
子智能体声明的类型或名称,用于显示。必填 |
description |
可选的人类可读描述 |
parentSubagentRunId |
可选——子智能体嵌套时的外层子智能体 |
parentToolCallId |
可选——生成该子智能体的工具调用 |
parentMessageId |
可选——持有该工具调用的消息 |
parentToolCallId 与 parentMessageId 服务于 agents-as-tools 模式,让客户端无需检查 rawEvent 就能把子智能体与创建它的调用关联起来(例如把子智能体输出渲染在工具调用卡片内)。
SUBAGENT_FINISHED
关闭子智能体在本次运行中的流片段。
| 属性 | 说明 |
|---|---|
subagentRunId |
与 SUBAGENT_STARTED 中的 id 一致。必填 |
result |
可选的完成载荷,镜像 RunFinished.result |
outcome |
可选类型化结果,镜像 RunFinished.outcome:{ type: "success" } 或 { type: "suspended", interruptIds?: [...] }。省略表示成功 |
挂起(Suspension)
子智能体可在任务中途暂停等待外部输入——例如其内部发起的人工审批。此时运行以中断结果结束(见中断),并且由于每个已启动的子智能体都必须在 RunFinished 前关闭,暂停的子智能体仍会发射 SUBAGENT_FINISHED——但带 outcome: { type: "suspended" },让 UI 渲染“等待中”而非“已完成”。
interruptIds 命名该子智能体直接拥有的运行级中断(每个此类 Interrupt 也带 subagentRunId 反向引用);当祖先因子孙中断而挂起时,它可为空或省略。
挂起是 subagentRunId 唯一可能有意跨运行的情况,两侧义务不同:
- 客户端必须接受后续运行复用挂起调用 id 的
SubagentStarted,并视为延续——把现有分组从 waiting 转回 running,绝不渲染重复项 - 生产者应尽可能复用 id。LangGraph 集成会这样做:其 id 派生自 checkpoint 任务身份,可跨越暂停。复用让客户端无缝继续分组
- 无法关联的生产者会生成新 id,这也是合法的。客户端的等待状态不会悬空:挂起结果的
interruptIds与客户端自己发送的 resume 条目可标识哪些审批已被回答,因此即使旧 id 下没有延续到达,等待徽章也能据此解除
SUBAGENT_ERROR
标记子智能体调用失败。
| 属性 | 说明 |
|---|---|
subagentRunId |
与 SUBAGENT_STARTED 中的 id 一致。必填 |
message |
人类可读错误信息。必填 |
code |
可选错误码 |
归因
除生命周期事件外,大多数事件都可携带可选的 subagentRunId 表示谁产生了它。
没有 subagentRunId 的事件属于父智能体。归因是增量式的:从不设置该字段的流与子智能体出现之前完全一样。
归因也可独立存在。生产者可以只给事件打标签而从不发射 SUBAGENT_STARTED/SUBAGENT_FINISHED——足以让 UI 按生产者分组,而无需承诺报告生命周期。客户端必须接受从未被宣告过的标识符。
可携带归因的事件:文本消息族、工具调用族、活动事件、推理族、步骤事件、状态事件,以及 RAW/CUSTOM。
不能携带的事件:RUN_STARTED、RUN_FINISHED、RUN_ERROR——它们描述整个运行;以及 MESSAGES_SNAPSHOT,它改为在每条消息上携带归因,因为一个快照混合了多个生产者的消息。
归因是来源,不是所有权
StateSnapshot 与 StateDelta 是可归因的。其上的归因记录哪个子智能体产生了更新——并不意味着子智能体拥有自己的状态。AG-UI 状态是运行作用域的:一次运行只有一份状态文档,带归因的快照或增量仍应用于那一份文档。标签是你可以呈现的来源信息(“研究者更新了共享草稿本”),而不是独立作用域。
不存在按子智能体划分的状态。 若你给快照加归因并期望父状态不受影响,它不会——快照会像任何快照一样替换运行状态。若需隔离子智能体数据,请在运行状态内使用不同的 key。
注意生产者没有义务归因状态。有些并不这样做:例如 LangGraph 集成在子智能体活动期间不发射状态,因为其状态是一份共享文档,委派中途的快照会携带部分视图。这是合理的生产者侧选择,不是协议要求。
归因转移到消息上
当归因事件创建消息时,subagentRunId 会转移到该消息上。这使渲染层无需回放事件流就能按子智能体分组会话——消息本身携带其来源,并在轮次与快照之间保持。
工具结果携带自己的归因
ToolCallResult 独立于它所回应的调用进行归因,这是有意为之:执行工具调用的一方可能与请求它的子智能体不同。前端执行的工具,或主管代表子智能体执行的调用,都会产生归属不同于调用方的结果。继承调用方归因会误报这些情况,因此每个结果声明自己的归因。
嵌套与并发
子智能体可以嵌套。SubagentStarted 上的 parentSubagentRunId 把子级链接到其外层子智能体;没有父链接的子智能体直接属于该运行。
子智能体也会并发运行,这正是区分“可用实现”与“看似合理实现”的场景。当三个子智能体同时流式输出时,它们的事件会交错,只有归因能区分它们。特别是:
- 两个子智能体可能同时拥有打开的文本消息。客户端必须独立跟踪每条,而不能假设同时只有一条打开消息
- 子智能体的
SubagentFinished只关闭该子智能体自己的开放流,绝不关闭兄弟或父级的 - 父级可能先于子级完成。因此
parentSubagentRunId可能指向已完成的子智能体,这是合法的
并发与 chunk 简写
TextMessageChunk/ToolCallChunk/ReasoningMessageChunk 事件是简写:客户端合成 START/CONTENT/END 边界,省略 id 的 chunk 表示“与上一个相同”。在并发下,“上一个”只在每个子智能体内有意义——因此简写在该发送子智能体自己的流内解析,而不是跨运行。
对生产者的一条实际规则是:既无 id 也无 subagentRunId 的 chunk,若父级有该类型的开放流则解析到父级流(未打标签即父级),否则解析到该类型唯一的开放流。当多个子智能体的流都可能认领它时,客户端无法解析,会直接拒绝而不是猜测。
并发流式输出时,为每个 chunk 添加归因,或重复 id。
客户端会执行的规则
以下每条规则都以事件存在为前提。仅归因本身就是完整、合法的子智能体支持用法,因此这里没有任何规则要求流必须发送生命周期事件。
SubagentFinished与SubagentError必须命名当前活跃的子智能体,且同一运行内子智能体不会被启动两次。生命周期事件携带 schema 必填字段(三者都有subagentRunId,SubagentStarted有name,SubagentError有message)——即使进程内生产者绕过 wire 级 schema 验证,客户端也会执行- 延续与关闭事件必须与其实体创建时的所有者一致。一个子智能体打开的文本消息不能由另一个子智能体继续
- 所有权也由回放历史确立:
MessagesSnapshot中的消息(及其携带的每个工具调用)归其subagentRunId所有——缺省表示父级——后续事件以不同所有者重新打开该 id 会被拒绝,与冲突的第二次打开完全相同 - 工具调用属于其
parentMessageId命名的助手消息。ToolCall本身不携带归因字段,因此ToolCallStart的显式subagentRunId与该消息所有者不一致时无法忠实表示,会被拒绝;未打标签的工具调用继承父消息所有者 - 步骤作用域限于打开它的智能体:子智能体不能关闭父级或兄弟的步骤
- 每个已启动的子智能体都在
RunFinished前关闭
以下事项有意不强制,因为协议不要求:
- 用于归因的
subagentRunId不必已被启动。无生命周期事件的归因是受支持模式,客户端不得把未宣告的标识符视为错误。UI 应按看到的任何 id 分组,没有name时回退到 id parentSubagentRunId只需命名一个已启动的子智能体,而非仍在活跃的——父级早于子级完成是合法的- 归因到已完成子智能体的事件会被接受。延续事件即使在其完成后仍携带所属子智能体的标签
- 关闭只需在
RunFinished前,而非RunError前。未关闭的子智能体是中止运行的预期形态 - 带归因的状态事件会被接受。生产者选择在委派中途不发射它们是生产者侧决定,不是规则
兼容性
旧客户端会直接拒绝生命周期事件。 归因是增量且安全的——
subagentRunId是未知字段,客户端会容忍——但SubagentStarted、SubagentFinished与SubagentError是未知事件类型,早于子智能体支持的客户端会在解码时、任何应用代码运行前失败。客户端无法过滤它们。若部分消费者早于子智能体支持,生产者不得向它们发射生命周期事件。
两个方向并不对称。
新智能体对接旧客户端
生命周期事件会破坏兼容,因此发射它们必须是生产者侧可选开启。支持子智能体的集成通常暴露开关,默认关闭——LangGraph 集成中是 subagent_visibility:
agent = LangGraphAgent(
name="my-agent",
graph=graph,
subagent_visibility="attributed",
)该值命名客户端看到的内容:
"inline"(默认):不发射生命周期事件,也不发射subagentRunId,子智能体相关内容不会进入MessagesSnapshot——流与子智能体支持出现之前完全一样,包括子智能体自己的文本作为父级工作到达"attributed":发射本文描述的完整表面"hidden":完全抑制子智能体内部流:客户端只看到父级生成它的工具调用、其结果,以及父级自己的回复
当所有消费者都足够新时再开启 "attributed"。仅归因是更安全的中间步骤,因为不认识该字段的客户端会忽略它。
新客户端对接旧智能体
自动处理。TypeScript 客户端会基于智能体报告的版本插入兼容 shim,并在两个方向生效:
- 客户端 → 智能体:shim 从出站输入消息中剥离
subagentRunId,使旧智能体不会收到无法解释的归因。这是关键的一半:回放的消息历史或新客户端写入的存储线程确实可能携带该字段 - 智能体 → 客户端:shim 还会丢弃
SubagentStarted、SubagentFinished、SubagentError,并从其余每个事件(包括MessagesSnapshot消息与RunStarted输入回显)中剥离subagentRunId。这是防御性规范化而非翻译
第二个方向的后果值得了解:位于该 shim 之后的消费者会看到扁平化、无归因的流,即使上游确实做了归因。若希望归因到达 UI,智能体必须报告支持子智能体的版本。
SDK 支持
| SDK | 状态 |
|---|---|
| TypeScript | 事件、归因、验证、订阅者 hook、protobuf |
| Python | 事件与归因 |
| .NET | 事件、归因、验证、protobuf |
二进制 protobuf 传输在 TypeScript 与 .NET 上都携带子智能体归因,且由同一 schema 生成,因此带归因的流可跨语言往返。
已知限制
- Protobuf 只覆盖事件类型的子集:36 种事件类型中有 19 种有 protobuf 映射(三个子智能体事件、文本消息、工具调用 start/args/end、状态、步骤与运行族,以及
MessagesSnapshot、Raw、Custom)。其余根本无法编码——其中若干携带归因:ToolCallResult、推理族与活动事件。chunk 简写也不可编码 - .NET 在来自不同子智能体的并行工具调用上会丢失第二个所有者:把运行转换为
Microsoft.Extensions.AI消息时,连续工具调用会合并为一条ChatMessage,而 AG-UI 按消息归因,因此只有第一个所有者保留