怎麼除錯你的 AI Agent：出錯時如何找原因、修 Prompt、加護欄

你照著教學做了一個 AI Agent，前幾次跑得好好的，今天卻突然漏掉一個步驟、亂呼叫工具，或回了一段看似專業但完全是編的內容——你盯著螢幕，卻不知道該從哪裡開始修。

這篇要解決的問題：給你一套可重複的 AI Agent 除錯流程，讓你能快速定位錯誤、修對地方、並加上護欄避免重蹈覆轍。 適合誰讀：已經做出第一個 Agent、但常被「偶爾出錯」困擾的上班族、自由工作者與中小企業導入者，不需要寫程式背景。 讀完你會得到：一個四層定位法、可複製的除錯 Prompt、Workflow 流程圖，以及一套讓 Agent 越用越穩的回歸驗證做法。

為什麼 AI Agent 除錯這麼難？

傳統程式出錯通常是「確定性」的：同樣的輸入，永遠得到同樣的錯誤，你照著錯誤訊息一行一行追，總能找到那個寫錯的地方。

AI Agent 完全不是這樣。它有三個讓人崩潰的特性：

第一，不確定性。同一個 Prompt、同一個輸入，今天對、明天錯，因為模型每次生成都有隨機性。你沒辦法用「重跑一次看看」來確認問題修好了沒。

第二，錯誤會藏在中間。Agent 的工作是「規劃步驟 → 呼叫工具 → 整合結果 → 輸出」，錯誤可能發生在任何一環。最終輸出看起來怪，根因卻可能在第二步它就把任務理解錯了。如果你只盯著最後的答案改 Prompt，往往是在錯的地方使力。

第三，錯得很有自信。程式出錯會直接報錯停掉；Agent 出錯卻會用流暢、專業的語氣把錯誤包裝起來，讓你一不小心就採信。這也是最危險的一點。

所以 AI Agent 的除錯，本質上不是「找那一行 bug」，而是「建立一套能看穿過程、定位層級、並防止復發的方法」。這篇就是要把這套方法交給你。

核心概念：把 Agent 的錯誤分成四層

除錯的第一個關鍵，是別再把 Agent 當成一個黑盒子。它的運作可以拆成四層，每一層的錯誤症狀與修法都不同。先學會分層，你就不會再亂槍打鳥。

打個比方：AI Agent 像一位新來的助理。第 1 層是「他有沒有聽懂你交代的事」；第 2 層是「他有沒有把事情拆對、按對順序做」；第 3 層是「他會不會用辦公室的設備（影印機、報帳系統）」；第 4 層是「他交回來的報告格式對不對、有沒有亂寫」。助理出包，你會先問清楚是哪一關卡住，而不是劈頭罵他「你怎麼這麼笨」——除錯 Agent 也是同一個道理。

掌握這張表後，每次出錯你只要問自己一句：這個錯，是哪一層的錯？ 答案會直接告訴你該去改哪裡。

實際教學：五步驟除錯流程

Step 1：重現並完整記錄錯誤

除錯的第一鐵律：沒有紀錄，不開始猜。

當 Agent 出錯，立刻把這次執行的四樣東西存下來：

1. 原始輸入：你給它的完整指令與資料。
2. 推理過程：它的思考軌跡（多數工具叫 thinking、reasoning 或 trace）。
3. 工具呼叫明細：每一次它呼叫了什麼工具、傳了什麼參數、拿回什麼結果。
4. 最終輸出：它實際回給你的內容。

很多人卡關，是因為錯誤發生時只截了最後一句輸出就把畫面關了，事後完全無法重建現場。把這四樣當成 Agent 的「行車紀錄器」，缺任何一段都會讓你少看到關鍵的那一秒。

Step 2：用四層定位法找出錯誤層級

有了紀錄，照著四層表由前往後比對：

• 看推理過程的第一句：它對任務的理解對嗎？錯了就是第 1 層。
• 看它列出的步驟：有沒有漏、有沒有多、順序對嗎？錯了是第 2 層。
• 看工具呼叫：選對工具了嗎？參數對嗎？該查資料卻憑空回答嗎？錯了是第 3 層。
• 看最終輸出：前面都對，只是格式跑掉或夾帶沒根據的內容？那是第 4 層。

關鍵心法：從前往後找，找到第一個出錯的點就停。 因為前面錯了，後面一定跟著錯，修後面是白費力氣。

Step 3：對症修正 Prompt 或工具

定位好層級，照下面修：

• 第 1 層（理解錯）：在 system prompt 裡把角色、任務目標、適用範圍講得更死。最有效的是加 1～2 個「正確示範」（few-shot），讓它照樣造句。
• 第 2 層（規劃錯）：別讓它自由發揮，直接把步驟用編號列出來，並寫清楚「不要做範圍外的事」。
• 第 3 層（工具錯）：把工具的 description 寫清楚——「什麼情況該用」「參數長什麼樣」要附範例；工具太多就砍到只留必要的，選擇少了就不容易選錯。
• 第 4 層（輸出錯）：明確規定輸出格式（例如指定 JSON 欄位或固定段落），並要求「資訊若來自工具結果才寫，否則標註不確定」。

一次只改一個地方，改完馬上測，才能確定是哪個改動有效。

Step 4：在會反覆出錯的地方加護欄

護欄（guardrail）是你為 Agent 設的安全網，專門對付那些「偶爾才犯、但一犯就嚴重」的錯。三種最實用的護欄：

1. 格式護欄：輸出必須符合指定結構，不符就退回讓它重做一次。
2. 誠實護欄：在 Prompt 明寫「找不到根據的事，就回『查無資料』，禁止編造」，直接壓低幻覺。
3. 動作護欄：寄信、刪檔、付款這類不可逆的動作，一律先停下來等人工確認，不讓 Agent 自己按下去。

護欄的精神不是綁手綁腳，而是讓 Agent 即使出錯，也錯在可控範圍內。

Step 5：建評測集，每次改完都回歸驗證

這是最被忽略、卻最能讓 Agent 變穩的一步。

把你遇過的每一個錯誤案例，連同「正確答案應該長怎樣」，存成一份評測集（一個試算表或一個文字檔就夠）。每次你改完 Prompt，就把整份評測集重跑一遍，確認：舊的錯不再出現、且沒有把原本對的弄壞。

沒有評測集，你會陷入「修好 A、弄壞 B、回頭修 B、又弄壞 A」的無限輪迴。有了它，每次改動都有客觀分數，Agent 才會真正越用越可靠。

範例：除錯 Prompt 與 Workflow 流程圖

下面這段 Prompt 不是給 Agent 跑的，而是讓你把出錯紀錄丟給 Claude 或 ChatGPT，請它幫你做四層定位。實測能省下大量手動比對時間：

你是一位 AI Agent 除錯專家。我會給你一次 Agent 的完整執行紀錄，
請依「四層定位法」找出第一個出錯的層級，並給我具體修正建議。

四層定義：
1. 輸入理解：是否正確理解任務
2. 規劃步驟：步驟是否完整、順序是否正確、有無多餘動作
3. 工具呼叫：是否選對工具、參數是否正確、該查資料時有無查
4. 最終輸出：格式是否正確、有無未經查證的內容（幻覺）

請務必「從第 1 層往後找，找到第一個出錯點就停」，不要直接看最終輸出下結論。

【原始輸入】
{貼上你給 Agent 的指令}

【推理過程】
{貼上 Agent 的思考軌跡}

【工具呼叫明細】
{貼上每次工具呼叫的參數與回傳}

【最終輸出】
{貼上 Agent 實際回的內容}

請依下列格式回覆：
- 出錯層級：第幾層
- 判斷依據：引用紀錄中的哪一段
- 修正建議：具體要改 system prompt 的哪句、或工具說明的哪裡
- 建議護欄：針對這個錯，該加哪一種護欄

文字版 Workflow 流程圖（把除錯變成固定流程，照著走就不會漏）：

Agent 出錯
   ↓
保存執行紀錄（輸入＋推理＋工具呼叫＋輸出）
   ↓
四層定位：從第 1 層往後找
   ↓
找到第一個出錯層級
   ├─ 第 1 層 → 補強 system prompt ＋ 加範例
   ├─ 第 2 層 → 明確列步驟 ＋ 限制範圍
   ├─ 第 3 層 → 改工具說明／減工具／加參數驗證
   └─ 第 4 層 → 規定輸出格式 ＋ 加事實檢查
   ↓
針對反覆出錯處加護欄（格式／誠實／動作）
   ↓
把此案例存入評測集
   ↓
重跑整份評測集回歸驗證
   ├─ 全過 → 完成
   └─ 有退步 → 回到四層定位重來

常見錯誤

一、只看最終輸出就改 Prompt。 這是最常見的坑。輸出怪不代表輸出層有問題，根因往往在前面的理解或規劃。不做四層定位就改，等於頭痛醫腳。

二、一次改一大堆東西。 同時改 system prompt、換模型、又調工具，結果對了也不知道是哪一項奏效，錯了更無從回溯。永遠一次只改一個變因。

三、用「重跑一次對了」就當作修好了。 Agent 有隨機性，跑對一次可能只是運氣。沒有評測集多次驗證，你只是把問題藏起來，下次照樣爆。

四、護欄加在錯的地方。 不是每個環節都要塞檢查，那會拖慢又難維護。護欄只加在「會反覆出錯」或「出錯後果嚴重」的地方。

五、把 Prompt 問題誤判成模型不夠強，急著換更貴的模型。 多數時候，把指令講清楚、補個範例就解決了。先窮盡 Prompt 的可能，再考慮升級模型。

最佳實務

• 留好行車紀錄器：從一開始就讓 Agent 輸出可追溯的推理與工具紀錄，別等出事才後悔沒存。
• 由前往後查、找到第一個錯就停：這是四層定位法的精髓，能避免在錯的層級白費工。
• 一次一變因：每次只動一個地方，改完立刻測，建立明確的因果。
• 護欄分三類：格式、誠實、動作，對症下藥，別亂加。
• 評測集是地基：把每個錯誤變成一道考題，讓 Agent 的進步可被量化，這是業餘與專業的分水嶺。
• 先窮盡 Prompt 再換模型：把 Prompt 當成最便宜的調整旋鈕，先轉到底。

實際案例：台灣電商客服 Agent 的除錯實戰

情境：台中一家中型網購業者，導入一個處理客戶退換貨詢問的 AI Agent，串接訂單系統與退貨政策文件，自動回覆顧客 LINE 上的問題。

導入前的痛點：上線兩週後客訴變多。Agent 看起來很會聊，卻常出兩種包：一是顧客問「我的訂單能不能退」，它沒去查訂單系統就憑感覺回「可以」，結果該商品根本不適用退貨；二是它偶爾自己編出一個「七天鑑賞期可延長到十四天」的政策，公司從沒這條規定。客服主管每天忙著善後，一度想直接關掉。

用四層定位法後的發現：團隊把幾筆出錯對話的完整紀錄調出來比對。第一類錯定位在第 3 層（工具呼叫）——Agent 在該查訂單系統時沒有觸發查詢，因為工具說明寫得太模糊，它不知道「顧客提到訂單編號或退貨」就該去查。第二類錯定位在第 4 層（輸出）——它在找不到明確政策時，會自行「腦補」一個聽起來合理的答案。

對症修正：第 3 層方面，把退貨查詢工具的 description 改寫清楚，明列「只要顧客詢問退換貨、提到訂單編號，就必須先呼叫此工具查詢實際狀態與資格」，並附參數範例；同時把原本掛上去的八個工具砍到只剩四個必要的，減少選錯機會。第 4 層方面，加上誠實護欄：「政策相關回答只能引用退貨政策文件原文，文件查無就回『這部分我幫您轉接專人確認』，禁止自行推論」；並加動作護欄：凡涉及「同意退款」的回覆一律標記、轉人工核可後才發出。最後把這幾筆錯誤對話全存進評測集，每次改 Prompt 都重跑。

成果數據（導入修正後一個月）：與退換貨相關的錯誤回覆從每週約 23 件降到 2 件，降幅約 91%；因 Agent 亂回政策造成的客訴歸零；客服主管每日善後時間從約 2 小時縮短到 20 分鐘以內。更重要的是，團隊從此有了一套固定流程：每遇到新的錯誤類型，就走一次四層定位、加護欄、進評測集，Agent 的穩定度持續往上爬，而不是每次都從零開始救火。

提醒：以上為退換貨客服情境，若你的 Agent 涉及金流、合約、醫療或法律建議，務必加強人工複核與動作護欄，相關回覆建議經專業人員確認，本文方法僅供流程參考，不構成法律或財務建議。

結論

AI Agent 的除錯，難在它不確定、錯在中間、又錯得很有自信。但只要你不再把它當黑盒子，改用一套有方法的流程，它就會從「偶爾能用」變成「可以信賴」。

記住這條主線：保存紀錄 → 四層定位（由前往後找第一個錯）→ 對症修 Prompt 或工具 → 在痛點加護欄 → 用評測集回歸驗證。 一次只改一個變因，把每個錯誤都變成評測集裡的一道考題，你的 Agent 就會在每一次除錯後變得更穩一點。

下一步，建議你先回頭把手上 Agent 的「行車紀錄器」打開，確保下次出錯時你看得到全程；接著為它建立第一份評測集。想更系統地設計 Agent 與護欄，可以看本站的 AI Agent 入門指南、了解 MCP 如何讓 Agent 安全連上工具，或直接到 Prompt 產生器 把這篇的除錯 Prompt 變成你自己的版本。

❓ 常見問題 FAQ

🔗 延伸閱讀

• AI Agent 是什麼？從入門到實戰一次搞懂
• MCP 是什麼？讓 AI 連上你的工具
• ChatGPT Prompt 教學：高效指令公式
• 瀏覽全部工作流藍圖
• 用 Prompt 產生器做出你的第一個配方