View a markdown version of this page

One-time relatório de insights - Amazon Bedrock AgentCore
Inicie a análiseSondagem para obter os resultadosRevise os resultados da análise de falhasResultados da intenção do usuárioResultados resumidos da execuçãoComo interpretar os resultados doRegras de validação

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.

Inicie a análise

exemplo
AgentCore CLI
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 <arn> --json
Interactive

  1. Executar agentcore para abrir a TUI, depois selecione executar e escolha Insights:

    Menu Executar: selecione Insights

  2. Escolha a fonte da sessão:

    Execute o assistente do Insights: selecione a fonte da sessão

  3. Selecione os insights a serem executados:

    Execute o assistente do Insights: selecione insights

    Continue com as etapas restantes do assistente (sessões, período de análise, nome) e confirme.

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

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

exemplo
AgentCore CLI

Liste todas as vagas do Insights:

agentcore view insights --json

Veja os detalhes de um trabalho específico:

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)

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 comsessionId.

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 sessionIdapproachTaken, finalOutcome e.

Como interpretar os resultados do

  • Comece com a análise de falhas: concentre-se nas categorias mais altasaffectedSessionCount. 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

  • insightse 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 usandoonlineEvaluationConfigSource, 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.