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 情境

AG-UI 定義了七個展示場景。 MAF 支援依 SDK 而異;請使用本頁的語言專區，了解目前的支援等級與實作指引。

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

使用 CopilotKit 建置代理程式 UI

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

要將 CopilotKit React 前端連接到 Agent Framework AG-UI 後端，請在 CopilotKit 執行環境中註冊你的端點 HttpAgent 。 這讓 CopilotKit 的前端工具能像 AG-UI 客戶端工具一樣順暢運作，所有 AG-UI 功能（串流、核准、狀態同步）都能自動運作。

CopilotKit 可協助您專注於代理程式的功能，同時提供精緻的使用者體驗，而不用無謂地重複。 若要深入瞭解如何開始使用 Microsoft Agent Framework 和 CopilotKit，請參閱 CopilotKit 的 Microsoft Agent Framework 整合 檔。

.NET 整合

.NET 整合功能將 MAF AIAgent 公開為 AG-UI HTTP 端點。 主機介面卡會將代理的回應串流轉換為 AG-UI 事件;核心代理行為如工具執行與核准仍屬於 MAF。

使用 .NET 整合功能來：

AG-UI 客戶決定如何呈現文字、工具、核准及事件陳述。

Architecture

C# 主機套件在一般 MAF 代理程式周圍新增了一個 ASP.NET Core 端點：

AG-UI client -- HTTP POST / SSE --> MapAGUIServer --> AIAgent

MapAGUIServer 會根據 MAF 訊息和執行選項調整 AG-UI 請求。 接著，它會將代理的串流回應轉換為使用 AG-UI .NET SDK 的 AG-UI 事件。

Installation

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

下一步

開始使用 AG-UI

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

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

Feature 直接使用代理 AG-UI 整合
Deployment 嵌入應用程式 透過 HTTP 進行遠端服務
用戶端存取 單一應用 多個客戶端（網絡、移動）
Streaming 同處理程序的非同步反覆項目 Sever-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 等效 說明
Agent 代理程式端點 每個代理程式都會成為 HTTP 端點
agent.run() HTTP POST 請求 用戶端透過 HTTP 傳送訊息
agent.run(..., stream=True) 伺服器推送的事件 透過 SSE 串流回應
客服專員回應更新 AG-UI 活動 TEXT_MESSAGE_CONTENT、TOOL_CALL_START 等。
功能工具 （@tool） 後端工具 在伺服器上執行，結果串流至用戶端
工具審批模式 人機互動 透過通訊協定的核准請求與回應
交談歷程記錄 線程管理 threadId 會維護跨要求的內容

Installation

安裝 AG-UI 整合套件：

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

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

控制終端訊息快照

根據預設，AgentFrameworkAgent會發出包含完整文字記錄的終端機MESSAGES_SNAPSHOT事件。 如果 HistoryProvider 或您的應用程式已經管理對話狀態，請將 emit_messages_snapshot=False 設為相應值，以避免在每次執行結束時重寫用戶端轉錄內容：

from agent_framework_ag_ui import AgentFrameworkAgent

wrapped_agent = AgentFrameworkAgent(
    agent=agent,
    emit_messages_snapshot=False,
)

此設定僅抑制終端訊息快照。 其他串流事件，包括 RUN_FINISHED，則保持不變。

呈現引用與註解

帶有 Content.annotations 的文字內容會發出一個名為 CUSTOM 的訊息連結的 annotationsAG-UI 事件。 此事件包含僅註解的更新，這些更新會在回應文字之後出現，例如來自 Responses API 的 grounding citations。 事件會提前 RUN_FINISHED 到來，且不會重複回覆文字。

{
  "type": "CUSTOM",
  "name": "annotations",
  "value": {
    "messageId": "assistant-message-id",
    "annotations": [
      {
        "type": "citation",
        "title": "Document",
        "url": "https://contoso.example/document.pdf",
        "annotated_regions": [
          {
            "type": "text_span",
            "start_index": 0,
            "end_index": 6
          }
        ]
      }
    ]
  }
}

每個事件都包含針對已識別文字訊息的新發出註解。 將它們附加在該訊息後面，並使用標題、網址或檔案 ID 來呈現來源。 事件保留框架註解欄位及額外屬性，但不包含提供者 raw_representation 物件。

AGUIChatClient 在串流更新與彙整回應中將這些事件批次還原為 Content.annotations。 它也保留了在 update.additional_properties["ag_ui_custom_event"] 中的自訂事件。 引用渲染與持久化仍是應用程式的職責，因為 MESSAGES_SNAPSHOT 不會重播這些即時自訂事件。

後續步驟

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

  1. 入門：建立您的第一個 AG-UI 伺服器和客戶端
  2. 後端工具渲染：為您的代理添加功能工具
  3. 工作流程：透過 AG-UI 展現多代理工作流程
  4. 人為介入：實施核准工作流程
  5. MCP 應用程式相容性：在您 AG-UI 的端點使用 MCP 應用程式
  6. 狀態管理：同步用戶端與伺服器之間的狀態

其他資源

Go 透過 provider/aguiprovider 為伺服器與用戶端提供 AG-UI 支援。

import "github.com/microsoft/agent-framework-go/provider/aguiprovider"

mux := http.NewServeMux()
mux.Handle("/", aguiprovider.NewJSONHTTPHandler(myAgent, aguiprovider.HandlerConfig{}))

if err := http.ListenAndServe(":8888", mux); err != nil {
    log.Fatal(err)
}

Tip

完整伺服器與用戶端範例請參考 AG-UI Go 範例 。

  • Last updated on