使用Strands Evals進行AI智能體故障檢測與根因分析

當AI智能體在生產環境中出現故障時，知道它失敗了只是開始。更困難的問題是它為什麼失敗以及如何修復。傳統評估只會告訴你“這個智能體在目標完成上得了60分”，但你需要手動審查執行軌跡來理解問題所在。對於大規模運營智能體的團隊，這種手動診斷成為從發現問題到交付修復之間的瓶頸。Strands Evals SDK中的檢測器消除了這一瓶頸，它通過自動識別智能體執行軌跡中的故障並進行根因分析，將診斷時間從數小時縮短到數分鐘。

本文將引導你調用檢測函數來診斷真實的智能體故障。你將學習如何解讀它們的結構化輸出：帶有置信度的分類故障、將根本原因與下游症狀聯繫起來的因果鏈，以及指明修復屬於系統提示詞還是工具定義的修復建議。你還將學習如何將檢測集成到評估管線中，實現每次測試運行的自動診斷。

檢測器補充了之前文章中介紹的評估框架，不僅回答“智能體表現如何？”，還回答“它為什麼失敗以及如何修復？”。

前提條件

要學習本文內容，你需要滿足以下前提條件：Python 3.10或更高版本；通過pip install strands-agents-evals安裝Strands Evals SDK；啓用Amazon Bedrock模型訪問（檢測器使用基於大語言模型的分析）；對於Amazon CloudWatch示例，需配置具有logs:StartQuery和logs:GetQueryResults權限的AWS憑證。

為什麼僅有分數不夠

Strands Evals框架通過Cases、Experiments和Evaluators提供可靠的質量信號：目標成功率、工具選擇準確率和有用性分數。這些對於捕獲迴歸和從統計層面理解性能非常重要。但考慮一下檢測到迴歸後會發生什麼。在部署後或構建時測試中的提示詞或工具更改後，智能體的目標成功率從85%下降到70%。評估器確認了下降。然後呢？

你需要識別哪些具體行為導致了故障，區分根本原因和下游症狀，確定修復屬於系統提示詞還是工具定義，並按影響優先級排序。這個診斷工作流傳統上需要高級工程師手動逐跨度檢查軌跡，並在數百個步驟間關聯故障，這個過程無法擴展。

檢測器自動化了這一工作流。評估器通過生成本案例級別的分數來回答“智能體表現如何？”。檢測器通過生成本跨度級別的診斷（帶有分類故障、因果鏈和修復建議）來回答“為什麼失敗？”。

檢測器工作原理

檢測器管線分兩個階段進行，每個階段都基於對執行軌跡的大語言模型分析。請參閲Understand observability for agentic resources in Amazon Bedrock AgentCore以瞭解智能體的會話、軌跡和跨度。

第一階段：故障檢測掃描會話中的每個跨度，對照一個全面的故障分類法（分為九個父類別：幻覺、錯誤操作、編排錯誤、任務指令違規、執行錯誤、上下文處理錯誤、重複行為、LLM輸出問題和配置不匹配）。對於每個識別的故障，它返回跨度位置、一個或多個類別、置信度和從軌跡中提取的證據。

第二階段：根因分析獲取檢測到的故障並追蹤它們之間的因果鏈。一個上游錯誤常常級聯成多個下游故障。根因分析將原因與症狀分開。它將每個故障的因果關係分類（PRIMARY、SECONDARY或TERTIARY），確定傳播影響，並生成按修復位置（系統提示詞、工具描述或其他）分類的修復建議。

兩個階段都通過分層策略處理不同大小的會話：適合所選檢測器模型上下文窗口的會話進行直接分析；中等大的會話進行故障路徑修剪（僅保留祖先和後繼跨度）；非常大的會話進行分塊分析併合並結果（將軌跡分割成重疊窗口並協調結果）。

下圖展示了端到端管線，有兩個入口點匯入相同的檢測和分析流程。

[圖：檢測器管線，集成和獨立入口點流入故障檢測和根因分析。]

開始故障檢測

以下示例使用來自《Evaluating AI agents for production: A practical guide to Strands Evals》中藥物發現研究助手的會話軌跡。該智能體基於Strands Agents和Amazon Bedrock構建。要跟着操作，請啓用OpenTelemetry跟蹤運行智能體，將會話導出為JSON，或使用後面展示的CloudWatchProvider獲取現有軌跡。請參閲Strands Agents SDK文檔中的User Simulation瞭解如何設置跟蹤和導出會話。

detect_failures函數接收一個Session對象（Strands Evals中的標準軌跡格式）並返回結構化故障。每個故障包括髮生故障的跨度、預定義故障分類法中的一個或多個類別、置信度和從軌跡中提取的證據。

import json
from strands_evals.detectors import detect_failures
from strands_evals.types.trace import Session
from strands_evals.detectors import ConfidenceLevel

with open("agent_trace.json") as f:
    session = Session.model_validate_json(f.read())

result = detect_failures(session, confidence_threshold=ConfidenceLevel.MEDIUM)

for failure in result.failures:
    for cat, conf, ev in zip(failure.category, failure.confidence, failure.evidence):
        print(f"[{conf}] {cat} at span {failure.span_id}")
        print(f" Evidence: {ev}")

以下是一個研究智能體的輸出，該智能體被要求“研究為現實世界中的AI供電所需的能源影響”。智能體遇到了工具配置問題並逐漸退化：

[0.9] execution-error-category-tool-schema at span f503a7d546fa4157
Evidence: Tool execution failed due to missing required parameter 'knowledgeBaseId'. Error: 'Parameter validation failed: Invalid type for parameter knowledgeBaseId, value: None'

[0.75] hallucination-category-hall-usage at span 0466979670d14099
Evidence: Agent claims 'I don't have access to the specific knowledge base needed' and then proceeds to provide detailed information about AI energy requirements 'based on general knowledge' without using any tools.

[0.9] orchestration-related-errors-category-goal-deviation at span d98d578e61233d33
Evidence: Agent completely abandons the original task about AI energy requirements and instead provides a lengthy response about marine biology, stating 'I'm going to pivot to discuss marine biology instead.'

在一次通過中，檢測器識別出多個級別的故障：執行錯誤（工具參數驗證）、語義問題（從“通用知識”產生幻覺）和編排問題（完全偏離目標）。一個跨度可以展示多個故障類別，每個類別都有獨立的置信度和證據。

添加根因分析

識別故障很有用，但理解它們發生的原因才能推動修復。analyze_root_cause函數獲取檢測到的故障並追蹤它們之間的因果鏈，將根本原因與下游症狀分開，並推薦每個修復所屬的位置。如果沒有向analyze_root_cause提供故障，它會自動運行故障檢測。

from strands_evals.detectors import detect_failures, analyze_root_cause

failures = detect_failures(session)
rca_result = analyze_root_cause(session, failures=failures.failures)

for rc in rca_result.root_causes:
    print(f"Causality: {rc.causality}")
    print(f" Span: {rc.failure_span_id} | Fix type: {rc.fix_type}")
    print(f" Root cause: {rc.root_cause_explanation}")
    print(f" Recommendation: {rc.fix_recommendation}")

繼續使用相同的研究智能體會話，根因分析揭示了因果結構：

Causality: PRIMARY_FAILURE
Span: f503a7d546fa4157 | Fix type: TOOL_DESCRIPTION_FIX
Root cause: Agent called retrieve tool without required knowledgeBaseId parameter because tool description does not clearly document that knowledgeBaseId is mandatory. This caused parameter validation failure and forced agent into multiple retry attempts with different parameter combinations.
Recommendation: Update retrieve tool description to explicitly mark knowledgeBaseId as a required parameter with clear documentation including format constraints and example values.

Causality: SECONDARY_FAILURE
Span: 0466979670d14099 | Fix type: SYSTEM_PROMPT_FIX
Root cause: Agent fabricated detailed AI energy consumption information claiming it is 'based on general knowledge' after all retrieval attempts failed, because system prompt lacks instruction prohibiting generation of factual content without tool-retrieved evidence.
Recommendation: Add instruction to system prompt requiring agent to explicitly acknowledge inability to complete research tasks when retrieval tools fail, and prohibit generating detailed factual content without tool-verified sources.

修復類型的區分使得根因分析可操作。工具模式錯誤是TOOL_DESCRIPTION_FIX，因為retrieve工具的knowledgeBaseId沒有清晰文檔化。下游的幻覺是SYSTEM_PROMPT_FIX，因為缺少如何處理持續工具故障的指令。只修復一個類別會留下另一個未處理。

一站式診斷：diagnose_session

為了方便，diagnose_session將兩個階段作為單一管線運行（檢測故障，然後分析根因）並返回一個統一的DiagnosisResult，包含去重後的建議：

from strands_evals.detectors import diagnose_session, ConfidenceLevel

result = diagnose_session(session, confidence_threshold=ConfidenceLevel.MEDIUM)
print(f"Found {len(result.failures)} failures, {len(result.root_causes)} root causes")

for rec in result.recommendations:
    print(f" - {rec}")

這會產生與前面示例相同的故障和根因，打包在一個結果中，建議在所有根因中去重。從一個函數調用中，你就得到一個按修復位置分類的具體更改的優先級列表。

與評估管線集成

當你將檢測器集成到現有評估工作流中時，它們提供額外價值。DiagnosisConfig將自動診斷附加到任何實驗，使得每個失敗的測試案例自動生成診斷：

from strands_evals import Experiment
from strands_evals.evaluators import GoalSuccessRateEvaluator
from strands_evals.detectors import ConfidenceLevel, DiagnosisConfig, DiagnosisTrigger
from strands_evals.types.evaluation_report import EvaluationReport

experiment = Experiment(
    cases=test_cases,
    task_function=my_agent_task,
    evaluators=[GoalSuccessRateEvaluator()],
    diagnosis_config=DiagnosisConfig(
        trigger=DiagnosisTrigger.ON_FAILURE,
        confidence_threshold=ConfidenceLevel.MEDIUM
    ),
)

report = experiment.run()
report.display(include_recommendations=True)

有兩種觸發模式可用。ON_FAILURE（默認）僅當至少一個評估器返回test_pass=False時運行診斷，這對於CI/CD迴歸檢測具有成本效益。ALWAYS對每個案例運行診斷，無論結果如何，這對於識別名義上通過案例中的次優路徑很有用。