回答一段段出現在畫面,最後卻少了一句;重新讀取對話,又看見完整答案。做 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 也不會自動變成操作授權。

四、動手跑:固定測試,再換程式
下面使用 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 課程安排一個能用假資料完成驗收的小專案。






