PI Agent 上線前怎麼驗證？用 1 條可回復流程搞定工具權限、狀態與冪等交付

很多團隊剛開始玩 AI Agent 時，在自己電腦上手動跑幾次 Demo 都覺得很神奇，但只要一把 PI Agent 丟進伺服器排程（Cron Job）準備讓它自動跑，問題就全冒出來了。

最讓人頭痛的往往不是模型寫不出東西，而是每次執行的條件都在變：有時工作目錄跑掉、有時 API 權限過期，甚至上一輪失敗留下來的暫存檔，被下一輪當成正常檔案繼續讀，最後把重複的內容洗進正式系統，想查修還很難重現問題。

如果直接把 Agent 放進核心營運流程，出事時抓蟲會抓到懷疑人生。比較穩妥的做法，是先挑一條低風險、就算出包也能一鍵還原的工作流，依序把輸入邊界、工具權限、狀態獨立與失敗處理測過一輪，確定每一步都有清楚的完成條件再放行。

一、挑選第一條「低風險、可回復」的驗證任務

剛要把 AI Agent 接上自動化時，千萬別想著一步到位，第一條任務絕對不要直接去碰刪除資料、改系統設定，或是直接對外發布通知。

建議從「單純讀取與整理」的封閉工作開始：

• 固定輸入來源：讓 Agent 只能讀取指定資料夾裡的文件或唯讀 API。
• 固定輸出路徑：把整理好的草稿寫入專屬的暫存目錄。
• 明確的禁止事項：嚴格限制不能修改原始檔案、不能跨目錄讀取機密（例如 .env 檔案），更不能自己連到未授權的外部網址。

實務提醒：這些安全邊界一定要寫在啟動腳本或系統權限裡強制約束，千萬不要只靠 Prompt 裡的一句「請不要修改檔案」，模型一恍神隨時可能破功。

二、把工作目錄與伺服器環境做成「前置檢查清單」

同樣一段指令，工程師在終端機手動敲、跟伺服器排程背景跑，拿到的環境可能完全不同。排程啟動時常常讀不到互動式 Shell 的設定檔，只要少了一個環境變數，Agent 就會直接卡死或亂跑。

在 Agent 正式動手前，最好讓腳本先跑這份自我檢查：

1. 確認執行基線：記錄當下的目錄路徑（pwd）、執行身分權限（UID）、相關 CLI 工具版本，以及輸入檔案的相對路徑。
2. 環境變數獨立管理：把 API Key 與必要設定放進專用的環境檔，啟動時由排程腳本明確載入。
3. 敏感資訊防護：執行 Log 裡只記錄「金鑰名稱是否存在」，絕不把 Token 明文印出來。
4. 遇缺即停：只要前置檢查發現少帶了變數或目錄不對，腳本就該直接中斷，不要讓 Agent 在半殘的環境下硬跑。

三、工具權限拆三層：讀取、產生與寫入

驗證工具呼叫（Tool Calling）時，大家很容易只看「有沒有呼叫成功」，但更關鍵的是：當遇到越權指令時，Agent 會不會主動拒絕？

建議把 Agent 能用的工具拆成三層管理：

• 讀取層（Read）：只開放白名單內的特定目錄與唯讀 API，避免目錄遍歷風險。
• 產生層（Generate）：在暫存區產出草稿、排版文字，這階段不牽涉任何外部系統狀態變更。
• 寫入層（Write）：要把資料寫回正式資料庫、發布文章或發送對外通知時，必須設有獨立條件，初期甚至該加入人工審核閘門（Human-in-the-loop）。

測試時，故意塞幾條不在權限內的指令給它，確認 Agent 真的會跳出錯誤並停下來，而不是假裝沒事硬做。

四、為每次執行建立獨立狀態與冪等鍵（Idempotency Key）

排程自動化遇到網路卡頓或 API 逾時是家常便飯，重跑無可避免。如果沒有把執行狀態切乾淨，上一輪留下來的半成品往往會混進下一輪，造成嚴重的資料污染。

想確保重跑時安全無虞，這三個設計一定要做：

• 獨立的 Run ID：每次觸發任務都產生一組專屬 ID，所有暫存檔與過程日誌都放在以該 ID 命名的目錄下，任務完成驗收後再搬移。
• 分段記錄狀態：把「模型已產出文字」、「檔案已寫入磁碟」與「外部系統已接收」分開記錄。很多時候模型寫完了但網路斷線，不能只看模型有回應就當作整趟任務成功。
• 設計冪等鍵（Idempotency Key）：寫入系統前，用「任務日期 + 內容雜湊（Hash）」當作唯一辨識碼去查紀錄。如果系統發現這筆資料已經交付過，就直接回傳既有結果，不要重複發送或洗版。

五、上線前必測的 4 種失敗情境

在正式讓 Agent 跑排程前，準備一組最小測試案例，把這 4 個情境跑過一輪：

1. 正常輸入：確認輸出格式、欄位與存放路徑完全正確。
2. 缺少輸入：故意不給來源檔案，確認 Agent 會直接停下來回報缺件，而不是自己腦補假內容。
3. 工具逾時：模擬 API 沒回應的狀況，確認系統會留下「待重試」狀態，不會把半成品當作完成。
4. 重複執行：手動把同一個任務連跑兩次，確認冪等機制有發揮作用，不會重複發布或重複寫入資料。

測完後，把當下的模型版本、Prompt、環境設定與測試結果存成一份基準紀錄（Baseline）。日後無論是更換底層模型、調整工具權限還是升級伺服器，只要重新跑一次這份測試，就能在幾分鐘內抓出是環境變了、權限掉了，還是模型理解力出了差錯。

常見問題 FAQ