# 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. **Topics** + [Lancer l'analyse](#insights-one-time-start) + [Sondage pour obtenir les résultats](#insights-one-time-poll) + [Consultez les résultats de l'analyse des défaillances](#insights-one-time-review) + [Résultats relatifs à l'intention des utilisateurs](#insights-one-time-user-intent) + [Résultats du résumé de l'exécution](#insights-one-time-execution-summary) + [Interprétation des résultats](#insights-one-time-interpreting) + [Règles de validation](#insights-one-time-validation) ## Lancer l'analyse **Example** ``` 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 --json ``` 1. Exécutez `agentcore` pour ouvrir le TUI, puis sélectionnez **Exécuter** et choisissez **Insights** : ![Menu Exécuter : sélectionnez Insights](http://docs.aws.amazon.com/fr_fr/bedrock-agentcore/latest/devguide/images/tui/insights-run-select.png) 1. Choisissez la source de la session : ![Exécuter l'assistant Insights : sélectionner la source de session](http://docs.aws.amazon.com/fr_fr/bedrock-agentcore/latest/devguide/images/tui/insights-run-source.png) 1. Sélectionnez les informations à exécuter : ![Exécuter l'assistant Insights : sélectionner des insights](http://docs.aws.amazon.com/fr_fr/bedrock-agentcore/latest/devguide/images/tui/insights-run-insights.png) Suivez les étapes restantes de l'assistant (sessions, période de rétrospective, nom) et confirmez. ``` 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 **Example** Répertoriez tous les emplois d'Insights : ``` agentcore view insights --json ``` Afficher les détails d'une tâche spécifique : ``` 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) ``` ## 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 avec`sessionId`. | ## 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` et`userMessages`. | ## 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 `sessionId``approachTaken`, et`finalOutcome`. | ## Interprétation des résultats + **Commencez par l'analyse des défaillances :** concentrez-vous sur les catégories les plus élevées`affectedSessionCount`. 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 + `insights`et s'`evaluators`excluent mutuellement : fournissez l'un ou l'autre, pas les deux. + Maximum de 10 informations par demande. + `dataSourceConfig`est obligatoire et doit inclure au moins un groupe de journaux et un nom de service. + Si vous l'utilisez`onlineEvaluationConfigSource`, 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.