AI Agent Failure Detection and Root Cause Analysis with Strands Evals｜Strands Evals を用いた AI エージェントの失敗検出と根本原因分析 | AIニュース最前線

プロダクション環境で AI エージェントが失敗した際、その事実を知ることは始まりに過ぎません。より難しい問いは「なぜ失敗したのか」そして「何を修正すべきか」です。従来の評価では「このエージェントのゴール達成率は 60% です」という結果しか得られず、何が間違っていたかを理解するために実行トレースを手動でレビューする必要が生じます。大規模にエージェントを運用するチームにとって、この手動診断は問題検出から修正版のリリースまでの間にボトルネックとなります。 [Strands Evals SDK](https://github.com/strands-agents/evals) の検出機能（Detectors）はこのボトルネックを解消し、エージェントの実行トレース内の失敗を自動的に特定して根本原因分析（Root Cause Analysis）を実行します。これにより、診断にかかる時間を数時間から数分に短縮できます。 本稿では、実際のエージェントの失敗を検証するために検出関数を呼び出す手順を解説します。構造化された出力の解釈方法、すなわち信頼度スコア付きのカテゴリ別失敗分類、根本原因と下流症状を結びつける因果連鎖（Causal Chains）、およびシステムプロンプトまたはツール定義のどちらに修正を加えるべきかを明記する修正推奨事項について学びます。また、すべてのテスト実行で自動診断を行うために、検出機能を評価パイプラインに統合する方法についても解説します。 検出機能は、前回の投稿で紹介した評価フレームワーク [Strands Evals](https://aws.amazon.com/blogs/machine-learning/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals/) を補完するものであり、「エージェントの性能はどうだったか？」という問いだけでなく、「なぜ失敗し、どのように修正すべきか？」という問いにも答えるものです。 ## 前提条件 本記事を追いかけるためには、以下の前提条件を満たす必要があります。 - Python 3.10 以降。 - pip install strands-agents-evals を実行して Strands Evals SDK のインストール済み。 - Amazon Bedrock モデルへのアクセス権限の有効化（検出器は、大規模言語モデル (LLM) ベースの分析を使用します）。 - Amazon CloudWatch の例を行う場合、logs:StartQuery および logs:GetQueryResults 権限を設定した AWS クレデンシャルが必要。 ## スコアだけでは不十分な理由 Strands Evals フレームワークは、ケース、実験、評価器を通じて、ゴール達成率、ツール選択の精度、有用性スコアといった信頼性の高い品質指標を提供します。これらは回帰現象の検出や統計レベルでのパフォーマンス理解に重要ですが、回帰を検出した後に何が起こるかを考えてみてください。デプロイ後やビルド時のテストにおけるプロンプトやツールの変更後、エージェントのゴール達成率が 85% から 70% に低下したとします。評価器がその低下を確認しました。次にどうすればよいでしょうか？ 失敗を引き起こした具体的な振る舞いを特定し、根本原因を下流の症状から区別し、修正がシステムプロンプトに属するのかツール定義に属するのかを決定し、影響度に基づいて優先順位をつける必要があります。この診断ワークフローは従来、シニアエンジニアがトレースをスパンごとに手動で検査し、数百ステップにわたる失敗を相関させることを必要としており、このプロセスはスケーラビリティに欠けます。 検出器はこのワークフローを自動化します。評価者は、ケースごとのスコアを生成することで「エージェントの成果はどの程度だったか」に回答し、検出器は、分類された失敗、因果連鎖、修正推奨事項を含むスパンレベルでの診断を生成することで「なぜ失敗したのか」に回答します。 ## 検出器の仕組み 検出器パイプラインは、実行トレースに対する LLM ベースの分析によって駆動される 2 つのフェーズで動作します。セッション、トレース、スパンの詳細については、[Amazon Bedrock AgentCore のエージェントリソースにおける観測可能性の理解](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-telemetry.html) を参照してください。 フェーズ 1：失敗検出は、セッション内の各スパンを、9 つの親カテゴリに整理された包括的な失敗分類体系に対してスキャンします。これらは、ハルシネーション（幻覚）、誤ったアクション、オーケストレーションエラー、タスク指示非準拠、実行エラー、コンテキスト処理エラー、反復行動、LLM 出力の問題、設定ミスマッチです。特定された各失敗について、スパンの位置、1 つ以上のカテゴリ、信頼度スコア、およびトレースから抽出された証拠を返します。 フェーズ2：根本原因分析は検出された失敗を取り込み、それらの間の因果連鎖を追跡します。単一の上位段階でのミスが、複数の下位段階の失敗に連鎖することがよくあります。根本原因分析では、原因と症状を区別し、各失敗の原因性を（PRIMARY、SECONDARY、またはTERTIARY）分類し、伝播影響を特定し、修正が必要な箇所（システムプロンプト、ツール説明、その他）に基づいて修正推奨事項を生成します。 両方のフェーズは、選択されたDetectorモデルのコンテキストウィンドウ内に収まるセッションに対する直接分析、中規模サイズのセッションに対して祖先および子スパンのみを保持する失敗パスの剪定、非常に大規模なセッションに対してトレースを重複するウィンドウに分割し結果を統合するチャンク化分析とマージという、段階的な戦略を通じてさまざまなサイズのセッションを処理します。 以下の図は、2つのエントリポイントが同じ検出および分析フローに収束するエンドツーエンドのパイプラインを示しています。 ![image](https://d2908q01vomqb2.cloudfront.net/f1f836cb4ea6efb2a0b1b99f41ad8b103eff4b59/2026/06/11/ML-21169-1.png) *図：統合型およびスタンドアロン型のエントリポイントから失敗検出と根本原因分析へと流れるDetectorパイプライン。* ## 失敗検出の始め方 以下の例では、[Evaluating AI agents for production: A practical guide to Strands Evals](https://aws.amazon.com/blogs/machine-learning/evaluating-ai-agents-for-production-a-practical-guide-to-strands-evals/) で紹介されている創薬研究アシスタントのセッショントレースを使用します。このエージェントは、Strands Agents と Amazon Bedrock を基盤に構築されています。追従して実行するには、[OpenTelemetry](https://opentelemetry.io/) によるトレーシングを有効にしてエージェントを実行し、セッションを JSON 形式でエクスポートするか、本記事の後半で紹介する CloudWatchProvider を使用して既存のトレースを取得してください。トレーシングの設定方法やセッションのエクスポート方法は、[Strands Agents SDK ドキュメントのユーザーシミュレーション](https://strandsagents.com/docs/user-guide/evals-sdk/simulators/user_simulation/#complete-example-customer-service-evaluation) を参照してください。 detect_failures 関数は、Session オブジェクト（Strands Evals の標準トレース形式）を受け取り、構造化された失敗情報を返します。各失敗情報には、発生したスパン、事前定義された失敗分類体系からの一つ以上のカテゴリ、信頼度スコア、およびトレースから抽出された証拠が含まれます。 ```json 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}") The following is output from a research agent that was asked to "Research the impact of energy requirements for powering AI in the real world." The agent encountered tool configuration issues and progressively degraded: [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}") 同じ研究エージェントセッションを継続して、根本原因分析は因果構造を明らかにします： 因果関係：主要失敗 スパン：f503a7d546fa4157 | 修正タイプ：ツール記述の修正 根本原因：エージェントが、retrieve ツールの説明に knowledgeBaseId が必須であることが明確に記載されていないため、必要な knowledgeBaseId パラメータなしで retrieve ツールを呼び出してしまいました。これによりパラメータ検証に失敗し、異なるパラメータ組み合わせでの複数の再試行が強制されました。 推奨事項：retrieve ツールの説明を更新し、knowledgeBaseId を必須パラメータとして明示的にマークするとともに、フォーマット制約と例値を含む明確なドキュメントを追加してください。 因果関係：二次失敗 スパン：0466979670d14099 | 修正タイプ：システムプロンプトの修正 根本原因：すべての検索試行が失敗した後、エージェントは「一般的な知識に基づく」と主張して詳細な AI エネルギー消費情報を捏造しました。これは、ツールで取得した証拠なしに事実に基づくコンテンツを生成することを禁止する指示がシステムプロンプトに含まれていないためです。 推奨事項：検索ツールが失敗した場合、エージェントが研究タスクの完了不能を明示的に認めるよう、かつツールで検証されたソースなしに詳細な事実情報を生成しないよう禁止する指示をシステムプロンプトに追加してください。 修正タイプの区別こそが、根本原因分析を実行可能にする鍵です。ツールスキーマエラーは、検索ツールの knowledgeBaseId が明確に文書化されていないため TOOL_DESCRIPTION_FIX に分類されます。一方、下流でのハルシネーション（幻覚）は、永続的なツール障害への対処方法に関する指示が欠落しているため 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) 2 つのトリガーモードが利用可能です。ON_FAILURE（デフォルト）は、少なくとも 1 つの評価器が test_pass=False を返した場合のみ診断を実行するため、継続的インテグレーションおよび継続的デリバリー (CI/CD) における回帰検出に対してコスト効率に優れています。ALWAYS は結果に関わらずすべてのケースで診断を実行し、形式的には合格するケースでも最適化されていないパスを特定するのに役立ちます。 この統合により、CI/CD パイプラインは「3 つのテストが失敗しました」と通知するとともに、その理由と修正すべき点を示します。これによりフィードバックループが完結します：ケースを定義し、実験を実行し、スコアと診断結果を同時に取得し、推奨される修正を適用して再実行して確認を行います。 **注意:** デテクターの実行には、LLM ベースの分析に Amazon Bedrock の推論機能が使用され、課金が発生します。詳細は [Amazon Bedrock の価格設定](https://aws.amazon.com/bedrock/pricing/) をご確認ください。Amazon CloudWatch Logs のストレージも課金の対象となります。詳細は [Amazon CloudWatch の価格設定](https://aws.amazon.com/cloudwatch/pricing/) をご覧ください。特に、頻繁に実行される CI/CD パイプラインにデテクターを統合する際は、AWS Cost Explorer で使用状況を確認してください。 ## Amazon CloudWatch からの本番環境セッションの診断 上記の例ではローカルのセッションファイルを使用していますが、本番環境ではエージェントのトレースが OpenTelemetry を通じて Amazon CloudWatch Logs にリアルタイムで記録されます。CloudWatchProvider はこれらのトレースを直接 Amazon CloudWatch から取得し、デテクターで分析可能な Session オブジェクトに変換します: ```python from strands_evals.providers import CloudWatchProvider from strands_evals.detectors import diagnose_session, ConfidenceLevel provider = CloudWatchProvider(agent_name="my-research-agent", region="us-east-1") data = provider.get_evaluation_data(session_id="abc-123-def-456") session = data["trajectory"] result = diagnose_session(session, confidence_threshold=ConfidenceLevel.MEDIUM) for rc in result.root_causes: print(f"[{rc.fix_type}] {rc.fix_recommendation}") ``` 内部では、プロバイダーは Amazon CloudWatch Logs Insights を照会してセッション ID に一致する OTEL (OpenTelemetry) レコードを取得し、スパンメタデータからエージェントフレームワーク（Strands、LangChain、またはその他）を自動検出し、スパンを標準化された Session へマッピングします。この検出機能は Strands エージェントだけでなく、Amazon CloudWatch に OpenTelemetry のトレースをエクスポートするあらゆるフレームワークで動作します。 また、これをオフライン評価用の実験パイプラインと組み合わせることも可能です。CloudWatchProvider を使用して、エージェントを再実行せずに過去の生産環境でのセッションを評価・診断できます。さらに、LangfuseProvider や OpenSearchProvider を用いて、Langfuse または OpenSearch からトレースを取得することも可能です。 ## ベストプラクティス **MEDIUM 信頼度から開始する。** LOW しきい値は潜在的な問題をより多く検出しますが、ノイズも多いため、特定の失敗事例を深く調査する場合に有用です。MEDIUM は日常利用において良好な信号対雑音比を提供します。HIGH は、高確度の発見のみが必要な生産環境の監視用に確保してください。 **CI/CD では ON_FAILURE を、定期的な監査には ALWAYS を使用する。** ON_FAILURE に設定することで、LLM のコストは失敗率に比例し、すべてのテスト実行で実用的になります。サブオプティマルな挙動が合格ケースの中に隠れているのを防ぐため、ALWAYS モードの実行を週次またはリリースごとにスケジュールしてください。 **PRIMARY の失敗をまず修正する。**二次的および三次的な失敗は、根本原因に対処することで解決することが多い。複数の推奨事項を実装する前に、PRIMARY の失敗を修正することで下流の失敗が解消されるか確認してください。これにより反復サイクルを削減できます。 **推奨事項を修正タイプごとにグループ化する。**TOOL_DESCRIPTION_FIX に関する変更と SYSTEM_PROMPT_FIX に関する変更をそれぞれまとめてください。これにより、評価を再実行する際に各変更カテゴリの影響を独立して測定可能になります。 **事前に検出された失敗を analyze_root_cause に渡す。**detect_failures をすでに実行しており、根本原因分析を実行する前に結果を検査したい場合は、重複した検出を避けるために直接渡してください: failures = detect_failures(session) # ... 失敗の検査またはフィルタリング ... rca = analyze_root_cause(session, failures=failures.failures) **実験にはテストセッションを使用する。**本記事で使用されている flawed_session.json は、[Strands Evals テストスイート](https://github.com/strands-agents/evals)で入手可能です。これを使用してローカルで検出器を試すことができます。 ## リソースのクリーンアップ 検出関数自体は永続的な AWS リソースをプロビジョニングしません。ただし、エージェントのトレースに対して Amazon CloudWatch Logs のエクスポートを設定している場合は、以下の点を確認する必要があるかもしれません: - Amazon CloudWatch ロググループ：ロググループを削除すると、すべてのログデータが永久的に削除され、元に戻すことはできません。続行する前に、保持が必要なログのエクスポートを確認してください。テスト用に作成したロググループがある場合は、Amazon CloudWatch コンソールから削除するか、aws logs delete-log-group --log-group-name コマンドを実行して削除してください。 **Amazon Bedrock モデルへのアクセス：** LLM 分析には Amazon Bedrock が使用されます。mo

Strands Evals を用いた AI エージェントの失敗検出と根本原因分析

背景や根拠まで確認しますか？

関連記事

調べる

選ぶ

サイト