這條連結從 Notion 需求開始
真實場景是這樣的：你正在開發一個微服務，需要在已有程式碼庫中新增一個警告模組。任務寫在 Notion 上，你需要 Agent 幫你完成從需求解析到程式碼提交的全流程。
第一步不是寫程式碼，而是定義工具。你需要告訴 Agent：Notion 文件的取得方式、程式碼庫的搜尋工具、終端命令的執行權限、Git 操作的介面。每一個工具都是一個 API 呼叫宣告－包括參數、傳回值和失敗處理。這就是 Agent Engineering 中最基礎也最容易被忽略的環節：工具定義。
如果工具定義不完整，Agent 會在第一關卡住。例如只給了 Notion API 卻沒給身份驗證令牌，Agent 會嘗試三次然後報錯退出——很多團隊把這種失敗歸結為“AI 能力不夠”，其實是工具層沒做紮實。
核心循環：規劃、呼叫、觀察、調整
工具就緒後，Agent 開始它的核心循環。拿剛才的告警模組任務為例：
- 規劃：Agent 閱讀 Notion 需求，呼叫程式碼搜尋工具找到目前專案結構，然後產生執行計劃－新檔案、修改設定檔、新增依賴。
- 呼叫工具：它先執行
git pull取得最新程式碼，然後建立新檔案。這裡的關鍵是 Agent 會產生具體命令，系統將其轉送到終端執行。 - 觀察結果：如果檔案建立成功，終端返迴路徑和權限資訊；如果失敗（例如目錄不存在），傳回錯誤碼。 Agent 需要根據觀察調整下一步。
- 調整：失敗時 Agent 會重新規劃，例如先建立目錄再建立檔案。這個過程可能會迭代數次。
這個循環看似簡單，但失敗點藏在細節裡。最典型的錯誤是：Agent 在第一次工具呼叫成功後過度自信，跳過驗證直接執行下一步。例如創建完文件後沒有檢查內容是否正確，直接執行了程式碼格式化，結果格式化了空文件。
上下文與 MCP：不要讓 Agent 迷失
有了循環，Agent 還需要記住它在做什麼。這就是 上下文管理。
每個工具呼叫的輸入和輸出都會寫入上下文視窗。問題是，上下文視窗有上限——GPT-4 是 128K token，Claude 是 200K。當迴圈執行 10 次以上，上下文可能會被歷史日誌填滿。這時 Agent 開始「遺忘」：它可能忘記最初的需求，或重複執行已經完成的操作。
解決方案是 MCP（Model Context Protocol）。這本質上是一種上下文裁剪策略：只保留當前步驟相關的系統提示、工具結果和摘要，丟棄無關細節。實現時可以透過滑動視窗、重要性評分等方式控制上下文品質。
例如我的實務中，每輪循環只保留最近 5 次工具呼叫的結果，超過的就壓縮成一句話摘要。這使 Agent 在超過 30 步的複雜任務中仍能保持 90% 以上的準確率。
權限模型：最容易被忽略的坑
Agent Engineering 和一般程式設計的最大差別在於：你授予 Agent 的是操作權限，不是程式碼邏輯。
你需要回答三個問題：
- Agent 能存取哪些檔案系統路徑？
- Agent 能執行哪些終端指令（如
rm -rf要禁止）？ - Agent 能呼叫哪些外部 API（如生產環境資料庫要只讀）？
失敗場景很具體：有個團隊允許 Agent 直接執行 npm publish，結果它在調試過程中把未完成的包發佈到了 npm 官方倉庫。這類問題無法透過提示工程解決，必須從工具權限層管控。
我的做法是：在工具定義中為每個指令綁定安全 ID，終端機執行前校驗權限。例如檔案寫入只允許在 /src 和 /tests 目錄下，指令黑名單包含 rm -rf、sudo、publish 等。
失敗復原：不打斷工作流程
即使有工具定義、循環、上下文和權限，Agent 仍然會失敗。問題在於：**失敗後怎麼辦？ **
大多數實作是拋出異常然後停止。但真實開發場景需要更多：可能是手動介入修正，然後讓 Agent 從斷點繼續。
一個可行的設計是「檢查點模式」：每完成一個子任務（如檔案建立、測試通過），就把目前狀態儲存到磁碟。當 Agent 在後續步驟失敗時，你可以手動恢復到這個檢查點，修正問題後重新開始後續流程。
另一種是「明確授權模式」：當 Agent 遇到無法自動解決的錯誤（如 API 認證過期），它應該暫停並要求手動輸入，而不是盲目重試。
例如，我的工作流程中有一個「手動介入閘門」：如果 Agent 連續兩次執行同一個操作失敗，系統會彈出一個終端提示，要求開發者輸入新的憑證或修改路徑。開發者在終端機輸入後，Agent 繼續執行。
什麼時候該放棄 Agent？
Agent Engineering 的適用邊界並非無限。以下幾種情況下，手動編碼或傳統自動化更為合適：
- 高度安全敏感的操作：例如修改生產環境配置、操作金融資料真實訂單。
- 需要人類判斷的決策：例如介面設計、命名衝突解決。
- 非確定性任務：Agent 不適合包含隨機性（如自動產生密碼）或需要多輪人工審核的工作流程。
- 超長週期任務：單一任務超過 1 小時或 200 步，目前情境管理技術很難保持一致性。
在這些邊界外，Agent Engineering 的效果會大幅下降。例如在做程式碼重構時，Agent 可能因為無法理解整個專案的隱式依賴關係而引入 bug。此時，你應該退回到傳統方式：手動重構 + 單元測試。
一條可執行的檢查清單
如果你準備在真實專案中使用 Agent Engineering，以下是我實踐後提煉的清單：
- 工具定義完整性檢查：每個工具的輸入/輸出/錯誤碼是否都宣告了？
- 權限最小化：Agent 只能存取它真正需要的檔案和指令。
- 情境裁切策略：設定最大保留輪次（建議 5-10 輪），超過後壓縮。
- 失敗復原機制：檢查點 + 人工介入介面。
- 監控日誌：記錄每一次工具呼叫和決策，方便回溯。
- 測試沙箱：先在隔離環境執行，確認無誤再放開權限。
這條清單不是一次性配置就完事，而是每次任務前都要過一遍。我看過太多因為「上週沒事」就跳過權限檢查，結果這週 Agent 刪了資料庫的案例。
下一步：成為 Agent 工程師
如果你想從一般開發者轉型成為 Agent 工程師，這篇內容的下一步應該進入更有系統的原始付費文章或課程。在課程中你會學到如何設計工具呼叫協議、如何調試 Agent 的上下文視窗、以及如何建構生產級的失敗恢復系統。
暫無評論，快來發表你的看法吧