Ejemplos de código Parámetros de solicitud Origen de la sesión Salida de resultados Respuesta Errores

Iniciar la evaluación de lotes

Inicie una evaluación por lotes para comparar los evaluadores con varias sesiones de agentes. El servicio descubre las sesiones a partir de CloudWatch los registros, ejecuta cada evaluador en cada sesión y produce resultados agregados.

Ejemplos de código

ejemplo

AgentCore CLI

La CLI se resuelve serviceNames logGroupNames automáticamente a partir de la configuración del proyecto cuando se utiliza--runtime:


agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate Builtin.Helpfulness Builtin.Faithfulness

Con indicadores opcionales:


# Custom name and lookback window
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --name my_baseline_eval \
  --lookback-days 1

# Specific sessions
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --session-ids session-abc123 session-def456

# With ground truth
agentcore run batch-evaluation \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate Builtin.Correctness \
  --ground-truth ground-truth.json

De forma predeterminada, el comando inicia el trabajo y regresa inmediatamente. Pasa --wait a bloque hasta que el trabajo alcance un estado terminal (COMPLETED,, oSTOPPED)FAILED, tras lo cual la CLI muestra las puntuaciones medias de cada evaluador y guarda los resultados en ellas. .cli/jobs/batch-eval-results/

agentcore run batch-evaluationtambién admite las siguientes marcas:

--wait— bloquear hasta que la tarea alcance un estado terminal.
--json— emitir una salida JSON legible por máquina.
--kms-key <arn>— cifrar los resultados de la evaluación por lotes con una clave de KMS gestionada por el cliente.
--dataset <name>/--dataset-version <version>— invoque al agente con escenarios de conjuntos de datos antes de la evaluación por lotes (omita la versión para un archivo local o utilice/). N DRAFT
--endpoint <name>— apunte a un punto final de tiempo de ejecución específico (por ejemplo,PROMPT_V1); por defecto, utiliza la variable de AGENTCORE_RUNTIME_ENDPOINT entorno. DEFAULT
--evaluator-arn <arns…>— hace referencia a los evaluadores mediante ARN en lugar de hacerlo. -e

La mayoría de las banderas tienen alias cortos: -r (--runtime), -e (--evaluator), -n (--name), -d (--lookback-days), -s (--session-ids) y -g (). --ground-truth

Para administrar un trabajo después de que se inicie, ejecútelo agentcore stop batch-evaluation -i <id> para detener un trabajo en ejecución y agentcore archive batch-evaluation -i <id> archivar un registro de trabajo.

AWS SDK (boto3)


import boto3
import uuid
import time
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

# All sessions in the log group
response = client.start_batch_evaluation(
    batchEvaluationName=f"baseline_eval_{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
        {"evaluatorId": "Builtin.Helpfulness"},
        {"evaluatorId": "Builtin.Faithfulness"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
        }
    },
    clientToken=str(uuid.uuid4()),
)

batch_eval_id = response["batchEvaluationId"]
print(f"Started: {batch_eval_id}")

# Poll until complete
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)

print(json.dumps(result, indent=4, default=str))

Con el filtrado de ID de sesión:


response = client.start_batch_evaluation(
    batchEvaluationName=f"targeted-eval-{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
            "filterConfig": {
                "sessionIds": ["session-001", "session-002", "session-003"]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Con filtrado por intervalo de tiempo:


from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)
response = client.start_batch_evaluation(
    batchEvaluationName=f"weekly-eval-{uuid.uuid4().hex[:8]}",
    evaluators=[
        {"evaluatorId": "Builtin.GoalSuccessRate"},
    ],
    dataSourceConfig={
        "cloudWatchLogs": {
            "serviceNames": ["MyAgent.DEFAULT"],
            "logGroupNames": ["/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"],
            "filterConfig": {
                "timeRange": {
                    "startTime": (now - timedelta(days=7)).isoformat(),
                    "endTime": now.isoformat(),
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Descripción
`batchEvaluationName`	Cadena	Sí	Un nombre para el trabajo de evaluación por lotes. Patrón: comienza con una letra, alfanuméricos y guiones bajos, máximo 48 caracteres.
`dataSourceConfig`	Objeto	Sí	Dónde encontrar las sesiones de agentes. Especifique una `cloudWatchLogs` fuente con el nombre del servicio de su agente y los nombres exactos de los grupos de registros o los prefijos de los nombres de los grupos de registros. Consulte Origen de la sesión a continuación.
`evaluators`	Enumeración	Sí	Lista de evaluadores. Cada entrada tiene un `evaluatorId` campo (por ejemplo,`Builtin.GoalSuccessRate`). Máximo 10 evaluadores.
`evaluationMetadata`	Objeto	No	Contiene `sessionMetadata` una lista de la verdad básica y los metadatos de cada sesión. Máximo 500 entradas.
`outputConfig`	Objeto	No	CloudWatch Destino opcional para los resultados de cada sesión y las métricas de puntuación. Especifique un espacio de nombres `cloudWatchConfig` para elegir el grupo de registros de resultados y el espacio de nombres de métricas. Consulte Salida de resultados a continuación.
`clientToken`	Cadena	No	Símbolo de idempotencia. Si vuelves a intentar una solicitud con el mismo token de cliente, el servicio devuelve el trabajo existente en lugar de crear uno nuevo.

Origen de la sesión

El dataSourceConfig parámetro especifica la ubicación de los CloudWatch registros en la que el servicio descubre las sesiones de los agentes.

Campos obligatorios

Campo	Tipo	Description (Descripción)
`cloudWatchLogs.serviceNames`	Lista de cadenas (exactamente 1)	El nombre del servicio que identifica los rastros de su agente en CloudWatch. Convención:`{RuntimeName}.DEFAULT`.
`cloudWatchLogs.logGroupNames`	Lista de cadenas (1—5)	Una forma de seleccionar grupos de registros de entrada. Especifique los nombres exactos de los grupos de CloudWatch registro donde se almacena la telemetría del agente. Mutuamente excluyente con `logGroupNamePrefixes`.
`cloudWatchLogs.logGroupNamePrefixes`	Lista de cadenas (1—5)	Una forma de seleccionar grupos de registros de entrada. El servicio descubre las sesiones de todos los grupos de registros cuyo nombre comience por uno de estos prefijos, por lo que los grupos de registros coincidentes recién creados se seleccionan automáticamente. Mutuamente excluyente con `logGroupNames`.

Especifique exactamente uno de logGroupNames ologGroupNamePrefixes. En ambos casos, serviceNames es necesario identificar los rastros de su agente dentro de los grupos de registro seleccionados.

Si suele logGroupNamePrefixes hacer coincidir los grupos de registros de Amazon Bedrock AgentCore Runtime, asegúrese de que su tiempo de ejecución envíe intervalos al propio grupo de registros del agente. En el caso de los agentes que aún utilizan el grupo de aws/spans registros compartido, defina el tiempo UNIFIED_TRACES_DESTINATION_ENABLED=true de ejecución. Para obtener más información, consulte Span destination para los agentes alojados en Amazon Bedrock AgentCore Runtime.


# Match input log groups by prefix instead of exact names
dataSourceConfig={
    "cloudWatchLogs": {
        "logGroupNamePrefixes": ["/aws/bedrock-agentcore/runtimes/MyAgent-"],
        "serviceNames": ["MyAgent.DEFAULT"]
    }
}

Campos opcionales

Campo	Tipo	Description (Descripción)
`cloudWatchLogs.filterConfig.sessionIds`	Lista de cadenas	Evalúe solo estos ID de sesión específicos. Si se omite, el servicio descubre todas las sesiones del grupo de registros.
`cloudWatchLogs.filterConfig.timeRange.startTime`	Fecha y hora ISO 8601	Filtra las sesiones creadas después de este tiempo.
`cloudWatchLogs.filterConfig.timeRange.endTime`	Fecha y hora ISO 8601	Filtra las sesiones creadas antes de esta hora.

Salida de resultados

De forma predeterminada, los resultados de la evaluación por lotes van a un grupo de registros dedicado y administrado por el servicio. Se usa outputConfig.cloudWatchConfig para controlar dónde se escriben los resultados de cada sesión y qué espacio de nombres de CloudWatch métricas recibe las puntuaciones de evaluación.

Elige dónde se escriben los resultados

DEDICATED_LOG_GROUP(predeterminado): escribe los resultados en un grupo de registro de resultados dedicado. Si no lo configuraslogGroupName, el servicio administra el grupo por ti. Para usar su propio grupo, configúrelo logGroupName (consulteUtilice un grupo de registros de salida personalizado).
SOURCE_LOG_GROUP— Vuelve a escribir los resultados en el mismo grupo de registros del que se leyeron los rastros del agente. Cuando utilice este valor, no lo definalogGroupName.

Utilice un grupo de registros de salida personalizado

ParaDEDICATED_LOG_GROUP, logGroupName configúrelo para escribir los resultados en el grupo de registros que elija. Un grupo de registros existente se usa tal cual; si no existe, el servicio lo crea, lo que requiere la función de ejecución para logs:CreateLogGroup otorgarla. El nombre no puede estar en el espacio de /aws/bedrock-agentcore/evaluations/ nombres reservado por el servicio, excepto en el grupo predeterminado administrado por el servicio.


# Write results back to the trace source log group
outputConfig={
    "cloudWatchConfig": {
        "resultDestination": "SOURCE_LOG_GROUP"
    }
}

# Write results to a custom dedicated log group
outputConfig={
    "cloudWatchConfig": {
        "resultDestination": "DEDICATED_LOG_GROUP",
        "logGroupName": "/my/team/batch-evaluation-results"
    }
}

Publica las métricas en un espacio de nombres personalizado

metricsNamespaceConfigúralo para publicar las métricas de puntuación en tu propio espacio de CloudWatch nombres en lugar de hacerlo. Bedrock-AgentCore/Evaluations El valor no puede empezar AWS/ por.


outputConfig={
    "cloudWatchConfig": {
        "metricsNamespace": "MyTeam/Evaluations"
    }
}

Respuesta

Campo	Tipo	Description (Descripción)
`batchEvaluationId`	Cadena	Identificador único para la evaluación del lote.
`batchEvaluationArn`	Cadena	ARN de la evaluación del lote.
`batchEvaluationName`	Cadena	El nombre que especificó.
`status`	Cadena	Estado inicial. Uno de:`PENDING`,`IN_PROGRESS`.
`evaluators`	Enumeración	Los evaluadores utilizados.
`createdAt`	Timestamp	Cuando se creó el trabajo.
`outputConfig`	Objeto	CloudWatch destino para ver los resultados de cada sesión y las métricas de puntuación.

Errores

Error	Estado HTTP	Description (Descripción)
`ValidationException`	400	Parámetros de solicitud no válidos. Compruebe las restricciones de campo y los campos obligatorios.
`AccessDeniedException`	403	Permisos insuficientes. Verifique las políticas de IAM.
`ConflictException`	409	Ya existe una evaluación por lotes con el mismo token de cliente con diferentes parámetros.
`ThrottlingException`	429	Se superó la tasa de solicitudes. Vuelva a intentarlo con retroceso exponencial.
`InternalServerException`	500	Service-side error. Intente realizar de nuevo la solicitud .

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Introducción

Obtenga los resultados de la evaluación por lotes