AI 知識

先定位 Harness、Loop、Graph 的第一個偏離點

AI 知識｜Agent Debug｜2026-08-01

AI Agent 一旦卡住，最直覺的反應往往是換更大的模型、提高推理強度，或把 Prompt 再寫得更長。

這些動作有時有效，但也可能讓成本增加，故障卻原封不動。原因很簡單：Agent 的實際表現不只由模型決定，還受到外圍執行環境、反覆工作的控制方式，以及任務流程如何連接影響。

與其先猜「模型是不是不夠強」，更有效的做法是先問：系統在哪一步第一次偏離預期？

本文把常見故障整理成 Harness、Loop、Graph 三層。這不是任何單一廠商發布的官方標準，而是一張實務診斷地圖；實際框架裡三者可能互相包含，但用來定位問題非常有效。

第一層：Harness 決定 Agent 實際拿得到什麼

語言模型本身只能根據輸入產生輸出。要讓它讀檔、搜尋、呼叫 API、操作瀏覽器、保存進度或等待批准，需要一套包在模型外面的 runtime，也就是 Harness。

Microsoft 將 Agent harness 描述為讓模型能執行工具、管理 history 與 context、套用 approval 與安全政策，並持續朝任務完成前進的外圍系統。OpenAI 在分享 Codex 的 agent-first 開發經驗時也指出，早期進度慢不是模型做不到，而是環境規格不足，缺少 Agent 可理解的工具、結構與規則。

因此，以下症狀應優先檢查 Harness：

  • Agent 讀到錯的檔案或過期資料。
  • 必要工具沒有註冊，或工具描述讓模型選錯。
  • 權限不足，動作在執行邊界被拒絕。
  • context 壓縮後遺失關鍵決策。
  • 高風險操作沒有 approval，或 approval 設計讓流程永遠停住。
  • 失敗後沒有保存狀態，重啟只能從頭再來。

這類問題不是多寫一句「請仔細一點」就能解決。需要修的是輸入、工具、權限、記憶、觀測或恢復機制。

第二層：Loop 決定 Agent 如何反覆，以及何時停手

Agent 很少一次就把複雜任務做對。它通常需要執行、檢查、取得回饋，再進入下一輪。

Anthropic 將 Agent loop 定義為重複工作週期，直到符合停止條件。這個定義裡最重要的不是「重複」，而是「停止條件」。如果沒有可驗證的完成標準、輪次上限與新的回饋，重試只會放大成本。

以下症狀通常指向 Loop：

  • Agent 反覆呼叫同一個工具，輸入幾乎沒有變化。
  • 每一輪都宣稱有進展，卻沒有新增測試、trace 或平台讀回。
  • token 與執行時間持續增加，品質沒有改善。
  • 沒有明確定義 done，Agent 只能自行猜何時交付。
  • 失敗後只增加 retry，沒有根據錯誤類型改變策略。

修正 Loop 時，應加入可驗證 exit criteria、最大輪次、每輪必須產生的新證據，以及遇到哪些狀態要停止並升級人工處理。

第三層：Graph 決定工作如何拆分與交接

當任務包含多個步驟、分支或多個 Agent，系統必須知道現在在哪個狀態、下一步去哪裡，以及前一步的輸出如何成為下一步的輸入。

LangGraph 把這類工作流表達成 state、nodes 與 edges：node 執行工作，edge 決定下一步。這種結構能處理分支、循環、checkpoint 與 human-in-the-loop，但也增加新的故障面。

以下症狀通常應先查 Graph：

  • 上一步已完成，下一步卻拿不到輸出。
  • 必要依賴還沒完成，流程就提前往下走。
  • 條件分支判斷錯誤，把任務送到不該去的節點。
  • 多 Agent handoff 遺失 callback、candidate 或狀態。
  • 失敗後從錯誤 checkpoint 恢復，重做或跳過了關鍵步驟。
  • 兩個節點互相等待，流程沒有可到達的出口。

這時再強的模型也無法替錯誤路由補上遺失的資料。需要修的是狀態 schema、edge 條件、dependency、handoff 契約與 checkpoint。

最重要的不是分類，而是找到第一個偏離點

錯誤訊息通常出現在因果鏈的最後面。最後一個步驟說「資料不存在」，不代表資料源真的沒有資料；也可能是前面某個節點沒有保存、某個工具查錯環境，或某一輪重試覆蓋了正確結果。

一個有效的診斷流程可以只有四步：

  1. 打開 trace、tool call、狀態轉移或執行紀錄。
  2. 從輸入開始，找到第一個與預期不同的步驟。
  3. 判斷偏離發生在 Harness、Loop 還是 Graph。
  4. 一次只改一層，使用同一條路徑重新驗證。

LangSmith 的 trace 文件也採取類似思路：先從完整 thread 掃描異常，再進入特定 run 檢查 input、output、timing、errors 與 metadata。重點不是畫出漂亮流程圖，而是保留足以還原因果鏈的證據。

換模型應該是診斷結果，不是第一反射

模型能力當然可能是問題。如果所有資料、工具、權限、路由與停止條件都正確，模型仍持續無法理解任務或做出合格判斷，換模型才是合理實驗。

但在那之前，先排除 Harness、Loop 與 Graph 的故障，通常能更快得到答案，也能避免把流程問題誤包裝成模型能力問題。

Agent 工程真正的分水嶺，不是能不能呼叫最強模型，而是系統能不能回答：它剛才做了什麼、從哪一步開始走歪、修改後能不能用同一路徑證明問題消失。

查證摘要

  • Harness 負責工具、context/history、approval、安全政策與執行環境等外圍能力。
  • Loop 是 Agent 重複工作直到符合停止條件；可靠 loop 應有可驗證標準與輪次上限。
  • Graph workflow 以 state、nodes、edges 表達任務狀態與路由，可支援分支、循環、checkpoint 與人工介入。
  • 三層故障地圖是本文整理的診斷方法，不是跨廠商共同發布的正式 taxonomy。

參考資料

回文章列表