AG-UI：一种轻量级的智能体—用户交互协议

为何智能体应用需要 AG-UI

在看代码之前，先解释为什么我们一开始就需要一个新协议。归根结底，是函数与智能体之间的根本差异。

请求/响应的局限

在传统 Web 开发中，交互是事务性的。您请求一个用户档案，服务器就返回它。这是一锤子买卖。

而智能体则不可预测且需要时间。当您让智能体“排查为何队友合并后 CI 流水线突然失败”，它不会立刻返回一个 JSON 对象。相反，它可能会：

1. 从 GitHub 拉取最近 50 条提交日志（Action）。
2. 注意到新增了一个依赖但未更新锁定文件（Observation）。
3. 将该软件包版本与已知 CVE 进行交叉比对（Reasoning）。
4. 询问您是否要回滚合并或向前打补丁（Human-in-the-loop）。

稍后我会在“事件类型”部分解释，但现在只需知道：标准 HTTP 请求会在等待这一切的过程中超时。您需要一种方式来串流这些部分更新，避免用户盯着一块“卡住”的屏幕。

智能体的特定需求

智能体需要超越文本的双向信息流。它们需要同步状态（State）。

设想一个帮助您写报告的智能体。它不只是聊天；而是在编辑文档。您和智能体可能会同时输入。AG-UI 通过将“文档”视为共享状态来处理这一点，使用高效更新使您的屏幕与智能体的记忆保持同步，而不会互相覆盖。

智能体与 UI 如何通信

AG-UI 用事件溯源（Event-Sourcing）模型取代了旧的远程过程调用（RPC）模型。智能体不会等待最终答案再返回，而是持续不断地发送事件流，描述它正在做什么。

事件流

把 AG-UI 的流想象成智能体大脑的新闻滚动条。客户端应用（您的前端）订阅这条滚动条，并根据所见更新 UI。该方式实现了解耦：您的 React 前端无需知道智能体如何思考，它只需知道要展示什么。

AG-UI 避免了等待空档。图片由作者制作。

核心事件类型

该协议定义了覆盖几乎所有交互场景的标准事件类型。以下是您最常见到的几类：

1. TEXT_MESSAGE_*：按片段串流生成文本的事件。通常包含 _START、_CONTENT（Token 流）与 _END 三种事件，共同营造出熟悉的“打字”效果。

2. TOOL_CALL：表示智能体想执行某项操作，比如查询天气或访问数据库。关键在于，AG-UI 可以串流工具调用的参数，让您的 UI 在智能体“说完话”之前就能预填表单。

3.  STATE_DELTA：协作的主力军。智能体不必在每次字母变化时重发整份文档，而是发送一个很小的“差异”（例如“在索引 5 处添加 'hello'”）。

4. INTERRUPT：安全阀。如果智能体触及敏感操作（如“删除数据库”），它会发出中断事件。流程会暂停，直到用户返回批准事件。

多模态与思考步骤

该协议并不限于文本。它支持多模态，也就是说可在对话中串流图像、音频和文件附件。它还对“思考步骤”进行标准化，将智能体的内部思考（推理轨迹）与最终公开响应区分开来。您可能在使用 ChatGPT 等工具时见过类似模式：将进度指示或中间步骤与最终回答分开展示。这样您就可以决定是展示执行进度，还是仅展示最终结果。

AG-UI 的构建模块

既然已经理解了流程，我们来看看让 AG-UI 对开发者强大的具体特性。

生成式 UI

文字很有用，但有时图表更合适。生成式 UI 允许智能体在运行时决定展示一个 UI 组件，而非文本。

AG-UI 串流事件；A2UI 定义组件。图片由作者制作。

这里有个容易让人困惑的区别（在框架部分我会再提一次）：AG-UI 是传递机制（传输层），而 A2UI （Agent-to-User Interface）是 UI 定义（载荷）。智能体可以使用 AG-UI 的 TOOL_CALL 事件来传输 A2UI 载荷——一个描述 UI 组件（如“股价卡片”）的声明式 JSON 树。您的前端接收后渲染出实际图表。

使用 JSON Patch 的共享状态

处理共享状态很棘手。如果智能体每秒都发送一个 5MB 的上下文对象，您的应用会变得非常卡顿。

AG-UI 通过 JSON Patch（RFC 6902） 解决这一问题。正如我先前在状态同步中提到的，当智能体更改其记忆中的一个值时，它会计算差异并发送 STATE_DELTA 事件。

[
  {
    "op": "replace",
    "path": "/user/status",
    "value": "active"
  }
]技术支持

客户端接收这条轻量指令并将其应用到本地状态。这种高效性使与智能体的实时协作成为可能。

协议版图中的 AG-UI

您或许听说过其他协议，例如 MCP（Model Context Protocol）。了解 AG-UI 在技术栈中的位置非常重要，避免用错工具。

智能体技术栈

我喜欢把它看作一座通信三角：

1. MCP（智能体 ↔ 工具）：连接智能体与后端世界：数据库、GitHub 仓库与内部 API。重点在“获取信息”。
2. A2A（智能体 ↔ 智能体）：让智能体彼此通信，将任务委派给子智能体。
3. AG-UI（智能体 ↔ 用户）：这是“最后一公里”。它把智能体的智能接入到人类用户。

连接智能体的“协议三位一体”。图片由作者制作。

AG-UI 并不关心智能体如何获得数据（那是 MCP 的工作，正如我上面提到的）；它只关心如何把这些数据展示给您。

实施 AG-UI

我们来看看实际场景中的样子。开发者通常以三种方式与 AG-UI 交互：构建 1）智能体应用（将前端连接到智能体）、构建 2）集成（让一个框架兼容），或构建 3）客户端（创建新的前端）。大多数人会属于第一类。

我马上会解释代码，但首先要明白，您通常不需要自己编写原始协议处理器。库会负责这些封装。但理解流程对调试至关重要。

建立事件通道

多数实现使用服务器发送事件（SSE），因为它简单、对防火墙友好，并且非常适合从服务器到客户端的单向串流。我之前也暗示过，正是 SSE 让该协议相比 WebSockets 更加轻量。

在典型设置中（例如使用 Microsoft Agent Framework 或 CopilotKit），服务器会暴露一个端点，将连接升级为流。

简单的事件订阅

下面是一个前端客户端监听流的概念性示例。请注意我们如何按不同事件类型更新 UI。

// Connect to the AG-UI stream
const eventSource = new EventSource('/api/agent/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'TEXT_MESSAGE_CONTENT':
      // Append text to the chat window
      updateChatLog(data.content);
      break;

    case 'TOOL_CALL_START':
      // Show a "Processing..." indicator or the specific tool UI
      showToolIndicator(data.tool_name);
      break;

    case 'STATE_DELTA':
      // Apply the JSON patch to our local state store
      applyPatch(localState, data.patch);
      break;

    case 'INTERRUPT':
      // Prompt the user for permission
      showApprovalModal(data.message);
      break;
  }
};技术支持

这种模式隐藏了智能体内部逻辑的复杂性。您的前端只是智能体所发送事件的“播放器”。

集成与生态支持

您不必从零开始构建。生态正在快速成熟，主流平台与框架正在收敛到类似的事件驱动交互模式。

工具的“黄金三角”

微软将智能体开发的“黄金三角”定义为：

1. DevUI：用于可视化智能体的思考过程（调试）。
2. OpenTelemetry：用于衡量性能与成本。
3. AG-UI：用于连接用户。

已支持的框架

生态正在迅速扩张。除了主要参与者外，整体支持也在不断增长：

1. Microsoft Agent Framework：为 ASP.NET Core 提供原生中间件（Microsoft.Agents.AI.Hosting.AGUI）。

2. CopilotKit：充当 AG-UI 的“浏览器”，提供一个即开即用、能渲染这些事件的完整 React 前端。

3. Python 生态：如 LangGraph、CrewAI、Mastra、Pydantic AI、Agno 与 LlamaIndex 等框架均可 暴露为 AG-UI 端点。

4. SDK：尽管 TypeScript 与 Python 占主导，Kotlin、Go、Dart、Java 与 Rust 的 SDK 也在活跃或开发中。

可靠性、调试与安全

在 AI 与浏览器之间开通直连通道会带来风险。以下是保障应用安全的做法。

受信任的前端服务器

切勿让客户端直接连接到原始的智能体运行时。正如我在“为何智能体应用需要 AG-UI”部分所强调的，请始终使用受信任的前端服务器（BFF 模式）。该服务器作为闸门，向智能体转发用户消息之前先进行认证、限流与输入校验。

安全注意事项

提示注入

恶意用户可能通过提示注入攻击来覆盖智能体的指令。正如我先前提到的，中间件应当对输入进行清洗。

未授权的工具调用

仅仅因为智能体能删除文件，并不意味着当前用户应当被允许。您的受信服务器必须基于用户权限对智能体可用工具进行过滤。

状态安全

由于状态通过 JSON 补丁共享，请警惕原型污染。确保您的补丁库禁止修改诸如 __proto__ 等受保护属性。

使用 Dojo 调试

如果智能体行为异常，请使用 AG-UI Dojo。这是一个测试套件，可视化原始事件流，帮助您捕捉诸如 JSON 补丁格式错误或工具调用已触发但未返回结果等问题。

结语

我们已经介绍了 AG-UI 的架构、事件类型与实施模式。

我也意识到，普通的个人开发者或小公司的成员并不可能现实地“采用 AG-UI”，并立刻“将前端与后端解耦”。这一切需要重大的架构决策、多团队协作与大多数人不具备的资源。

但即使您不实现它，理解 AG-UI 仍然重要。当您评估智能体框架、决定自建还是上平台时，明白什么是“良好”的智能体—UI 通信，会让您的判断更有依据。您会识别出某个工具何时在把您逼进脆弱的模式。

如果您想更深入地构建这类系统，请查看我们的 AI 智能体入门 与 构建可扩展的智能体系统 课程，助您更进一步。