博主未授權任何人或組織機構轉載博主任何原創文章，感謝各位對原創的支持！
博主鏈接

本人就職于國際知名終端廠商，負責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）和共享狀態的場景；

---