View a markdown version of this page

One-time rapport d'analyse - Amazon Bedrock AgentCore
Lancer l'analyseSondage pour obtenir les résultatsConsultez les résultats de l'analyse des défaillancesRésultats relatifs à l'intention des utilisateursRésultats du résumé de l'exécutionInterprétation des résultatsRègles de validation

One-time rapport d'analyse

Utilisez-le StartBatchEvaluation pour effectuer une analyse des informations à la demande au cours des sessions de votre agent. Cela est utile lorsque vous souhaitez étudier le comportement d'un agent après un déploiement, un pic de défaillances ou lors d'une vérification manuelle périodique.

Lancer l'analyse

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

La CLI est asynchrone par défaut : elle imprime l'ID de la tâche et sort. --waitÀ utiliser pour bloquer jusqu'à ce que la tâche soit terminée :

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

Si une configuration d'évaluation en ligne est déjà déployée, vous pouvez hériter de ses paramètres :

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

  1. Exécutez agentcore pour ouvrir le TUI, puis sélectionnez Exécuter et choisissez Insights :

    Menu Exécuter : sélectionnez Insights

  2. Choisissez la source de la session :

    Exécuter l'assistant Insights : sélectionner la source de session

  3. Sélectionnez les informations à exécuter :

    Exécuter l'assistant Insights : sélectionner des insights

    Suivez les étapes restantes de l'assistant (sessions, période de rétrospective, nom) et confirmez.

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

Vous pouvez également :

  • Limitez l'analyse à une plage de temps spécifique en ajoutant filterConfig.timeRange

  • Analysez des sessions spécifiques par identifiant en utilisant filterConfig.sessionIds

Sondage pour obtenir les résultats

Exemple
AgentCore CLI

Répertoriez tous les emplois d'Insights :

agentcore view insights --json

Afficher les détails d'une tâche spécifique :

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)

Consultez les résultats de l'analyse des défaillances

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']}")
Champ Type Description

failures[].name

String

Nom de la catégorie d'échec (par exemple, « Erreurs d'exécution », « Hallucinations »).

failures[].affectedSessionCount

Entier

Nombre de sessions concernées par cette catégorie.

failures[].subCategories[].name

String

Nom de la sous-catégorie (par exemple, « Limitation du débit », « Violations du schéma d'outil »).

failures[].subCategories[].affectedSessionCount

Entier

Nombre de sessions concernées par cette sous-catégorie.

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

String

Nom du cluster responsable.

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

String

Solution suggérée pour cette cause première.

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

Entier

Nombre de sessions affectées par cette cause première.

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

List

Sessions de ce cluster, chacune avecsessionId.

Résultats relatifs à l'intention des utilisateurs

Le userIntentResult champ contient les intentions des utilisateurs groupées :

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

userIntents[].clusterId

Entier

Identifiant du cluster.

userIntents[].name

String

Nom du cluster décrivant l'intention commune.

userIntents[].description

String

Description détaillée du modèle d'intention.

userIntents[].affectedSessionCount

Entier

Nombre de sessions ayant cette intention.

userIntents[].affectedSessions

List

Sessions de ce cluster, chacune avec sessionId etuserMessages.

Résultats du résumé de l'exécution

Le executionSummaryResult champ contient des modèles d'exécution en cluster :

Champ Type Description

executionSummaries[].clusterId

Entier

Identifiant du cluster.

executionSummaries[].name

String

Nom du cluster décrivant le modèle d'exécution.

executionSummaries[].description

String

Description détaillée du patron

executionSummaries[].affectedSessionCount

Entier

Nombre de sessions avec ce modèle.

executionSummaries[].affectedSessions

List

Les sessions de ce cluster, chacune avec sessionIdapproachTaken, etfinalOutcome.

Interprétation des résultats

  • Commencez par l'analyse des défaillances : concentrez-vous sur les catégories les plus élevéesaffectedSessionCount. Ce sont là les problèmes les plus importants.

  • Analysez les causes profondes : dans chaque sous-catégorie, des groupes de causes profondes vous indiquent exactement ce qui ne va pas et comment y remédier. Chaque cluster inclut un recommendation champ.

  • Utilisez les intentions des utilisateurs pour établir des priorités : catégories Cross-reference d'échec associées à des clusters d'intentions utilisateurs. Les défaillances affectant vos intentions d'utilisateur les plus courantes doivent être prioritaires.

  • Suivez les modèles d'exécution : les résumés d'exécution révèlent comment votre agent aborde les problèmes, ce qui est utile pour comprendre si les échecs sont dus à la stratégie de l'agent par rapport à tool/environment des problèmes.

Règles de validation

  • insightset s'evaluatorsexcluent mutuellement : fournissez l'un ou l'autre, pas les deux.

  • Maximum de 10 informations par demande.

  • dataSourceConfigest obligatoire et doit inclure au moins un groupe de journaux et un nom de service.

  • Si vous l'utilisezonlineEvaluationConfigSource, ne fournissez pas insights ou evaluators (la configuration est héritée).

  • Si elle filterConfig.timeRange est spécifiée, elle startTime doit être antérieure àendTime.

  • Les horodatages doivent être au format ISO 8601 valide.

  • Une seule évaluation par lots peut être active par compte à la fois.

  • Un maximum de 500 sessions sont analysées par analyse d'informations.