Cómo crear un dataset de evaluación de agentes: tareas reales, trayectorias y pruebas de regresión

La semana pasada, el agente de informes diarios todavía generaba reportes sin problema. Tras una actualización de modelo, sigue devolviendo un resumen final que parece correcto, pero en la trayectoria faltan el chequeo de permisos y la herramienta de refresco de datos. Un agente de soporte da una respuesta final correcta, pero llama la herramienta de reembolso con argumentos incorrectos; un benchmark público no detecta ese riesgo. En una retrospectiva de incidente ya existen traceId, tool call, approvalId, state event y juicio humano, pero nada quedó fijado como prueba obligatoria antes del próximo release.

Este tipo de regresión no se cubre cambiando de modelo ni corriendo otra demo. Un dataset de evaluación de agentes debe salir de la distribución real de tareas y de trayectorias de fallo en producción: tool calls, formatos de argumentos, transiciones de estado, approval records y human labels. Después debe entrar en CI como gate de regresión. Aquí el foco son casos de fallo y escenarios reales: cómo construir un eval dataset sostenible que proteja el límite de calidad de cada release.

1. Por qué los benchmarks públicos no bastan

1.1 Límites de los benchmarks públicos

Los benchmarks públicos miden capacidad del modelo, no la calidad de tus tareas de negocio. Conjuntos como AgentBench y WebArena ofrecen tareas estándar, pero no cubren la toolchain, el modelo de permisos ni la state machine de tu equipo.

Por ejemplo, tu agente de reportes puede necesitar llamar check_permission, refresh_data y generate_report en el orden “comprobar → refrescar → generar”. Un benchmark público no probará ese flujo porque no conoce tus tool schemas ni tus límites de permisos.

Que el modelo tenga buen score en un benchmark público no significa que tus tareas de negocio no vayan a degradarse. Un dataset de evaluación de agentes debe medir tu distribución real de tareas, no una capacidad general de razonamiento.

1.2 Valor principal de un dataset propio

Un eval dataset propio captura riesgos que los benchmarks públicos no ven. La comparación típica es esta:

Usa benchmarks públicos para elegir modelos y tu dataset propio para proteger release gates. Se complementan, pero no se sustituyen. Si ya leíste Comparativa de benchmarks de evaluación de agentes, sabes qué conjuntos públicos sirven para selección. Aquí nos centramos en construir datos de evaluación desde tu propio entorno de producción.

2. Campos clave de un agent eval dataset

2.1 Campos obligatorios

Un agent eval dataset no es solo guardar entrada de usuario y respuesta esperada. Debe registrar trayectoria de tool calls, transiciones de estado y juicio humano. Estos son los campos obligatorios:

LangSmith, en Evaluation concepts, recomienda que la evaluación de agentes cubra selección de herramientas, formato de argumentos y trayectoria de ejecución, no solo la respuesta final. OpenAI Agents SDK Tracing ofrece campos como trace_id, workflow_name y span para registrar tool calls y eventos de estado, pero esos campos brutos deben anonimizarse y extraerse antes de entrar en un dataset.

2.2 Campos opcionales

Añade estos campos según la necesidad del negocio:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Si leíste el modelo de permisos de agentes (N157) y el diseño de aprobación humana (N155), sabes que approval records debe guardar paso de aprobación, aprobador y resultado, para verificar que una operación de alto riesgo pasó por aprobación.

2.3 Anonimización y privacidad

Un production trace no puede entrar tal cual en el conjunto de evaluación. La documentación de OpenAI Agents SDK Tracing advierte que algunos spans pueden capturar entradas/salidas del modelo o entradas/salidas de herramientas de función, por lo que debes configurar si se incluyen datos sensibles.

Campos que deben anonimizarse: PII (nombre, email, teléfono), secrets (API key, contraseña de base de datos), datos de clientes (número de pedido, monto de transacción).

Campos que conviene conservar: traceId, span_id para diagnóstico, workflow_name para clasificación, nombre de herramienta y nombre de estado para assertions.

Los métodos de anonimización incluyen reemplazar por placeholders como <user_id>, aplicar hash o eliminar directamente. Phoenix, en Running Evals on Traces, muestra que un trace puede convertirse en entrada de evaluación, pero aun así necesita label, score y rubric. No metas un trace bruto completo directamente en el eval dataset.

3. De production trace a eval example

3.1 Flujo de recolección de datos

Para convertir un production trace en eval example hacen falta cuatro pasos: anonimización, etiquetado, estratificación y almacenamiento. No es una obra única de ingeniería; es operación continua.

Checklist:

1. Exportar traces fallidos desde la plataforma de monitoreo (ver Monitoreo de agentes y recuperación ante fallos).
2. Clasificar por tipo de fallo: error de tool call, error de formato de argumento, error de transición de estado, error de respuesta final.
3. Anonimizar: eliminar PII/secret/datos de clientes y conservar traceId, span_id, workflow_name.
4. Añadir etiqueta humana: correcto/incorrecto/parcialmente correcto + motivo del fallo.
5. Guardar por capa: golden set / negative cases / edge cases.

La documentación de Phoenix datasets indica que los examples pueden recolectarse desde production, staging, evaluations o manual. Producción aporta la distribución real de tareas; staging ayuda a completar escenarios de borde.

3.2 Criterios de estratificación

Dimensiones de etiquetado, alineadas con una rubric LLM-as-judge: corrección de selección de herramientas, corrección del formato de argumentos, corrección del orden de ejecución, calidad de la respuesta final y alineación con etiquetas humanas.

OpenAI Evaluation best practices recomienda que los datos de prueba incluyan typical, edge y adversarial cases, con human expert labellers. Esta estratificación corresponde a esa idea, pero enfatiza tareas frecuentes y modos de fallo típicos, porque el objetivo es proteger el release gate, no cubrir todo escenario posible.

4. Cómo escribir trajectory assertions

4.1 Tipos de restricciones de trayectoria

Las trajectory assertions definen las reglas de tool calls, formato de argumentos, transiciones de estado y aprobaciones que el agente debe cumplir. Estos son cinco tipos comunes:

LangSmith Evaluation concepts menciona trajectory, tool selection y argument formatting como partes de la evaluación de agentes. Phoenix Running Evals on Traces usa span_id para asociar resultados de evaluación con un segmento concreto de ejecución, lo que permite que una assertion de trayectoria apunte al span fallido.

Si leíste la evaluación de planificación de agentes (N158) y los límites entre state machine y prompt, sabes que los campos de trayectoria de estado vienen de state, event y checkpoint. Sirven para verificar si la transición de estado sigue el orden esperado.

4.2 Ejemplo de código

Este es un pseudocódigo de trajectory assertions para una evaluación de agentes genérica:

# Ejemplo de trajectory assertions
def assert_trajectory_correct(result):
    # Extraer la lista de tool calls
    tools_called = [call.tool for call in result.tool_calls]

    # Herramientas obligatorias
    required_tools = ["check_permission", "refresh_data"]
    for tool in required_tools:
        assert tool in tools_called, f"Missing required tool: {tool}"

    # Herramientas prohibidas
    forbidden_tools = ["delete_user"]
    for tool in forbidden_tools:
        assert tool not in tools_called, f"Called forbidden tool: {tool}"

    # Restricciones de formato de argumentos
    for call in result.tool_calls:
        if call.tool == "refund":
            assert isinstance(call.args["refund_amount"], (int, float)), "refund_amount must be number"
            assert len(call.args["user_id"]) == 36, "user_id must be uuid format"

    # Orden de transiciones de estado
    expected_states = ["init", "check", "approve", "execute"]
    actual_states = [event.state for event in result.state_events]
    assert actual_states == expected_states, "State transition order mismatch"

    # Existencia de paso de aprobación
    approval_events = [e for e in result.state_events if e.type == "approval"]
    assert len(approval_events) >= 1, "Missing approval step"

Este código muestra cómo comprobar herramientas obligatorias, herramientas prohibidas, formatos de argumentos, orden de transiciones de estado y pasos de aprobación. En una implementación real puedes usar trajectory assertions de LangSmith o trace eval de Phoenix, pero la lógica central es la misma.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Si leíste Evaluación de planificación de agentes, sabes que las trayectorias de planificación también pueden convertirse en muestras de regresión para verificar descomposición de tareas y autocorrección.

5. Rubric por capas para LLM-as-judge

5.1 Por qué el score total no basta

Si LLM-as-judge solo entrega un score total, el resultado fluctúa y es difícil de diagnosticar. Un 80 puede significar que la selección de herramientas fue incorrecta pero la respuesta salió bien por casualidad, o que la respuesta fue incorrecta pero el formato se veía bien. No puedes distinguir si el problema está en el prompt, tool schema, retrieval o state machine.

LangSmith Evaluation concepts recomienda definir criterios de calidad para componentes clave del agente: correct tool selection, proper argument formatting y trajectory. Al puntuar cada componente por separado, es mucho más rápido localizar regresiones después de un cambio de modelo o prompt.

Si leíste Prácticas avanzadas de prompt engineering, sabes que DeepEval también enfatiza métricas por capas como TaskCompletenessMetric, no solo la salida final.

5.2 Tabla de puntuación por capas

La siguiente rubric divide la evaluación de agentes en cinco dimensiones, cada una con 0-2 puntos:

Ejemplo de configuración de rubric para LangSmith o Phoenix:

rubric:
  dimensions:
    - name: tool_selection
      weight: 0.3
      criteria:
        0: "Llamó la herramienta incorrecta"
        1: "Llamó algunas herramientas correctas"
        2: "La selección de herramientas es totalmente correcta"

    - name: argument_formatting
      weight: 0.2
      criteria:
        0: "El tipo de argumento es incorrecto"
        1: "Algunos campos tienen errores de formato"
        2: "El formato de argumentos es totalmente correcto"

    - name: execution_order
      weight: 0.2
      criteria:
        0: "La transición de estado salta o se repite"
        1: "El orden de ejecución tiene desviaciones"
        2: "El orden de ejecución es totalmente correcto"

    - name: final_answer_quality
      weight: 0.2
      criteria:
        0: "No satisface la solicitud del usuario"
        1: "Satisface parcialmente la solicitud"
        2: "Satisface por completo la solicitud"

    - name: human_alignment
      weight: 0.1
      criteria:
        0: "Contradice el juicio experto"
        1: "Parcialmente alineado"
        2: "Muy alineado"

La selección de herramientas tiene el peso más alto (0.3) porque el núcleo de un agente es llamar la herramienta correcta. La alineación humana tiene el peso más bajo (0.1), porque sirve para calibrar si LLM-as-judge coincide con el juicio experto.

6. Release gates y pruebas de regresión

6.1 Pasos de integración en CI

El valor de un agent eval dataset aparece cuando se conecta a CI y se convierte en release gate. Estos son los pasos:

Checklist:

1. Añadir un paso de ejecución de eval en la CI pipeline, como pytest, LangSmith offline eval o Phoenix experiments.
2. Configurar un umbral de pass rate, por ejemplo 90%.
3. Exigir que el golden set pase completo (100%).
4. Configurar reglas de alerta para negative cases. Pueden notificar al equipo sin bloquear.
5. Configurar comparación de versiones (improvement/regression) entre baseline y versión actual.
6. Definir cuándo se dispara el gate: PR / merge / canary.

LangSmith Evaluation concepts menciona que offline evaluations puede usarse para regression testing, unit testing y backtesting sobre examples de datasets. La documentación de Phoenix experiments explica que se pueden comparar cambios de prompt, LLM o lógica de aplicación para juzgar improvement/regression. DeepEval afirma que sus evals son pytest-native y pueden ejecutarse en CI/CD o Python scripts, usando LLMTestCase y TaskCompletenessMetric para puntuar agent traces por capas.

6.2 Tabla de umbrales

Ejemplo de configuración de CI:

evaluation:
  triggers:
    - pull_request
    - merge_to_main
    - canary_deployment

  conditions:
    pass_rate: 0.9
    golden_set: 1.0
    no_regression: true

  notifications:
    on_failure: ["team-lead", "on-call"]
    on_negative_alert: ["team-lead"]

Los disparadores incluyen PR, para evitar que código problemático llegue a main; merge, para asegurar que el estado fusionado aún cumple condiciones; y canary, para validar antes de tráfico de producción. Si leíste control de costos y enrutamiento de modelos (N156), sabes que los umbrales de costo también pueden convertirse en condiciones de gate. Aquí nos centramos en umbrales de evaluación.

7. Retrospectiva de un caso real

7.1 Descripción del escenario

El agente de informes diarios funcionaba bien la semana pasada: llamaba check_permission para verificar permisos, refresh_data para refrescar datos y luego generate_report para generar el reporte. Tras actualizar el modelo, el agente sigue entregando un resumen final que parece correcto, pero la trayectoria omite check_permission y refresh_data.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

El usuario recibe un reporte sin chequeo de permisos y con datos desactualizados, aunque a simple vista no se nota. Un benchmark público no detecta este riesgo porque no tiene tu tool schema ni tu state machine.

7.2 Localización del problema

Exporta el trace fallido desde la plataforma de monitoreo (ver Monitoreo de agentes y recuperación ante fallos). El análisis de trayectoria muestra que la lista de tool calls no contiene check_permission ni refresh_data, el estado salta de init directamente a execute, faltan check y approve, y la respuesta final parece correcta aunque la fuente de datos no se refrescó.

Etiqueta: error de selección de herramientas + salto de transición de estado.

7.3 Actualización del dataset

Añade el caso fallido a negative cases. A la vez, refuerza el golden set: busca la tarea de informe diario exitosa de la semana anterior, incluye la secuencia completa de tool calls y etiquétala como caso correcto.

Actualiza las trajectory assertions: añade check_permission y refresh_data a la required tool list, y fija la assertion de orden de estado como ["init", "check", "approve", "execute"].

7.4 Intercepción por el gate de CI

La siguiente PR dispara una ejecución de eval. El negative case genera una alerta: falta el tool call a check_permission. El golden set pasa completo, así que el caso exitoso base sigue bien.

La causa está en el prompt. Tras la actualización, el modelo interpreta “generar reporte” como ejecución directa e ignora el chequeo previo y el refresco de datos.

7.5 Corrección y regresión

Corrige el prompt y enfatiza que antes de generar el reporte se deben verificar permisos y refrescar datos. Ejecuta de nuevo eval: el pass rate sube de 85% a 95%, el negative case pasa sin alerta, el golden set pasa completo y la comparación de versiones muestra improvement sin regression.

Merge y release. El gate de CI evitó que esta regresión llegara a producción.

7.6 Tabla de mapeo de campos

Este ciclo muestra el camino completo desde fallo de producción hasta prueba de regresión. Después de cada retrospectiva de incidente, convierte traceId, tool call, approvalId, state event y juicio humano en eval example. Así el próximo release no tropieza con el mismo error.

8. Qué leer después

• State machines de agentes y límites del prompt: entender de dónde salen las restricciones de transición de estado y los campos de trajectory assertion
• Modelo de permisos de agentes: entender approval records y reglas de tool calls de alto riesgo
• Diseño de aprobación humana: convertir approval records y flujos de aprobación en pruebas duraderas
• Control de costos y enrutamiento de modelos: entender cómo los umbrales de costo se vuelven condiciones de gate
• Monitoreo de agentes y recuperación ante fallos: exportar failed traces y construir una retrospectiva de incidentes