# 1 回限りのインサイトレポート
`StartBatchEvaluation` を使用して、エージェントのセッションでオンデマンドインサイト分析を実行します。これは、デプロイ後、障害の急増後、または定期的な手動チェックとしてエージェントの動作を調査する場合に便利です。
**Topics**
+ [分析を開始する](#insights-one-time-start)
+ [結果のポーリング](#insights-one-time-poll)
+ [障害分析の結果を確認する](#insights-one-time-review)
+ [ユーザーインテントの結果](#insights-one-time-user-intent)
+ [実行の概要結果](#insights-one-time-execution-summary)
+ [結果の解釈](#insights-one-time-interpreting)
+ [検証ルール](#insights-one-time-validation)
## 分析を開始する
**Example**
```
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --json
```
CLI はデフォルトで非同期 です 。ジョブ ID を出力して終了します。ジョブが完了するまで `--wait`を使用して をブロックします。
```
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --wait --json
```
オンライン評価設定が既にデプロイされている場合は、その設定を継承できます。
```
agentcore run insights --online-eval-config-arn --json
```
1. `agentcore` を実行して TUI を開き、**実行**を選択して**インサイト**を選択します。
1. セッションソースを選択します。
1. 実行するインサイトを選択します。
残りのウィザードステップ (セッション、ルックバック期間、名前) を続行して確認します。
```
import boto3
import uuid
client = boto3.client("bedrock-agentcore", region_name="us-west-2")
response = client.start_batch_evaluation(
batchEvaluationName=f"insights-run-{uuid.uuid4().hex[:8]}",
insights=[
{"insightId": "Builtin.Insight.FailureAnalysis"},
{"insightId": "Builtin.Insight.UserIntent"},
],
dataSourceConfig={
"cloudWatchLogs": {
"serviceNames": ["MyAgent.DEFAULT"],
"logGroupNames": [
"/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
],
}
},
# Optional: narrow to a specific time range
filterConfig={
"timeRange": {
"startTime": "2026-05-27T00:00:00Z",
"endTime": "2026-06-03T00:00:00Z",
},
# Or analyze specific sessions by ID
"sessionIds": ["session-001", "session-002", "session-003"]
},
clientToken=str(uuid.uuid4()),
)
batch_eval_id = response["batchEvaluationId"]
print(f"Started: {batch_eval_id}")
```
以下の操作も可能です。
+ 追加して分析を特定の時間範囲に絞り込む `filterConfig.timeRange`
+ を使用して ID で特定のセッションを分析する `filterConfig.sessionIds`
## 結果のポーリング
**Example**
すべてのインサイトジョブを一覧表示します。
```
agentcore view insights --json
```
特定のジョブの詳細を表示します。
```
agentcore view insights --json
```
```
import time
while True:
result = client.get_batch_evaluation(batchEvaluationId=batch_eval_id)
status = result["status"]
print(f"Status: {status}")
if status in ("COMPLETED", "COMPLETED_WITH_ERRORS", "FAILED", "STOPPED"):
break
time.sleep(30)
```
## 障害分析の結果を確認する
```
if "failureAnalysisResult" in result:
for category in result["failureAnalysisResult"]["failures"]:
print(f"\nCategory: {category['name']} ({category['affectedSessionCount']} sessions)")
for sub in category.get("subCategories", []):
print(f" Subcategory: {sub['name']} ({sub['affectedSessionCount']} sessions)")
for rc in sub.get("rootCauses", []):
print(f" Root cause: {rc['name']}")
print(f" Recommendation: {rc['recommendation']}")
print(f" Affected sessions: {rc['affectedSessionCount']}")
```
| フィールド | タイプ | 説明 |
| --- | --- | --- |
| `failures[].name` | 文字列 | 失敗カテゴリ名 (「実行エラー」、「幻覚」など）。 |
| `failures[].affectedSessionCount` | 整数 | このカテゴリの影響を受けるセッションの数。 |
| `failures[].subCategories[].name` | String | サブカテゴリ名 (「レート制限」、「ツールスキーマ違反」など）。 |
| `failures[].subCategories[].affectedSessionCount` | 整数 | このサブカテゴリの影響を受けるセッションの数。 |
| `failures[].subCategories[].rootCauses[].name` | String | 根本原因クラスター名。 |
| `failures[].subCategories[].rootCauses[].recommendation` | String | この根本原因の推奨される修正。 |
| `failures[].subCategories[].rootCauses[].affectedSessionCount` | 整数 | この根本原因の影響を受けるセッションの数。 |
| `failures[].subCategories[].rootCauses[].affectedSessions` | リスト | このクラスター内のセッション。それぞれに があります`sessionId`。 |
## ユーザーインテントの結果
`userIntentResult` フィールドには、クラスター化されたユーザーインテントが含まれます。
```
if "userIntentResult" in result:
for cluster in result["userIntentResult"]["userIntents"]:
print(f" {cluster['name']} ({cluster['affectedSessionCount']} sessions)")
print(f" {cluster['description']}")
```
| フィールド | タイプ | 説明 |
| --- | --- | --- |
| `userIntents[].clusterId` | 整数 | クラスター識別子。 |
| `userIntents[].name` | String | 共通インテントを記述するクラスター名。 |
| `userIntents[].description` | String | インテントパターンの詳細な説明。 |
| `userIntents[].affectedSessionCount` | 整数 | このインテントを持つセッションの数。 |
| `userIntents[].affectedSessions` | リスト | このクラスター内のセッション。それぞれに `sessionId`と があります`userMessages`。 |
## 実行の概要結果
`executionSummaryResult` フィールドには、クラスター化された実行パターンが含まれます。
| フィールド | タイプ | 説明 |
| --- | --- | --- |
| `executionSummaries[].clusterId` | 整数 | クラスター識別子。 |
| `executionSummaries[].name` | String | 実行パターンを説明するクラスター名。 |
| `executionSummaries[].description` | String | パターンの詳細な説明。 |
| `executionSummaries[].affectedSessionCount` | 整数 | このパターンのセッション数。 |
| `executionSummaries[].affectedSessions` | リスト | このクラスター内のセッション。それぞれに `sessionId`、`approachTaken`、および があります`finalOutcome`。 |
## 結果の解釈
+ **障害分析から始める:** が最も高いカテゴリに焦点を当てます`affectedSessionCount`。これらは最も影響の大きい問題を表します。
+ **根本原因を詳しく調べる:** 各サブカテゴリ内で、根本原因クラスターは何が起こり、どのように修正するかを正確に指示します。各クラスターには `recommendation`フィールドが含まれます。
+ **ユーザーインテントを使用して優先順位を付ける:** 障害カテゴリをユーザーインテントクラスターと相互参照します。最も一般的なユーザーインテントに影響する障害は、最優先事項である必要があります。
+ **実行パターンの追跡:** 実行の概要は、エージェントが問題にどのように対処するかを示しています。これは、障害がエージェントの戦略とツール/環境の問題のどちらに起因するかを理解するのに役立ちます。
## 検証ルール
+ `insights` と `evaluators`は相互に排他的です。両方ではなく、どちらかを指定します。
+ リクエストごとに最大 10 個のインサイト。
+ `dataSourceConfig` は必須であり、少なくとも 1 つのロググループと 1 つのサービス名を含める必要があります。
+ を使用する場合は`onlineEvaluationConfigSource`、 `insights`または を指定しないでください `evaluators` (設定は継承されます）。
+ `filterConfig.timeRange` を指定する場合、 は より前`startTime`である必要があります`endTime`。
+ タイムスタンプは有効な ISO 8601 形式である必要があります。
+ アカウントごとに一度にアクティブにできるバッチ評価は 1 つだけです。
+ インサイトの実行ごとに最大 500 セッションが分析されます。