AG-UI 1.0 開源協定登場:用單一雙向事件串流,打通任何 AI 代理與前端介面
由 CopilotKit 團隊發起的開源協定 AG-UI 推出 1.0 穩定版,透過 8 大類、31 種型別化事件串流,讓 LangChain、CrewAI 等代理無縫對接網頁、終端與行動介面。
由前端代理框架 CopilotKit 團隊發起、採用 MIT 開源授權的 AG-UI(Agent-User Interaction Protocol,代理與使用者互動協定),近期正式推出規格凍結的 1.0 穩定版本,並在 GitHub 上累積超過兩萬顆星標。
這套協定想解決一個讓 AI 應用團隊頭痛已久的工程問題:當開發者替 AI 代理加上網頁或手機介面時,往往得為每一套後端框架重寫一次串接程式碼。
原因在於,現代 AI 代理不再只是「問一句、答一句」的傳統請求回應模式。它們會在生成文字的中途呼叫外部工具、即時更新共享狀態、暫停等待人類審核,甚至在背景派出子代理分頭執行任務。
不同框架對這些動態行為的資料格式各有各的寫法。一旦團隊想把後端從 LangChain 換成 CrewAI,或是想讓同一個代理同時服務網頁應用、終端機與 Slack 頻道,前端介面的串接邏輯就得跟著大幅改寫。
AG-UI 選擇用一套標準化的雙向事件串流取代這些零散的膠水碼。它由一份統一的 JSON Schema 定義完整規範,並直接從這份規格自動產生 TypeScript、Python 與 .NET 官方軟體開發套件,確保跨語言開發時欄位與型別完全一致。
更關鍵的是,官方明確承諾 AG-UI 1.0 具備雙向相容性。舊版 0.x 的代理可以直接對接 1.0 客戶端,反之亦然,讓既有專案能按自己的節奏分批升級。
為了讓工程團隊快速評估,官方也同步釋出互動式展示平台 AG-UI Dojo 與官方導覽影片。接下來,我們從協定定位、事件架構到實戰應用場景,拆解 AG-UI 1.0 到底替開發者省下了哪些重工。
延伸閱讀:Vercel UI SDK 登場:把 50 多種無障礙互動行為拆成積木,讓 AI 寫程式代理自己組介面、直接操作
補齊最後一哩路:AG-UI、MCP 與 A2A 的三角分工
在目前的開源代理生態系中,已經有兩個廣為人知的標準,分別是 Anthropic 主導的 MCP(Model Context Protocol,模型上下文協定)與 Google 推動的 A2A(Agent-to-Agent,代理間通訊協定)。
許多開發者第一次看到 AG-UI 時,常會誤以為它是來競爭的新標準,但事實上三者各自負責完全不同的通訊層級。根據 AG-UI 官方文件與架構圖的定義,一個成熟的 AI 應用往往會同時使用這三層協定,彼此互補而非互斥。
具體來說,MCP 負責的是「代理連向工具與資料」,讓代理能以統一介面讀取資料庫、檔案或外部服務。A2A 負責的是「代理連向其他代理」,讓不同系統中的多個代理彼此委派任務並交換結果。
而 AG-UI 負責的則是「代理連向使用者介面」,也就是代理應用最貼近使用者的那一層。它把代理的思考過程、工具進度與產出即時送到螢幕前,同時把使用者的點擊、編輯或核准操作送回後端。
官方也特別釐清 AG-UI 與 A2UI、MCP Apps、Open-JSON-UI 等「生成式介面規格」的差異。後者定義的是畫面上「要長出什麼元件」的宣告式描述,而 AG-UI 則是底層的「執行期傳輸協定」,負責把這些介面描述連同文字、工具呼叫與狀態更新一起安全送達前端。

單一雙向事件串流:8 大類、31 種事件怎麼運作?
傳統的網頁 API 習慣等伺服器把整包答案算完再一次回傳,但在代理場景下,使用者需要即時看到模型吐出的每個字元、正在呼叫哪個工具,以及目前卡在哪一個步驟。
AG-UI 把這整段互動簡化為一個「單一請求、雙向事件串流」的模型。當對話或任務啟動時,前端應用程式只需送出一份名為 RunAgentInput 的標準輸入包裹,裡面包含歷史對話訊息、前端主動提供給代理呼叫的工具清單、目前的共享狀態以及上下文資訊。
後端代理收到這份輸入後,便會透過持續開啟的連線,依序串流回傳具備明確型別的事件物件。AG-UI 1.0 規格總共定義了 8 大類、合計 31 種事件類型,涵蓋代理執行期間幾乎所有狀態變化:
| 事件類別 | 代表事件範例 | 核心用途說明 |
|---|---|---|
| 執行生命週期(Runs & steps) | RUN_STARTED、RUN_FINISHED、RUN_ERROR |
標記任務開始、完成、錯誤與細部步驟進度 |
| 文字訊息(Text messages) | TEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT |
支援逐字元串流輸出與多輪對話識別 |
| 工具呼叫(Tool calls) | TOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_RESULT |
即時呈現代理呼叫工具的參數與回傳結果 |
| 共享狀態(State) | STATE_SNAPSHOT、STATE_DELTA、MESSAGES_SNAPSHOT |
透過快照與 JSON Patch 增量同步前後端狀態 |
| 推理過程(Reasoning) | REASONING_START、REASONING_ENCRYPTED_VALUE |
顯示模型思考脈絡,並支援加密推理來回傳遞 |
| 活動進度(Activity) | ACTIVITY_SNAPSHOT、ACTIVITY_DELTA |
回報背景工作與長任務的即時進度狀態 |
| 子代理(Subagents) | SUBAGENT_STARTED、SUBAGENT_FINISHED |
支援巢狀任務委派,並將事件歸屬至對應子代理 |
| 透傳事件(Passthrough) | RAW、CUSTOM |
保留原始資料與自訂擴充欄位的彈性通道 |
在這些事件中,只有最基本的執行生命週期事件屬於強制要求。這意味著剛起步的簡易代理只需要送出幾個核心事件就能符合 AG-UI 規格,等到系統需要共享畫布狀態、前端工具或子代理協作時,再逐步加上對應的事件家族即可。
八大互動積木:共享狀態、前端工具與人機協作
許多團隊在自建 AI 介面時,最頭痛的不是聊天視窗,而是「當代理跟使用者操作同一個畫面時,兩邊狀態怎麼同步」。例如代理正在幫使用者修改一份待辦清單、程式碼檔案或試算表,如果每次微調都要重傳整份資料,不僅浪費頻寬,還容易覆蓋使用者剛輸入的內容。
AG-UI 在狀態管理家族中直接採用了雙軌機制。初次連線或需要重置時,伺服器會傳送完整快照 STATE_SNAPSHOT;後續每次細微變動則傳送 STATE_DELTA,利用標準的 JSON Patch 格式只描述「哪個欄位新增、修改或刪除」。
這種設計讓前端畫面可以像多人協作軟體一樣流暢更新,代理與使用者都能讀寫同一份型別化的共享狀態,不再需要自己手寫複雜的資料合併邏輯。
除了狀態同步,AG-UI 還在官方 Dojo 展示平台中整理出開發者最常使用的八大互動積木:
- 串流對話與多模態:支援多輪對話中的逐字輸出、取消與恢復執行,並在輸入與工具結果中直接傳遞圖片、音訊、影片與文件。
- 前端工具(Frontend tools):代理可以直接呼叫執行在使用者瀏覽器或 App 端的功能,例如讀取當前頁面表單內容、切換介面分頁,並把執行結果傳回後端。
- 人機協作(Human-in-the-loop):當代理準備執行高風險動作時,可發出帶有
interrupt中斷結果的事件暫停執行。前端會跳出核准、編輯參數或拒絕的按鈕,待使用者確認後再於下一輪執行接續完成。 - 推理與子代理歸屬:透過推理事件家族,前端能選擇性展示模型的思考草稿,並藉由
REASONING_ENCRYPTED_VALUE安全往返加密推理狀態;當系統發生巢狀委派時,每個事件都會清楚標記所屬的子代理執行緒,讓介面能分別呈現各子代理的進度。
傳輸無關與跨框架整合:從 LangChain 到企業級雲端
為了避免協定被單一網路技術綁死,AG-UI 在設計上刻意保持「傳輸層無關」(Transport-agnostic)。
官方規格同時定義了最普遍的 HTTP + SSE(Server-Sent Events,伺服器推送事件)純文字串流綁定,以及針對高吞吐量與低延遲場景設計的二進位 HTTP + Protobuf 綁定。如果團隊的基礎設施已經採用 WebSockets 或 Webhook,也能透過中介層直接轉接。
這套標準化的好處,很快反映在主流 AI 框架的支援廣度上。根據官方列出的整合清單,AG-UI 已被 Google、Microsoft、Amazon 與 Oracle 等大型企業採用或納入手冊,並內建於眾多主流開源代理框架中。
目前官方支援的合作夥伴與內建整合涵蓋 LangChain、CrewAI、Microsoft Agent Framework、Google ADK、Google Antigravity、AWS Strands Agents、Mastra、Pydantic AI、LlamaIndex、Agno、AG2、Claude Agent SDK、Claude Managed Agents、IBM watsonx Orchestrate、Spring AI、Cloudflare Agents 與 OpenAI Agents 等,甚至也能直接部署在 Amazon Bedrock AgentCore 執行環境中。
在客戶端呈現方面,AG-UI 同樣不限定前端技術棧。開發者除了能搭配 CopilotKit 支援 React、Angular、Vue 與 React Native,還能使用官方提供的 Slack 與 Microsoft Teams 頻道套件,或直接寫入終端機介面。
目前社群也已貢獻 Kotlin、Go、Java、Dart、Rust、Ruby、C++ 與 Swift 等多語言非官方 SDK,讓行動裝置與桌面原生應用都能講同一套語言。
延伸閱讀:GitHub 公開 Agent Host Protocol(AHP):跨編輯器、手機與雲端的 AI 工作階段怎麼接續?
開發者如何上手:從腳手架到 30 行伺服器
對於想快速體驗 AG-UI 的開發者,官方提供兩種截然不同的切入方式,無論團隊偏好全套框架還是極簡自建都能快速啟動。
最省事的路線是執行官方腳手架指令 npx create-ag-ui-app@latest。它會引導開發者選擇後端偏好的代理框架,並自動建立一套接好 Next.js 與 CopilotKit 或終端機介面的完整範本專案,設定好模型金鑰後即可在本機啟動測試。
如果團隊不想依賴任何龐大的應用框架,也可以直接用約 30 行程式碼實作協定本身。在官方示範的 Python FastAPI 範例中,伺服器端只需安裝 ag-ui-protocol,接收前端傳來的 RunAgentInput 後,透過 EventEncoder 依序輸出 RunStartedEvent、TextMessageStartEvent、TextMessageContentEvent 與 RunFinishedEvent 即可完成串流。
另一頭的 TypeScript 前端客戶端,則只需安裝 @ag-ui/client 並建立 HttpAgent 實例,掛上對應的事件回呼函式就能開始接收資料。由於前端只認得 AG-UI 標準事件,未來後端無論換成 Pydantic AI、LangGraph 還是自研腳本,前端程式碼幾乎不需要改動一行。
至於什麼樣的團隊最適合導入 AG-UI?如果你的產品只需要單純的一問一答文字客服,傳統 REST API 或簡易 SSE 就已足夠;但只要系統涉及多步驟工具視覺化、前後端共享畫布狀態、人工審核中斷,或是未來可能需要更換後端代理框架,越早採用標準化的事件協定,後續維護成本就越低。
企業實務導入與中介層轉接策略
在企業實際導入 AI 代理的過程中,許多團隊手邊已經有跑在生產環境的舊版代理服務,不可能為了換協定就把所有後端程式碼全部重寫。AG-UI 對此在官方倉庫中提供了完整的 integrations/ 與 middlewares/ 範本與轉接層。
透過輕量級的中介層(Middleware),開發者可以把既有框架輸出的串流格式,即時翻譯成標準的 AG-UI 事件再送往前端。這樣一來,前端團隊可以先統一改寫成標準化的事件接收器,後端團隊則能分階段替換或升級底層模型與代理引擎,完全不會互相卡住開發進度。
此外,對於需要同時支援多租戶或多種客戶端的產品團隊來說,AG-UI 的事件驅動模型也更容易做統一的稽核與監控。因為每一次工具呼叫、參數傳遞與人工核准中斷都對應到明確的事件名稱與識別碼,團隊只需在事件匯流排上掛載紀錄器,就能完整重現代理在前端畫面上的每一步互動軌跡。
常見問題(FAQ)
Q1:已經用了 MCP 或 A2A,還需要導入 AG-UI 嗎?
需要,因為三者解決的是不同問題。MCP 讓代理存取外部工具與資料,A2A 讓多個代理彼此溝通協作,而 AG-UI 專門處理代理與使用者介面之間的雙向互動,包括串流文字、共享畫面狀態與人工審核暫停。一個完整的代理應用通常會同時搭配這三種協定。
Q2:AG-UI 一定要搭配 CopilotKit 前端框架才能使用嗎?
不需要。雖然 AG-UI 由 CopilotKit 團隊發起,但協定本身與 SDK 完全獨立且開源於 MIT 授權下。開發者可以直接使用官方 @ag-ui/client、Python 或 .NET SDK 自行渲染畫面,或是對接終端機、Slack、Teams 與各類原生行動應用。
Q3:AG-UI 1.0 與早期的 0.x 版本相容嗎?
根據官方 1.0 規格說明,AG-UI 1.0 具備雙向向後相容性,也就是 0.x 版本的代理伺服器可以正常服務 1.0 客戶端,而 1.0 版本的代理也能與 0.x 客戶端順利互動,團隊可依自身節奏分批升級。
Q4:如果我的應用需要極低延遲,SSE 會不會成為瓶頸?
AG-UI 屬於傳輸層無關的協定。除了網頁開發最容易除錯的 HTTP + SSE 模式外,1.0 規格也正式提供二進位編碼的 HTTP + Protobuf 傳輸綁定,適合對傳輸體積與效能要求較高的微服務或原生應用場景。
總結
AI 代理正從單純的聊天機器人,演進為能操作介面、調度子代理並與人類即時協作的複雜軟體系統。過去讓工程團隊耗費大量時間的「前後端對接膠水碼」,在 AG-UI 1.0 推出後終於有了清晰、中立且跨框架的共通語言。
透過將執行生命週期、工具呼叫、JSON Patch 共享狀態、人機協作中斷與子代理歸屬全部標準化為 31 種事件,AG-UI 讓後端專心把代理邏輯做好,前端專心打磨互動體驗,真正實現「任何代理都能接上任何應用」的模組化願景。
想進一步評估是否適合自家專案,建議直接前往 AG-UI Dojo 互動展示平台試玩八大功能範例,或閱讀官方 1.0 規格文件並透過腳手架在本機跑起第一個範例。