---
title: "子智能体"
description: "1.0：归因、所有权、嵌套、并行执行、状态与终止。"
---

> 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.

# 子智能体

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

完整的概念说明、示例与兼容性讨论见[子智能体（概念）](https://ag-ui.ndjp.net/concepts/subagents/)。本页给出规范层面的规则。

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

Source: https://ag-ui.ndjp.net/spec/1-0/events/subagents/index.mdx
