# 仕組み
<a name="insights-how-it-works"></a>

AgentCore インサイトは、エージェントの本番稼働動作に関する 3 つの質問に答えます。**なぜ失敗するのですか?** **ユーザーが求めているもの** と **の問題解決方法** 

## 取得する内容
<a name="insights-what-you-get"></a>

インサイトを実行すると、次の情報が表示されます。
+  個々のエラー ではなく、根本原因別にグループ化された反復的な問題など、**障害パターンの優先順位付けされたリスト** 。各パターンは、何が問題で、その理由を示します。Insights は [AgentCore レコメンデーション](optimization-recommendations.md)機能と統合され、障害パターンの修正を生成します。
+  **ユーザーインテントのマップ — **ユーザーが達成しようとしている最も一般的なことを、頻度でランク付けします。
+  **エージェントの動作パターンの概要 — **エージェントが通常問題にどのように対処し、どのような成果を達成するか。

これらは、設定できる 3 つのインサイトタイプに対応しています。
+  `Builtin.Insight.FailureAnalysis` — 障害パターン検出と根本原因分析
+  `Builtin.Insight.UserIntent` — ユーザーインテントの抽出とクラスタリング
+  `Builtin.Insight.ExecutionSummary` — エージェントの動作の要約とクラスタリング

## 分析の仕組み
<a name="insights-how-analysis-works"></a>

Insights は、ユーザーのメッセージ、エージェントの推論、ツール呼び出し、レスポンスの完全な記録であるエージェントのセッショントレースを調べ、次の 2 つのレベルで結果を生成します。

### セッションレベルの分析
<a name="insights-session-level"></a>

各セッションは個別に分析され、以下を判断します。
+ 実行中にエージェントが障害に遭遇したかどうか — セッションが成功したように見える場合でもエンドユーザーに表示されないトレース内の隠れた障害を含む
+ 発生した障害のカテゴリ (ツールエラー、幻覚、間違ったツールの選択など)
+ エージェントの実行のどの特定のステップが失敗の原因となったか
+ 根本原因
+ ユーザーが達成しようとしていること
+ エージェントが取ったアプローチと最終的な結果

### パターン検出
<a name="insights-pattern-discovery"></a>

個々のセッションが分析されると、サービスは同様の検出結果をグループ化することで、すべてのセッションで繰り返し発生するパターンを識別します。障害分析では、3 レベルの階層が生成されます。

1.  **失敗カテゴリ:** 「実行エラー」、「幻覚」、「誤ったアクション」などの広範なグループ化。

1.  **サブカテゴリ: **「レート制限」や「ツールスキーマエラー」など、より具体的な障害タイプ。

1.  **根本原因クラスター:** 各サブカテゴリ内で、特定の反復的な根本原因。各クラスターは以下を指示します。
   + 根本原因
   + 影響を受けるセッションの数
   + 詳細を検査できるセッション

ユーザーインテントと実行概要の場合、サービスは頻度でランク付けされたフラットクラスターを生成します。

## 実行時
<a name="insights-when-it-runs"></a>

インサイトの実行タイミングはユーザーが制御します。
+  **1 回限り:** デプロイ後、ユーザーの苦情が急増した後、毎週のレビューの一環としてなど、分析が必要なときはいつでもインサイト`StartBatchEvaluation`で を呼び出します。
+  **繰り返し:** クラスタリング頻度 (`DAILY`、`WEEKLY`、または `MONTHLY`) を設定すると、サービスが自動的に実行され、手動による介入なしで定期的なレポートが提供されます。

## 失敗カテゴリ
<a name="insights-failure-categories"></a>

Insights は、エージェントの障害タイプの広範な分類を認識します。


| Category | 例 | 
| --- | --- | 
| 実行エラー | 認証の失敗、リソースが見つかりません、サービスエラー、レート制限、タイムアウト、ツールスキーマ違反 | 
| タスク指示の問題 | 指示への非準拠、問題識別の失敗 | 
| アクションが正しくない | ツールの選択が正しくない、情報の取得が不十分である、不適切な明確化リクエスト | 
| コンテキスト処理 | ターン間のコンテキスト処理の失敗 | 
| ハルシネーション | 作成機能、誤解、誤った使用、履歴作成、パラメータ幻覚、作成ツール出力 | 
| 反復動作 | ツールコールの繰り返し、情報リクエストの繰り返し、ステップの繰り返し | 
| オーケストレーションエラー | 推論の不一致、目標の逸脱、早期終了、認識されない終了 | 
| LLM 出力の問題 | 非機密出力 | 
| 設定の不一致 | ツール定義の不一致 | 
| コーディング固有 | エッジケースの監視、依存関係の問題 |