使用 Agent-EvalKit 系統化評估 AI 代理

構建 AI 代理的團隊通常像評估其他軟件一樣評估它們：檢查輸出是否符合預期。但是，自主選擇工具並跨多個來源排序操作的代理會產生輸出級測試無法完全表徵的行為。一個代理可能會提供結構良好、可操作的響應，同時產生幻覺，因為其工具返回了空結果而捏造事實。它也可能在跳過可靠過程所需的驗證步驟的情況下得出正確結論。由於這些失敗隱藏在最終響應的表面之下，捕獲它們需要追溯代理完整執行路徑的評估：代理調用了哪些工具，這些工具返回了什麼數據，以及響應是否忠實地反映了這些數據。

彌補這一差距需要大多數代理團隊沒有人員從頭構建的基礎設施。你需要具有真實結果的測試用例、用於捕獲工具調用和中間狀態的可觀測性儀器，以及評估忠實度和工具使用情況以及表面準確性的指標。

Agent-EvalKit 是一個開源工具包 (Apache 2.0)，通過集成 AI 編碼助手（包括 Claude Code、Kiro CLI 和 Kilo Code）使這種評估基礎設施可用。它將整個工作流帶入你的開發環境，而不是將評估視為部署後的單獨工作。你用自然語言描述評估目標，工具包處理每個階段，從讀取代理源代碼和生成有針對性的測試用例，到運行評估並生成包含改進建議的報告，這些建議引用代碼庫中的特定位置。以下各節介紹了 Agent-EvalKit 如何在其六個評估階段中工作，並使用使用 Strands Agents SDK 和 Amazon Bedrock 構建的旅行研究代理作為運行示例。

代理評估需要什麼

除了基礎設施本身，選擇衡量什麼同樣要求很高。代理質量跨越多個維度，沒有單一指標可以捕獲：響應是否基於工具實際返回的內容、代理是否以正確的參數調用了正確的工具、以及最終輸出是否連貫且對提問者有用。一個響應可能讀起來很好，同時悄悄地對空工具結果產生幻覺；代理可能通過一系列錯誤的工具調用得出一個看似合理的答案，因此每個維度都必須單獨檢查，而不是從相鄰維度推斷。

沒有單一的評估器風格能很好地處理所有這三個方面。基於代碼的評估器提供快速、可重複的結果，但會懲罰有效的變體。大語言模型 (LLM) 作為評判的評估器提供細緻的評估，但代價是額外的推理和提示設計。最有效的評估策略結合了兩種方法。將評估分數轉化為具體的代碼更改是許多努力最終停滯的地方，這就是為什麼評估工作流需要以具體的、代碼級別的建議結束，而不是一個數字儀表板。

Agent-EvalKit 的工作原理

Agent-EvalKit 通過你現有的 AI 編碼助手工作，而不是作為單獨的評估平台運行。你的助手，無論 Claude Code、Kiro CLI 還是 Kilo Code，都成為評估引擎，通過應用其閲讀代碼和在每個評估階段推理代理行為的能力。你通過像 /evalkit.plan 和 /evalkit.data 這樣的斜槓命令驅動這個工作流，並附加自然語言指導，告訴助手你的代理哪些質量維度最重要。這種設計將評估保留在開發環境中，因此幫助你構建代理的同一個助手也幫助你評估它。

該過程從你的代理源代碼開始，助手讀取工具定義、系統提示和框架配置，以構建代理做什麼、可以調用哪些工具以及其行為可能在哪裏崩潰的詳細模型。工具包在後續階段產生的每個工件，從評估計劃到最終報告，都建立在這個代碼級別的理解之上。

基於此基礎，助手設計一個個性化的評估計劃，其中指標針對代理的能力和風險領域，然後通過後續階段生成測試用例、用 OpenTelemetry 兼容的追蹤儀器化代理、在收集結構化追蹤的同時運行每個測試用例、並根據你的標準評估結果。該過程以一份報告結束，其中優先建議引用代碼中的特定位置，將評估結果直接連接到可操作的修復。如果你指示系統關注由空工具結果觸發的幻覺，例如，該指導將影響測試用例生成、指標選擇以及報告最終強調的模式。

下圖説明了從測試用例到指標評估的流程。

工具包將此工作組織為六個階段，每個階段在 eval/ 目錄中產生工件，供下一階段使用。你通過 AI 助手以斜槓命令的形式調用每個階段，命令後的文本作為該階段的自然語言指導。一旦初始工件就位，你可以使用不同的指導重新調用任何階段以轉移焦點或深化分析，而無需從頭重建。

這六個階段涵蓋了完整的評估生命週期，從理解代理的能力到推薦具體的代碼改進。

計劃 (/evalkit.plan) 讀取代理代碼以瞭解其工具和框架，然後生成一個評估計劃，將每個指標與具體的評估方法配對。你的指導決定了計劃優先考慮哪些質量維度，這些優先級會延續到後期階段的工作評估代碼中。

數據 (/evalkit.data) 生成基於評估計劃的測試用例，每個測試用例都有輸入和預期結果，針對代理需要處理的特定行為和故障模式。如果你已經有來自生產日誌或手動測試的測試數據，你可以改為將這一階段指向你現有的數據集。

追蹤 (/evalkit.trace) 通過向代理添加 OpenTelemetry 兼容的追蹤使完整執行路徑可見。對於支持的框架，包括 Strands、LangGraph 和 CrewAI，它會檢測框架並應用適當的儀器化。請參閲 Agent-EvalKit 存儲庫瞭解當前的支持矩陣。

運行代理 (/evalkit.run_agent) 針對每個測試用例執行你的代理，為每次運行生成一個結構化的追蹤文件，捕獲工具調用、模型響應和中間狀態的完整歷史。

評估 (/evalkit.eval) 將計劃中的指標實現為可執行的評估代碼，針對收集的追蹤運行它，並保存結構化結果。它支持 DeepEval 和 Strands Evals SDK 等評估庫，選擇最適合你的代理和指標的方法。

報告 (/evalkit.report) 分析跨測試用例的模式並生成優先建議，這些建議引用代理代碼中的特定位置，每個建議包括其預期影響，以便你可以將改進工作引導到最有差異的地方。

在這些階段中，模糊的質量關注變成了結構化的證據體系：測試用例、執行追蹤、指標分數和優先建議，所有這些都鏈接回代碼中的特定位置。

演示研究：評估旅行研究代理

在使用 Strands Agents SDK 和 Amazon Bedrock 構建旅行研究代理的開發過程中，我們注意到代理有時在其響應中提供可疑的精確數字。該代理使用網絡搜索、航班信息、氣候數據、貨幣兑換和預算計算工具幫助用户規劃旅行，但我們無法確定精度問題有多普遍，或者哪些查詢觸發了它。

Agent-EvalKit 分析了代理的代碼，在計劃階段，設計了一個圍繞三個指標的集中評估：忠實度衡量響應是否基於工具實際返回的數據；工具參數準確性檢查代理是否以正確的輸入調用工具；響應質量評估輸出有多連貫和有用。數據階段隨後生成了 100 個多輪測試會話，涵蓋目的地研究、季節時機、行程構建、比較問題和預算計算，後續階段運行每個會話並捕獲詳細的執行追蹤。

結果揭示了質量與可靠性之間的明顯分界線。響應質量得分為 83.9%，確認代理產生了清晰、可操作的旅行建議；工具參數準確性達到 64.5%，顯示代理通常選擇了正確的工具，但有時傳遞了不精確的參數。忠實度僅得分 32.3%，表明每當其網絡搜索工具返回空或不完整結果時，代理會虛構匯率、温度和景點細節，並將這些發明呈現為來自其工具。

下圖顯示了單個執行中的這種幻覺模式，代理收到空工具響應並呈現虛構數據，就好像它來自其工具一樣。

報告將幻覺護欄確定為最高優先級的修復，建議系統提示指令在工具返回空結果時進行披露，並改進所有代碼路徑中的工具錯誤處理。在運行 Agent-EvalKit 之前，我們知道代理有時似乎不可靠。之後，我們知道了根本原因是空工具輸出觸發了幻覺，並且有具體的代碼更改來解決它。

演練

以下各節將引導你完成 Agent-EvalKit 的先決條件、安裝工具包並針對你的代理運行端到端評估。

先決條件

運行 Agent-EvalKit 評估需要雲訪問基礎模型推理和本地工具進行評估工作流。

一個有效的 AWS 賬户，在 Amazon Bedrock 控制台中啓用了基礎模型。Agent-EvalKit 使用 LLM 作為評判指標，需要基礎模型進行評分，因此在繼續之前，請確認您的模型在“模型訪問”頁面上可用。

Python 3.11 或更高版本和 Git。

uv 包管理器。在 macOS 和 Linux 上，使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安裝。

一個受支持的 AI 編碼助手（Claude Code、Kiro CLI 或 Kilo Code）已安裝並配置在您的機器上。本文中的示例使用 Claude Code，但工作流適用於所有三個。請參閲每個助手的文檔以獲取安裝説明。

開始使用

使用 uv 安裝工具包，它直接從 Agent-EvalKit GitHub 存儲庫拉取。

uv tool install evalkit --from git+https://github.com/awslabs/Agent-EvalKit.git

初始化一個評估項目並將代理代碼複製到項目目錄中。您的代理目錄應包含源代碼、工具定義和運行代理所需的任何配置。有關受支持的代理框架和項目結構的詳細信息，請參閲 Agent-EvalKit 存儲庫。

evalkit init my-agent-evaluation cd my-agent-evaluation cp -r /path/to/your/agent .

從評估項目內部啓動您的 AI 助手。對於 Claude Code，運行 claude 命令。

claude

對於引導式首次評估，quick 命令將逐步引導您完成所有六個階段，解釋每個階段的作用以及下一步要運行哪個命令。

/evalkit.quick /evalkit.quick Evaluate my agent at ./my_agent for response quality and tool accuracy

為了獲得更多控制，您可以單獨運行每個階段。