Agent Engineering 爆火後，我學到的 5 個工程教訓

從一次失控的 Agent 呼叫開始

三個月前，我接手了一個 AI agent 專案：讓 agent 自動管理客戶工單系統，包括讀取工單、分配負責人、發送回覆。聽起來很簡單，對吧？結果上線第一天，agent 在一個循環裡連續調用了 37 次「重新分配」API，把同一個工單轉了 37 個人，客戶直接投訴到 CEO 那裡。那一刻我意識到，Agent Engineering 不是寫幾件 prompt 就完事的－－它需要體系化的工程思考。

以下是我在後續重構中學到的 5 個核心教訓。

1. 工具架構不要只寫 schema，要寫“約束”

最初我定義工具函數時，只寫了函數名稱、參數、返回類型。如 assign_ticket(ticket_id, assignee_id)。結果 agent 經常傳入不存在的 assignee_id，或把工單 assign 給已離職的人。

真正改變我判斷方式的結論是：工具 schema 必須包含業務語意的約束。

我的做法：

在參數描述裡寫上「請確保 assignee_id 是目前在職員工」這類規則。
更徹底地，在參數層級加枚舉或驗證 regex。例如 assignee_id 只允許數字，長度固定為 6。
如果參數依賴外部數據，例如“只能 assign 給你的直屬下屬”，那就在工具代碼裡先查資料庫做校驗，返回清晰錯誤而非讓 agent 猜。

踩坑修正前，我的 schema 只有 5 行；修正後，每個工具的描述平均增加到 15 行，並且內建了參數校驗。代價是多了些程式碼，但 agent 呼叫失敗率從 23% 降到了 4%。

終端機中 agent 連續工具呼叫的日誌輸出，顯示循環偵測觸發的警告

2. 權限管控必須從“預設允許”改為“明確拒絕”

很多 agent 框架預設 agent 能呼叫所有註冊的工具。我早期也是－結果 agent 自動呼叫了「刪除工單」接口，誤刪了一個非測試工單。

教訓：agent 權限範圍應該小到不能再小，然後逐步放寬。

可以執行的做法：

用一個設定檔或資料庫表，明確列出每個 agent 允許執行的動作。
在工具註冊階段，用裝飾器或中間件做權限檢查。如 @require_permission('ticket:assign')。
對於危險操作（刪除、修改金額、發送外部通知），加二次確認步驟，讓 agent 產生「預先執行」請求，人工確認後才真正執行。

我後來在重構中添加了一個“權限清單”對象，agent 啟動時加載，每次工具調用前都校驗。這個改動讓誤操作降為零。但注意：權限清單本身需要定期審計，因為業務角色會變更。

筆記型電腦上顯示的 Agent 權限清單截圖，列出各操作允許/拒絕狀態

3. 循環不會自己消失，你必須主動偵測並打斷

前面提到那個 37 次重新分配就是循環導致的。 agent 發現工單狀態不對，認為自己“應該重新分配”，分配後狀態不變，於是繼續分配。

循環是 Agent Engineering 最常見的失敗場景。解決方案不複雜：

步驟計數器：在一次 agent 運行中，限制總步驟數（例如最多 20 步）。超過就強制結束並回傳中間結果。
狀態指紋偵測：記錄每次狀態快照，如果偵測到重複狀態，表示可能陷入循環，觸發斷點。
內建去重邏輯：有些循環是因為 agent 重複呼叫相同參數的工具。你可以在工具呼叫層快取最近的呼叫（例如最近 5 個呼叫 hash），發現重複就回傳「已執行，無需重複」。

具體做法：我寫了一個 LoopDetector 類，維護一個最近 10 個狀態指紋的佇列。每次工具呼叫後，計算當前狀態 hash 並對比，如果重複率超過閾值，就中斷並輸出警告。這個機制上線後，循環導致的故障減少了 90%。

4. MCP 是雙面刃：能擴展能力，也可能引入幻象依賴

MCP（Model Context Protocol）是 agent 取得外部上下文的好方法，例如連接資料庫、檔案系統、Web API。但我在嘗試 MCP 時，發現 agent 經常依賴 MCP 中未明確說明的數據，導致推理偏差。

一個典型問題：agent 從 MCP 取得了使用者最近訂單列表，但 MCP 傳回的資料中混入了已取消的訂單。 agent 沒有過濾，直接拿已取消訂單的狀態作為用戶活躍度的判斷依據。

我的教訓：MCP 的資料必須自備過濾和解釋。資料來源回傳什麼，agent 就用什麼，你不會希望 agent 去盲猜資料可靠性。

解決方法：

在 MCP 整合時，為每個資料欄位加上「資料來源說明」和「有效期限」。
返回資料時，附帶一個“資料品質標籤”，例如“最近 1 小時已更新”、“可能包含已取消訂單”。
如果可能，在工具函數裡預先做資料清洗。例如「取得用戶訂單」工具內部就過濾掉已取消的訂單。

引入這些後，agent 基於 MCP 的決策準確率提昇明顯。但也要注意：不要給 MCP 過度加工數據，否則可能掩蓋真實問題。

5. 當你發現投入產出比下降時，及時換路線

不是所有問題都適合用 agent 解決。我在專案中遇到這樣的場景：花了兩週時間優化 agent 對某個特定工單類型的處理，準確率只從 80% 提高到 82%。而如果改用傳統規則+簡單的分類模型，一天就能達到 95%。

如何判斷是否該換路線？

邊際效益：如果每次優化只提升不到 1% 而已，且程式碼複雜度暴漲，那就收手。
失敗模式：如果 agent 的失敗是隨機的（例如不同場景下錯誤原因完全不一樣），那麼很可能該場景不適合 agent，改用確定性方案。
可測試性：如果難以建構測試案例來驗證改進效果，表示問題可能太模糊，agent 只會碰運氣。

我的決策原則：如果在 3 次迭代內無法將關鍵指標（如成功率）提升到可接受水平，就停下來——先用一個簡單方案兜底，然後花時間理解根本原因，而不是盲目堆 prompt。

適合什麼場景繼續投入？

任務有明確模式但規則複雜，例如工單分類、郵件回覆。
你需要 agent 自主決策，但失敗代價可控，例如推薦內容、生成草稿。
你具備工程化能力，能做好工具定義、權限、循環偵測。

什麼時候該換路線？

任務完全隨機或無規律，例如使用者輸入毫無模式。
失敗代價極高，例如金融交易、醫療診斷。
你無法控制 agent 的輸入輸出格式，例如整合外部不可控 API。

如果你現在想開始，最值得先抄寫的一步

找一個真實但低風險的任務（例如內部工單的自動分配），先手動完成一次 agent 建立全流程：註冊工具、設定權限、加入循環偵測、測試 10 個場景。然後記錄失敗數據。不要追求完美，第一個版本越簡單越好——因為你會重寫的。

我在這個過程中最大的感受是：Agent Engineering 的成功不在於 agent 多聰明，而在於它的工程限制有多嚴謹。