跳到主要內容

【2026 最新】AG-UI 串流排錯:少最後一句怎麼查?三組 Mock Chunk 實作教學

最後更新: ·
AG-UI 串流排錯:三組 Mock Chunk 檢查結束訊號與尾段內容

回答一段段出現在畫面,最後卻少了一句;重新讀取對話,又看見完整答案。做 AG-UI 串流排錯,先別急著改提示詞:最後一塊資料可能同時裝著「結束訊號」與「還沒送出的文字」。

這篇寫給第一次看 Agent 串流紀錄、願意複製終端機指令的讀者。先用包裹比喻理解原理,再用空尾塊、文字尾塊、工具參數尾塊三組 Mock(人為指定的假資料),學會分辨內容遺失、重複事件與收尾問題。動手段落需已有 Python 3.12、Git 與可安裝 Python 套件的環境。

AlphaLab 於 2026 年 11 月 21 日,以固定主分支與 PR commit 執行上游回歸測試,另保存三組事件 trace。測試使用假模型事件,未連接 GLM 或其他模型端點;下文把實際測得的 adapter 行為、原回報者的觀察與建議驗收分開。

先說結論:結束訊號不等於空內容

AG-UI 串流排錯的把手:先驗內容,再驗收尾。像最後一箱貨外面貼著「配送結束」,箱子裡仍可能有商品。看到標籤就把整箱丟掉,倉庫帳本有貨,收件人卻少收到一件。這是比喻,不是 AG-UI 的正式公式。

  • 空結束塊是控制組:維持正常結束,不平白多送內容或提前關閉。
  • 帶文字的結束塊:保留文字順序,最後一段也要出現在事件串流。
  • 帶工具參數的結束塊:拼回完整參數,另驗事件生命週期、JSON 與用途。

一、AG-UI 串流排錯先看三份帳本

AG-UI 官方介紹把它定位為連接 Agent 後端與使用者介面的事件協定。這裡的 adapter 是「轉接員」:把 LangGraph/模型送來的片段,轉成前端能讀的 AG-UI 事件。模型寫出來、轉接員送出去、畫面顯示出來,是三個要分別核對的結果。

第一份帳本是原始 Chunk:保存本次片段的 content、response_metadata.finish_reason、tool_call_chunks 與實際存在的用量。第二份是AG-UI 事件:同一個 messageId 的文字 delta 按序接起來;工具參數則按 toolCallId 接起來。Delta 就是「這次新增的一小段」。

第三份是 MESSAGES_SNAPSHOT,即訊息列表的快照。官方事件文件把它與逐段文字事件分開定義。排查時,以同一則訊息或工具呼叫的識別碼比對;別拿不同執行、不同對話的完整答案來補同一欄。

若原始片段有尾字、AG-UI delta 沒有,先查轉接層;若事件已有、畫面沒有,再查前端累積與渲染。若連原始片段都缺,就回到更上游。這是定位程序,尚不能靠其中一個畫面替根因定案。一般 HTTP/SSE/工具錯誤的分層,可先讀AI 錯誤排查四層教學。

二、這次回報指出哪一道門?先對版本

GitHub #3428於 2026 年 11 月 20 日指出 Python LangGraph adapter 的一條提前返回路徑。同日一位回報者描述自己的 OpenAI 相容端點會在最後一塊一起帶文字與 finish_reason;他明確說工具參數尾塊尚未在該環境重現。後者是待測情境,不能借用前者當成實證。

AlphaLab 核對的固定主分支原始碼,會先記錄用量,再處理內部模型呼叫的過濾,接著在 finish_reason 為真時返回;後面的文字與工具處理因此沒有走到。這個結論只綁定本文固定的程式版本。

截至 2026 年 11 月 21 日查閱,修補 PR #3431仍為 Open、尚未合併;PyPI 的 ag-ui-langgraph列為 0.0.47。PR 測試通過、合併完成、套件發布,是三張不同收據。本文比較原始碼 commit,不把同版號套件或 TypeScript adapter 一起宣稱修好。

三、三組 Mock Chunk:把最後一箱拆開看

① 空結束塊:「沒有新貨,只是打烊」

怕修補後多出事件?先留控制組。先送 Hello ,再送 content=""、finish_reason="stop" 與用量,最後送模型結束事件。驗收重點是文字維持原樣,且文字串流只有一次開始、一次結束。另用 content=[] 測空列表,避免把字串與內容區塊混為一談。

② 文字結束塊:「最後一句就在箱裡」

先送 Hello ,最後一塊改成 world! 並附 finish_reason="stop"。同一則訊息的兩個文字 delta 應依序組成 Hello world!。本次主分支自訂 trace 只累積到前段,PR trace 則保留兩段;兩邊文字案例的總用量皆保留 17。這個 17 是指定假資料,不是模型帳單。

③ 工具參數結束塊:「括號還在路上」

先開名為 search 的工具呼叫,接著送 {"q":,最後一塊送 "AG-UI"} 並附 finish_reason="tool_calls"。本次主分支 trace 留下前綴,PR trace 可組成 {"q":"AG-UI"};它驗的是假資料觸發的轉接流程,不代表真實端點一定用這種切塊方式。

依官方工具事件規格,參數片段由 TOOL_CALL_ARGS 延伸;收到 TOOL_CALL_END 前先不執行。結束代表參數傳送告一段落,語法與參數值還要驗。這裡只用假搜尋資料,不接寄信、刪檔或交易工具;完整 JSON 也不會自動變成操作授權。

AG-UI 串流排錯三組 Mock 尾塊與固定 commit 回歸測試結果
AlphaLab 隔離環境的 Mock 結果:比較固定主分支與 PR commit,非真實模型端點或正式前端成績。

四、動手跑:固定測試,再換程式

下面使用 macOS/Linux shell,在全新練習目錄操作。checkout --detach 會切換工作樹,所以只對這份新 clone 執行,別在自己尚未保存的專案中照貼。先執行 python3.12 --version、git --version;版本或網路環境不齊,就先閱讀三組輸入與斷言,不必連付費模型。

git clone https://github.com/ag-ui-protocol/ag-ui.git agui-tail-lab
cd agui-tail-lab
git checkout --detach 1de7b12898f2aadd17fb0f03cbbe96dd2c07ddc9
cd integrations/langgraph/python
python3.12 -m venv .venv
.venv/bin/python -m pip install "ag-ui-langgraph[fastapi]==0.0.47" "pytest==9.2.0" "langchain==1.5.2" "langchain-core==1.8.4" "langgraph==1.2.24" "ag-ui-protocol==1.0.0" "pydantic==2.14.4" "fastapi==0.165.0"

這個隔離環境提供依賴;在套件原始碼目錄執行時,匯入的是該 checkout 的 ag_ui_langgraph。FastAPI 明確列入,是為了讓本次版本的 endpoint 匯入能完成,不是要啟動公開伺服器。其他傳遞依賴仍會解析,請保存自己的完整 freeze;本文實測另保留全部依賴版本。

從固定 PR commit 取得同一份測試。這個連結是可閱讀的 Python 測試檔;先查看再存成下列檔名,不要把網頁錯誤頁當 Python 執行。

curl -fL https://raw.githubusercontent.com/brixtonpham/ag-ui/c41dd8c35ef806c37e13605a320324d1ee1dca16/integrations/langgraph/python/tests/test_finish_reason_chunk_content.py -o tests/test_finish_reason_chunk_content.py
.venv/bin/python -m pip freeze
.venv/bin/python -m pytest tests/test_finish_reason_chunk_content.py -q --junitxml=before.xml

將 freeze 輸出複製到依賴筆記。pytest 的 --junitxml 會產生可由編輯器或 CI 讀取的測試報告,操作見官方報告輸出文件;既有同名檔會被取代,所以這裡使用全新練習目錄。本次相同測試在固定主分支得到 8 失敗、6 通過。失敗在這裡是要保留的基準,先讀斷言差異,再判斷是不是同一個尾塊問題;匯入失敗或測試根本沒收集到,不算重現成功。

接著仍在同一個套件目錄,取得固定 PR commit,確認工作樹只含剛才新增的測試與紀錄,再切換。fetch 取得的是提案程式;這一步僅作隔離比較。

mv tests/test_finish_reason_chunk_content.py baseline-finish-reason-test.py
git fetch origin refs/pull/3431/head
git checkout --detach c41dd8c35ef806c37e13605a320324d1ee1dca16
cmp baseline-finish-reason-test.py tests/test_finish_reason_chunk_content.py
.venv/bin/python -m pytest tests/test_finish_reason_chunk_content.py -q --junitxml=after.xml

本次 PR commit 得到 14 通過。測試檔還涵蓋列表文字、原始 dict、關閉文字發送、推理資料與空尾塊;PR 摘要曾寫 12 題,本文以實際取得並執行的 14 題為準。要聚焦三類,可加 -k "empty_finish_reason or trailing_text_on_finish_reason or tool_call_args_continuation",但發布前仍跑完整檔案。

五、修補驗收:文字、生命週期與快照分開簽收

修補方向是讓有內容的尾塊走內容處理,而純收尾塊保留既有行為。不要把「先處理」簡化成整段搬到所有過濾前:內部模型呼叫、emit-messages 與工具設定仍要被尊重;用量記錄也要留在能涵蓋尾塊的位置。直接採用 PR 前,先檢查其實際差異與測試。

  • 內容:按識別碼接回所有文字或參數,不漏尾段、不把快照再追加一次。
  • 生命週期:本文三個單一串流案例各只有一次 START/END;另外測取消、錯誤與多工具情境。
  • 用量:檢查 RUN_FINISHED 的用量收據;避免改流程後重複記帳。
  • 快照:在自己的測試提供有內容的最終 state,按相同訊息 ID 對照全文與工具參數。

最後一項刻意獨立:本次自訂三組 trace 的 state mock 為空,因此沒有測得「完整快照補回答案」。原回報描述的快照行為保留其歸屬;實際應用仍須建立有內容的 state fixture。快照像盤點表,可以協助對帳,不能把盤點表整頁再接到已收貨清單後面。

本文建議按 ID 做明確的覆核/取代策略,並測同一份快照重送時畫面維持一致。這是應用端設計;AG-UI 事件抵達,不代表你的 reducer 已正確處理。串流斷線與重試的狀態保存,另見OpenUI 串流復原教學;兩者處理的是不同故障層。

回退時,保留 before.xml/after.xml、原 commit 與依賴收據。這個練習回到原 commit 並重跑同一份測試即可比較;正式服務則應部署回已驗證的建置產物與其依賴,先在小流量驗收。等修補有正式發布,再核對發布內容並用自己的 fixture 重跑,別把 pip install -U 當成已修復證據。

常見問題:八個直接答案

快照完整,就能忽略串流漏字嗎?

要看產品契約。逐字顯示與工具卡可能在快照之前就被使用;應分開驗收串流完整性與最後狀態。

每個 finish_reason 都代表空片段嗎?

先看同一塊內容。本次文字 Mock 在同一塊帶結束原因與非空文字,固定主分支因此漏掉尾段。

工具參數案例已在 GLM 端點重現了嗎?

本次只驗 Mock。原回報者也說未在自己的端點重現該工具尾塊情境;不要把兩者合成真模型結論。

JSON 能解析,就可以執行工具嗎?

還要驗參數結構、允許值與權限。傳輸完成與授權完成是不同條件;副作用操作另設明確門禁。

14 題全過,代表整個應用沒問題嗎?

只涵蓋這份固定測試。實際前端、網路中斷、並行工具與真實供應商要另留整合驗收。

PR 測試通過,就直接升級正式套件嗎?

先查發布。本文查閱時 PR 尚未合併;commit、版本號與發布內容應逐一對上。

空尾塊直接刪掉就好嗎?

先保留控制組。收尾與用量各有責任;測文字不變、收尾不提前、用量仍存在,再評估處理方式。

完全新手今天先做到哪裡?

先畫三欄:原始 Chunk、事件、最終 state。用 Hello 與 world! 指出在哪欄少了尾段,再請能執行測試的人補上版本與 trace。

給新手的三個重點

  • 結束訊號與內容分開判讀:最後一箱仍可能有貨。
  • Mock 證明指定流程,真實端點與前端另驗;快照要用有內容的 state。
  • 同一份測試比較兩個固定版本,保留失敗、用量與回退收據。

接著閱讀

左右滑動查看更多推薦

下一步:先讓最後一段有自己的測試

今天先完成文字尾塊,再保留空尾塊控制組,最後加上工具參數。三張測試收據都能說清楚輸入、版本、輸出與邊界,才擴展到自己的應用。記住:先驗內容,再驗收尾。你要找的不是「最後看起來對了」,而是每一層都能對得上。

想繼續把這套排錯方法接進專案,可從AI 專區補齊需要的觀念,或到AlphaLab 課程安排一個能用假資料完成驗收的小專案。

ALPHALAB 社群

有問題?來 Telegram 聊

和 Terry、編輯、其他網友一起討論這篇文章。提問、分享觀點,回覆更即時。

加入 Telegram 討論

📩 訂閱 AlphaLab 電子報

週日 Weekly 週報+週二、週四 Alpha Signal,每週最多三封。

我們不會 spam,隨時可退訂。已訂閱?管理訂閱偏好(會寄登入連結到你的信箱)

主題篩選與退訂說明

寄送日期以台灣時間為準。主題偏好會篩選每期精選,並非每篇新文章的即時通知;當期符合主題的文章不足時會略過寄送。

未勾選任何主題會收到所有主題的精選,並不會停止寄信。

取消勾選 Alpha Signal 可停止週二、週四短報,仍保留週日週報。若要停止所有電子報,請使用信件底部的「取消訂閱」。