2026 AI Agent 總產出壞 JSON？按資料流定位問題

2026 年 8 月 20 日 · AI Agent · 約 16 分鐘閱讀

這篇文章寫給正在處理 JSON 解析失敗、工具參數錯誤與多步驟結果遺失的開發及維運團隊。文章沿著輸入契約、模型生成、API 回應、解析驗證、工具執行與結果回傳逐段定位根因，並提供對照表、最小重現流程與日誌欄位建議。

遇到 AI Agent JSON 錯誤時，先不要把責任歸因於模型；應沿著「輸入契約—模型生成—API 回應—解析驗證—工具執行—結果回傳」逐段定位，平台若支援嚴格結構化輸出，先啟用該能力，再保留應用程式層的語意驗證。這套方法適用於 API 回傳無法解析、Function Calling 缺少參數、工具執行失敗，以及多步驟 Agent 執行到中途遺失上下文的情況。

這篇文章適合三類讀者：

被解析錯誤困住的後端開發者，可按照錯誤出現的位置縮小範圍。
維護多步驟 Agent 的工程師，需要確認呼叫識別碼、工具結果與必要上下文是否原樣回傳。
負責生產事故的維運人員，需要建立可關聯的呼叫日誌，而不是靠無限重試掩蓋根因。

先用一條失敗資料流還原問題

一個典型故障可能長這樣：Agent 應該產生工具參數，API 回應看似成功，但應用程式收到的內容不是可解析 JSON；團隊於是增加重試次數，下一次雖然得到合法 JSON，工具卻因路徑不存在或帳號沒有權限而失敗。若只看最後一個錯誤訊息，就會把格式問題、平台狀態與業務問題混在一起。

排障時可把每次呼叫拆成六個可觀測節點：

輸入契約：Schema 是否能被平台接受，欄位是否完整。
模型生成：模型是否產生拒絕、截斷或不完整的內容。
API 回應：回應是否包含成功狀態、停止原因、呼叫識別碼或錯誤物件。
解析與驗證：解析器是否使用正確的 JSON Schema 方言與驗證規則。
工具執行：參數結構合法，是否仍符合權限、資源與業務範圍。
結果回傳：工具結果與原始呼叫識別碼是否完整交還給模型或下一個 Agent 節點。

先記錄故障落在哪個節點，再決定修正方向；不要先改提示詞，也不要先增加重試。

先讓最小 Schema 通過，再恢復業務約束

輸入契約本身被平台拒絕時，模型根本還沒有開始產生有效結果。第一輪應刪除非必要的巢狀結構、引用、複雜條件與過度嚴格的格式，只保留最少的必填欄位，確認平台接受後，再逐步恢復業務規則。

JSON Schema 並不是所有工具都用同一套方言或同一個支援子集。規範本身提供不同版本與宣告方式，$schema 會影響驗證器如何理解關鍵字；因此，Schema 檔案、平台要求與應用程式驗證器不能各自採用未記錄的預設值。可先參考 JSON Schema 規範版本說明與 $schema 宣告的基礎指南，再把實際使用的方言寫入版本控制。

建議按照以下順序檢查：

根節點是否為平台支援的物件型態。
Function Calling 的參數 Schema 是否與實際工具介面一致。
必填欄位是否真的在每個分支都會被填入。
enum、陣列、巢狀物件與格式限制是否在平台支援範圍內。
Schema 中的引用是否能被平台解析，而不是只在本地驗證器中有效。
開發與生產環境是否載入同一份 Schema 雜湊值。

Function Calling 缺少欄位時，先查契約而不是補字串

若 Function Calling 的參數少了欄位，應先比較三份資料：送出的工具定義、模型回傳的呼叫參數，以及工具執行器實際要求的輸入。三者只要有一份版本不同，就可能出現「模型輸出合法、工具卻拒絕」的情況。

工具呼叫通常不是單純把一段文字交給函式，而是由模型提出呼叫、應用程式執行工具，再把工具結果回傳至對話流程。可依照 Gemini Function Calling 官方流程說明核對呼叫與結果交接的順序。應用程式不應自行在 JSON 字串後面補逗號、預設帳號或缺少的路徑；這樣做會把契約錯誤變成更難追蹤的業務錯誤。

讀取拒絕與截斷狀態，不要直接交給解析器

模型回應被拒絕或內容遭截斷時，回應本文可能不是一份可供解析的 JSON。應用程式若無條件執行 JSON.parse 或等效解析，就只會得到表面上的格式錯誤，無法知道真正原因。

處理邏輯至少應分開以下狀態：

拒絕：保存拒絕狀態與必要的安全處理資訊，轉入人工確認或替代流程。
截斷：讀取停止原因與長度限制，判斷是輸出過長、串流未收完，還是傳輸中斷。
API 錯誤：保存 HTTP 狀態、錯誤類型與請求識別資訊，只有瞬時錯誤才考慮重試。
成功但內容不符契約：進入 Schema 驗證與語意驗證，不應與平台拒絕混為一談。

串流介面尤其不能只串接已收到的文字片段便立即解析。可參照 Responses API 串流拒絕狀態說明，確認拒絕資料、事件順序與完成狀態，再決定何時把內容交給解析器。若平台提供 Structured Output，仍要查看實際錯誤回應與拒絕情況；Structured Outputs 官方文件並不代表所有失敗都會被轉換成可直接執行的結果。

Structured Output 為什麼仍可能失敗

Structured Output 主要處理輸出結構是否符合指定 Schema，但它不能保證外部資源存在、帳號具備權限，也不能替應用程式完成跨欄位的商業規則。不同平台支援的型態與限制亦不完全相同，Gemini 的 Structured Output 支援類型與限制應與實際模型及介面版本對照。

因此，驗證應分成兩層：

結構驗證：確認 JSON 可解析、型態正確、必填欄位存在、列舉值有效。
語意驗證：確認日期範圍、欄位關係、資源狀態、權限與業務上限合理。

結構驗證失敗時，回到 Schema 或回應狀態；語意驗證失敗時，回到工具輸入與業務規則。兩者使用不同錯誤碼，後續處置才不會錯誤重試。

用對照表決定下一個排查節點

下表把症狀與可執行的下一步綁定，適合放入事故處理手冊。若無法判定，優先查看原始 API 回應，而不是只看最末端的解析例外。

症狀	優先檢查	不應先做的事	下一個決策
請求建立前即被拒絕	Schema 方言、必填欄位、平台支援子集	改提示詞、增加重試	先縮成最小 Schema，再逐項恢復約束
回應有拒絕或截斷狀態	停止原因、長度限制、串流完成事件	把本文直接送進解析器	分流處理拒絕、截斷與傳輸錯誤
JSON 解析成功但驗證失敗	驗證器版本、`$schema`、格式行為	直接刪掉驗證規則	固定方言並記錄驗證器版本
JSON 合法但工具拒絕	資源、權限、欄位關係、業務範圍	由程式偷偷補值	回傳明確業務錯誤，要求重新規劃
多步驟執行後上下文消失	呼叫識別碼、工具結果、必要訊息	只保留最後一段文字	按介面規則完整回傳狀態與結果

固定解析器方言，避免開發與生產各自解讀

「解析成功」不等於「依同一套規則驗證成功」。本地可能使用較新的驗證器，生產伺服器卻載入另一個版本；有些環境對格式關鍵字只做提示，有些環境則直接拒絕。這類差異會讓同一份 JSON 在測試與生產得到不同結果。

每次部署至少應記錄：

Schema 版本與 $schema 值。
驗證器套件版本與執行語言版本。
平台、模型、API 介面與 SDK 版本。
原始回應是否經過串流重組、字串清理或欄位轉換。
驗證失敗的路徑、關鍵字與實際值類型。

不要用正規表示式取代 JSON 解析，也不要為了讓驗證通過而把所有欄位轉成字串。若平台支援的 Schema 子集較小，可把平台層 Schema 與應用程式層語意規則分開維護，並用相同的最小案例驗收。

JSON 合法但業務仍失敗時，轉向工具執行層

JSON 合法但業務執行失敗，通常不是格式問題。下列情況即使通過 JSON Schema，也可能讓工具拒絕：

路徑格式正確，但檔案或目錄不存在。
帳號欄位存在，但呼叫憑證沒有對應權限。
訂單識別碼格式正確，但訂單已取消或不屬於目前租戶。
起訖時間都是合法字串，但結束時間早於開始時間。
數值型態正確，但超過業務允許範圍。
工具要求的欄位關係未被 Schema 表達，例如兩個欄位必須同時出現。

工具執行器應回傳可分類的業務錯誤，例如資源不存在、權限不足、狀態衝突或輸入超限，而不是只回傳「執行失敗」。這些結果若要交回模型，仍須保留原始呼叫識別碼與必要上下文，避免下一步把錯誤當成全新任務。

多步驟回傳時，保留識別碼與完整上下文

工具呼叫結果回傳後上下文丟失，常見原因不是模型記憶能力，而是應用程式只保存了工具輸出的文字，卻遺漏工具呼叫的名稱、識別碼、參數或前一輪必要訊息。多步驟 Agent 因此無法把結果對應回正確呼叫，後續可能重複執行或產生不相關的 JSON。

排查時應逐筆比較：

模型最初提出的工具呼叫結構。
應用程式實際送給工具執行器的內容。
工具執行器產生的結果與錯誤分類。
回傳模型時保留的呼叫識別碼、工具名稱與結果內容。
下一個模型回應所使用的完整狀態。

不同介面對狀態保存與訊息回傳的要求可能不同，不能把一個 API 的做法直接套到另一個 API。若 Agent 透過 MCP 連接工具，也應依 MCP 工具規範檢查工具名稱、輸入 Schema、結果格式與錯誤處理；完整的狀態語意則應一併參考 MCP 官方規範總覽。

用最小重現與統一日誌收尾

真正可修復的 AI Agent JSON 錯誤，必須能在脫離生產流量後重現。建議工程團隊建立一份脫敏案例，保留足以重建資料流的資訊，但移除個人資料、憑證、秘密金鑰與真實業務內容。

可勾選的收尾清單如下：

[ ] 保存脫敏後的輸入訊息、工具定義與 Schema。
[ ] 記錄模型、API 介面、SDK、驗證器與部署版本。
[ ] 保存原始 API 回應及串流完成、拒絕或截斷狀態。
[ ] 記錄解析結果、驗證錯誤路徑與實際欄位類型。
[ ] 記錄工具執行參數、資源查詢結果、權限判定與業務錯誤。
[ ] 保存呼叫識別碼、父子執行關係與每一步的時間戳。
[ ] 以同一份最小案例在開發與生產相容環境重跑。
[ ] 只有確認屬於瞬時網路、服務忙碌或傳輸中斷時，才啟用有限重試。

若團隊需要整理操作文件，可將這份清單與 nuvcloud 的支援說明放在同一個事故處理入口；若必須隔離現有生產環境，則可從 nuvcloud 控制中心規劃獨立的遠端 Mac 測試工作區，讓重現、日誌保存與版本切換不干擾正式服務。

單純沿用目前的本機環境，常見缺點是依賴套件與驗證器版本難以固定、團隊成員的權限與設定不一致，還可能因生產資料無法安全複製而無法重現；若改用一般雲端主機，又可能遇到 macOS 相容性、實體工具鏈與遠端除錯條件不足。對需要短期隔離環境、重現 Mac 相關 Agent 工具鏈或測試跨平台執行結果的團隊而言，租用 nuvcloud 的 Mac 可把環境建立、權限隔離與使用期限拆開管理，比臨時改動現有主機更適合做一次性的故障復現；但若是長期穩定的高負載服務，或必須直接連接特定實體介面，自購設備仍可能更合理。