引言

在 AI 代理（Agent）技术快速发展的 2026 年，我们面临一个关键问题：如何让 AI 代理与用户界面进行标准化通信？

每个团队都在构建自己的流式传输方案、状态管理机制和工具调用协议。这种碎片化不仅造成重复开发，更让代理难以在不同应用间复用。AG-UI（Agent-User Interaction Protocol）应运而生，试图成为代理与 UI 之间的"通用语言"。

本文将深入探讨 AG-UI 协议的设计理念、技术规范，以及在实际应用中暴露出的系统性问题 —— 特别是在多代理架构中的子代理渲染缺陷。

一、AG-UI 是什么？

1.1 协议定位

AG-UI（Agent-User Interaction Protocol）是一个开放、轻量级、基于事件的协议，用于标准化 AI 代理与用户界面应用的连接。

在代理协议栈中的定位：

MCP（Model Context Protocol）：为代理提供工具和上下文
A2A（Agent-to-Agent）：代理之间的通信
AG-UI：将代理接入用户应用的桥梁

1.2 核心理念

AG-UI 的设计哲学可以概括为：

"实现一次协议，适配所有客户端"

就像为代理添加"通用翻译器" —— 无需为每个前端应用构建自定义 API，一个 AG-UI 兼容的代理可以与任何兼容客户端协作：

聊天界面
Copilot 助手
自定义 AI 工具
终端应用
协作平台（Slack、Microsoft Teams）

二、AG-UI 核心规范

2.1 架构设计原则

AG-UI 基于以下四个核心原则：

1. 事件驱动通信

代理通过发出标准化事件创建更新流，前端订阅并响应这些事件。

2. 双向交互

不仅是代理向前端推送，前端也可以向代理发送输入、工具调用结果、用户确认等。

3. 灵活兼容性

事件只需"AG-UI-compatible"而非完全匹配格式，降低集成门槛。

4. 传输无关

支持多种传输方式：

HTTP Server-Sent Events (SSE)
HTTP 二进制协议
WebSocket
Webhooks

2.2 客户端-服务器模型

text

┌─────────────────┐         ┌─────────────────┐
│   前端应用       │         │   后端服务       │
│  + AG-UI Client │◄───────►│ AI Agent        │
│                 │         │  + AG-UI Server │
└─────────────────┘         └─────────────────┘
        │                           │
        └───── 协议层接口 ──────────┘
   run(input: RunAgentInput) 
      -> Observable<BaseEvent>

2.3 事件系统（约 16 种标准事件）

AG-UI 定义了约 16 种标准事件类型，所有事件继承自 BaseEvent，包含 type、timestamp 和可选的 rawEvent 字段。

1. 生命周期事件 (Lifecycle Events)

控制代理运行的整体流程：

事件类型	作用	关键字段
`RunStarted`	开始代理运行	`threadId`, `runId`, `parentRunId`, `input`
`RunFinished`	完成运行	`outcome`, `result`
`RunError`	错误终止	`message`, `code`
`StepStarted`	开始执行步骤	`stepName`
`StepFinished`	完成步骤	`stepName`

RunStarted 示例：

json

{
  "type": "RunStarted",
  "timestamp": "2026-08-13T10:00:00Z",
  "threadId": "thread_abc123",
  "runId": "run_xyz789",
  "parentRunId": "run_parent456",  // 用于子代理链接
  "input": {
    "prompt": "帮我分析这段代码"
  }
}

2. 文本消息事件 (Text Message Events)

流式传输文本内容：

事件类型	作用	关键字段
`TextMessageStart`	初始化新消息	`messageId`, `role`
`TextMessageContent`	流式传输文本块	`messageId`, `delta`
`TextMessageEnd`	完成消息	`messageId`
`TextMessageChunk`	便捷的自动展开器	`messageId`, `role`, `delta`

role 取值：

developer - 系统开发者消息
system - 系统消息
assistant - AI 助手消息
user - 用户消息
tool - 工具返回消息

3. 工具调用事件 (Tool Call Events)

管理工具的调用生命周期：

事件类型	作用	关键字段
`ToolCallStart`	开始工具调用	`toolCallId`, `toolCallName`, `parentMessageId`
`ToolCallArgs`	流式传输参数	`toolCallId`, `delta`
`ToolCallEnd`	完成工具规范	`toolCallId`
`ToolCallResult`	返回工具输出	`messageId`, `toolCallId`, `content`
`ToolCallChunk`	便捷的自动展开器	`toolCallId`, `toolCallName`, `delta`

工具调用流程：

text

ToolCallStart → ToolCallArgs (多次) → ToolCallEnd → ToolCallResult

4. 状态管理事件 (State Management Events)

双向状态同步：

事件类型	作用	关键字段
`StateSnapshot`	完整状态快照	`snapshot`
`StateDelta`	增量更新	`delta` (JSON Patch)
`MessagesSnapshot`	对话历史	`messages`

StateDelta 使用 RFC 6902 JSON Patch：

json

{
  "type": "StateDelta",
  "delta": [
    { "op": "add", "path": "/progress", "value": 50 },
    { "op": "replace", "path": "/status", "value": "processing" }
  ]
}

5. 活动事件 (Activity Events)

在消息之间展示进行中的活动：

事件类型	作用	关键字段
`ActivitySnapshot`	完整活动状态	`messageId`, `activityType`, `content`, `replace`
`ActivityDelta`	增量活动更新	`messageId`, `activityType`, `patch`

activityType 示例： "PLAN", "SEARCH", "THINKING"

6. 推理事件 (Reasoning Events)

展示 LLM 的思维过程（支持隐私保护）：

事件类型	作用
`ReasoningStart`	开始推理
`ReasoningMessageStart`	开始推理消息
`ReasoningMessageContent`	推理内容流
`ReasoningMessageEnd`	完成推理消息
`ReasoningEnd`	结束推理
`ReasoningEncryptedValue`	加密的思维链

7. 特殊事件 (Special Events)

事件类型	作用	关键字段
`Raw`	外部系统事件透传	`event`, `source`
`Custom`	应用特定扩展	`name`, `value`

三、AG-UI 的应用场景

3.1 主要特性

AG-UI 支持以下核心能力：

✅ 实时交互能力

💬 流式传输的实时代理对话
🔄 双向状态同步
🧠 实时上下文增强

✅ UI 与消息

🧩 生成式 UI（Generative UI）
📝 结构化消息支持

✅ 工具与协作

🛠️ 前端工具集成
🧑‍💻 人机协作（Human-in-the-loop）

3.2 生态系统支持

AG-UI 已获得主要 AI 框架和平台的支持：

框架伙伴关系：

✅ LangGraph
✅ CrewAI

第一方支持：

Microsoft Agent Framework
Google ADK (Agent Development Kit)
AWS Strands Agents
Mastra
Pydantic AI
Agno
LlamaIndex
AG2
Claude Managed Agents

客户端实现：

CopilotKit（第一方）
Terminal + Agent
Slack、Microsoft Teams

社区 SDK：

官方：TypeScript、Python、.NET
社区：Kotlin、Golang、Dart、Java、Rust、Ruby、C++

四、暴露出的系统性问题

尽管 AG-UI 设计优雅、生态丰富，但在实际应用中，特别是多代理（Multi-Agent）架构下，暴露出了严重的子代理可观察性缺陷。

4.1 问题发现的时间线

2026 年 5 月 20-22 日，在短短 60 小时内，有 6 个独立 GitHub Issue 都指向了同一个结构性问题：

assistant-ui Issue #3030 - 子代理工具 UI 渲染问题
Zed IDE Discussion #49452 - 数据已流经协议但未渲染
Claude Code 子代理可观察性分析 - 系统性缺陷分析

4.2 核心问题：子代理事件无法正确渲染

问题描述

在多代理编排（Orchestrator）架构中：

text

主代理 (Orchestrator)
  ├─ 调用子代理 A (数据分析)
  │   ├─ 工具调用: fetch_data()
  │   └─ 工具调用: analyze_stats()
  └─ 调用子代理 B (报告生成)
      └─ 工具调用: generate_pdf()

当前协议的理论支持：

RunStarted 包含 parentRunId 字段建立父子关系
所有子代理事件使用相同 threadId 但不同 runId

实际问题：

❌ 缺少明确的子代理范围标识
- 没有专门的 SubAgentStarted / SubAgentFinished 事件
- 只通过 parentRunId 建立链接，前端难以判断事件归属
- 没有"进入子代理"和"退出子代理"的明确边界
❌ 嵌套可视化不清晰
- StepStarted / StepFinished 主要为单个 run 内的步骤设计
- 不适用于子代理的完整生命周期管理
- 前端需要自行维护 runId 的层级关系
❌ 缺少子代理元数据
- 没有子代理的名称、类型、描述等元信息
- 无法在 UI 中清晰展示"当前正在运行哪个子代理"
- stepName 字段不足以描述完整的子代理上下文
❌ 多子代理并行时事件归属模糊
- 当多个子代理同时执行，事件流中只有 runId 区分
- 工具调用 UI 不知道应该渲染在：
  - 子代理消息下方（内联）
  - 主代理对话的一部分
  - 独立的嵌套 UI 区域

来自社区的真实反馈

assistant-ui 开发者 599yongyang 的问题：

"在 assistant-ui 中，当单个代理直接调用工具时，工具 UI 渲染效果良好。但在多代理场景下：

如何将工具调用 UI 与正确的子代理关联？

工具 UI 应该渲染在何处？

如何表示代理层次结构？"

Zed IDE 社区的观察：

"The data is already flowing through the protocol — it's just not rendered." （数据已经流经协议 —— 只是没有渲染。）

Microsoft 的承认：

"In early prototypes, a terminal or a basic chat window is enough. But once agents start handing off to each other, pausing for approvals, or asking follow-up questions, those interfaces fall apart." （早期原型中，终端或基本聊天窗口就够了。但一旦代理开始互相交接、暂停等待批准或提出后续问题，这些界面就崩溃了。）

4.3 更严重的问题：Claude Code 的四种失败模式

根据 yurukusa 的深度分析，子代理问题不仅限于 UI 渲染，还包括：

1. 派遣伪造 (Dispatch Fabrication)

父代理报告已生成子代理并返回结果
但子代理实际上从未运行过
叙述被当作执行证明，没有验证机制

2. 静默停滞 (Silent Stall)

子代理在权限门或交互提示处阻塞
没有信号传播到父 CLI
父代理将工具调用成功视为子代理执行成功的证明
实际上子进程可能已死或无限期等待

3. 缺少监督原语 (Absence of Supervision Primitives)

没有超时、中止或进度监控机制
真实案例：12+ 小时挂起，需要 OS 级强制杀死
操作员没有可访问的控制界面

4. 范围扩展 (Scope Expansion)

子代理返回比请求更广泛的建议
父代理执行这些建议而不重新检查用户的原始授权范围

4.4 问题的根本原因

这不是简单的 bug，而是结构性缺陷：

"主代理界面被视为可观察性原语必须工作的地方，而子代理界面没有继承任何这些原语。"

AG-UI 在设计时主要考虑单代理场景：

parentRunId 只是事后添加的"补丁"
缺少完整的层次结构和可观察性设计
没有考虑监督、超时、状态传播等关键需求

五、协议改进建议

5.1 新增子代理专用事件

建议在协议中正式引入子代理生命周期事件：

typescript

// 子代理启动事件
{
  type: "SubAgentStarted",
  runId: "run_sub_123",
  parentRunId: "run_main_456",
  agentName: "数据分析代理",
  agentType: "data_analyst",
  agentDescription: "负责数据获取和统计分析",
  depth: 1,  // 嵌套深度
  metadata: {
    specialization: "financial_data",
    expectedDuration: "30s"
  }
}

// 子代理完成事件
{
  type: "SubAgentFinished",
  runId: "run_sub_123",
  parentRunId: "run_main_456",
  outcome: {
    type: "success",
    summary: "成功分析 500 条记录"
  },
  duration: 28.5  // 秒
}

// 子代理错误事件
{
  type: "SubAgentError",
  runId: "run_sub_123",
  parentRunId: "run_main_456",
  error: {
    code: "TIMEOUT",
    message: "代理执行超时",
    recoverable: false
  }
}

5.2 增强 RunStarted 事件

为现有 RunStarted 事件添加更多元数据：

typescript

{
  type: "RunStarted",
  threadId: "thread_abc",
  runId: "run_xyz",
  parentRunId: "run_parent",  // 已有
  
  // 新增字段
  agentInfo: {
    name: "代码审查代理",
    type: "code_reviewer",
    role: "sub-agent",  // "main-agent" | "sub-agent"
    depth: 2
  },
  
  // 监督配置
  supervision: {
    timeout: 60000,  // 毫秒
    requiresApproval: true,
    scope: ["read_files", "analyze_code"]
  }
}

5.3 添加监督和控制原语

引入代理监控和控制事件：

typescript

// 进度报告
{
  type: "AgentProgress",
  runId: "run_sub_123",
  progress: {
    current: 3,
    total: 10,
    unit: "files",
    message: "正在分析第 3 个文件"
  }
}

// 等待批准
{
  type: "AgentAwaitingApproval",
  runId: "run_sub_123",
  request: {
    action: "delete_files",
    description: "需要删除 5 个临时文件",
    risk: "medium"
  }
}

// 超时警告
{
  type: "AgentTimeoutWarning",
  runId: "run_sub_123",
  elapsed: 55000,
  timeout: 60000,
  canExtend: true
}

5.4 嵌套上下文信息

在所有子代理事件中添加上下文路径：

typescript

{
  type: "TextMessageContent",
  messageId: "msg_789",
  delta: "分析完成",
  
  // 新增：上下文路径
  context: {
    runId: "run_sub_123",
    parentRunId: "run_main_456",
    path: ["主编排器", "数据分析代理", "统计模块"],
    depth: 2
  }
}

5.5 UI 渲染指南

协议文档应明确推荐的 UI 渲染模式：

模式 1：嵌套折叠视图

text

💬 主代理: 我将调用专门的代理来处理这个任务
  📁 数据分析代理 (运行中)
    🔧 工具: fetch_data() ✓
    🔧 工具: analyze_stats() ⏳
  📁 报告生成代理 (等待中)

模式 2：时间线视图

text

10:00:00 主代理启动
10:00:02 └─ 数据分析代理启动
10:00:03    ├─ 调用工具: fetch_data()
10:00:05    └─ 调用工具: analyze_stats()
10:00:08 └─ 数据分析代理完成
10:00:09 └─ 报告生成代理启动

模式 3：分栏视图

text

┌────────────────┬────────────────┐
│ 主对话         │ 子代理活动      │
├────────────────┼────────────────┤
│ 💬 分析数据... │ 📊 数据分析代理 │
│                │   - 获取数据 ✓  │
│                │   - 统计分析 ⏳ │
└────────────────┴────────────────┘

六、当前状态与展望

6.1 问题识别现状

✅ 问题已被识别

多个 GitHub Issue 和社区讨论
开发者博客和技术分析文章
主要厂商（Microsoft、Google）已承认问题

🚧 部分临时解决方案

各家框架的自定义补丁
应用层的 workaround
一些 Issue 已关闭但解决方案不明确

❌ 缺少统一标准

没有协议层面的正式修复提案
各家实现方式不一致
可能造成新的碎片化

6.2 为什么问题还没解决？

1. 协议设计的历史局限

AG-UI 最初为单代理场景设计，多代理支持是后期需求。

2. 跨层复杂性

这不仅是前端渲染问题，涉及：

后端监督机制
状态传播协议
权限和授权管理
超时和异常处理

3. 标准化的困境

作为 2025-2026 年新推出的协议，各大厂商正在快速集成，可能采取"先用起来，问题后修"的策略。

4. 向后兼容考虑

任何协议级别的重大改动都需要考虑现有实现的兼容性。

6.3 开发者可以做什么？

短期：应用层解决方案

自行维护层次结构

typescript

// 在应用层追踪 runId 关系
const agentHierarchy = new Map<string, {
  parentRunId: string | null,
  depth: number,
  name: string,
  status: 'running' | 'completed' | 'error'
}>();

// 监听 RunStarted 事件
onRunStarted((event) => {
  agentHierarchy.set(event.runId, {
    parentRunId: event.parentRunId || null,
    depth: calculateDepth(event.parentRunId),
    name: event.input?.agentName || 'Unknown',
    status: 'running'
  });
});

使用 Custom 事件传递元数据

typescript

// 发送自定义子代理元数据
{
  type: "Custom",
  name: "sub_agent_metadata",
  value: {
    runId: "run_sub_123",
    agentName: "数据分析代理",
    agentType: "data_analyst",
    depth: 1
  }
}

参考现有实现

研究 Microsoft Agent Framework 的实现
参考 CopilotKit 的 UI 组件
学习 assistant-ui 的处理方式

长期：推动协议改进

向 AG-UI 官方提交 Feature Request
- GitHub 仓库：ag-ui-protocol/ag-ui
- 参考现有 Issue，提供详细的使用场景和技术方案
参与社区讨论
- assistant-ui 项目的相关讨论
- LangGraph、CrewAI 等框架的多代理支持
- 各大厂商的技术论坛
贡献实现和文档
- 提交 PR 改进协议规范
- 编写多代理场景的最佳实践文档
- 开源自己的解决方案

七、总结

AG-UI 协议代表了 AI 代理标准化的重要一步，它的核心价值在于：

✅ 统一的通信接口 - 一次实现，到处运行
✅ 丰富的事件系统 - 支持流式、工具调用、状态同步
✅ 生态系统支持 - 主要框架和平台已集成
✅ 开放标准 - MIT 许可，社区驱动

然而，在多代理架构这个实际生产中必然遇到的场景下，协议暴露出明显的不足：

❌ 子代理可观察性缺失 - 缺少专用事件和元数据
❌ 嵌套结构难以渲染 - 前端需要复杂的状态管理
❌ 监督原语缺失 - 没有超时、中止、进度监控
❌ 安全边界模糊 - 权限和范围管理不完善

这不是简单的 bug，而是协议设计的结构性缺陷，需要协议层面的协调修复。

作为开发者，我们既可以用临时方案先行，也应该积极推动标准的完善。毕竟，真正的标准化不是一蹴而就，而是在实践中不断迭代和改进的过程。

参考资源

官方文档

社区讨论

技术博客

作者注： 本文基于 2026 年 8 月的协议规范和社区反馈撰写。AG-UI 作为一个活跃发展的开源项目，规范可能会持续更新。建议关注官方文档获取最新信息。

如果你也在构建多代理系统并遇到类似问题，欢迎在评论区分享你的经验和解决方案。让我们一起推动 AI 代理标准化的进程！