はじめに
AIエージェントの本番運用が広がるにつれ、「エージェントがなぜ失敗したのか」を特定する難しさが深刻な課題になっている。エージェントの実行軌跡は長く、確率的で、マルチエージェント構成ではさらに複雑化する。従来のログ分析やプロンプトの試行錯誤では、根本原因の特定に多大な工数がかかっていた。
Microsoft Researchが公開した AgentRx は、この課題に正面から取り組むオープンソースの診断フレームワークである。失敗したエージェント軌跡から「最初の回復不能な障害ステップ（Critical Failure Step）」を自動的に特定し、9カテゴリの障害分類体系に基づいて原因を帰属する。
この記事で学べること
- AgentRxの4段階診断パイプラインの仕組み
- 9カテゴリの障害分類体系（Failure Taxonomy）の内容
- 115の失敗軌跡ベンチマークによる評価結果
- AgentRxのセットアップと実行方法
対象読者
- AIエージェントを開発・運用しているエンジニア
- マルチエージェントシステムの品質改善に取り組んでいるチーム
- エージェントの障害分析を自動化・効率化したい方
TL;DR
- AgentRxはMicrosoft Research発のオープンソース診断フレームワークで、AIエージェントの失敗原因を自動特定する
- 4段階パイプライン（軌跡正規化→制約合成→ガード付き評価→LLM判定）で、監査可能なログとともに「最初の致命的ステップ」を特定する
- 障害特定精度が既存手法比で +23.6% 、根本原因帰属が +22.9% 改善
- 115の手動アノテーション済み失敗軌跡ベンチマークとコードがOSSとして公開されている
AIエージェントのデバッグはなぜ難しいのか
従来のソフトウェアデバッグでは、スタックトレースやログから障害箇所を比較的容易に特定できる。しかしAIエージェントのデバッグには、以下の固有の困難がある。
| 要因 | 説明 |
|---|---|
| 確率的な実行 | 同じ入力でも異なる実行パスをたどり、再現性が低い |
| 長い実行軌跡 | 数十ステップに及ぶ軌跡の中から根本原因を見つける必要がある |
| マルチエージェント | 複数エージェント間の相互作用で障害が伝播する |
| ツール出力のノイズ | API応答やファイル操作の結果が非決定的 |
| 障害の遅延発現 | 根本原因のステップと実際にタスクが失敗するステップが異なる |
AgentRxの論文（arXiv: 2602.02475）によると、プロンプトベースのアプローチでは、障害ステップの特定精度が低く、「なぜ失敗したのか」の説明が不十分であることが報告されている。
AgentRxの4段階診断パイプライン
AgentRxは、ドメインに依存しない4段階のパイプラインで障害診断を行う。
Stage 1: 軌跡正規化（Trajectory Normalization）
異なるドメイン・フレームワークから出力される異種ログを、共通の中間表現（IR: Intermediate Representation）に変換する。τ-benchのAPI呼び出しログ、Magentic-Oneのマルチエージェントログ、Flashのインシデント管理トレースなど、形式が異なるログを統一的に扱えるようにする段階である。
# Stage 1: 生ログをIRに変換
python run.py trajectory.json --stage ir --run-name my_run
Stage 2: 制約合成（Constraint Synthesis）
ツールスキーマとドメインポリシーから、実行可能な制約を自動生成する。制約は 静的制約 と 動的制約 の2種類がある。
- 静的制約: ツールのAPIスキーマから導出される制約（例: 「APIは有効なJSON応答を返さなければならない」）
- 動的制約: ドメインポリシーや実行コンテキストから導出される制約（例: 「ユーザーの確認なしにデータを削除してはならない」）
# 静的制約の生成
python src/invariants/static_invariant_generator.py \
--input-path trajectory.json --domain tau --endpoint trapi
# 動的制約の生成
python src/invariants/dynamic_invariant_generator.py \
--input-path trajectory.json --domain tau --mode stepbystep
Stage 3: ガード付き評価（Guarded Evaluation）
生成された制約をステップごとに評価する。各制約にはガード条件が設定されており、該当するステップでのみ評価される。評価結果は 監査可能な検証ログ として記録され、各違反にはエビデンスが紐付けられる。
# 制約の検証
python src/invariants/checker.py --input-path trajectory.json \
--static-invariants static_inv.json \
--dynamic-invariants-dir dyn_inv/
この段階で生成される検証ログが、AgentRxの透明性を支える中核要素である。単に「ここが間違っている」と指摘するのではなく、「この制約がこのエビデンスに基づいて違反している」という形式で記録される。
Stage 4: LLM判定（LLM-based Judging）
検証ログと障害分類体系（後述）を入力として、LLMが Critical Failure Step （最初の回復不能な障害ステップ）を特定する。LLM判定には以下の2つのモードがある。
# LLM判定の実行
python src/judge/judge.py --domain tau --log_file trajectory.json \
--endpoint trapi --mode combined
9カテゴリの障害分類体系
AgentRxは、グラウンデッド・セオリー（質的研究手法）に基づいて導出された、ドメイン横断的な障害分類体系を定義している。この分類体系により、障害の「種類」を体系的に理解できる。
| # | カテゴリ | 説明 | 具体例 |
|---|---|---|---|
| 1 | Plan Adherence Failure | 計画に従わず指示を逸脱 | 「3件取得」の指示に対し1件のみ取得 |
| 2 | Invention of New Information | 存在しない情報の捏造 | 実在しないユーザーIDの生成 |
| 3 | Invalid Invocation | ツール呼び出しの引数エラー | 必須パラメータの欠落、型不一致 |
| 4 | Misinterpretation of Tool Output | ツール出力の誤解釈 | エラー応答を成功と判断 |
| 5 | Intent–Plan Misalignment | ユーザー意図と計画の不一致 | 「削除」の依頼に対し「更新」を計画 |
| 6 | Under-specified User Intent | ユーザー指示の曖昧さ | 対象が複数該当するが確認せず実行 |
| 7 | Intent Not Supported | サポート外の操作要求 | 利用可能なツールでは実現不可能な操作 |
| 8 | Guardrails Triggered | ガードレール発動 | 安全制約によるブロック |
| 9 | System Failure | インフラ障害 | API タイムアウト、認証エラー |
この分類体系は、エージェント側の問題（1〜5）、ユーザー・環境側の問題（6〜7）、システム側の問題（8〜9）に大別できる。開発者は障害カテゴリの分布を分析することで、エージェントの改善ポイントを体系的に把握できる。
AgentRxベンチマーク: 115の失敗軌跡
AgentRxの評価には、3つのドメインにまたがる 115の手動アノテーション済み失敗軌跡 が使用されている。このベンチマークもOSSとして公開されている。
| ドメイン | ベンチマーク | 軌跡数 | 中央値ステップ数 | 特徴 |
|---|---|---|---|---|
| 構造化APIワークフロー | τ-bench | 29 | 36 | 小売・サービス業務のAPI操作 |
| インシデント管理 | Flash | 42 | 3 | システム障害対応・トラブルシューティング |
| オープンエンドタスク | Magentic-One | 44 | 33 | Web検索・ファイル操作のマルチエージェント |
評価結果
AgentRxは、プロンプトベースラインと比較して以下の改善を達成している。
| 指標 | 改善幅 | 説明 |
|---|---|---|
| 障害ステップ特定（Step Localization） | +23.6% | 正しいCritical Failure Stepの特定精度 |
| 根本原因帰属（Root-Cause Attribution） | +22.9% | 正しい障害カテゴリへの分類精度 |
これらの改善は、制約合成とガード付き評価によるエビデンスベースのアプローチが、単純なプロンプティングを大幅に上回ることを示している。
セットアップと実行方法
環境構築
AgentRxはPythonで実装されており、Azure OpenAI または互換エンドポイントを使用してLLM判定を行う。
# リポジトリのクローン
git clone https://github.com/microsoft/AgentRx.git
cd AgentRx
# 依存関係のインストール
pip install -r requirements.txt
環境変数の設定
LLMエンドポイントの設定が必要である。Azure OpenAIを使用する場合は以下のように設定する。
# Azure OpenAI エンドポイント
export AGENT_VERIFY_ENDPOINT="https://my-resource.openai.azure.com/"
export AGENT_VERIFY_DEPLOYMENT="gpt-5"
認証には Azure AD トークン（az login またはManaged Identity）を使用する。
パイプラインの実行
全ステージを一括実行する場合は、以下のコマンドを使用する。
# 全パイプライン一括実行
python run.py trajectory.json
# ドメインを明示的に指定する場合
python run.py trajectory.json --domain tau
出力は runs/<run_name>/ ディレクトリに保存される。診断レポートには、各ステップの制約違反、エビデンス、Critical Failure Stepの特定結果が含まれる。
ステージごとの実行
デバッグや部分的な再実行のために、各ステージを個別に実行することもできる。
# Stage 1: IR変換
python run.py trajectory.json --stage ir --run-name my_run
# Stage 2: 静的制約生成
python run.py trajectory.json --stage static --run-dir runs/my_run
# Stage 3: 動的制約生成
python run.py trajectory.json --stage dynamic --run-dir runs/my_run
# Stage 4: 制約検証
python run.py trajectory.json --stage check --run-dir runs/my_run
# Stage 5: LLM判定
python run.py trajectory.json --stage judge --run-dir runs/my_run
# Stage 6: レポート生成
python run.py trajectory.json --stage report --run-dir runs/my_run
対応ドメインと拡張性
AgentRxは現在、以下の3ドメインに対応している。
| ドメイン識別子 | 対象 | 用途 |
|---|---|---|
tau |
τ-bench | 小売・カスタマーサービスのAPI操作 |
magentic |
Magentic-One | マルチエージェントのWeb・ファイル操作 |
flash |
Flash | インシデント管理・障害対応 |
(auto) |
自動検出 | LLMフォールバックによるドメイン推定 |
フレームワークの設計はドメインに依存しないため、新しいドメインへの拡張も可能である。data/ ディレクトリにドメインポリシーとツールスキーマを追加することで、カスタムドメインの制約合成に対応できる。
従来手法との違い
AgentRxが既存のデバッグ手法と異なる点を整理する。
| 観点 | プロンプトベース手法 | AgentRx |
|---|---|---|
| 障害特定方法 | LLMにログを渡して推測 | 制約合成+エビデンスベース検証 |
| 監査可能性 | なし（ブラックボックス） | 検証ログで全ステップ追跡可能 |
| ドメイン依存 | プロンプトごとにカスタマイズ必要 | ドメイン非依存のパイプライン |
| 障害分類 | 自由記述 | 9カテゴリの体系的分類 |
| 再現性 | 低い（LLM応答に依存） | 高い（制約は決定的に評価） |
特筆すべきは 監査可能性 である。AgentRxは各ステップで制約違反のエビデンスを記録するため、「なぜその障害ステップが特定されたのか」を事後的に検証できる。これはエンタープライズ環境でのコンプライアンス要件にも対応しうる特徴である。
活用シナリオ
AgentRxは以下のようなシナリオで活用が見込まれる。
開発フェーズ: エージェントのテスト実行で失敗した軌跡をAgentRxで分析し、改善ポイントを体系的に特定する。障害カテゴリの分布から、プロンプト改善が必要なのか、ツール定義の修正が必要なのかを判断できる。
運用フェーズ: 本番環境で発生したエージェント障害の事後分析に使用する。監査可能な検証ログは、インシデントレビューやポストモーテムの根拠資料として活用できる。
ベンチマーク: 自社エージェントの障害パターンをAgentRxの分類体系で整理し、バージョン間の品質推移を定量的に追跡する。
まとめ
- AgentRxは、AIエージェントの障害診断を「試行錯誤」から「体系的なエンジニアリング」に転換するフレームワークである
- 4段階パイプラインと9カテゴリの障害分類体系により、監査可能な形で根本原因を特定できる
- 115の失敗軌跡ベンチマークにより、既存手法比で障害特定 +23.6%、根本原因帰属 +22.9% の改善が確認されている
- コードとデータセットがOSSとして公開されており、自社エージェントへの適用が可能である
エージェントの障害分析を自動化・標準化したい開発チームにとって、AgentRxは有力な選択肢となるだろう。