技術分享
Skill 工程化：把 AI 技能當軟體來測試、版控與維運
LangChain 2026 年調查顯示 89% 團隊有 AI 可觀測性、卻只有 52% 建立系統性評測，多數 Skill 上線後陷入「沒人敢改」的困境。本文從測試分層、模型釘版與依賴治理、promptfoo 等工具的 CI 發布關卡到可觀測性閉環，說明如何用軟體工程紀律讓 AI 技能可測試、可版控、可長期維運。
先分症狀，再查原因：單一 Agent 的故障速查邏輯
單一 AI Agent 上了生產環境後，最常見的困擾不是整套系統掛掉，而是它偶爾給出離譜的答案、卡在某個步驟，或呼叫外部服務失敗，而且往往沒有清楚的錯誤堆疊可查。故障其實比想像中頻繁：Sierra 團隊 2024 年發表的 τ-bench 用模擬客服情境實測，即使是當時最強的 function calling Agent（GPT-4o），任務成功率也不到 50%；清華大學等機構的 AgentBench（ICLR 2024）跨 8 種環境評測後同樣指出，長程推理與指令遵循能力不足，是 LLM Agent 可用性的主要障礙。與其每次從頭 debug，不如先把故障依「症狀」分類，再對照常見成因與解法，快速縮小範圍。
本文不談事故的分級與復盤流程，也不涉及多代理協作，只聚焦單一 Agent 在執行層面最常見的錯誤，整理成三張「症狀、可能成因、第一時間處置」速查表：幻覺與輸出品質、API 與外部依賴、死鎖與控制流。建議把它當成事故現場的止血手冊：先讓 Agent 恢復可用，再回頭談根治。
幻覺與輸出品質類：答案看起來對，其實是編的
這是最難察覺的一類故障：程式沒報錯、回應讀起來流暢，內容卻是捏造的。而且別指望換個模型就能根治——Vectara 的 Hallucination Leaderboard 用 HHEM 評測模型「摘要是否忠於原文」，2025 年 4 月的版本中表現最好的 Gemini 2.0 Flash 幻覺率僅 0.7%，但同年 11 月改用更大、更難的領域資料集後，全體模型的幻覺率大幅上升，榜首也只壓到 3.3%。連「有原文可依據」的受限任務都無法歸零，開放式問答只會更高。格式問題則已有成熟工程解：OpenAI 於 2024 年 8 月推出 Structured Outputs 時公布的評測顯示，僅靠 prompt 要求複雜 JSON 的模型合規率不到 40%，啟用 schema 約束解碼的 GPT-4o 則達 100%。診斷第一步，是分清問題出在「內容正確性」還是「格式結構」，兩者處置方向完全不同。
| 症狀 | 可能成因 | 第一時間處置 |
|---|---|---|
| 捏造不存在的資料或引用來源 | 缺乏檢索依據、temperature 過高、prompt 未允許「不知道」 | 加上 RAG 檢索與來源標註；要求引用出處；調低 temperature |
| 輸出格式時好時壞（JSON 破損） | 未用結構化輸出，模型自由發揮 | 改用 function calling／JSON schema 約束；加輸出驗證與重試 |
| 答非所問或忽略指令 | 關鍵指令埋在過長 context 裡被稀釋 | 精簡並前置關鍵指令；拆解任務；縮短單次 context |
| 同一輸入答案飄移不一致 | temperature 偏高、未固定參數 | 對需要一致性的任務調降 temperature、固定參數 |
API 與外部依賴類：不是 Agent 壞了，是它依賴的東西壞了
Agent 幾乎都要呼叫 LLM API、外部工具或內部服務，這些依賴的抖動很容易被誤判成 Agent 本身的問題。依賴故障是常態而非例外：2025 年發表於 ACM ICPE 的實證研究統計主流 LLM 服務的公開事故紀錄，OpenAI API 的中位修復時間約 1.23 小時、Anthropic API 約 0.77 小時——一次上游事故往往長達數十分鐘以上，光靠重試撐不過去，必須有降級方案。官方工程實務也反映了這個現實：OpenAI 與 Anthropic 的 SDK 都內建對逾時、429 與 5xx 錯誤的指數退避自動重試（預設 2 次），等於把「上游會壞」當成預設假設。診斷關鍵是把「Agent 的推理」和「它呼叫的東西」拆開，確認錯誤發生在請求發出之前還是之後。
| 症狀 | 可能成因 | 第一時間處置 |
|---|---|---|
| 間歇性逾時 | 上游 API 延遲、網路抖動、單次 prompt 過長 | 設合理 timeout 與指數退避重試；拆短 prompt |
| 突然大量 429、被限流 | 併發過高、未做速率控制 | 加入 rate limit 與請求佇列；分散請求；申請更高配額 |
| 工具回傳格式改變導致解析失敗 | 第三方 API 改版、欄位缺漏 | 對工具輸出做 schema 驗證；加防禦式解析與 fallback |
| 成本或延遲突然飆高 | 重試風暴、context 不斷膨脹 | 監控 token 用量；設重試上限；定期壓縮對話歷史 |
死鎖、迴圈與控制流類：Agent 卡住不動或停不下來
當 Agent 具備自主呼叫工具、多輪推理的能力，就可能陷入停不下來的狀態。這不是邊角案例：AgentBench 的錯誤分析顯示「超過回合上限」是最主要的失敗型態，在知識圖譜任務中占失敗的 67.9%，成因正是反覆繞圈、缺乏回溯的長程規劃。2026 年的 arXiv 研究《When Agents Do Not Stop》更以靜態分析掃描 6,549 個 LLM Agent 開源專案，確認 47 個專案存在共 68 處無限迴圈缺陷，最大宗正是「重試沒有上限」與「工具呼叫迭代沒有上限」，主要衝擊是 API 成本燒盡與服務癱瘓。這類故障的商業代價是空轉燒掉 token、讓使用者等不到回應；但相較幻覺它有個好處：症狀明顯，容易在監控上被抓到。
| 症狀 | 可能成因 | 第一時間處置 |
|---|---|---|
| 反覆呼叫同一工具、陷入無限迴圈 | 未設步數上限、模型誤判任務尚未完成 | 加最大步數／回合上限；明確定義「完成」條件 |
| 在某步驟卡住不回應 | 工具呼叫阻塞、等外部回應卻無 timeout | 對每個工具呼叫設 timeout；逾時即中止 |
| 兩個任務互相等待（死鎖） | 共享資源競用、鎖沒有釋放 | 為資源存取設順序與逾時；避免長時間持鎖 |
| 中途中斷後狀態不一致 | 沒有檢查點、失敗未回滾 | 引入冪等設計與檢查點；失敗時可安全重放 |
三步定位法：把單次故障變成可複用的速查表
遇到新故障時，用三個問題快速定位：第一，這是「輸出內容」的問題，還是「執行流程」的問題？第二，錯誤出在 Agent 自己的推理，還是它呼叫的外部依賴？第三，同樣的輸入是否穩定重現？第三題特別重要，因為 Agent 的失敗常是機率性的——τ-bench 為此提出 pass^k 指標，衡量「連續 k 次全部成功」的機率，實測 GPT-4o 在零售客服任務連跑 8 次全對的比例不到 25%，單次成功遠遠不等於可靠。答得出這三題，就能把故障對應到上面某一類，直接套用處置；前提是 Agent 本身要有足夠的可觀測性，完整記錄每一次工具呼叫、輸入輸出與 token 用量，否則再好的速查表也無從對照。
更重要的是，把每次定位到的症狀與解法補進團隊自己的速查表，故障處理才會越來越快，也不會重複踩同一個坑。恩梯科技提供 AI 導入顧問與客製化系統開發服務，協助企業為單一 Agent 建立可觀測的日誌、故障速查表與可靠性設計，讓 AI 上線後不只是能跑，更能長期穩定地跑。
參考資料
- Sierra（Yao et al.），《τ-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains》，2024。來源連結
- Liu et al.（清華大學等機構），《AgentBench: Evaluating LLMs as Agents》，ICLR 2024。來源連結
- Vectara，《Hallucination Leaderboard》2025 年 4 月版本存檔，2025。來源連結
- Vectara，《Introducing the Next Generation of Vectara's Hallucination Leaderboard》，2025。來源連結
- OpenAI，《Introducing Structured Outputs in the API》（經 Okoone 報導引述），2024。來源連結
- Chu et al.，《An Empirical Characterization of Outages and Incidents in Public LLM Services》，ACM ICPE 2025。來源連結
- OpenAI，《OpenAI Python API Library》官方文件（重試預設值）。來源連結
- Anthropic，《anthropic-sdk-python》原始碼（DEFAULT_MAX_RETRIES）。來源連結
- Hou et al.，《When Agents Do Not Stop: Uncovering Infinite Agentic Loops in LLM Agents》，2026。來源連結
