View a markdown version of this page

One-time rapporto di approfondimento - Amazon Bedrock AgentCore
Avviate l'analisiSondaggio per visualizzare i risultatiEsamina i risultati dell'analisi degli erroriRisultati delle intenzioni dell'utenteRiepilogo dei risultati dell'esecuzioneInterpretazione dei risultatiRegole di convalida

One-time rapporto di approfondimento

Utilizzalo StartBatchEvaluation per eseguire un'analisi approfondita su richiesta delle sessioni del tuo agente. Ciò è utile quando si desidera analizzare il comportamento degli agenti dopo una distribuzione, un picco di guasti o come controllo manuale periodico.

Avviate l'analisi

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

La CLI è asincrona per impostazione predefinita: stampa l'ID del lavoro ed esce. Utilizzalo --wait per bloccare fino al completamento del lavoro:

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

Se disponi già di una configurazione di valutazione online, puoi ereditarne le impostazioni:

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

  1. Esegui agentcore per aprire la TUI, quindi seleziona esegui e scegli Insights:

    Menu Esegui: seleziona Insights

  2. Scegli la fonte della sessione:

    Esegui la procedura guidata Insights: seleziona l'origine della sessione

  3. Seleziona gli approfondimenti da eseguire:

    Esegui la procedura guidata Insights: seleziona approfondimenti

    Continua con i passaggi rimanenti della procedura guidata (sessioni, periodo di lookback, nome) e conferma.

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

Puoi anche:

  • Restringi l'analisi a un intervallo di tempo specifico aggiungendo filterConfig.timeRange

  • Analizza sessioni specifiche per ID utilizzando filterConfig.sessionIds

Sondaggio per visualizzare i risultati

Esempio
AgentCore CLI

Elenca tutti i lavori in Insights:

agentcore view insights --json

Visualizza i dettagli di un lavoro specifico:

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)

Esamina i risultati dell'analisi degli errori

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']}")
Campo Tipo Description

failures[].name

Stringa

Nome della categoria di errore (ad es. «Errori di esecuzione», «Allucinazioni»).

failures[].affectedSessionCount

Numero intero

Numero di sessioni interessate da questa categoria.

failures[].subCategories[].name

Stringa

Nome della sottocategoria (ad esempio, «Rate limiting», «Violazioni dello schema degli strumenti»).

failures[].subCategories[].affectedSessionCount

Numero intero

Numero di sessioni interessate da questa sottocategoria.

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

Stringa

Nome della causa principale del cluster.

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

Stringa

Correzione consigliata per questa causa principale.

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

Numero intero

Numero di sessioni interessate da questa causa principale.

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

List

Sessioni in questo cluster, ciascuna consessionId.

Risultati delle intenzioni dell'utente

Il userIntentResult campo contiene intenti utente raggruppati:

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

userIntents[].clusterId

Numero intero

Identificatore del cluster.

userIntents[].name

Stringa

Nome del cluster che descrive l'intento comune.

userIntents[].description

Stringa

Descrizione dettagliata del modello di intento.

userIntents[].affectedSessionCount

Numero intero

Numero di sessioni con questo intento.

userIntents[].affectedSessions

List

Sessioni in questo cluster, ognuna con sessionId euserMessages.

Riepilogo dei risultati dell'esecuzione

Il executionSummaryResult campo contiene modelli di esecuzione raggruppati:

Campo Tipo Description

executionSummaries[].clusterId

Numero intero

Identificatore del cluster.

executionSummaries[].name

Stringa

Nome del cluster che descrive il modello di esecuzione.

executionSummaries[].description

Stringa

Descrizione dettagliata del pattern.

executionSummaries[].affectedSessionCount

Numero intero

Numero di sessioni con questo schema.

executionSummaries[].affectedSessions

List

Sessioni in questo cluster, ciascuna con sessionIdapproachTaken, efinalOutcome.

Interpretazione dei risultati

  • Inizia con l'analisi degli errori: concentrati sulle categorie con i risultati più elevatiaffectedSessionCount. Queste sono le questioni più importanti.

  • Approfondisci le cause principali: all'interno di ogni sottocategoria, i cluster di cause principali indicano esattamente cosa non va e come risolverlo. Ogni cluster include un campo. recommendation

  • Usa le intenzioni degli utenti per stabilire le priorità: categorie di Cross-reference errori con i cluster di intenti degli utenti. Gli errori che influiscono sulle intenzioni degli utenti più comuni dovrebbero avere la massima priorità.

  • Tieni traccia dei modelli di esecuzione: i riepiloghi dell'esecuzione rivelano come l'agente affronta i problemi, utili per capire se gli errori derivano dalla strategia dell'agente o dai problemi. tool/environment

Regole di convalida

  • insightse evaluators si escludono a vicenda: fornisci l'una o l'altra, non entrambe.

  • Massimo 10 approfondimenti per richiesta.

  • dataSourceConfigè obbligatorio e deve includere almeno un gruppo di log e un nome di servizio.

  • Se si utilizzaonlineEvaluationConfigSource, non fornire insights o evaluators (la configurazione è ereditata).

  • Se filterConfig.timeRange specificato, startTime deve essere precedente a. endTime

  • I timestamp devono essere in formato ISO 8601 valido.

  • Può essere attiva una sola valutazione in batch per account alla volta.

  • Vengono analizzate un massimo di 500 sessioni per ogni analisi approfondita.