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

Iniciar la evaluación del lote

Inicie una evaluación por lotes para ejecutar los evaluadores en 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 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 lo devuelve inmediatamente. Pase --wait a bloquear hasta que el trabajo alcance un estado terminal (COMPLETED, oSTOPPED)FAILED, tras lo cual la CLI muestra las puntuaciones medias por evaluador y guarda los resultados en. .cli/jobs/batch-eval-results/

agentcore run batch-evaluationtambién admite los siguientes indicadores:

--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 KMS administrada por el cliente.
--dataset <name>/--dataset-version <version>— invoque el agente con escenarios de conjuntos de datos antes de la evaluación del lote (omita la versión de un archivo local o utilice/). N DRAFT
--endpoint <name>— se dirige a un punto final de tiempo de ejecución específico (por ejemplo,PROMPT_V1); entonces, el valor predeterminado es la variable de AGENTCORE_RUNTIME_ENDPOINT entorno. DEFAULT
--evaluator-arn <arns…>— hacer referencia a los evaluadores por ARN en lugar de. -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 haya iniciado, ejecute 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 intervalos 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 de lotes. Patrón: comienza con una letra, alfanumérica y guiones bajos, máximo 48 caracteres.
`dataSourceConfig`	Objeto	Sí	Dónde encontrar las sesiones de los agentes. Especifique una `cloudWatchLogs` fuente con el nombre del servicio del 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 datos básicos y metadatos por sesión. Máximo 500 entradas.
`outputConfig`	Objeto	No	CloudWatch Destino opcional para los resultados y las métricas de puntuación por sesión. Especifique un `cloudWatchConfig` para elegir el grupo de registros de resultados y el espacio de nombres de las métricas. Consulte Salida de resultados a continuación.
`clientToken`	Cadena	No	Símbolo de idempotencia. Si reintentas realizar 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 las trazas de su agente CloudWatch. Convención:`{RuntimeName}.DEFAULT`.
`cloudWatchLogs.logGroupNames`	Lista de cadenas (1—10)	Una forma de seleccionar grupos de registros de entrada. Especifique los nombres exactos de los grupos de CloudWatch registros en los que se almacena la telemetría del agente. Mutuamente excluyente con `logGroupNamePrefixes`.
`cloudWatchLogs.logGroupNamePrefixes`	Lista de cadenas (de 1 a 5)	Una forma de seleccionar grupos de registros de entrada. El servicio descubre las sesiones de todos los grupos de registros cuyo nombre comience con uno de estos prefijos, por lo que los grupos de registros coincidentes recién creados se recopilan automáticamente. Mutuamente excluyente con `logGroupNames`.

Especifique exactamente uno de logGroupNames o. logGroupNamePrefixes En ambos casos, serviceNames es necesario identificar las trazas de su agente dentro de los grupos de registros seleccionados.

Si solía logGroupNamePrefixes hacer coincidir los grupos de registros de Amazon Bedrock AgentCore Runtime, asegúrese de que su tiempo de ejecución envíe los intervalos al propio grupo de registros del agente. Para los agentes que aún utilizan el grupo de aws/spans registros compartido, establezca el tiempo de UNIFIED_TRACES_DESTINATION_ENABLED=true ejecución. Para obtener más información, consulte el destino de Span 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`	ISO 8601: fecha/hora	Filtra las sesiones creadas después de esta hora.
`cloudWatchLogs.filterConfig.timeRange.endTime`	ISO 8601: fecha/hora	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 registro 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 las evaluaciones.

Elija 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, defina logGroupName (consulteUtilice un grupo de registros de salida personalizado).
SOURCE_LOG_GROUP— Vuelve a escribir los resultados en el mismo grupo de registros desde el que se leyeron las trazas de los agentes. Cuando utilice este valor, no lo establezcalogGroupName.

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 el rol de ejecución para logs:CreateLogGroup otorgarlo. El nombre no puede estar en el espacio de /aws/bedrock-agentcore/evaluations/ nombres reservado para el servicio, aparte del 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 métricas en un espacio de nombres personalizado

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


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	Cuándo se creó el trabajo.
`outputConfig`	Objeto	CloudWatch destino para los resultados y las métricas de puntuación por sesió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. Compruebe las políticas de IAM.
`ConflictException`	409	Ya existe una evaluación por lotes con el mismo token de cliente con parámetros diferentes.
`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