從工程視角拆解 Agent Engineering：核心機制、邊界與代價

這份清單真的適合你現在嗎？

先別急著往下看步驟。 agent engineering checklist 不是通用補丁，用錯階段的殺傷力比沒有清單更大。如果你正在以下三種狀態裡，這份清單大機率可以幫助你：

1. 已經從 demo 階段走出來：你用 LangChain、AutoGPT 或原生框架跑通過一個原型，但發現它在真實數據上表現不穩定，想系統性地排查瓶頸。
2. 要做多工具協作 agent：你的 agent 不只呼叫一個 API，而是需要讀取本機檔案、執行 SQL、呼叫第三方服務。此時，工具註冊的規範性和錯誤兜底比模型本身更關鍵。
3. 正在從單輪 agent 轉向多輪任務：context 長度和記憶策略開始成為瓶頸，你需要明確每一步該檢查什麼。

相反，如果你剛接觸 agent，連 LLM 的 tool calling 能力都沒測試過，那麼這份清單會顯得過於沉重。你應該先建造一個只有 3 個步驟的 demo，跑通一次再回來。

第一步與最不能跳過的環節：工具註冊與權限檢查

agent engineering 最核心的不是 prompt，而是工具註冊的邊界定義。當你在程式碼裡註冊一個 read_file 工具時，定義了它的參數（檔案路徑）、描述（用於讀取文字檔案）、以及可選的返回格式。但最容易出錯的不是參數，而是：agent 呼叫該工具時你給了多少權限。

假設你的 agent 可以執行 Shell 指令，而你在權限配置裡只寫了白名單指令列表，卻沒限制執行目錄。那麼 agent 可能會因為上下文噪音而嘗試 rm -rf /（真實案例）。因此，第一步必須檢查每個工具的作用域：

• 檔案操作工具：是否限制在沙箱目錄？
• 網路請求工具：是否只允許 GET，禁止 open 連接埠？
• 資料庫工具：是否限制為唯讀連線？

這一步最不能跳過的理由是：一旦 agent 上線，任何權限漏洞都會被使用者輸入或系統 prompt 注入利用。

最容易流於形式的步驟：錯誤處理與回退策略

很多團隊在 checklist 裡寫了“實現錯誤處理”，但實際上只是把 tools 的返回裡加上了 try-catch 和 "error": "..."。這遠遠不夠。真正的 agent 錯誤處理必須涵蓋三個層級：

1. 工具執行層級：工具本身可能逾時、回傳異常格式、甚至崩潰。你需要一個統一的工具 error 類型，並定義 agent 在收到 error 後是重試、換工具還是終止。
2. 上下文一致級：如果 agent 連續兩次 tool call 都失敗，它可能已經陷入循環。此時應基於先前的呼叫次數和失敗原因，強制進入「總結失敗原因並切換策略」的節點。
3. 安全回退級：當 agent 無法完成任務時，它應該傳回一個明確的「無法完成」訊息，而不是假裝成功。很多早期 agent 在失敗時只會回傳 None 或空字串，使用者以為一切正常。

**為什麼這一步容易流於形式？ ** 因為開發者往往只檢查“有沒有處理異常”，而忽略“異常後 agent 的行為是否合理”。一個簡單的測試方法：故意讓一個工具拋異常，觀察 agent 在 3 步驟內是否能給出有意義的下一步。

當天可執行的最小檢查路徑

如果你只有半天檢查 agent 的工程質量，按以下順序操作：

1. 檢查每個工具的權限與作用域（15 分鐘）

   • 列出所有註冊的 tools
   • 確認它們是否只暴露了必要能力
   • 確認參數校驗是否嚴格（例如路徑參數不能包含 ..）

2. 執行一次整合測試（30 分鐘）

   • 寫一個測試案例，讓 agent 完成一個需要連續 3 個工具呼叫的任務
   • 故意在其中一個工具回傳異常，觀察 agent 行為
   • 檢查日誌：工具呼叫是否有完整記錄（請求、回應、時間戳記）

3. 檢查系統 prompt 中的身份與約束（10 分鐘）

   • 確認 system message 裡沒有「你可以做任何事」這類開放語句
   • 確認有明確的「如果不知道，就說不知道」約束

4. 審查日誌系統（15 分鐘）

   • 確保每次 tool call 的完整輸入輸出都被記錄
   • 確保日誌中包含 token 消耗（後續優化成本時需要）

這個路徑不求全面，但能暴露 80% 的常見問題。

做完清單後，你需要什麼？

這份檢查清單解決的問題是「agent 是否能穩定工作在已知場景」。當你通過它後，會面對下一步挑戰：如何在生產環境中持續監控、如何做 A/B 測試的 prompt 迭代、如何協調多個 agent 之間的衝突。這些已經不是單項目清單能涵蓋的，需要更有系統的工程實務。