# Ejecutor de conjuntos de datos por lotes
<a name="dataset-evaluations-batch"></a>

Los `BatchEvaluationRunner` delegados transfieren la recopilación y la evaluación por completo al servicio a través de las `GetBatchEvaluation` API `StartBatchEvaluation` y. Tras invocar a su agente para cada escenario, el encargado envía un trabajo por lotes y sondea hasta que se complete, y devuelve los resultados agregados.

Utilice el sistema de procesamiento por lotes cuando necesite sumar las puntuaciones de varias sesiones sin tener que gestionar usted mismo la recopilación de intervalos, para realizar mediciones de referencia, conjuntos de datos de gran tamaño y realizar comparaciones. pre/post 

## Funcionamiento
<a name="batch-ds-how-it-works"></a>

El ejecutor procesa los escenarios en cuatro fases:

1.  **Invocar:** todos los escenarios se ejecutan simultáneamente mediante un grupo de subprocesos. Cada escenario recibe un identificador de sesión único y, dentro de un escenario, se ejecuta secuencialmente para mantener el contexto de la conversación.

1.  **Espera:** un retraso de ingesta configurable (predeterminado: 180 segundos) permite CloudWatch ingerir los datos de telemetría. Este retraso se paga una vez, no por escenario.

1.  **Enviar:** el ejecutor llama `StartBatchEvaluation` con el grupo de CloudWatch registros, los ID de sesión de la fase de invocación, los ID del evaluador y la información básica del conjunto de datos.

1.  **Encuesta:** el corredor sondea `GetBatchEvaluation` hasta que el trabajo alcance un estado terminal y devuelva los resultados agregados.

## Invocador de agentes
<a name="batch-ds-agent-invoker"></a>

El corredor requiere un invocador de agentes, un invocador que invoca a tu agente durante un solo turno. El invocador es independiente del marco: puedes llamar a tu agente mediante boto3`invoke_agent_runtime`, una llamada directa a una función, una solicitud HTTP o cualquier otro método.

```
import json
import boto3
from bedrock_agentcore.evaluation import AgentInvokerInput, AgentInvokerOutput

REGION       = "<region-code>"
AGENT_ARN    = "arn:aws:bedrock-agentcore:<region-code>:<account-id>:runtime/<agent-id>"
LOG_GROUP    = "/aws/bedrock-agentcore/runtimes/<agent-id>-DEFAULT"
SERVICE_NAME = "<agent-id>.DEFAULT"

agentcore_client = boto3.client("bedrock-agentcore", region_name=REGION)

def agent_invoker(invoker_input: AgentInvokerInput) -> AgentInvokerOutput:
    payload = invoker_input.payload
    if isinstance(payload, str):
        payload = json.dumps({"prompt": payload}).encode()
    elif isinstance(payload, dict):
        payload = json.dumps(payload).encode()

    print(f"[{invoker_input.session_id}] > sending payload: {payload.decode()}")
    response = agentcore_client.invoke_agent_runtime(
        agentRuntimeArn=AGENT_ARN,
        runtimeSessionId=invoker_input.session_id,
        payload=payload,
    )
    response_body = response["response"].read()
    print(f"[{invoker_input.session_id}] < received response: {response_body.decode()}")
    return AgentInvokerOutput(agent_output=json.loads(response_body))
```


| Campo | Tipo | Description (Descripción) | 
| --- | --- | --- | 
|  `AgentInvokerInput.payload`  |  `str` o `dict`  | El turno es la entrada del conjunto de datos. | 
|  `AgentInvokerInput.session_id`  |  `str`  | Estable en todos los giros de un escenario. Transmita esta información a su agente para mantener el contexto de la conversación. | 
|  `AgentInvokerOutput.agent_output`  |  `Any`  | La respuesta del agente. | 

## Ejemplo
<a name="batch-ds-example"></a>

El siguiente ejemplo carga un conjunto de datos desde un archivo JSON y ejecuta la evaluación por lotes. Para conocer el formato del conjunto de datos, consulte [Esquema del conjunto de datos](dataset-evaluations-schema.md).

```
from bedrock_agentcore.evaluation import (
    BatchEvaluationRunner,
    BatchEvaluationRunConfig,
    BatchEvaluatorConfig,
    CloudWatchDataSourceConfig,
    FileDatasetProvider,
)

# Load dataset from a local file (see Dataset schema for format)
dataset = FileDatasetProvider("dataset.json").get_dataset()

# Or load from the Dataset Management service
from bedrock_agentcore.evaluation import DatasetClient, DatasetManagementServiceProvider
ds_client = DatasetClient(region_name=REGION)
dataset = DatasetManagementServiceProvider(dataset_id="my-dataset-id", client=ds_client).get_dataset()

# Configure the batch evaluation
config = BatchEvaluationRunConfig(
    batch_evaluation_name="dataset-batch-eval",
    evaluator_config=BatchEvaluatorConfig(
        evaluator_ids=[
            "Builtin.GoalSuccessRate",
            "Builtin.Correctness",
            "Builtin.TrajectoryExactOrderMatch",
            "Builtin.Helpfulness",
        ],
    ),
    data_source=CloudWatchDataSourceConfig(
        service_names=[SERVICE_NAME],
        log_group_names=[LOG_GROUP],
        ingestion_delay_seconds=180,
    ),
    polling_timeout_seconds=1800,
    polling_interval_seconds=30,
)

# Run
runner = BatchEvaluationRunner(region=REGION)
result = runner.run_dataset_evaluation(
    agent_invoker=agent_invoker,
    dataset=dataset,
    config=config,
)

# Display aggregate results
print(f"Status: {result.status}")
print(f"Batch evaluation ID: {result.batch_evaluation_id}")

if result.evaluation_results:
    er = result.evaluation_results
    print(f"Sessions completed: {er.number_of_sessions_completed}")
    print(f"Sessions failed:    {er.number_of_sessions_failed}")
    print(f"Total sessions:     {er.total_number_of_sessions}")

    for summary in er.evaluator_summaries or []:
        avg = summary.statistics.average_score if summary.statistics else None
        print(f"  {summary.evaluator_id}: avg={avg}")
```

## Obteniendo detalles por sesión
<a name="batch-ds-per-session-detail"></a>

Los resultados agregados muestran los promedios de todas las sesiones. Para ver las puntuaciones por sesión y por evaluador, busque los eventos de evaluación en: CloudWatch

```
if result.output_data_config:
    events = runner.fetch_evaluation_events(result)
    print(f"\nEvaluation events: {len(events)}")
    for ev in events:
        attrs = ev.get("attributes", {})
        print(f"  session: {attrs.get('session.id', '')[:40]}")
        print(f"  evaluator: {attrs.get('gen_ai.evaluation.name')}")
        print(f"  score: {attrs.get('gen_ai.evaluation.score.value')}")
        print(f"  label: {attrs.get('gen_ai.evaluation.score.label')}")
        print()
```

## Referencia de la configuración
<a name="batch-ds-config-reference"></a>

```
BatchEvaluationRunConfig(
    batch_evaluation_name="my-batch-eval",   # Job name
    evaluator_config=BatchEvaluatorConfig(
        evaluator_ids=["Builtin.GoalSuccessRate"],
    ),
    data_source=CloudWatchDataSourceConfig(
        service_names=["MyAgent.DEFAULT"],   # Exactly 1 service name
        log_group_names=[LOG_GROUP],         # 1-5 log group names
        ingestion_delay_seconds=180,         # Wait for CW ingestion (default: 180)
    ),
    polling_timeout_seconds=1800,            # Max wait for job completion (default: 1800)
    polling_interval_seconds=30,             # Poll interval (default: 30)
    simulation_config=None,                  # Set SimulationConfig for simulated scenarios
)
```


| Campo | Predeterminado | Description (Descripción) | 
| --- | --- | --- | 
|  `batch_evaluation_name`  | — | Nombre del trabajo de evaluación por lotes. | 
|  `evaluator_config.evaluator_ids`  | — | Lista de identificadores de evaluadores (integrados o personalizados). | 
|  `data_source.service_names`  | — | Nombre del servicio que identifica las huellas de su agente. CloudWatch | 
|  `data_source.log_group_names`  | — | CloudWatch nombres de grupos de registros donde se almacena la telemetría del agente. | 
|  `data_source.ingestion_delay_seconds`  | 180 | Hay que esperar segundos después de la invocación para CloudWatch ingerir los intervalos. | 
|  `polling_timeout_seconds`  | 1800 | Tiempo máximo de espera para que se complete el trabajo por lotes. | 
|  `polling_interval_seconds`  | 30 | Segundos entre las solicitudes de sondeo. | 
|  `simulation_config`  | Ninguno | Configuración para escenarios simulados. Se establece `SimulationConfig(model_id="…​")` cuándo el conjunto de datos contiene `SimulatedScenario` instancias. Consulte [Simulación de usuario](user-simulation.md). | 

## Estructura de resultados
<a name="batch-ds-result-structure"></a>

El corredor devuelve un`BatchEvaluationResult`:

```
BatchEvaluationResult
  ├── batch_evaluation_id: str
  ├── batch_evaluation_arn: str
  ├── batch_evaluation_name: str
  ├── status: str
  ├── created_at: datetime
  ├── evaluation_results: Optional[BatchEvaluationSummary]
  │     ├── number_of_sessions_completed: int
  │     ├── number_of_sessions_in_progress: int
  │     ├── number_of_sessions_failed: int
  │     ├── number_of_sessions_ignored: int
  │     ├── total_number_of_sessions: int
  │     └── evaluator_summaries: List
  │           ├── evaluator_id: str
  │           ├── statistics.average_score: float
  │           ├── total_evaluated: int
  │           └── total_failed: int
  ├── error_details: Optional[List[str]]
  ├── agent_invocation_failures: List[FailedScenario]
  └── output_data_config: Optional[CloudWatchOutputDataConfig]
        ├── log_group_name: str
        └── log_stream_name: str
```
+  `agent_invocation_failures`enumera los escenarios en los que la invocación del agente falló antes de que se enviara el trabajo por lotes. Estas sesiones no se incluyen en la evaluación por lotes.
+  `output_data_config`apunta al flujo de CloudWatch registro en el que se escriben los detalles de cada sesión. Se usa `runner.fetch_evaluation_events(result)` para leerlo.

## Gestión de errores
<a name="batch-ds-error-handling"></a>
+  Los **errores de invocación del escenario** se registran como trabajo por lotes, `FailedScenario` pero no lo bloquean; solo se envían las sesiones correctas.
+ Si **todos los escenarios fallan**, el ejecutor se activa `ValueError` antes de llamar a la API.
+  Tiempo de **espera de la encuesta:** `TimeoutError` si el trabajo lo supera`polling_timeout_seconds`.
+  **Job fallido:** `RuntimeError` si el estado de evaluación del lote es `FAILED` o`STOPPED`.