AG-UI 與代理框架集成

AG-UI 是一種協議，使您能夠構建基於 Web 的 AI 代理應用程序，具有實時流媒體、狀態管理和交互式 UI 組件等高級功能。 代理程式框架 AG-UI 整合可在代理程式和 Web 用戶端之間提供無縫連線。

什麼是 AG-UI？

AG-UI 是用於建立 AI 代理介面的標準化協議，提供：

• 遠程代理託管： 將 AI 代理部署為多個客戶端可訪問的網絡服務
• 即時串流：使用 Server-Sent Events (SSE) 串流代理回應，以獲得即時反饋
• 標準化溝通： 一致的消息格式，實現可靠的客服人員互動
• 會話管理：在多個請求中維持對話上下文
• 進階功能：人機交互審批、狀態同步和自訂 UI 渲染

何時使用 AG-UI

當您需要時，請考慮使用 AG-UI：

• 構建與 AI 代理互動的 Web 或移動應用程序
• 將代理程式部署為多個並發使用者可存取的服務
• 實時流式傳輸代理響應以提供即時用戶反饋
• 實作核准工作流程，讓使用者在執行前確認動作
• 在用戶端和伺服器之間同步處理狀態，以取得互動式體驗
• 根據代理工具的呼叫呈現自訂 UI 元件

支援的功能

代理程式架構 AG-UI 整合支援所有 7 種 AG-UI 協定功能：

1. Agentic Chat：具有自動工具呼叫的基本串流聊天功能
2. 後端工具轉譯：在後端執行的工具，並將結果串流至用戶端
3. Human in the Loop：功能核准請求以供使用者確認
4. Agentic Generative UI： 用於長時間運行操作的非同步工具，並具有進度更新
5. 基於工具的生成式 UI：根據工具調用渲染的自定義 UI 組件
6. 共用狀態：用戶端與伺服器之間的雙向狀態同步
7. 預測狀態更新： 將工具參數流式傳輸為樂觀狀態更新

使用 CopilotKit 建置代理程式 UI

CopilotKit 提供了豐富的 UI 元件，用於根據標準 AG-UI 協定建立代理程式使用者介面。 CopilotKit 支援串流聊天介面、前端和後端工具呼叫、人機迴圈互動、生成式 UI、共享狀態等等。 您可以在 AG-UI Dojo 範例應用程式中看到 CopilotKit 支援的各種代理程式 UI 案例範例。

CopilotKit 可協助您專注於客服專員的能力，同時提供精緻的使用者體驗，而無需重新發明輪子。 若要深入瞭解如何開始使用 Microsoft Agent Framework 和 CopilotKit，請參閱 CopilotKit 的 Microsoft Agent Framework 整合 檔。

AG-UI 與直接代理使用情況

雖然您可以使用代理程式架構和RunRunStreamingAsync方法直接在應用程式中執行代理程式，但 AG-UI 提供其他功能：

特徵 / 功能	直接使用代理	AG-UI 整合
部署	嵌入應用程式	透過 HTTP 進行遠端服務
用戶端存取	單一應用	多個客戶端（網絡、移動）
串流	同一程序非同步迭代	Server-Sent 事件（SSE）
狀態管理	應用程式管理	通訊協定層級狀態快照集
會話上下文	應用程式管理	協定管理的會話識別碼
審批工作流程	自定義實作	內建中介軟體模式

架構概觀

AG-UI 整合使用 ASP.NET Core 並遵循乾淨的基於中間件的架構：

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  ASP.NET Core           │
│  MapAGUI("/", agent)    │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AIAgent                │
│  (with Middleware)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  IChatClient            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

關鍵組件

• ASP.NET Core Endpoint： MapAGUI 擴充方法處理 HTTP 請求和 SSE 串流
• AIAgent：從 IChatClient 或自訂實作建立的代理程式架構代理程式
• 中介軟體管道：用於核准、狀態管理和自訂邏輯的可選中介件
• 通訊協定配接器：在代理程式架構類型和 AG-UI 通訊協定事件之間進行轉換
• 聊天用戶端：Microsoft.Extensions.AI 聊天用戶端（Azure OpenAI、OpenAI、Ollama 等）

代理程式架構如何轉化為 AG-UI

了解代理程式框架概念如何對應到 AG-UI 有助於您建立有效的整合：

代理程式架構概念	AG-UI 等效	Description
AIAgent	代理程式端點	每個代理程式都會成為 HTTP 端點
agent.Run()	HTTP POST 請求	用戶端透過 HTTP 傳送訊息
agent.RunStreamingAsync()	伺服器推送的事件	透過 SSE 串流回應
AgentResponseUpdate	AG-UI 活動	自動轉換為協定事件
AIFunctionFactory.Create()	後端工具	在伺服器上執行，結果串流
ApprovalRequiredAIFunction	人機交互	中間件轉換為審核協議
AgentSession	會話管理	ConversationId 維護上下文
ChatResponseFormat.ForJsonSchema<T>()	狀態快照	結構化輸出會變成狀態事件

安裝

AG-UI 整合包含在 ASP.NET Core託管套件中：

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore

此套件包含 AG-UI 整合所需的所有相依性，包括 Microsoft.Extensions.AI。

後續步驟

若要開始使用 AG-UI 集成：

1. 入門：建立您的第一個 AG-UI 伺服器和客戶端
2. 後端工具渲染：為您的代理添加功能工具

其他資源

• 代理程式架構文件
• AG-UI 通訊協定文件
• Microsoft.Extensions.AI 文檔
• Agent Framework GitHub 存放庫

AG-UI 與直接代理使用情況

雖然您可以使用代理程式架構和runrun(..., stream=True)方法直接在應用程式中執行代理程式，但 AG-UI 提供其他功能：

特徵 / 功能	直接使用代理	AG-UI 整合
部署	嵌入應用程式	透過 HTTP 進行遠端服務
用戶端存取	單一應用	多個客戶端（網絡、移動）
串流	同一程序非同步迭代	Server-Sent 事件（SSE）
狀態管理	應用程式管理	雙向通訊協定層級同步
執行緒上下文	應用程式管理	由協定管理的執行緒識別碼
審批工作流程	自定義實作	內建協定支援

架構概觀

AG-UI 整合使用乾淨的模組化架構：

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  FastAPI Endpoint       │
│  (add_agent_framework_  │
│   fastapi_endpoint)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AgentFrameworkAgent    │
│  (Protocol Wrapper)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Orchestrators          │
│  (Execution Flow Logic) │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Agent              │
│  (Agent Framework)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Chat Client            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

關鍵組件

• FastAPI 端點：處理 SSE 串流和請求路由的 HTTP 端點
• AgentFrameworkAgent：輕量級包裝器，可使代理框架代理程式適應 AG-UI 協定
• 協調器：處理不同的執行流程 （預設、人機迴圈、狀態管理）
• 事件橋接器：將代理程式架構事件轉換為 AG-UI 協定事件
• 訊息配接器：AG-UI 與代理程式架構訊息格式之間的雙向轉換
• 確認策略： 領域特定確認消息的可擴展策略

代理程式架構如何轉化為 AG-UI

了解代理程式框架概念如何對應到 AG-UI 有助於您建立有效的整合：

代理程式架構概念	AG-UI 等效	Description
Agent	代理程式端點	每個代理程式都會成為 HTTP 端點
agent.run()	HTTP POST 請求	用戶端透過 HTTP 傳送訊息
agent.run(..., stream=True)	伺服器推送的事件	透過 SSE 串流回應
客服專員回應更新	AG-UI 活動	TEXT_MESSAGE_CONTENT、TOOL_CALL_START 等。
功能工具 （@tool）	後端工具	在伺服器上執行，結果串流至用戶端
工具審批模式	人機交互	透過通訊協定的核准請求與回應
交談歷程記錄	線程管理	threadId 維護跨請求的上下文

安裝

安裝 AG-UI 整合套件：

pip install agent-framework-ag-ui --pre

這會同時安裝核心代理程式架構和 AG-UI 整合元件。

後續步驟

若要開始使用 AG-UI 集成：

1. 入門：建立您的第一個 AG-UI 伺服器和客戶端
2. 後端工具渲染：為您的代理添加功能工具

其他資源

• 代理程式架構文件
• AG-UI 通訊協定文件
• AG-UI Dojo 應用程式 -示範代理程式架構整合的範例應用程式
• Agent Framework GitHub 存放庫