View a markdown version of this page

1 回限りのインサイトレポート - Amazon Bedrock AgentCore
分析を開始する結果のポーリング障害分析の結果を確認するユーザーインテントの結果実行の概要結果結果の解釈検証ルール

1 回限りのインサイトレポート

StartBatchEvaluation を使用して、エージェントのセッションでオンデマンドインサイト分析を実行します。これは、デプロイ後、障害の急増後、または定期的な手動チェックとしてエージェントの動作を調査する場合に便利です。

分析を開始する

例
AgentCore CLI
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 <arn> --json
Interactive

  1. agentcore を実行して TUI を開き、実行を選択してインサイトを選択します。

    実行メニュー: Insights を選択します。

  2. セッションソースを選択します。

    インサイトウィザードの実行: セッションソースの選択

  3. 実行するインサイトを選択します。

    インサイトウィザードの実行: インサイトの選択

    残りのウィザードステップ (セッション、ルックバック期間、名前) を続行して確認します。

AWS SDK (boto3)
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

結果のポーリング

例
AgentCore CLI

すべてのインサイトジョブを一覧表示します。

agentcore view insights --json

特定のジョブの詳細を表示します。

agentcore view insights <id> --json
AWS SDK (boto3)
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 セッションが分析されます。