Agent 連續呼叫同一個失敗 API 五次——問題根本不在程式碼裡

Bug 上了正式環境。我的 Agent 一直重複呼叫同一支 API，而且連呼叫了五次。習慣使然，我第一個動作是打開程式碼。Retry 邏輯沒問題。函式流程也正常。Log 裡一個 Error 都沒有。程式碼給不了答案。直到打開 Trace，原因才浮現出來。

Agent 的程式碼只是個空殼

打開任何一個 Agent 的原始碼，你會看到模型設定、工具清單、System Prompt，大概就這樣。什麼情況下要呼叫哪個工具、要走哪條推理路徑——這些都不在程式碼裡。跑 LangGraph 架構的團隊都說：「你沒辦法靠 Code Review 來評估 Agent 的品質。」

• 同樣的程式碼、同樣的輸入，每次的工具呼叫模式都不一樣
• 跟 handleSubmit() 不同，分支邏輯根本不存在於程式碼中
• GPT-5.2 同一個問題問十次：工具呼叫順序的一致性大概只有四成
• 明明出錯了卻找不到程式碼的 Bug，根本無從重現

傳統軟體裡，程式碼就是行為本身。但在 Agent 裡，程式碼只是鷹架，實際行為是在執行期才浮現的。

Trace 才是新的原始碼

Trace 記錄每一個足跡。Agent 推理了什麼、呼叫了哪個工具、為什麼呼叫。除錯、測試、效能分析，現在都要透過 Trace 來進行。當 Agent 碰到錯誤卻一直重複同樣的呼叫，那是推理層面的問題，只有在 Trace 裡才看得到。

• 比對兩份 Trace，Prompt 改動帶來的影響馬上一清二楚
• 在 LangSmith 載入 Trace 就像打中斷點一樣
• 一份 Trace 就能精確定位推理在哪個環節出了軌

測試的思維必須根本性地改變

Agent 本來就是非確定性的——要在正式環境持續評估。沒有 Trace 收集、沒有評估資料集、沒有行為漂移偵測的 Pipeline，你根本沒辦法大規模地跑 Agent。

• 每週自動從正式環境的 Trace 中取樣，跑評估 Pipeline
• 只靠上線前的測試，無法保證非確定性系統的品質
• 沒有 Trace 的監控，等於只有在看伺服器有沒有活著
• Agent 可以「看起來運作正常」，但其實在做錯誤的事——只有 Trace 抓得到這種問題

協作和產品分析也都發生在 Trace 上

程式碼在 GitHub 上 Review。Agent 的判斷在可觀測性平台上 Review。團隊在 Trace 上留言、分享決策節點、像審查 PR 一樣審查推理過程。

• 產品分析工具和除錯工具，最終都會匯聚到 Trace 上
• 分析工具呼叫模式，可以反推使用者真正的需求

結語

程式碼是建築藍圖，Trace 是監視器錄影。出事了，你要做的第一件事是倒帶看錄影，不是再翻一遍藍圖。