Agent Engineering 檢視清單：機制、邊界與實作路徑

這份清單真的適合你嗎？先做一次階段匹配

Agent Engineering 的難度不在於寫程式碼，而在於決策－什麼時候用 ReAct、何時用 Plan-Execute、Tool Schema 該多細、Memory 是否該外掛資料庫。很多團隊在架構階段就跳進坑里，花兩週寫了一個在 demo 上完美但在生產上崩掉的 Agent。

**這份檢查清單面向誰？ ** 如果你正在設計第一個生產級 Agent，或重構一個已上線的 Agent 以提升穩定性，那麼它很適合你。但如果你只是用 LangChain 快速調通了一個調用大模型的函數，而 Agent 只在一個固定的管道裡跑，那麼你暫時不需要閱讀全部——聚焦在“工具定義與權限”那一部分就夠了。

**什麼階段跳過這份清單？ ** 如果你還沒有明確的任務邊界（Agent 到底要完成什麼業務邏輯），或者你連最基礎的 Prompt 工程都沒做好，那麼先別碰 Agent。先花時間把單一指令的準確性打磨到 90% 以上，否則 Agent 只會放大問題。

清單裡最先該做、最不能跳過的是哪幾步

1. 明確“Agent 到底做了什麼決策”

很多 Agent 出問題是因為開發者沒想清楚：哪個決策由模型做，哪個決策由程式碼做。常見錯誤是把所有路由交給模型，結果模型在一個簡單分支上反覆猶豫。

檢查項： 列出 Agent 的全部“決策節點”，每個節點標註其決策是由 LLM 推理、規則引擎或硬編碼完成。例如，一個面向客服的 Agent 可以這樣拆分：

• 意圖分類 → LLM（但輸出格式必須嚴格限定）
• 工具選擇 → LLM + 白名單約束
• 執行順序 → 固定工作流程（程式碼控制）
• 結果輸出 → 範本填滿 + LLM 潤飾

如果你的 Agent 有超過 3 個「LLM 獨裁」的決策點，考慮引入規則或人工確認。

2. 工具定義與權限邊界

工具（Tool/Function Calling）是 Agent 和外部世界互動的窗口，也是最大的風險點。

檢查清單：

• 每個工具的 Name 和 Description 是否清晰無歧義？ Description 應包含「何時呼叫、參數意義、返回格式」。
• 工具的參數是否有 schema 明確約束？避免模​​型自己推斷參數格式。
• Agent 所持有的工具集合是否以最小權限原則設計？例如，寫入資料庫的工具不應包含 truncate 權限；刪除操作的 ID 參數必須由上游校驗。

一個真實場景： 某團隊給 Agent 開放了一個「執行 SQL 查詢」的工具，參數是 raw SQL。結果 Agent 在測試中執行了 DROP TABLE，因為他們沒在 Description 裡寫明“只允許 SELECT 查詢”，也沒有在工具代碼層做校驗。事後他們在工具函數內加了一個 SQL 白名單解析器，並且限制回傳行數。

3. Memory 策略：不是為了“記住”而是為了“不遺忘”

Agent 的 Memory 分為三類：短期記憶（當前會話）、長期記憶（跨會話持久化）、工作記憶（當前步驟）。很多同學直接塞一個 Chat History 列表，結果 Agent 在第三輪就開始「忘記」用戶的需求。

檢查清單：

• 是否明確設定了上下文視窗的長度？例如，LLM 最大 8k token，但你給 Agent 塞了 6k 的 chat history，剩下 2k 留給推理，這很可能不夠。
• 是否有 summarization 機制？當 chat history 超過閾值，用另一個模型把歷史壓縮成摘要。
• long-term memory 的回想策略：是基於 embedding 向量檢索，還是基於結構化欄位（如使用者 ID、時間戳記）？後者較穩定，但召回率低；前者高召回，但有噪音。
• 最容易忽略的失敗點： 同時使用了 vector memory 和 chat history，但沒有去重。結果 Agent 在同一段對話中反覆引用同一事實，造成上下文衝突。

哪些步驟最容易流於形式，為什麼

1. Context 管理：看起來做了，其實沒效果

很多人以為「把相關文件全部塞進 System Prompt」就算完成 context 管理。但實際效果是：Agent 被大量無關資訊淹沒，關鍵指令反而被稀釋。

失敗範例： 一個程式碼產生 Agent 的 System Prompt 裡包含了完整的 API 文件、公司編碼規格、過去三個專案的註解片段。結果 Agent 產生的程式碼經常引用錯誤的 API 版本，因為它在滾動視窗裡沒看到最新的介面簽章。

正確做法： 採用「分塊 + 檢索」策略。把長文檔切分成語意區塊，每次只把與目前任務最相關的幾個區塊注入 System Prompt 中。同時，每個區塊必須附帶元資料（版本、日期、來源），讓 Agent 知道資訊的時效性。

2. 安全性與對齊檢查：大多數人只在開發環境測試

安全測試最容易流於形式，因為生產環境的各種對抗輸入在開發環境中很難模擬。

具體步驟鏈：

1. 建構至少 5 個「對抗性輸入」：包含 prompt injection、角色扮演誘導（如「假裝你是系統管理員」）、工具誤用（如「刪除所有資料」）、非目標語言、超大 payload。
2. 對每種輸入記錄 Agent 的行為：是否拒絕執行、是否產生錯誤訊息、是否觸發異常。
3. 如果你的 Agent 在收到 Ignore previous instructions 時真的忽略了先前的指令，馬上加輸入過濾層。
4. 檢查 Agent 是否無條件信任 tool 回傳的結果。例如，一個搜尋工具返回了惡意鏈接，Agent 是否直接作為答案輸出？應該加一個輸出審核步驟。

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

如果你只有半小時，按以下順序快速檢查：

1. 工具定義（5分鐘）： 選一個最危險的工具（例如寫入操作），確認它的 Description 裡寫清了“只允許做什麼、禁止做什麼”，並在程式碼層實現了參數校驗。
2. Context 上限（5分鐘）： 列印目前 Agent 一輪呼叫中 System Prompt + Tool Results + Chat History 的 token 消耗，確保它佔模型上限的 80% 以內。
3. 單次測試（10分鐘）： 用三個 case 測試 Agent：一個正常調用，一個意圖模糊的調用，一個包含拒絕操作指令的調用。看 Agent 是否行為可預測。
4. 日誌檢查（10分鐘）： 開啟 tool-call 日誌（哪個工具被呼叫了、傳入參數、回傳結果、耗時）。確保日誌包含 trace_id，方便後續追蹤。

做完清單後怎麼進入下一階段的系統實踐

當你跑通最小檢查路徑，並且修復了最明顯的漏洞，你已經具備了「防禦性工程」的基礎。下一步需要係統性地提升 Agent 的自主能力與可靠性：

1. 引入 evals 體系： 為你的 Agent 建立一組評估數據，包含「正確決策率」「工具呼叫準確率」「拒絕成功率」。每次修改 Prompt 或工具定義後，自動執行一次 evals。
2. 從單一 Agent 到多 Agent 協作： 當業務複雜到單一 Agent 的上下文視窗無法容納所有邏輯時，拆成多個 Specialist Agent，並用 Orchestrator Agent 進行路由。
3. 持續監控與回滾： 在生產環境中採集 Agent 的決策日誌，標註「異常行為」並定期複盤。如果某次更新導致指標下滑，要快速回滾到上一個穩定版本。

如果你希望把普通開發者轉型成為 Agent 工程師，上面提到的 evals 體系、多 Agent 編排、生產級監控等內容，已經超出了單篇文章的容量。下一步可以進入更系統化的原始付費文章或課程，深入每個模組的程式碼級實現。