Cómo evaluar si tu agente realmente funciona: evals prácticos

"El agente funciona" es la frase más peligrosa del desarrollo de IA. Funciona en tu ejemplo, con tu prompt y con tu paciencia; eso no significa que funcione con clientes reales, a las 2 AM, con un mensaje mal escrito. Un eval es la respuesta: un conjunto de casos de prueba, ejecutados de forma sistemática, con métricas que te dicen si el agente rinde o no. Esta guía te dice cómo armar tu primer suite de evals con 20-50 casos, qué medir y cuándo confiar en el resultado para soltar el agente en producción.

Qué es un eval y por qué importa

Un eval es un experimento reproducible: tomas un dataset de casos, ejecutas tu agente con cada caso y mides la calidad de la respuesta contra un criterio definido. Sin evals, cada cambio de prompt, modelo o herramienta es una apuesta: el agente puede mejorar en tu prueba manual y empeorar en el 30% de los casos reales sin que lo notes.

Paso 1: el dataset de prueba (20-50 casos)

El dataset debe representar las tareas que esperas atender. Empieza con casos sintéticos explícitamente etiquetados si aún no tienes usuarios; sustitúyelos o complétalos con incidentes y consultas reales anonimizadas. Una distribución inicial orientativa, no una regla universal:

• 70% casos normales: las preguntas o tareas más frecuentes de tu operación real.
• 20% casos límite: formatos raros, datos faltantes, ambigüedad, usuarios confundidos.
• 10% casos de seguridad: intentos de inyección, peticiones fuera de alcance, datos sensibles.

Cada caso tiene tres partes: la entrada, la respuesta esperada (o los criterios de una buena respuesta) y las condiciones: qué herramientas debía llamar, qué datos debía usar. Empieza con 20 casos y crece: cada error real que encuentres en producción se convierte en un caso nuevo del dataset. Así el eval documenta la mejora del agente con el tiempo.

Paso 2: las métricas

Métrica	Qué detecta	Cómo se mide
Correctitud	Respuestas correctas vs. esperadas	Comparación con golden set o LLM-as-judge
Tool calls correctas	Uso adecuado de herramientas	¿Llamó la herramienta correcta con argumentos válidos?
Alucinación de datos	Inventa hechos	¿Respondió con datos fuera de su contexto?
Costo por caso	Gasto por ejecución	Tokens de entrada/salida por ejecución
Latencia	Velocidad de respuesta	Tiempo total por caso
Fallos técnicos	Errores, timeouts, crashes	Tasa de errores del pipeline

La correctitud es la métrica base: para tareas con respuesta determinista (una fecha, un cálculo, un dato de la base), se compara directamente; para respuestas abiertas, un segundo modelo evaluador (LLM-as-judge) puntúa contra los criterios. Las métricas de operación —costo y latencia— son las que se disparan silenciosamente cuando escalas, por eso se miden desde el día uno.

Paso 3: automatizar con LangSmith y Langfuse

Los evals manuales mueren a la segunda semana. La automatización es lo que los convierte en un hábito:

• LangSmith: ejecuta datasets contra tu agente, gestiona los casos, corre evaluadores (incluidos LLM-as-judge) y compara versiones: un cambio de modelo se valida corriendo la misma suite antes y después.
• Langfuse: captura cada ejecución de producción con sus traces, y sus evaluaciones puntúan casos reales además del dataset; las métricas de costo y latencia vienen integradas por traza.

El flujo recomendado: LangSmith para la suite de desarrollo (antes de cada release), Langfuse para la observación de producción (detectar degradaciones cuando el agente ya está vivo). Los dos resuelven lo mismo desde ángulos complementarios; empieza con uno y agrega el otro cuando el volumen lo justifique.

Paso 4: los umbrales de producción

Los números concretos dependen de tu caso, pero los umbrales que separan una demo de un agente confiable siguen este patrón:

• Correctitud: fija un umbral según el riesgo de la tarea y revísalo por categoría. Como objetivo interno de ejemplo podrías exigir 90% global y cero fallos en los casos críticos de esta suite; no son una certificación ni demuestran seguridad fuera del dataset.
• Fallos críticos: cero —un caso donde el agente hace algo irreversible (escribir datos incorrectos, enviar mensajes equivocados) sin detección.
• Costo: dentro del presupuesto por caso que calculaste con la fórmula de costos.
• Latencia: dentro del límite que exige tu canal (segundos para chat, menos para voz).
• Regresión: ningún caso del dataset que pasaba, falla después de un cambio.

La regla de oro: nunca despliegues un cambio de prompt o modelo sin correr la suite. Cinco minutos de evals ahorran una semana de incidentes.

Errores comunes al empezar con evals

• Confundir casos sintéticos con tráfico real: los sintéticos sirven para explorar límites, pero no justifican afirmar que mediste a usuarios. Anota su origen y revisa si representan la operación.
• Un solo veredicto global: si la suite devuelve "85%" sin decir qué casos fallan, no puedes mejorar nada; revisa caso por caso.
• Evaluar solo con LLM-as-judge: el judge es una métrica más, no la verdad; úsalo para respuestas abiertas y conserva casos deterministas (datos, cálculos, tool calls) con comparación exacta.
• Evals de una sola vez: la suite vale por su historial; correrla solo antes del lanzamiento no detecta regresiones posteriores.
• Ignorar costo y latencia: un eval que solo mide calidad te deja ciego al problema que aparecerá al escalar.

El hábito correcto: cada cambio de prompt o modelo corre la suite completa, y cada incidente en producción se convierte en un caso nuevo. En dos semanas tienes un dataset que documenta la evolución real de tu agente.

Una suite pequeña para empezar hoy, sin plataforma de pago

Descarga casos-stock.jsonl y comparar-modelos.csv. Los ocho casos son sintéticos, diseñados para el agente de stock en Python: productos disponibles, agotados, desconocidos, ambigüedad, reserva no permitida, inyección, fallo de herramienta y bucle.

Cada línea JSONL contiene id, entrada, criterio y si es crítica. Los casos de timeout y bucle requieren que tu harness inyecte el fallo o simule respuestas repetidas; escribir “simula timeout” en un prompt no crea de forma fiable un fallo de infraestructura. Las pruebas locales descargables de la guía Python comprueban el contrato con un cliente simulado; para medir un modelo real debes ejecutar además estas preguntas contra la API.

Procedimiento reproducible

1. Congela código, prompt, schemas y dataset en una versión. Registra el ID efectivo del modelo y los parámetros.
2. Ejecuta cada caso tres veces como exploración inicial; son 24 ejecuciones, no 24 usuarios. Conserva también errores y timeouts en el denominador.
3. Marca exito_end_to_end solo si llamada, argumentos, ejecución y respuesta cumplen el criterio. Guarda una traza sanitizada y el coste total del intento.
4. Separa fallos críticos. Si una reserva no autorizada se ejecuta, no permitas que siete respuestas correctas lo oculten en un promedio.
5. Ejecuta la misma suite antes y después del cambio. Investiga regresiones por caso; repite la prueba si la diferencia podría deberse a variabilidad del modelo.

Con 24 ejecuciones no puedes estimar incidentes raros con precisión. Un resultado de 24/24 no significa 100% de seguridad en producción. Para tareas sensibles, amplía escenarios, repeticiones, controles deterministas y revisión humana.

Qué puntuar sin un LLM juez

En stock puedes comprobar la herramienta invocada, SKU y cantidad exacta del resultado. Usa evaluación humana con una rúbrica corta para la respuesta final: comunica el dato correcto, no afirma una reserva y reconoce incertidumbre cuando falta información. No compares solo cadenas literales; “quedan 23” y “hay 23 unidades” pueden ser equivalentes.

Si introduces LLM-as-judge, calibra sus decisiones contra una muestra etiquetada por personas y registra desacuerdos. No pases texto de usuarios a otro proveedor sin revisar privacidad. Un juez rápido no sustituye permisos del backend ni demuestra que una acción externa ocurrió.

Resultado que debes conservar: número de intentos, éxitos por caso, fallos críticos, coste, latencia y versión. La plantilla se entrega vacía a propósito: no contiene resultados inventados ni una clasificación prefabricada de modelos.

Verificación de tu suite de evals

1. Ejecutas el dataset completo y obtienes puntajes por caso, no un veredicto global.
2. Puedes identificar los casos que fallan y ver la ejecución (traza) de cada uno.
3. Corres la suite tras un cambio y ves la comparación antes/después.
4. Cada incidente real de producción tiene su caso en el dataset.
5. Costo y latencia se miden en la misma corrida.

Un eval no es una certificación, es un instrumento de medición: cuanto más lo usas, más aprendes sobre tu agente. Para complementar la suite con observación continua, observabilidad para agentes cubre la detección de fallos en producción, y cuánto cuesta un agente te da el presupuesto por caso que los evals deben vigilar. El hub de seguridad, coste y operación tiene el resto de las guías de producción, y el curso gratuito de instalación te deja el primer agente corriendo para que empieces a evaluarlo hoy.