View a markdown version of this page

One-time Insights-Bericht - Amazon Grundgestein AgentCore
Starten Sie die AnalyseUmfrage nach ErgebnissenÜberprüfen Sie die Ergebnisse der FehleranalyseErgebnisse der BenutzerabsichtZusammenfassung der Ergebnisse der AusführungErgebnisse interpretierenRegeln für die Validierung

One-time Insights-Bericht

Verwenden Sie diese StartBatchEvaluation Option, um eine On-Demand-Analyse von Erkenntnissen über die Sitzungen Ihres Agenten durchzuführen. Dies ist nützlich, wenn Sie das Verhalten von Agenten nach einer Bereitstellung, einer Zunahme von Ausfällen oder als regelmäßige manuelle Überprüfung untersuchen möchten.

Starten Sie die Analyse

Beispiel
AgentCore CLI
agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --json

Die CLI ist standardmäßig asynchron — sie druckt die Job-ID und wird beendet. Verwenden Sie diese --wait Option, um zu blockieren, bis der Job abgeschlossen ist:

agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --wait --json

Wenn Sie bereits eine Konfiguration für die Online-Evaluierung bereitgestellt haben, können Sie deren Einstellungen übernehmen:

agentcore run insights --online-eval-config-arn <arn> --json
Interactive

  1. Starten Sieagentcore, um die TUI zu öffnen, wählen Sie dann Ausführen und anschließend Insights aus:

    Menü ausführen: Wählen Sie Insights

  2. Wählen Sie die Sitzungsquelle aus:

    Insights-Assistenten ausführen: Sitzungsquelle wählen

  3. Wählen Sie die Insights aus, die ausgeführt werden sollen:

    Insights-Assistenten ausführen: Wählen Sie Insights aus

    Fahren Sie mit den verbleibenden Schritten des Assistenten fort (Sitzungen, Lookback-Zeitraum, Name) und bestätigen Sie.

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}")

Sie können auch:

  • Grenzen Sie die Analyse auf einen bestimmten Zeitraum ein, indem Sie Folgendes hinzufügen filterConfig.timeRange

  • Analysieren Sie bestimmte Sitzungen anhand ihrer ID mit filterConfig.sessionIds

Umfrage nach Ergebnissen

Beispiel
AgentCore CLI

Alle Insights-Jobs auflisten:

agentcore view insights --json

Details für einen bestimmten Job anzeigen:

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)

Überprüfen Sie die Ergebnisse der Fehleranalyse

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']}")
Feld Typ Description

failures[].name

Zeichenfolge

Name der Fehlerkategorie (z. B. „Ausführungsfehler“, „Halluzinationen“).

failures[].affectedSessionCount

Ganzzahl

Anzahl der von dieser Kategorie betroffenen Sitzungen.

failures[].subCategories[].name

Zeichenfolge

Name der Unterkategorie (z. B. „Ratenbegrenzung“, „Verstöße gegen das Toolschema“).

failures[].subCategories[].affectedSessionCount

Ganzzahl

Anzahl der von dieser Unterkategorie betroffenen Sitzungen.

failures[].subCategories[].rootCauses[].name

Zeichenfolge

Clustername der Grundursache.

failures[].subCategories[].rootCauses[].recommendation

Zeichenfolge

Vorgeschlagene Lösung für diese Hauptursache.

failures[].subCategories[].rootCauses[].affectedSessionCount

Ganzzahl

Anzahl der Sitzungen, die von dieser Grundursache betroffen sind.

failures[].subCategories[].rootCauses[].affectedSessions

Auflisten

Sitzungen in diesem Cluster, jeweils mitsessionId.

Ergebnisse der Benutzerabsicht

Das userIntentResult Feld enthält gruppierte Benutzerabsichten:

if "userIntentResult" in result:
    for cluster in result["userIntentResult"]["userIntents"]:
        print(f"  {cluster['name']} ({cluster['affectedSessionCount']} sessions)")
        print(f"    {cluster['description']}")
Feld Typ Description

userIntents[].clusterId

Ganzzahl

Cluster-ID.

userIntents[].name

Zeichenfolge

Clustername, der die gemeinsame Absicht beschreibt.

userIntents[].description

Zeichenfolge

Detaillierte Beschreibung des Absichtsmusters.

userIntents[].affectedSessionCount

Ganzzahl

Anzahl der Sitzungen mit dieser Absicht.

userIntents[].affectedSessions

Auflisten

Sitzungen in diesem Cluster, jeweils mit sessionId unduserMessages.

Zusammenfassung der Ergebnisse der Ausführung

Das executionSummaryResult Feld enthält geclusterte Ausführungsmuster:

Feld Typ Description

executionSummaries[].clusterId

Ganzzahl

Cluster-ID.

executionSummaries[].name

Zeichenfolge

Clustername, der das Ausführungsmuster beschreibt.

executionSummaries[].description

Zeichenfolge

Detaillierte Beschreibung des Musters.

executionSummaries[].affectedSessionCount

Ganzzahl

Anzahl der Sitzungen mit diesem Muster.

executionSummaries[].affectedSessions

Auflisten

Sitzungen in diesem Cluster, jeweils mit sessionIdapproachTaken, undfinalOutcome.

Ergebnisse interpretieren

  • Beginnen Sie mit der Fehleranalyse: Konzentrieren Sie sich auf die Kategorien mit den höchsten WertenaffectedSessionCount. Dies sind die wichtigsten Probleme.

  • Gehen Sie den Ursachen auf den Grund: In jeder Unterkategorie erfahren Sie anhand von Ursachenclustern genau, was falsch läuft und wie Sie es beheben können. Jeder Cluster umfasst ein recommendation Feld.

  • Verwenden Sie Benutzerabsichten, um Prioritäten zu setzen: Cross-reference Fehlerkategorien mit Benutzerabsichtsclustern. Fehler, die sich auf Ihre häufigsten Benutzerabsichten auswirken, sollten höchste Priorität haben.

  • Ausführungsmuster verfolgen: Anhand von Ausführungszusammenfassungen wird aufgezeigt, wie Ihr Agent Probleme angeht. So können Sie nachvollziehen, ob Fehler eher auf die Strategie des Agenten als auf Probleme zurückzuführen sind. tool/environment

Regeln für die Validierung

  • insightsund schließen evaluators sich gegenseitig aus — geben Sie das eine oder das andere an, nicht beides.

  • Maximal 10 Erkenntnisse pro Anfrage.

  • dataSourceConfigist erforderlich und muss mindestens eine Protokollgruppe und einen Dienstnamen enthalten.

  • Wenn Sie es verwendenonlineEvaluationConfigSource, geben Sie insights oder nicht an evaluators (die Konfiguration wird vererbt).

  • Wenn filterConfig.timeRange angegeben, startTime muss es früher als seinendTime.

  • Zeitstempel müssen ein gültiges ISO 8601-Format haben.

  • Pro Konto kann jeweils nur eine Batch-Auswertung aktiv sein.

  • Pro Insights-Run werden maximal 500 Sitzungen analysiert.