【6G新技术探索】AG-UI（Agent User Interaction Protocol） 协议介绍

博主未授权任何人或组织机构转载博主任何原创文章，感谢各位对原创的支持！
博主链接

本人就职于国际知名终端厂商，负责modem芯片研发。
在5G早期负责终端数据业务层、核心网相关的开发工作，目前牵头6G技术研究。


博客内容主要围绕：
       5G/6G协议讲解
       高级C语言讲解
       Rust语言讲解

AG-UI 协议介绍

AG-UI：Agent User Interaction Protocol
HomePage

一、架构概述

       AG-UI 建立在一个灵活的、事件驱动的架构上，使前端应用程序和AI Agent之间能够无缝、高效地通信。AG-UI遵循客户端-服务器架构：

• Application：面向用户的应用程序（例如聊天或任何支持AI的应用程序）；
• AG-UI客户端：通信客户端，如HttpAgent或用于连接到现有协议的专用客户端；
• Agent：处理请求并生成流响应的后端AI Agent；
• Secure Proxy：提供额外功能并充当安全代理的后端服务；

二、AG-UI 中的事件

       AG-UI 使用基于流事件的架构，事件是Agent和前端之间通信的基本单元，支持实时、结构化的交互。支持的事件类型如下所示：

事件类型	说明
生命周期事件	监测Agent的运行进度
文本消息事件	处理流文本内容
工具调用事件	通过Agent管理工具执行
状态管理事件	Agent与UI间状态同步
特殊事件	支持用户自定义事件

2.1 生命周期事件

       表示Agent运行的生命周期。一个典型的Agent运行遵循下面的状态机模式：它以一个RunStarted事件开始，可能包含多个可选的StepStarted和StepFinished对，并以一个RunFinished事件（成功）或一个RunErrorevent（失败）结束。

       生命周期事件为Agent运行提供了关键的结构，使前端能够跟踪进度，适当地管理UI状态，并优雅地处理错误。它们创建了一个统一的框架，用于理解操作何时开始和结束，使实现加载指示器、进度跟踪和错误恢复机制等功能成为可能。

RunStarted和RunFinished或RunError事件是强制性的，是Agent运行的整体状态机框架。Step事件是可选的，可以在一次运行中多次发生，允许结构化的、可观察的进度跟踪。

• RunStarted：是Agent开始处理请求时发出的第一个事件，此事件作为前端初始化UI元素（如进度指示器或加载状态）的标记。它还提供了关键的标识符，可用于将后续事件与此特定运行关联起来；
• RunFinished：表明Agent已成功完成当前运行的所有工作。接收到此事件后，前端应该完成等待Agent完成的所有UI状态。此事件标记了一个干净的终止点，并指示除非显式请求，否则在此运行中不会发生进一步的处理；
• RunError：表明Agent遇到了无法恢复的错误，导致运行提前终止。此事件提供有关发生错误的信息，允许前端显示适当的错误消息，并可能提供恢复选项。在发生RunError事件后，在此运行中不会发生进一步的处理；
• StepStarted：指示Agent正在开始其处理的特定子任务或阶段。提供了对代理进程的细粒度可见性，从而在UI中实现更精确的跟踪和反馈。步骤是可选的，但强烈建议将复杂操作分解为可观察的阶段。stepName可以是当前正在执行的节点或函数的名称；
• StepFinished：表明Agent已经完成了特定的子任务或阶段。当与相应的StepStarted事件配对时，它将为离散的工作单元创建有界上下文。前端可以使用这些事件来更新进度指示器，显示完成动画，或者显示特定于该步骤的结果。stepName必须匹配相应的StepStarted事件，以正确配对步骤的开始和结束；

2.2 文本消息事件

       表示对话中文本消息的生命周期。文本消息事件遵循流模式，内容是增量交付的。消息以TextMessageStart事件开始，接着是一个或多个TextMessageContent事件，在文本块可用时传递它们，并以TextMessageEnd事件结束。

       这种流式处理方法支持在消息内容生成时实时显示消息内容，与等待整个消息完成后再显示任何内容相比，可以创建响应更快的用户体验。

2.3 工具调用事件

       表示Agent进行的工具调用的生命周期。工具调用遵循类似于文本消息的流模式。当代理需要使用工具时，它会发出一个ToolCallStartevent，随后是一个或多个ToolCallArgs事件，这些事件以流的形式将参数传递给工具，并以一个ToolCallEnd事件结束。

       这种流式方法允许前端实时显示工具执行进度，使Agent的操作更加透明，并提供关于正在调用哪些工具以及使用哪些参数的即时反馈。

2.4 状态管理事件

       用于管理和同步Agent与前端的状态。协议中的状态管理遵循一种高效的snapshot-delta 模式，其中完整的状态快照会在初始时或者不频繁地周期发送，而增量更新会在进行中动态发送。这种方法对完整性和效率都进行了优化：快照确保前端具有完整的状态上下文，而增量最小化更新的数据传输。它们一起使前端能够准确及时的维护代理状态。快照作为同步点，将状态重置为已知基线，而增量在快照之间提供轻量级更新。

• StateSnapshot：完整表示Agent当前的状态。此事件通常在交互开始时或需要同步时发送。它包含与前端相关的所有状态变量，允许它完全重建其内部表示。前端应该用这个快照的内容替换它们现有的状态模型，而不是试图将它与以前的状态合并；
• StateDelta：事件以JSON Patch操作（如RFC 6902中定义）的形式包含对代理状态的增量更新。每个增量表示应用于当前状态模型的特定更改。这种方法具有带宽效率，只发送已更改的内容，而不是整个状态。前端应该按顺序应用这些补丁，以保持准确的状态表示。如果前端在应用补丁后检测到不一致，它可能会请求一个新的 StateSnapshot；
• MessagesSnapshot：事件提供当前会话中消息的完整历史记录。与一般状态快照不同，它特别关注对话记录。此事件可用于初始化聊天历史记录、在连接中断后进行同步，或在用户加入正在进行的对话时提供全面视图。前端应该使用它来建立或刷新显示给用户的会话上下文；

2.5 特殊事件

       特殊事件通过允许特定于系统的功能和与外部系统的集成，为协议提供了灵活性。这些事件不遵循其他事件类型的标准生命周期或流模式，而是用于特殊目的。

三、AG-UI中的Agent

       Agent 是 AG-UI 协议中处理请求和生成响应的核心组件。它们为前端应用程序建立了一种标准化的方式，通过一致的接口与AI服务进行通信，而不考虑底层实现。在AG-UI中，Agent完成下面的工作：

• 管理会话状态和历史消息记录；
• 处理传入消息和上下文；
• 通过事件驱动的流接口生成响应消息；
• 遵循标准化的通信协议；

Agent可以实现与任何AI服务的连接，包括：

• 大型语言模型（llm），如GPT-4或Claude；
• 自定义AI系统；
• 检索增强生成（RAG）系统；
• 多Agent系统；

四、AG-UI基础消息结构

       在AG-UI协议中，消息构成了通信的主干。它们代表了用户和AI Agent之间的对话历史，并提供了一种标准化的方式来交换信息，而不管正在使用的底层AI服务是什么。

       AG-UI消息遵循供应商中立的格式，确保不同AI提供商之间的兼容性，同时保持一致的结构。这允许应用程序在不更改客户端实现的情况下在AI服务（如OpenAI、Anthropic或自定义模型）之间切换。基本消息结构如下所示：

interface BaseMessage {id: string // Unique identifier for the messagerole: string // The role of the sender (user, assistant, system, tool)content?: string // Optional text content of the messagename?: string // Optional name of the sender
}

五、AG-UI中的工具调用

       工具是AG-UI协议中的一个基本概念，它使AI Agent能够与外部系统交互，并将人类判断纳入其工作流程。通过在前端定义工具并将其传递给Agent，开发人员可以创建复杂的人机交互体验，将人工智能功能与人类专业知识相结合。在AG-UI中，工具是Agent可以调用的函数：

• 请求特定信息
• 在外部系统中执行操作
• 要求人工输入或确认
• 访问特定功能

工具是人工智能推理和现实世界行为之间的桥梁，允许Agent完成仅通过对话无法完成的任务。

5.1 工具结构

工具遵循一致的结构，定义了它们的名称、用途和预期参数：

interface Tool {name: string // Unique identifier for the tooldescription: string // Human-readable explanation of what the tool doesparameters: {// JSON Schema defining the tool's parameterstype: "object"properties: {// Tool-specific parameters}required: string[] // Array of required parameter names}
}

·parameters·字段使用JSON Schema定义工具接受的参数结构。Agent（生成有效的工具调用）和前端（验证和解析工具参数）都使用该模式。

5.2 Frontend-Defined工具

AG-UI工具系统的一个关键是工具在前端定义，并在执行期间传递给Agent：

// Define tools in the frontend
const userConfirmationTool = {name: "confirmAction",description: "Ask the user to confirm a specific action before proceeding",parameters: {type: "object",properties: {action: {type: "string",description: "The action that needs user confirmation",},importance: {type: "string",enum: ["low", "medium", "high", "critical"],description: "The importance level of the action",},},required: ["action"],},
}// Pass tools to the agent during execution
agent.runAgent({tools: [userConfirmationTool],// Other parameters...
})

这种方法有几个优点：

• 前端控制：前端决定Agent可以使用哪些功能；
• 动态功能：可以根据用户权限、上下文或应用程序状态添加或删除工具；
• 关注点分离：Agent专注于推理，而前端处理工具实现；
• 安全性：敏感操作由应用程序控制，而不是Agent；

六、与其它Agent协议的关系

       AG-UI主要关注的是Agent与用户间的交互，与A2A （Agent-to-Agent protocol）和MCP （Model Context protocol）等协议是互补的关系。例如，同一Agent代理可以通过A2A与另一个Agent通信，同时通过AG-UI与用户通信，并调用MCP服务器提供的工具。这些协议在智能体生态系统中起到互补作用：

• AG-UI：处理人机协同交互（human-in-the-loop）和流式UI更新；
• A2A：促进Agent之间的通信和协作；
• MCP：标准化不同模型间的工具调用和上下文处理；

总结

       AG-UI标准化了前端应用程序如何通过开放协议连接到AI Agent。可以将其视为人工智能驱动系统的通用翻译器，无论代理说什么语言：AG-UI都确保了流畅的通信。AG-UI帮助开发人员构建需要实时交互、实时状态流和人机协同交互的下一代AI工作流。AG-UI的优势：

• 可以通过类似CopilotKit等框架直接将AI Agent与前端集成；
• 为人类与Agent间的通信构建高效的协议模块；
• 适用于聊天、流式状态更新、人机协同交互（human-in-the-loop）和共享状态的场景；

---