AI 代理的系統化除錯：AgentRx 框架正式發佈

概覽

• 問題： 調試 AI 代理（Agent）的失敗非常困難，因為執行軌跡長、具隨機性，且通常涉及多個代理，導致真正的根因被掩埋。

• 解決方案： AgentRx (在新分頁開啟) 通過從工具架構（Tool Schemas）和領域策略中合成受保護的可執行約束（guarded, executable constraints），並逐步記錄有證據支持的違規行為，從而精確定位第一個不可恢復的「關鍵失敗步驟」（critical failure step）。

• 基準測試 + 分類法： 我們發布了 AgentRx Benchmark (在新分頁開啟)，包含橫跨 τ-bench、Flash 和 Magentic-One 的 115 個手動標註失敗軌跡，以及一個基於實證的九大類失敗分類法。

• 結果 + 發布： AgentRx 在失敗定位（+23.6%）和根因歸屬（+22.9%）方面優於提示詞（Prompting）基準模型。我們正將此框架和數據集開源。

隨著 AI 代理從簡單的聊天機器人轉型為能夠管理雲端事故、導航複雜網頁界面以及執行多步驟 API 工作流的自主系統，一個新的挑戰隨之而來：透明度。

當人類犯錯時，我們通常可以追溯其邏輯。但當 AI 代理失敗時——可能是因為幻覺出工具輸出，或是在五十步任務中的第十步偏離了安全策略——要準確識別出問題發生的位置和原因，是一個艱鉅的手動過程。

今天，我們很高興宣布開源發布 AgentRx (在新分頁開啟)，這是一個自動化、與領域無關的框架，旨在精確定位代理軌跡中的「關鍵失敗步驟」。除了框架之外，我們還發布了 AgentRx Benchmark (在新分頁開啟)，這是一個包含 115 個手動標註失敗軌跡的數據集，旨在幫助社群構建更透明、更具韌性的代理系統。

挑戰：為什麼 AI 代理難以調試

現代 AI 代理通常具有以下特點：

• 長週期（Long-horizon）： 它們在長時間內執行數十個動作。

• 機率性（Probabilistic）： 相同的輸入可能導致不同的輸出，使問題難以重現。

• 多代理（Multi-agent）： 失敗可能會在代理之間「傳遞」，掩蓋了原始根因。

傳統的成功指標（如「任務是否完成？」）提供的信息不足。為了構建安全的代理，我們需要識別軌跡變得不可恢復的確切時刻，並獲取該步驟出錯的證據。

AgentRx 介紹：自動化的診斷「處方」

AgentRx（「Agent Diagnosis」的縮寫）將代理執行視為需要驗證的系統追蹤（System Trace）。AgentRx 不依賴單一 LLM 來「猜測」錯誤，而是使用結構化的多階段流水線：

• 軌跡標準化： 將來自不同領域的異質日誌轉換為通用的中間表示。

• 約束合成： 框架根據工具架構（例如，「API 必須返回有效的 JSON 響應」）和領域策略（例如，「未經用戶確認不得刪除數據」）自動生成可執行的約束。

• 受保護的評估： AgentRx 逐步評估約束，僅在其*保護條件（guard condition）*適用時檢查每個約束，並生成一份包含證據支持的違規行為且可審計的驗證日誌。

• 基於 LLM 的判定： 最後，LLM 判定器利用驗證日誌和基於實證的失敗分類法來識別關鍵失敗步驟——即第一個不可恢復的錯誤。

AgentRx 工作流：給定失敗軌跡、工具架構和領域策略，AgentRx 合成受保護的約束，逐步評估它們以生成帶有證據的可審計違規日誌，並使用 LLM 判定器預測關鍵失敗步驟和根因類別。

代理失敗的新基準測試

為了評估 AgentRx，我們開發了一個手動標註的基準測試，包含橫跨三個複雜領域的 115 個失敗軌跡：

• τ-bench： 用於零售和服務任務的結構化 API 工作流。

• Flash： 現實世界的事故管理和系統故障排除。

• Magentic-One： 使用通用多代理系統執行的開放式網頁和文件任務。

利用紮根理論（Grounded-theory）方法，我們推導出了一個可以跨領域推廣的九大類失敗分類法。這套分類法能幫助開發者區分「計劃遵循失敗」（代理忽略了自己設定的步驟）和「捏造新信息」（幻覺）。

分類類別	描述
計劃遵循失敗	忽略了必要步驟 / 執行了額外的未計劃動作
捏造新信息	篡改了追蹤/工具輸出中未提及的事實
無效調用	工具調用格式錯誤 / 缺少參數 / 不符合架構規範
工具輸出誤解	錯誤讀取工具輸出；基於錯誤假設行動
意圖與計劃不匹配	誤讀用戶目標/約束，導致計劃錯誤
用戶意圖不明確	因缺少必要信息而無法繼續
意圖不受支持	沒有可用工具能執行所要求的操作
觸發護欄	執行因安全/訪問限制而被阻斷
系統故障	連接/工具端點故障

各領域失敗密度的分析。在像 Magentic-One 這樣的多代理系統中，軌跡通常包含多個錯誤，但 AgentRx 專注於識別第一個關鍵違規。

關鍵結果

在我們的實驗中，AgentRx 展現出相較於現有基於 LLM 提示詞基準模型的顯著提升：

• 失敗定位準確度提升 +23.6%（絕對值）。

• 根因歸屬提升 +22.9%。

通過可審計日誌提供失敗背後的「原因」，AgentRx 讓開發者能夠從反覆試錯的提示詞調整轉向系統化的代理工程。

加入社群：開源發布

我們相信代理的可靠性是現實世界部署的前提。為了支持這一點，我們正在開源 AgentRx 框架和完整的標註基準測試。

• 閱讀論文： AgentRx: Diagnosing AI Agent Failures from Execution Trajectories

• 探索代碼與數據： https://aka.ms/AgentRx/Code (在新分頁開啟)

我們邀請研究人員和開發者使用 AgentRx 來診斷他們自己的代理工作流，並為不斷增長的失敗約束庫做出貢獻。齊心協力，我們可以構建不僅強大，而且可審計、可靠的 AI 代理。

致謝

我們要感謝 Avaljot Singh 和 Suman Nath 對本項目的貢獻。

在新分頁開啟這篇博文 Systematic debugging for AI agents: Introducing the AgentRx framework 首先發布於 Microsoft Research。