# One-time relatório de insights Use `StartBatchEvaluation` para executar uma análise de insights sob demanda sobre as sessões do seu agente. Isso é útil quando você deseja investigar o comportamento do agente após uma implantação, um pico de falhas ou como uma verificação manual periódica. **Topics** + [Inicie a análise](#insights-one-time-start) + [Sondagem para obter os resultados](#insights-one-time-poll) + [Revise os resultados da análise de falhas](#insights-one-time-review) + [Resultados da intenção do usuário](#insights-one-time-user-intent) + [Resultados resumidos da execução](#insights-one-time-execution-summary) + [Como interpretar os resultados do](#insights-one-time-interpreting) + [Regras de validação](#insights-one-time-validation) ## Inicie a análise **Example** ``` agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --json ``` A CLI é assíncrona por padrão — ela imprime o ID do trabalho e sai. Use `--wait` para bloquear até que o trabalho seja concluído: ``` agentcore run insights --runtime MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 --wait --json ``` Se você já tiver uma configuração de avaliação on-line implantada, poderá herdar suas configurações: ``` agentcore run insights --online-eval-config-arn --json ``` 1. Executar `agentcore` para abrir a TUI, depois selecione **executar** e escolha **Insights**: ![Menu Executar: selecione Insights](http://docs.aws.amazon.com/pt_br/bedrock-agentcore/latest/devguide/images/tui/insights-run-select.png) 1. Escolha a fonte da sessão: ![Execute o assistente do Insights: selecione a fonte da sessão](http://docs.aws.amazon.com/pt_br/bedrock-agentcore/latest/devguide/images/tui/insights-run-source.png) 1. Selecione os insights a serem executados: ![Execute o assistente do Insights: selecione insights](http://docs.aws.amazon.com/pt_br/bedrock-agentcore/latest/devguide/images/tui/insights-run-insights.png) Continue com as etapas restantes do assistente (sessões, período de análise, nome) e confirme. ``` 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}") ``` Você também pode: + Limite a análise a um intervalo de tempo específico adicionando `filterConfig.timeRange` + Analise sessões específicas por ID usando `filterConfig.sessionIds` ## Sondagem para obter os resultados **Example** Liste todas as vagas do Insights: ``` agentcore view insights --json ``` Veja os detalhes de um trabalho específico: ``` 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) ``` ## Revise os resultados da análise de falhas ``` 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` | String | Nome da categoria de falha (por exemplo, “Erros de execução”, “Alucinações”). | | `failures[].affectedSessionCount` | Inteiro | Número de sessões afetadas por essa categoria. | | `failures[].subCategories[].name` | String | Nome da subcategoria (por exemplo, “Limitação de taxa”, “Violações do esquema da ferramenta”). | | `failures[].subCategories[].affectedSessionCount` | Inteiro | Número de sessões afetadas por essa subcategoria. | | `failures[].subCategories[].rootCauses[].name` | String | Nome do cluster de causa raiz. | | `failures[].subCategories[].rootCauses[].recommendation` | String | Correção sugerida para essa causa raiz. | | `failures[].subCategories[].rootCauses[].affectedSessionCount` | Inteiro | Número de sessões afetadas por essa causa raiz. | | `failures[].subCategories[].rootCauses[].affectedSessions` | Lista | Sessões nesse cluster, cada uma com`sessionId`. | ## Resultados da intenção do usuário O `userIntentResult` campo contém as intenções do usuário agrupadas: ``` 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` | Inteiro | Identificador de cluster. | | `userIntents[].name` | String | Nome do cluster que descreve a intenção comum. | | `userIntents[].description` | String | Descrição detalhada do padrão de intenção. | | `userIntents[].affectedSessionCount` | Inteiro | Número de sessões com essa intenção. | | `userIntents[].affectedSessions` | Lista | Sessões nesse cluster, cada uma com `sessionId` `userMessages` e. | ## Resultados resumidos da execução O `executionSummaryResult` campo contém padrões de execução em cluster: | Campo | Tipo | Description | | --- | --- | --- | | `executionSummaries[].clusterId` | Inteiro | Identificador de cluster. | | `executionSummaries[].name` | String | Nome do cluster que descreve o padrão de execução. | | `executionSummaries[].description` | String | Descrição detalhada do padrão. | | `executionSummaries[].affectedSessionCount` | Inteiro | Número de sessões com esse padrão. | | `executionSummaries[].affectedSessions` | Lista | Sessões nesse cluster, cada uma com `sessionId``approachTaken`, `finalOutcome` e. | ## Como interpretar os resultados do + **Comece com a análise de falhas:** concentre-se nas categorias mais altas`affectedSessionCount`. Esses representam os problemas mais impactantes. + **Analise as causas-raiz: em cada subcategoria, os clusters de causas** raiz informam exatamente o que está errado e como corrigi-lo. Cada cluster inclui um `recommendation` campo. + **Use as intenções do usuário para priorizar:** categorias de Cross-reference falha com clusters de intenções do usuário. Falhas que afetam suas intenções de usuário mais comuns devem ter a maior prioridade. + **Acompanhe os padrões de execução: os** resumos de execução revelam como seu agente aborda os problemas — úteis para entender se as falhas resultam da estratégia do agente ou dos tool/environment problemas. ## Regras de validação + `insights`e `evaluators` são mutuamente exclusivos — forneça um ou outro, não ambos. + Máximo de 10 insights por solicitação. + `dataSourceConfig`é obrigatório e deve incluir pelo menos um grupo de registros e um nome de serviço. + Se estiver usando`onlineEvaluationConfigSource`, não forneça `insights` ou `evaluators` (a configuração é herdada). + Se `filterConfig.timeRange` for especificado, `startTime` deve ser anterior `endTime` a. + Os carimbos de data e hora devem estar no formato ISO 8601 válido. + Somente uma avaliação em lote pode estar ativa por conta por vez. + No máximo 500 sessões são analisadas por execução de insights.