AG-UI (Agent User Interaction Protocol) 架构解析

AG-UI (Agent User Interaction Protocol) 是一套开放协议，旨在标准化前端应用程序与 AI Agent (人工智能代理) 之间的连接与交互方式。AG-UI 解决了 AI 应用开发中的三大核心挑战：实时交互性、状态流式传输、人机协作。

1. 核心概念

AG-UI (Agent User Interaction Protocol) 是一套开放协议，旨在标准化前端应用程序与 AI Agent (人工智能代理) 之间的连接与交互方式。AG-UI 解决了 AI 应用开发中的三大核心挑战：

• 实时交互性：支持字符级的流式响应，提供即时反馈

• 状态流式传输：实时、增量地同步 Agent 状态到前端

• 人机协作：内置工具调用和人工确认机制，实现 Human-in-the-Loop 工作流

1.1 设计理念

• 标准化与解耦：为前端和 AI Agent 提供统一的通信标准，解耦具体实现

• 事件驱动：所有通信基于异步事件流，支持实时、非阻塞交互

• 供应商中立：消息和事件格式设计为通用型，易于切换不同 AI 服务

• 轻量级：最小化对底层技术栈和传输方式的限制，降低集成门槛

• 双向互动：Agent 不仅能响应用户，也能接受用户的输入，实现紧密协作

• 前端定义工具：工具的能力由前端定义并传递给 Agent，增强前端控制力和安全性

2. 系统架构

AG-UI 采用客户端-服务器架构，通过标准化事件流实现前端与 Agent 的通信。

2.1 核心组件

• 前端应用：用户直接交互的界面，如聊天应用或集成 AI 功能的应用

• AG-UI 客户端：处理与 Agent 通信的客户端库（如 HttpAgent）

• AI Agent：处理请求并生成响应的 AI 服务

• 安全代理：可选的后端服务，提供请求路由、认证、多 Agent 管理等功能

2.2 工作流程

1. 前端应用通过 AG-UI 客户端发起请求，包含对话历史、可用工具、上下文信息等

2. AI Agent 处理请求，通过一系列事件 (Events) 将响应流式传输回客户端

3. AG-UI 客户端接收事件，更新前端 UI 或执行其他操作（如调用工具）

4. 如需工具调用，前端执行工具并将结果作为消息 (Message) 发回给 Agent

5. Agent 继续处理，生成更多事件

6. 整个交互过程是双向的、实时的

3. 核心技术组件

3.1 Agents

Agent 是 AG-UI 协议的核心，处理请求并生成响应。

• AbstractAgent：所有 AG-UI Agent 的抽象基类，提供状态管理、消息历史跟踪和事件流处理的框架

• HttpAgent：通过 HTTP 与远程 AI 服务通信的具体实现，支持多种传输方式：

• HTTP SSE (Server-Sent Events)：基于文本的流式传输

• HTTP Binary Protocol：高性能的二进制传输格式

Agent 运行输入：

3.2 Events (事件)

事件是 AG-UI 中前端和 Agent 之间通信的基本单元。在 AG-UI 中，所有通信都基于事件流，它们以流式方式从 Agent 传输到前端，或从前端传回 Agent。

3.2.1 事件流转基本模型

AG-UI 采用事件驱动的架构模式，所有交互通过事件流进行传递：

3.2.2 事件类型与流转过程

AG-UI 定义了五大类事件，每类事件在通信过程中承担不同角色：

3.2.3 三种主要事件流模式

AG-UI 使用三种核心事件流模式来处理不同类型的交互：

1. 生命周期模式 - 跟踪 Agent 运行状态：

2. 流式内容模式 - 用于文本和工具调用：

3. 状态同步模式 - 维护共享状态：

3.2.4 完整交互图示

下图展示了一个典型的 AG-UI 交互过程，包含各类事件的流转：

3.2.5 事件时序与状态变化

在 AG-UI 交互过程中，事件流和状态变化同步进行，展示了实时交互性：

3.3 Messages (消息)

消息构成对话历史，代表用户和 AI Agent 之间的交流内容。

消息类型：

• UserMessage：用户发送给 Agent 的消息

• AssistantMessage：Agent 发送给用户的消息，可能包含文本内容和工具调用请求

• SystemMessage：提供给 Agent 的指令或上下文

• ToolMessage：工具执行后的结果

工具调用流程：

3.4 State Management (状态管理)

AG-UI 支持 Agent 和前端之间的状态实时同步。

状态同步方法：

• STATE_SNAPSHOT 事件：提供 Agent 当前状态的完整快照

• STATE_DELTA 事件：提供对 Agent 状态的增量更新，使用 JSON Patch (RFC 6902) 格式

状态同步流程：

3.5 Tools (工具)

工具使 Agent 能够与外部系统交互或请求人工输入。

工具定义：工具由前端定义，并作为 RunAgentInput 的一部分传递给 Agent。

interface Tool {
name: string // 工具名称
description: string // 工具描述
parameters: JSONSchema // 参数结构（JSON Schema）
}

工具调用生命周期：通过 ToolCallStart, ToolCallArgs, ToolCallEnd 事件流式传递工具调用请求。

前端定义工具的优势：

• 前端控制 Agent 可用的能力

• 根据用户权限或上下文动态调整工具

• 关注点分离（Agent 负责推理，前端负责实现）

• 增强安全性（敏感操作由应用程序控制）

4. 与其他协议的关系

AG-UI 专注于Agent 与用户之间的交互层，与其他协议相互补充：

• AG-UI：处理 Agent 与用户之间的交互

• A2A (Agent-to-Agent Protocol)：处理 Agent 之间的通信和协作

• MCP (Model Context Protocol)：标准化工具调用和跨模型上下文处理

一个 Agent 可能同时通过不同协议与多个实体交互，形成完整的 AI 生态系统。

5. 技术实现考量

5.1 传输层

AG-UI 协议与具体传输机制解耦，可以在多种传输层之上实现：

• Server-Sent Events (SSE)

• WebSockets

• HTTP/2

• 其他自定义传输机制

5.2 集成场景

AG-UI 可以集成到多种前端框架和 Agent 框架：

• 前端框架：React, Vue, Angular 等

• Agent 框架：LangGraph, CrewAI, Mastra, AG2 等

5.3 人机协作最佳实践

使用 AG-UI 构建人机协作系统时的最佳实践：

• 通过工具调用实现用户确认流程

• 使用状态同步展示 Agent 的思考过程

• 设计清晰的交互界面，显示 Agent 状态和当前活动

• 构建渐进式交互模式，允许用户在任何时刻介入