AI Agent 越改越複雜？先找出真正出問題的那一層

我現在遇到 AI Agent 執行失敗，會先避免一件事：看到結果不對，就立刻往系統裡加東西。

找錯資料，就把 Prompt 寫得更長。

結果不穩定，就要求它多試幾次。

流程卡住，就增加 Planner（規劃）、Reviewer（審查）或 Judge（判定）Agent。

原本只有幾個步驟的工作，最後慢慢長出更多工具、規則、循環與角色。整套系統看起來更完整，實際上卻可能變得更難理解，也更難找出錯誤到底從哪裡開始。

真正的問題有時候很小。

可能是工具沒有回傳日期，也可能是沒有定義什麼叫完成，或者 Reviewer 發現錯誤後，系統根本不知道該把任務退回哪一步。

在原因還沒確認以前，繼續增加功能，只會把問題藏到更深的地方。

所以我現在的第一步，是找出哪一層最早出錯，再決定要修改什麼。

這篇會用三個層次診斷問題

上一篇「Harness、Loop、Graph Engineering 差在哪？」中介紹了三者的差異。

這篇直接把它們放進排錯情境，分別檢查三件事：

1. Harness（工作環境）：Agent 有沒有拿到正確的資料、工具與工作條件？
2. Loop（回饋循環）：Agent 有沒有根據證據檢查、修正與停止？
3. Graph（任務路徑）：任務失敗後，系統知不知道下一步該去哪裡？

這三層是我根據官方資料整理出的診斷框架，方便實際排錯；它不屬於 OpenAI、Anthropic 或 LangGraph 共同提出的官方模型。OpenAI 的 Harness Engineering 著重 Agent 周圍的環境、工具、文件與回饋能力；Anthropic 討論可靠的 Agent 與長時間任務機制；LangGraph 則提供節點、分支、子圖與檢查點（checkpoint）等流程編排能力。

假設我們要建立一個 AI 資訊整理 Agent

假設我們想建立一個每週執行的 AI 資訊整理流程：

搜尋最近一週的 AI 消息
→ 篩選值得關注的主題
→ 找到原始來源
→ 整理重點摘要
→ 檢查日期與重要數字
→ 產出一份報告

以下只是用來說明診斷方式的假設情境，不代表已經完成實際測試或效能比較。

第一次執行後，可能出現這些問題：

• 找到的消息不是最近一週
• 同一件新聞重複出現
• 引用二手文章，沒有找到原始來源
• 不斷搜尋，卻不知道什麼時候才算足夠
• 摘要寫完就宣布完成，沒有查核日期與數字
• Reviewer 發現問題後，不知道要退回研究還是重新寫作

表面上看起來都是「Agent 做得不好」，但背後原因並不相同。

如果每次出錯都直接重寫 Prompt、增加工具或新增 Agent，這個流程很快就會變得難以維護。

拿不到正確資料，先檢查 Harness

假設 Agent 經常找到過期消息。

最直覺的處理方式可能是補一句：

請更仔細搜尋最新、可信而且正確的資訊。

但這句話沒有回答幾個更基本的問題：

• 搜尋工具有沒有回傳發布日期？
• 能不能限制搜尋的時間範圍？
• 搜尋結果有沒有保留原始連結？
• Agent 能不能打開並閱讀完整來源？
• 相同事件要用什麼方式去重？
• 查不到第一手來源時，是否要停止並標記？

如果搜尋工具根本沒有提供日期，要求 Agent「只找最近一週」仍然可能失敗。

如果工具只回傳搜尋摘要，Agent 也可能在沒有讀過原文的情況下，直接把摘要當成事實。

這類問題應該先從 Harness 處理。

OpenAI 在 Harness Engineering 的實作中提到，早期進展較慢的原因包含環境規格、工具、內部結構與可讀性不足。他們後續讓 Agent 能直接讀取 UI、日誌、指標與執行追蹤紀錄（trace），用這些證據重現問題並驗證修正。

Anthropic 在長時間 Agent 的研究中指出，只讓模型跨多個上下文視窗（context window）重複執行仍然不夠。Agent 還需要留下清楚的進度與工作產物，讓下一次執行知道前一輪做了什麼。

放到資訊整理流程裡，可以先做這些最小修改：

1. 搜尋結果必須包含標題、來源、發布日期與原始連結。
2. 沒有日期的內容不能進入正式候選清單。
3. 優先保留官方公告、研究原文與第一手資料。
4. 相同連結與相同事件先完成去重。
5. 查不到原始來源時，標記為待人工確認。
6. 保留 Agent 實際使用過的來源與工具紀錄。

這些調整的作用，是讓 Agent 在更清楚、可追蹤的環境裡工作。它們不會直接提升模型的推理能力。

加入新工具以前，先檢查現有工具

搜尋品質不好時，很容易再接一個搜尋服務。

但工具增加後，也會多出新的判斷：

• 哪個工具應該優先使用？
• 不同工具的結果衝突時相信誰？
• 相同新聞要怎麼去重？
• 每個工具的成本和限制是什麼？

所以我會先確認，現有工具是真的缺少必要能力，還是輸入、輸出和使用規則沒有整理清楚。

如果問題只是回傳欄位不完整，增加第二個工具不一定會改善，反而會多出另一組需要整理的資料。

一直重試沒有進展，先檢查 Loop

第二種情況是 Agent 能正常搜尋，但不知道什麼時候應該停止。

第一輪找到 10 則消息。

第二輪又找到 8 則。

第三輪開始出現相同事件。

第四輪繼續換關鍵字搜尋，但沒有新增真正重要的資訊。

這時候，Agent 需要的是明確的完成條件。繼續增加搜尋能力，通常無法解決停止判斷缺失的問題。

有效的 Loop 會讓每一輪根據上一輪留下的證據調整。每一輪都應該回答：

1. 這一輪要解決哪個缺口？
2. 取得了什麼新的證據？
3. 哪些條件仍然沒有通過？
4. 下一輪會根據什麼改變方法？
5. 什麼情況下應該停止？

以每週 AI 資訊整理為例，可以先定義：

• 所有消息都在指定時間範圍內
• 每一則消息都有可以開啟的原始來源
• 相同事件已完成去重
• 日期、產品名稱與重要數字已查核
• 最後保留 5 至 8 則值得閱讀的消息
• 最多進行三輪搜尋
• 三輪後仍找不到來源，就交給人確認

這樣 Agent 不需要無限搜尋。

條件通過時停止，超過最大輪數時也停止，只是後者要清楚回報還缺少哪些資料。

Anthropic 建議從最簡單的方案開始，只有在需求真的需要時才增加複雜度。他們也特別強調，Agent 適合有清楚成功標準、能取得回饋，並且保留人工監督的任務。

修正要帶回上一輪的證據

沒有設計的重試通常是：

搜尋結果不好
→ 再搜尋一次

有設計的修正則是：

三則消息缺少原始來源
→ 只針對這三則重新搜尋
→ 檢查是否找到第一手資料
→ 通過、再次失敗或交給人確認

兩者的差別，在於下一輪有沒有使用上一輪留下的錯誤證據。

如果每一次都重新執行相同指令，Agent 只是在重複，不是在修正。

不知道下一步去哪裡，先檢查 Graph

第三種情況是流程已經拆成多個角色：

• Research Agent（研究 Agent）搜尋資料
• Editor Agent（編輯 Agent）整理觀點
• Writer Agent（寫作 Agent）撰寫內容
• Reviewer Agent（審查 Agent）查核事實

看起來分工清楚，執行後卻可能出現：

• Writer 還沒拿到完整資料就開始寫
• Research Agent 更新了來源，Editor 仍使用舊版本
• Reviewer 發現來源錯誤，只把意見退給 Writer
• 不同 Agent 同時修改同一份文件
• Reviewer 退件後，沒有人知道該回到哪個步驟

這時候再增加一個負責管理的 Manager Agent，可能只會多出一層交接。

系統需要先把工作路徑定義清楚：

搜尋資料
↓
來源與日期檢查
├─ 不通過：回到搜尋資料
└─ 通過
    ↓
主題篩選
↓
撰寫摘要
↓
事實查核
├─ 來源有問題：回到搜尋資料
├─ 表達有問題：回到撰寫摘要
└─ 全部通過：交給人確認

Graph 要定義的是：

• 哪一個步驟先執行
• 哪些工作可以平行
• 每個角色讀取與寫入什麼資料
• 什麼條件允許流程繼續
• 失敗後要退回哪個節點
• 哪些位置需要人工決定
• 中斷後要從什麼狀態恢復

LangGraph 的官方文件以圖結構（graph）、狀態（state）、條件分支（branching）與子圖（subgraphs）編排工作流程，並透過持久化機制保存檢查點。這類設計適合真的存在條件分支、狀態保存與失敗返回需求的任務。

如果工作只有搜尋、整理、人工確認三個固定步驟，一個 Agent 加上清楚的工具與完成條件，可能就已經足夠。

先把單一流程跑穩，再決定是否需要多角色和複雜 Graph，通常比較容易維護。

AI Agent 的複雜度是怎麼長出來的？

Agent 系統容易出現一個循環：

遇到失敗
→ 加入新的工具或角色
→ 系統出現更多交接與判斷
→ 錯誤變得更難定位
→ 再加入更多檢查

每加入一個工具、Loop 或角色，系統都會多出新的交接與判斷。

所以我會先問：新加入的複雜度，對應的是哪個已經觀察到的問題？

例如：

實際系統裡，一個問題可能同時涉及不同層次。

例如錯誤難以追蹤，可能同時需要 Graph 的明確節點，以及 Harness 的日誌。

但修改時仍然應該先找到錯誤最早出現的位置，不要一次把整套系統重做。

我會用四個步驟做最小診斷

第一步：把問題寫成可以觀察的症狀

不要只寫：

Agent 效果不好。

改成：

• 搜尋結果中有四則超出日期範圍
• 八則內容裡有三則沒有原始來源
• Agent 連續三輪找到相同事件
• Reviewer 退件後，流程沒有返回研究步驟
• Writer 使用的不是最新資料版本

症狀越具體，越容易判斷問題在哪裡。

第二步：找出最早開始出錯的位置

錯誤資料可能在搜尋階段就已經進入流程，最後才從 Writer 的文章裡被看見。

也可能資料本身正確，但驗證方式不足。

先找到最早出錯的位置，才能避免只修最後看到的表面結果。

第三步：一次只修改一個主要變因

例如先只調整其中一項：

• 搜尋時間範圍
• 工具輸出格式
• 最大重試次數
• 完成條件
• Reviewer 的退回路徑

修改後，使用同一組任務重新測試。

如果同時更換模型、增加工具、重寫 Prompt 和修改 Graph，就很難知道最後是哪一個改動真正有效。

第四步：確認有效後，再加入固定系統

有些失敗只是一次性的例外，不需要永久增加一個節點。

只有當同一種問題重複發生，而且修正方式已經驗證有效，才值得把它寫進：

• Harness 的固定規則
• Loop 的檢查與停止條件
• Graph 的正式節點
• 回歸測試或人工檢查清單

這樣可以避免每次遇到例外，系統就再長出一層。

可直接使用的 Agent 問題診斷 Prompt

請先不要直接修改系統，也不要增加新的工具、規則、重試或 Agent。

請根據目前的任務紀錄與錯誤結果，協助我診斷問題較可能出在哪一層。

一、Harness
檢查：
- Agent 是否取得正確資料
- 工具輸入與輸出是否清楚
- 權限是否過大或不足
- 狀態、記憶與進度是否有保留
- 是否有足夠的日誌與執行紀錄

二、Loop
檢查：
- 是否有明確的成功條件
- 是否有客觀的完成證據
- 失敗後是否取得新的回饋
- 下一輪是否根據證據改變方法
- 是否有最大嘗試次數與停止條件

三、Graph
檢查：
- 工作順序是否清楚
- 每個角色的輸入與輸出是否明確
- 失敗後是否知道要返回哪個步驟
- 是否有不必要的分支或角色
- 人工確認點是否放在正確位置

請輸出：

1. 目前觀察到的具體症狀
2. 最早開始出錯的步驟
3. 最可能出問題的主要層級
4. 支持這個判斷的證據
5. 目前不建議增加的複雜度
6. 最小修正方案
7. 修正後應使用什麼方式驗證
8. 仍缺少哪些資訊

證據不足時請直接說明，不要猜測。
一次只提出一個主要修改方向，不要直接重做整個系統。

什麼時候增加複雜度是合理的？

有些任務確實需要更完整的設計。

例如長時間任務需要保存進度，高風險操作需要權限限制與人工批准，輸出結果需要固定資料格式（schema）、測試或來源驗證，多個角色也可能需要明確的交接與失敗恢復路徑。

這些複雜度都有清楚對應的問題。

如果問題還沒出現，先放進所有可能用到的工具、角色與節點，只會增加尚未證明有用的維護成本。

Agent 系統的判斷標準很直接：每一個工具、循環和節點，都要能說明它在解決哪個問題。

先改最早出錯的那一層

下一次 Agent 出問題時，我會先把症狀寫清楚，找到錯誤最早出現的位置，再判斷它屬於工作環境、回饋循環，還是任務路徑。

找到真正出問題的那一層後，只修改一個主要變因，重新使用相同任務驗證。

這樣比較容易確認哪個改動真的有效，也能避免原本簡單的 Agent 越改越複雜。

參考資料

• OpenAI，《Harness engineering: leveraging Codex in an agent-first world》
• Anthropic，《Effective harnesses for long-running agents》
• Anthropic，《Building effective agents》
• LangGraph.js，Graph API overview
• LangGraph.js，Persistence