View a markdown version of this page

One-time informe de información - Amazon Bedrock AgentCore
Inicie el análisisSondeo de resultadosRevise los hallazgos del análisis de fallasResultados de la intención del usuarioResultados resumidos de la ejecuciónInterpretación de los resultadosReglas de validación

One-time informe de información

Úselo StartBatchEvaluation para realizar un análisis de información a pedido sobre las sesiones de su agente. Esto resulta útil cuando se quiere investigar el comportamiento de los agentes después de una implementación, si se produce un aumento en el número de errores o si se trata de una comprobación manual periódica.

Inicie el análisis

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

La CLI es asíncrona de forma predeterminada: imprime el ID del trabajo y sale. Se usa --wait para bloquear hasta que se complete el trabajo:

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

Si ya tiene implementada una configuración de evaluación en línea, puede heredar su configuración:

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

  1. Ejecute agentcore para abrir la TUI, luego seleccione ejecutar y elija Insights:

    Menú Ejecutar: seleccione Insights

  2. Elija la fuente de la sesión:

    Ejecute el asistente de Insights: seleccione la fuente de la sesión

  3. Seleccione las estadísticas que desee ejecutar:

    Ejecute el asistente de información: seleccione información

    Continúe con los pasos restantes del asistente (sesiones, período retrospectivo, nombre) y 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}")

También puede:

  • Limite el análisis a un intervalo de tiempo específico añadiendo filterConfig.timeRange

  • Analice sesiones específicas por ID utilizando filterConfig.sessionIds

Sondeo de resultados

ejemplo
AgentCore CLI

Enumere todos los trabajos de Insights:

agentcore view insights --json

Vea los detalles de un trabajo 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 los hallazgos del análisis de fallas

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 (Descripción)

failures[].name

Cadena

Nombre de la categoría de error (p. ej., «Errores de ejecución», «Alucinaciones»).

failures[].affectedSessionCount

Entero

Número de sesiones afectadas por esta categoría.

failures[].subCategories[].name

Cadena

Nombre de la subcategoría (p. ej., «Limitación de velocidad» o «Infracciones del esquema de herramientas»).

failures[].subCategories[].affectedSessionCount

Entero

Número de sesiones afectadas por esta subcategoría.

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

Cadena

Nombre del clúster de causa raíz.

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

Cadena

Solución sugerida para esta causa raíz.

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

Entero

Número de sesiones afectadas por esta causa raíz.

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

Enumeración

Sesiones de este clúster, cada una consessionId.

Resultados de la intención del usuario

El userIntentResult campo contiene las intenciones de los usuarios 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 (Descripción)

userIntents[].clusterId

Entero

Identificador de clúster.

userIntents[].name

Cadena

Nombre del clúster que describe la intención común.

userIntents[].description

Cadena

Descripción detallada del patrón de intención.

userIntents[].affectedSessionCount

Entero

Número de sesiones con esta intención.

userIntents[].affectedSessions

Enumeración

Sesiones de este grupo, cada una con sessionId yuserMessages.

Resultados resumidos de la ejecución

El executionSummaryResult campo contiene patrones de ejecución agrupados:

Campo Tipo Description (Descripción)

executionSummaries[].clusterId

Entero

Identificador de clúster.

executionSummaries[].name

Cadena

Nombre del clúster que describe el patrón de ejecución.

executionSummaries[].description

Cadena

Descripción detallada del patrón.

executionSummaries[].affectedSessionCount

Entero

Número de sesiones con este patrón.

executionSummaries[].affectedSessions

Enumeración

Sesiones de este grupo, cada una con sessionIdapproachTaken, yfinalOutcome.

Interpretación de los resultados

  • Comience con el análisis de los errores: céntrese en las categorías con los valores más altosaffectedSessionCount. Estos representan los problemas más impactantes.

  • Profundice en las causas fundamentales: dentro de cada subcategoría, los clústeres de causas fundamentales indican exactamente qué es lo que está fallando y cómo solucionarlo. Cada clúster incluye un recommendation campo.

  • Utilice las intenciones del usuario para priorizar: categorías de Cross-reference errores con clústeres de intención del usuario. Los errores que afecten a las intenciones de usuario más comunes deberían ser de máxima prioridad.

  • Realice un seguimiento de los patrones de ejecución: los resúmenes de ejecución revelan cómo su agente aborda los problemas, lo que resulta útil para comprender si los errores se deben a la estrategia del agente o a tool/environment problemas.

Reglas de validación

  • insightsy evaluators se excluyen mutuamente: proporcionan una u otra, no ambas.

  • Máximo 10 estadísticas por solicitud.

  • dataSourceConfiges obligatorio y debe incluir al menos un grupo de registros y un nombre de servicio.

  • Si lo usaonlineEvaluationConfigSource, no proporcione insights o evaluators (la configuración se hereda).

  • Si filterConfig.timeRange se especifica, startTime debe ser anterior aendTime.

  • Las marcas horarias deben tener un formato ISO 8601 válido.

  • Solo puede estar activa una evaluación de lote por cuenta a la vez.

  • Se analizan un máximo de 500 sesiones por ejecución de insights.