跳到主要内容

子智能体(Subagents)

把运行的输出归因到产生它的子智能体,包括生命周期、嵌套、并发与兼容性。

许多智能体框架允许智能体把工作委派给子智能体——主管分派研究任务、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
end

SUBAGENT_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 按消息归因,因此只有第一个所有者保留

另见

  • 事件参考——完整事件目录,包括子智能体事件
  • 消息——归因如何出现在消息上
  • 状态管理——为什么状态是运行作用域的

Type to search…

↑↓ navigate↵ selectEsc close