构建未来交互体验：AG-UI 如何赋能智能体与前端通信？

---

🧠 什么是 AG-UI?

AG-UI（Agent User Interaction Protocol，智能体用户交互协议） 是由 CopilotKit 公司发布的一个开放、轻量且基于事件的通信协议。它通过标准 HTTP 协议或可选的二进制通道，以流式方式传输一系列 JSON 事件，旨在对 AI Agent 与前端应用程序之间的交互进行标准化。

CopilotKit 成立于 2022 年，是一家专注于为企业产品打造 AI 助手的初创公司。

• 官网描述为：AI Copilots for your product. Build fast, customize effortlessly.
• 官网地址：https://www.copilotkit.ai/

⚙️ AG-UI 主要解决什么问题？

据 CopilotKit 的开发团队介绍，目前大多数 agent 都属于后端自动化工具，主要用于执行数据迁移、表单填写、内容总结等任务，这些 agent 通常在后台运行，对用户不可见。

然而，随着交互式 agent（如 Cursor、Windsurf、Devin 等）的发展，它们已经能够实现与用户的实时协同工作，并带来了大量新的应用场景。在这种背景下，agent 需要具备以下核心能力：

• 实时更新
• 工具编排
• 可共享的可变状态
• 安全边界控制
• 前端同步

为此，他们构建并发布了 AG-UI 协议，以支持上述功能。

🔗 AG-UI 介绍

AG-UI 在 AI agent 和前端应用程序之间架起了一座桥梁，使得两者之间的交互更加顺畅，从而提升用户体验。其整体架构如下图所示：

各组件说明如下：

• Application：用户使用的应用程序（例如聊天应用或其他 AI 应用）
• AG-UI Client：通用通信客户端，如 HttpAgent，也可根据需要使用专用客户端连接现有协议
• Agent：负责处理用户请求并生成流式响应的后端服务
• Secure Proxy：提供额外功能或作为安全代理的中间层服务

🏗️ 核心组件

AG-UI 的核心组件包括以下几个部分：

📡 1. 协议层（Protocol Layer）

AG-UI 协议层为 agent 通信提供了灵活的基础结构。其核心目标是使应用程序能够启动并运行 agent，同时接收事件流。

🌐 2. 标准 HTTP 客户端（Standard HTTP Client）

AG-UI 提供了一个标准的 HTTP 客户端 HttpAgent，可用于连接任何支持 POST 请求的端点。该端点接收 RunAgentInput 类型的请求体，并返回 BaseEvent 对象的数据流。

HttpAgent 支持 HTTP SSE (Server-Sent Events) 和 HTTP binary protocol 两种模式。

💬 3. 消息类型（Message Type）

为了更好地管理 agent 通信过程中的不同交互场景，AG-UI 定义了多种事件类型：

• 生命周期事件（Lifecycle events）：用于监控 Agent 的运行状态，包括：

  • RunStarted
  • StepStarted / StepFinished
  • RunFinished（成功）
  • RunError（失败）

• 文本消息事件（Text message events）：用于处理文本流式内容。这些事件遵循流式传输模式，逐步交付文本内容。一个完整的文本消息通常以 TextMessageStart 开始，随后是多个 TextMessageContent 事件传递具体内容，最后以 TextMessageEnd 结束。

• 工具调用事件（Tool call events）：用于管理 Agent 对工具的调用。当 Agent 使用某个工具时，会触发 ToolCallStart 事件，接着通过 ToolCallArgs 流式传输参数，最终以 ToolCallEnd 结束。

• 状态管理事件（State management events）：用于同步 Agent 与 UI 之间的状态。采用高效的“快照-增量”机制：

  • 初始或周期性发送完整状态快照（StateSnapshot）
  • 后续变更通过增量更新（StateDelta）传输，减少数据传输量

• 特殊事件（Special events）：支持自定义功能或与外部系统集成，包括：

  • Raw
  • Custom

🤖 4. 运行 Agent（Running Agent）

创建 agent 客户端实例并启动 agent 执行流程。

🔄 5. 状态管理（State Management）

AG-UI 通过专用事件来管理状态，主要包含以下事件：

• STATE_SNAPSHOT：某一时刻的完整状态表示；
• STATE_DELTA：使用 JSON 补丁格式（RFC 6902）的增量状态变更；
• MESSAGES_SNAPSHOT：表示完整的对话历史；

🛠️ 6. 工具和交接（Tools and Handoff）

AG-UI 通过标准化事件支持 agent 之间的任务移交和工具调用。

📦 事件（Events）

AG-UI 中的所有通信均基于事件驱动机制。每个事件都继承自 BaseEvent 接口，定义如下：

interface BaseEvent {
  type: EventType;
  timestamp?: number;
  rawEvent?: any;
}

目前官方已提供 TypeScript 和 Python SDK，便于开发者快速接入协议。

🆚 MCP vs A2A vs AG-UI

去年底，Anthropic 发布了 MCP（Model Context Protocol），今年 Google 推出了 A2A（Agent to Agent），均为面向本轮 AI 技术发展的通信协议。

相比之下，AG-UI 更聚焦于 agent 与用户之间的交互层面。三者并非竞争关系，而是各自服务于不同的目的：

协议	主要作用
AG-UI	处理用户与 agent 的交互及界面更新
A2A	促进 agent 之间的通信与协作
MCP	规范模型间工具调用与上下文处理

这三者可以互为补充。例如，同一个 agent 可以通过 A2A 与其他 agent 通信，使用 AG-UI 与用户互动，同时借助 MCP 调用工具。

三个协议共同构成了完整的 User-Agent-LLM 交互协议栈，如下图所示：

🔗 相关链接

• CopilotKit 官网：https://copilotkit.ai/
• AG-UI GitHub：https://github.com/ag-ui-protocol/ag-ui
• AG-UI Docs：https://docs.ag-ui.com/