AG-UI 1.0 開源協定正式凍結:代理與前端講同一套事件串流

由 CopilotKit 團隊發起、MIT 授權的 AG-UI 協定已在 2026 年 9 月 17 日凍結為 1.0 穩定版,把代理對前端的互動收斂成 31 種事件、8 個家族的單一雙向串流。雙權威治理設計、有到期日的相容翻譯層,以及凍結兩個月後的生態現況,是採用前該看懂的三件事。

用 AI 摘要這篇文章:

代理應用的協定地圖,在 2026 年補上了最後一塊明確的拼圖。由 CopilotKit 團隊發起、MIT 授權的 AG-UI(Agent User Interaction Protocol,代理與使用者互動協定),已經在 2026 年 9 月 17 日把規格凍結為 1.0 穩定版:整份協定由一份 JSON Schema 定義結構,把代理對前端的全部互動收斂成「一個請求進、一列帶型別的事件出」的雙向串流,事件型別共 31 種、分屬 8 個家族。截至 2026 年 11 月 19 日,專案在 GitHub 已累積 20,490 顆星、2,107 次 fork,TypeScript 官方套件已迭代到 1.0.5(2026 年 11 月 17 日發布),文件站甚至已經掛出 1.1 草稿版本頁。

AG-UI 官方規格文件頁面,標題為 Specification,副標說明這是 AG-UI 協定 1.0 版的行為規範Pin
AG-UI 1.0 規格文件首頁:開宗明義定義協定行為採 BCP 14 的 MUST、MUST NOT 語言,結構則以 JSON Schema 為權威。

這則新聞值得放在時間軸上看。AG-UI 不是剛冒出來的實驗品:官方文件的更新紀錄顯示,倉庫早在 2025 年 4 月 9 日就公開,之後經歷了約 17 個月的 0.x 演進,才在 9 月中旬由一條名為「freeze the draft as 1.0」的提交把草稿定格。對正在規劃代理應用前後端架構的團隊來說,現在真正的問題已經從「要不要賭一套新標準」變成「這份凍結契約的治理設計禁得起什麼、扛不住什麼」。

代理協定棧補上了缺的那一層

過去兩年,代理生態先後長出兩套開放協定:MCP(Model Context Protocol)讓代理連向工具與資料來源(我們先前實測過的 mcp-use 開源庫就是在這一層把 LLM 接上 MCP 伺服器),由 Anthropic 在 2024 年 11 月提出;A2A(Agent2Agent)讓代理連向其他代理,由 Google 發起、如今是以 Linux Foundation 專案的形式運作。AG-UI 官方文件把自家協定定位為這張地圖上的第三層:代理連向使用者介面。三者互補,一個成熟的代理應用常常同時用上全部三層。

這個分工之所以重要,是因為它回答了一個經常被誤解的問題:AG-UI 要不要取代 MCP 或 A2A?官方文件的答案很直接:不要,也輪不到。MCP 管代理怎麼讀資料庫、怎麼呼叫搜尋引擎;A2A 管多個代理怎麼互相委派任務;AG-UI 管的是代理執行過程怎麼即時呈現在使用者眼前,以及使用者的點擊、編輯、核准怎麼傳回後端。文件還特別劃清了與 A2UI、MCP Apps、Open-JSON-UI 這類「生成式介面規格」的界線:那些規格描述畫面上要長出什麼元件,AG-UI 則是把這些描述連同文字、工具呼叫與狀態更新一起送到前端的執行期傳輸協定。換句話說,前者決定內容,後者負責運送。

協定連接的兩端發起與治理主體
MCP代理對工具與資料來源Anthropic(2024 年 11 月)
A2A代理對代理Google 發起,現屬 Linux Foundation
AG-UI 1.0代理對使用者介面CopilotKit 團隊,MIT 授權

一個請求進去,31 種事件出來

AG-UI 的核心模型可以用一句話講完:前端送出一份名為 RunAgentInput 的標準輸入,裡面裝著對話歷史、前端可提供代理呼叫的工具清單、共享狀態與上下文;後端代理收到後,透過持續開啟的連線依序串流回帶型別的事件物件。1.0 規格把事件分成 8 個家族,合計 31 種型別,這個數字對應官方倉庫 spec/1.0/schema.json 中 EventType 列舉的成員總數。

事件家族代表事件誰來消費
執行生命週期RUN_STARTED、RUN_FINISHED、RUN_ERROR、STEP_*客戶端本身
文字訊息TEXT_MESSAGE_*介面層
工具呼叫TOOL_CALL_*應用層
推理過程REASONING_*、REASONING_ENCRYPTED_VALUE介面層
共享狀態STATE_SNAPSHOT、STATE_DELTA、MESSAGES_SNAPSHOT應用的狀態儲存
活動進度ACTIVITY_SNAPSHOT、ACTIVITY_DELTA介面層
子代理SUBAGENT_STARTED、SUBAGENT_FINISHED、SUBAGENT_ERROR客戶端本身
透傳RAW、CUSTOM應用層(自行選擇)

設計上最值得注意的取捨是:規格只強制實作方發出執行生命週期事件,其餘七個家族全都是「有東西要說才發」的選配功能。這代表一個只會回字的簡單代理,發出 RUN_STARTED、幾個文字事件、RUN_FINISHED 就算符合規格;等到需要共享畫布狀態、前端工具或子代理協作,再逐家族補上即可。狀態同步採快照加增量的雙軌制:初次連線傳完整 STATE_SNAPSHOT,之後的細微變動用 STATE_DELTA 搭配標準 JSON Patch 描述,避免每次微調都重傳整份資料。推理家族還內建了 REASONING_ENCRYPTED_VALUE,讓加密的推理產物可以在前後端之間往返存放而不被讀取內容;巢狀委派發生時,每個事件都會標上所屬的子代理執行識別碼,介面才能分別呈現各個子代理的進度。

人工審核的中斷機制也標準化了。代理準備執行高風險動作時,執行會以帶 interrupt 結果的方式收尾,事件裡帶著它在等待什麼;前端跳出核准、修改參數或拒絕的選項,使用者的決定放進下一輪 RunAgentInput 的接續欄位,執行從暫停點繼續。工具回傳也不再只能是一段字串:TOOL_CALL_RESULT 的內容欄位接受字串或有序的內容段落清單,工具可以直接回一份文件、一張圖片或一筆搜尋結果,不必硬塞成文字。

從 0.x 到 1.0:行為規則第一次寫成白紙黑字

對已經在 0.x 上跑產品的團隊,1.0 真正的改動不是事件清單換血,而是「規格文件本身的存在」。官方變更紀錄寫得很直白:0.x 只定義了資料形狀,行為規則其實活在 TypeScript 客戶端的實作裡;1.0 把順序、未知與不合法的區別、警告時機全部寫成規範性條文。幾個具體差異值得記下:舊的五個 THINKING_* 事件退休,改由推理家族接手;RUN_FINISHED 可帶上結束結果(成功、中斷或取消,未標示即視為成功);能力宣告從三份手寫副本收進 schema 統一定義;「遇到不認識的事件或欄位怎麼辦」從各自表述變成規則:未識別的內容會存活到執行過濾階段、被剝除時要發警告,而已知的欄位帶不合法值則直接判定為嚴重錯誤。

凍結不是口號:這份規格怎麼裁決爭議

很多協定都說自己「穩定」,AG-UI 1.0 比較少被討論的一面,是它對治理細節的較真。規格開宗明義把權威切成兩半:JSON Schema 對「結構」有絕對權威,哪個欄位存在、什麼型別、必填與否,以 schema 為準;規格文件對「行為」有絕對權威,事件順序、未知值怎麼處理、何時該發警告,以文件為準,而且全程用 BCP 14 的 MUST、MUST NOT 語言寫成。文件甚至預先寫下了裁決規則:若兩者對結構各說各話,schema 贏,規格文件算有 bug。這種把「誰說了算」寫進文件的作法,讓爭議一出現就有明確的裁決路徑。

同樣的較真也出現在二進位傳輸。1.0 除了定義好除錯的 HTTP 加 SSE 純文字綁定,也正式規範了 HTTP 加 Protobuf 的二進位綁定,並在倉庫裡用一份名為 proto-freeze.txt 的檔案凍結 Protobuf 的欄位編號:每個欄位佔用哪個編號由產生器自動指派,欄位退役後編號改為保留,沒有人可以手工改號。版本協商同樣內建在協定裡,不依賴傳輸層:消費端在 RunAgentInput.protocolVersion 聲明自己講的版本,產生端在 RUN_STARTED.protocolVersion 回報自己的版本,雙方各報各的,一份錄製下來的事件流因此可以自行判讀當時的版本組合,對事後稽核相當友善。

雙向相容是真的,但翻譯層有到期日

官方 README 以醒目區塊宣稱:1.0 具備雙向相容性,0.x 的代理可以服務 1.0 的客戶端,反之亦然。這個宣稱有具體機制支撐:以 TypeScript 客戶端為例,它內建一個常駐的相容邊界,遇到 0.x 退休形狀(例如舊的五個 THINKING_* 事件)會自動翻譯成對應的 REASONING_* 事件,而不是直接丟棄。1.0 新增的東西也刻意設計成加法:新的選填欄位、新的事件型別,舊客戶端看到不認識的內容會讓它存活、不中斷執行。

但閱讀規格的版本相容章節會發現一個容易被忽略的但書:退休形狀的翻譯是有期限的。規格要求每個退休形狀登錄在棄用清單上,註明替代品、翻譯位置與翻譯本身的到期日;到期之後,實作可以移除翻譯層,屆時舊形狀就被當成一般未識別內容處理。相容章節也明確區分兩種降級:無損降級可以安靜地做,有損降級(例如丟掉某個內容段落)必須發出指名失去什麼的警告,而且預設不得靜音。對打算長期維運的團隊來說,結論很實際:雙向相容是官方承諾,但它是靠會過期的翻譯層兌現的,升級節奏拖太久的專案,該定期回來看棄用清單的到期日,而不是把「1.0 相容」當成永久保證。

既有後端不想整套重寫,官方倉庫也留了漸進路徑:integrations 與 middlewares 兩個目錄收了各框架的轉接層範本,中介層可以把舊框架輸出的串流格式即時翻成標準事件再送往前端,讓前端先統一、後端慢慢換。

從時間線看:凍結兩個月後,生態鋪到了哪裡

把公開紀錄排成一列,可以看出這個專案的推進速度。2025 年 4 月 9 日倉庫公開;2026 年 9 月 17 日規格凍結,同日 npm 的 @ag-ui/client 與 PyPI 的 ag-ui-protocol 都送上 1.0.0;之後 TypeScript 套件在兩個月內連發 1.0.1 到 1.0.5 五個修訂版,最新一版落在 11 月 17 日,倉庫最後一次推送是 11 月 18 日,文件站的版本選單已經出現 1.1 草稿頁。Python 套件目前停留在 1.0.0,需要 Python 3.9 以上。

生態面,官方 README 宣稱協定已獲 Google、Microsoft、Amazon 與 Oracle 採用,整合清單列出 20 個以上的框架與環境:LangChain、CrewAI、Microsoft Agent Framework、Google ADK、AWS Strands Agents、Mastra、Pydantic AI、LlamaIndex、Agno、AG2、Claude Agent SDK、IBM watsonx Orchestrate、Spring AI、Cloudflare Agents、OpenAI Agents 等,甚至可直接部署到 Amazon Bedrock AgentCore。其中幾個名字對 TechMoon 讀者不陌生:我們先前介紹過的 Mastra 開源代理框架已把 AG-UI 內建為傳輸層選項,Pydantic AI 的 Peers 代理訊息功能所屬的 Pydantic AI 也在清單上。要注意的是,這份清單屬官方自報,「採用」在各公司內部的實際部署規模並沒有公開資料佐證,官方也為每個框架在 Dojo 展示平台準備了可動手試的線上範例。

AG-UI Dojo 互動展示平台首頁,左側為整合與精選範例清單,右側為可直接試用的聊天介面Pin
AG-UI Dojo 互動展示平台(2026 年 11 月 19 日):左欄可切換各框架整合與功能範例,右側是可直接對話的實際 demo。

想實際摸一下協定本身,門檻刻意壓得很低。求快的人跑 npx create-ag-ui-app@latest,選一個偏好的代理框架就得到一套接好前後端的範本,範本預設呼叫 OpenAI 的模型,填好金鑰就能在本機啟動;不想要大框架的人,官方在 README 裡示範了用 Python FastAPI 手寫一個約 30 行的代理伺服器,安裝 ag-ui-protocol 套件後,依序輸出執行開始、文字訊息、執行結束幾個事件就能跑通最小流程,而且這條路完全不需要 API 金鑰。 TypeScript 端裝 @ag-ui/client、.NET 端裝 AGUI.Client,社群另外貢獻了 Kotlin、Go、Java、Dart、Rust、Ruby、C++ 與 Swift 等八種語言的 SDK。前端呈現也不綁死在單一技術棧:CopilotKit 支援 React、Angular、Vue 與 React Native,另有 Slack 與 Microsoft Teams 頻道套件,終端機介面也有官方文件。

採用前該知道的未定事項

以上都是可核對的公開事實,但有幾件事在採用決策裡仍屬未知。1.1 草稿目前只累積了兩個小幅加法(加密推理值的型別標註、串流工具結果可回報失敗)、尚無重大變更,官方也言明尚無任何 SDK 實作;.NET SDK 的版本細節請以官方釋出紀錄為準;各種語言 SDK 對 1.0 的符合度落差,規格提供了測試素材集(fixtures)與一致性(conformance)目錄,但沒有公開的跨實作評比報告。另外,協定本身不解決安全問題:規格在安全章節明言,它把模型輸出變成應用程式的動作,工具呼叫會變成實際執行、狀態事件會變成寫入,同意與防護的責任留在實作方手上,導入時的前端工具權限設計仍需自行把關。

整體判斷:AG-UI 1.0 的價值在於把「代理怎麼跟人互動」這一層從各框架的私有膠水碼,變成一份有權威切分、有凍結機制、有明確相容契約(連但書都寫清楚)的開放規格。如果你的代理應用已經或即將出現多步驟工具視覺化、前後端共享狀態、人工審核中斷這類需求,現在把介面層對齊 AG-UI 的事件模型,換框架時的介面重寫成本會明顯下降;如果產品只是單純的一問一答,傳統請求回應加簡單串流依然夠用,不必為了採用標準而採用標準。

Sliven 褚崇名
Sliven 褚崇名

每日分享科技新知、免費資源以及 WordPress、虛擬主機相關主題,任何問題歡迎在科技月球下方留言,或是發送 Email 至 [email protected] 與我聯繫。

文章: 2571

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *


Share to...