跳到主要内容

子智能体

1.0:归因、所有权、嵌套、并行执行、状态与终止。

框架可以把工作委派给子智能体。对前端而言,这一切以一条事件流到达;没有额外信息就无法分辨谁产生了哪条消息。子智能体支持解决这一点:把事件归因到产生它的调用,并报告调用何时开始与停止。它不编排、调度或定义子智能体——那属于框架。

完整的概念说明、示例与兼容性讨论见子智能体(概念)。本页给出规范层面的规则。

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 在来自不同子智能体的并行工具调用上会丢失第二个所有者。

Type to search…

↑↓ navigate↵ selectEsc close