Eval Harness para agentes de IA: evaluaciones repetibles

Idea en 30 segundos

Eval harness es una forma de ejecutar el mismo conjunto de escenarios para un agente, evaluar resultados con reglas iguales, y comparar candidate con baseline.

Problema

Sin eval harness, los equipos suelen probar agentes de forma manual:

• lanzan algunas solicitudes en chat;
• miran unos ejemplos de respuesta;
• concluyen que el cambio parece seguro.

Esto no da una señal estable: un cambio puede verse bien en ejemplos aleatorios, pero romper escenarios críticos en producción.

Consecuencias más frecuentes:

• no se puede comparar candidate y baseline de forma justa;
• cuesta reproducir regresiones;
• CI no tiene una condición clara para bloquear release.

Concepto principal / modelo

Eval harness no es una sola prueba, sino un pipeline de validación: dataset fijo, condiciones controladas de run, evaluación, comparación con baseline y reporte.

Cuanto más estables sean estos componentes, menor la probabilidad de que el diff entre candidate y baseline venga de condiciones de run y no de un cambio real de comportamiento.

Cómo funciona

En práctica, eval harness se ejecuta como parte de la release pipeline. Cada cambio pasa por el mismo conjunto de escenarios.

Eval harness no reemplaza unit tests. Unit tests validan componentes locales; harness valida comportamiento del sistema sobre escenarios completos.

Implementación

En práctica, eval harness se sostiene en algunas reglas simples. Los ejemplos de abajo son esquemáticos y no dependen de un framework específico.

1. Estructura de escenario (test case)

case = {
    "id": "price_btc_basic",
    "input": "What is the price of BTC?",
    "expected_tool": "crypto_price_api",
    "checks": ["tool_selection", "valid_output_schema"],
}

Casos claros simplifican análisis de regresión y reducen ambigüedad al revisar runs.

2. Runner para ejecutar casos

def run_case(agent, case):
    result = agent.run(case["input"])
    return {
        "case_id": case["id"],
        "selected_tool": result.selected_tool,
        "output": result.output,
        "stop_reason": result.stop_reason,
    }

Nueva versión y baseline deben correr con condiciones iguales: mismos timeouts, tool-mocks, límites y configuración de runtime.

3. Evaluación y comparación con baseline

def evaluate_case(run_result, case):
    checks = {
        "tool_selection": run_result["selected_tool"] == case["expected_tool"],
        "valid_output_schema": isinstance(run_result["output"], dict),
    }
    return {"passed": all(checks.values()), "checks": checks}

candidate = run_eval_suite(agent=candidate_agent, dataset=dataset)
baseline = load_baseline_report("reports/baseline.json")
diff = compare(candidate, baseline)

Para tareas abiertas, a los checks deterministas se suele agregar LLM-as-a-judge como capa separada de evaluación. Baseline también debe versionarse y vincularse a modelo, prompt y configuración runtime concretos.

4. Reporte y CI gate

summary = build_summary(candidate, diff)

if summary["task_success_rate"] < 0.92:
    fail("gate_failed:task_success_rate")
if summary["hallucination_rate"] > 0.03:
    fail("gate_failed:hallucination_rate")

write_json("reports/eval-summary.json", summary)

Un buen eval harness siempre guarda artefactos: resultados por caso, motivos de fallo, diff contra baseline y reporte final.

5. Release gate en la estrategia general

Los criterios para bloquear release y umbrales de CI gate se describen aparte en Testing Strategy, para no duplicarlos en cada artículo.

Errores típicos

Dataset inestable

Los escenarios cambian "sobre la marcha", por lo que los resultados entre runs no son comparables de forma justa.

Causa típica: dataset no versionado y sin IDs de casos fijos.

Versión de modelo no fijada

Los proveedores LLM a veces actualizan modelos sin cambiar nombre genérico. Si la versión no está fijada (por ejemplo, gpt-4o-2024-08-06), los resultados pueden cambiar entre runs.

Causa típica: se usa alias de modelo (gpt-4o, sonnet) sin version pinning.

En sistemas de producción, normalmente se fija una versión concreta de modelo o snapshot.

Ejecución manual en lugar de automatización

Harness se ejecuta solo cuando "hay tiempo", no en cada cambio relevante.

Causa típica: sin integración en CI y sin pass/fail gate claro.

Sin comparación con baseline

El equipo mira solo métricas absolutas de candidate y deja pasar regresiones sutiles.

Causa típica: el reporte no incluye diff entre candidate y baseline.

Checks deterministas y no deterministas mezclados

Checks deterministas y LLM-as-a-judge se mezclan en un "score total", por eso es difícil entender qué se rompió.

Causa típica: no hay secciones separadas de evaluación por tipo de check.

Sin artefactos de run

Solo existe porcentaje final de éxito, sin trazas ni checks por caso.

Causa típica: harness no guarda resultados detallados en archivos de reporte.

Runs eval inestables

El mismo caso a veces pasa y a veces falla, por eso el equipo deja de confiar en el reporte.

Causa típica: entorno externo inestable, falta de mocks, timeouts variables o condiciones de run no uniformes.

Resumen

FAQ

Q: ¿Eval harness es solo un conjunto de pruebas?
A: No. Es un proceso gestionado: dataset, runner, evaluators, comparación con baseline y CI gate.

Q: ¿Se puede prescindir de LLM-as-a-judge?
A: Sí, si las tareas están bien cubiertas por checks deterministas. Para tareas abiertas, LLM-as-a-judge suele agregarse como capa separada de evaluación.

Q: ¿Con qué frecuencia ejecutar eval harness?
A: Como mínimo en cada cambio que pueda afectar comportamiento del agente: modelo, prompts, tools o reglas de runtime.

Q: ¿Qué es lo más importante en la primera versión del harness?
A: Dataset estable, baseline guardado, umbrales claros de pass/fail y artefactos del run.

Qué sigue

Para el panorama general, empieza por Testing Strategy. Luego cubre la lógica crítica con Unit Testing, arma un Golden Datasets estable, y para cambios entre versiones agrega Regression Testing.

Cuando aparezcan los primeros incidentes reales, añade Replay and Debugging e incluye esos casos en el dataset de tu eval harness.