---
title: "子智能体（Subagents）"
description: "把运行的输出归因到产生它的子智能体，包括生命周期、嵌套、并发与兼容性。"
---

> Documentation Index
> Fetch the complete documentation index at: https://ag-ui.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 子智能体（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 构建上，值含义相同——只是名称变了。

## 生命周期事件

三个事件界定子智能体的活动。

```text
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）

子智能体可在任务中途暂停等待外部输入——例如其内部发起的人工审批。此时运行以中断结果结束（见[中断](https://ag-ui.ndjp.net/concepts/interrupts/)），并且由于每个已启动的子智能体都必须在 `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`：

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

## 另见

- [事件参考](https://ag-ui.ndjp.net/reference/events/)——完整事件目录，包括子智能体事件
- [消息](https://ag-ui.ndjp.net/concepts/messages/)——归因如何出现在消息上
- [状态管理](https://ag-ui.ndjp.net/concepts/state/)——为什么状态是运行作用域的

Source: https://ag-ui.ndjp.net/concepts/subagents/index.mdx
