Si tu agente funciona el martes pero se rompe el jueves después de un cambio en el prompt, no tenés un problema de agente. Tenés un problema de evaluación. Los sistemas no deterministas exigen harnesses deterministas, pero la mayoría de los equipos sigue deployando agentes como si fueran landing pages: miran el output una vez y deployan.
En este deep-dive te muestro cómo construir un programa de evals en producción desde cero: taxonomía de fallos, datasets dorados, jueces calibrados, tutorial de DeepEval con código real y un gate en CI que bloquea merges malos.
1. El Problema: Los Agentes Fallan en Silencio
El reporte State of Agent Engineering de LangChain encontró que solo el 27% de los equipos corre evals antes de cada deploy. Es decir, casi tres de cada cuatro deploys de agentes salen sin ningún chequeo automático de calidad. En software tradicional eso sería inaceptable: el mismo input debe producir el mismo output. Los agentes rompen ese contrato porque generan respuestas desde una distribución de probabilidad, mantienen estado entre turnos y ejecutan acciones reales con consecuencias reales.
Peor aún, la mayoría de los fallos ocurren en silencio, enterrados en pasos de razonamiento que nadie monitorea. Tu agente puede devolver la respuesta final correcta habiendo llamado la herramienta equivocada, filtrando datos a mitad de la trayectoria, o teniendo suerte en una corrida y entrando en loop infinito en la siguiente. Mirar solo el mensaje final no detecta nada de eso.
Los 4 modos de fallo que acechan en producción
Mal uso de herramientas (37%): el agente llama la herramienta correcta con parámetros incorrectos. Acciones alucinadas (28%): afirma haber hecho algo que nunca ejecutó. Loops infinitos (19%): reintenta sin reconocer el fallo. Scope creep (16%): actúa fuera de su alcance autorizado.
Cada uno de estos se ve bien si solo leés el mensaje final. Por eso la evaluación de trayectoria, no el chequeo de respuestas, es la disciplina central de esta guía.
2. Conceptos Mínimos: Offline vs Online, Determinista vs Juez
Antes de escribir código necesitás cuatro distinciones. Si las entendés mal, cada eval que construyas va a medir lo incorrecto.
Evals offline vs online
Offline corre sobre un dataset fijo antes del deploy: regresiones, comparación de prompts, cambio de modelo. Online puntúa trazas live de producción en continuo: drift, nuevos clusters de fallo, degradación de calidad. Necesitás ambas. Offline bloquea el merge, online vigila lo que el gate no vio.
Chequeos deterministas primero
¿Herramienta correcta? ¿Parámetros requeridos presentes? ¿JSON válido? ¿Se filtró PII? Nada de esto necesita un juez LLM. Los chequeos deterministas son gratis, instantáneos y exactos. Reservá el juez caro para lo que solo la semántica puede puntuar: calidad de razonamiento, completitud de tarea, tono.
LLM-como-juez, calibrado
Un juez sin rúbrica es una opinión con API key. Siempre puntuá con rúbrica multi-criterio con descripciones ancla, testeá sesgo de posición y de longitud, y calibrá contra 500+ casos etiquetados por humanos antes de confiar en métricas agregadas. Recalibrá cada vez que cambie el modelo juez, el prompt o el sistema.
Trayectoria, no solo respuestas
Para agentes multi-paso, puntuá el camino: eficiencia de pasos, correctitud de herramienta, correctitud de argumentos, adherencia al plan, calidad de razonamiento. Una respuesta correcta alcanzada con la herramienta equivocada es un fallo disfrazado de éxito.
La regla de oro de la economía de evals
Corré la cascada: chequeos deterministas en cada request, un clasificador barato en lo que pasa, el juez LLM solo en lo que necesita puntuación semántica. Los equipos que mandan todo al juez pagan 10x el costo y esperan 10x la latencia por peor señal.
3. Tutorial: DeepEval + LangSmith en 5 Pasos
El stack que recomiendo para la mayoría de los equipos: DeepEval para scoring pytest-nativo en CI, LangSmith para gestión de datasets, tracing y observabilidad en producción. DeepEval es open source en github.com/confident-ai/deepeval con más de 15k estrellas y más de 50 métricas pre-construidas. LangSmith está documentado en docs.langchain.com/langsmith. Uno maneja el gate, el otro la memoria.
Paso 1 — Instalá y definí modos de fallo desde incidentes reales
Partí de incidentes pasados de producción, no de hipótesis: herramienta equivocada, precio alucinado, loop infinito, PII filtrada. Cada incidente se convierte en un caso de eval. Primero instalá el framework:
pip install deepeval pip install pytest
Paso 2 — Escribí evals de trayectoria como tests pytest
DeepEval se integra con pytest, incluyendo parametrize y flags paralelos. Este es el patrón: un caso de test por incidente, una métrica determinista para correctitud de herramienta más una métrica con juez para completitud de tarea. Assert sobre la trayectoria, no solo sobre el string final:
import pytest
from deepeval import assert_test
from deepeval.test_case import LLMTestCase
from deepeval.metrics import TaskCompletionMetric
def test_refund_agent_uses_correct_tool():
test_case = LLMTestCase(
input="Refund order #4821, customer was charged twice",
actual_output=agent.run("Refund order #4821"),
expected_output="Refund issued for order #4821 via refund_tool",
tools_called=["refund_tool"],
expected_tools=["refund_tool"],
)
metric = TaskCompletionMetric(threshold=0.7)
assert_test(test_case, [metric])Paso 3 — Corré la suite en local
Un comando corre todo el set de regresión. Verde acá significa que el cambio de prompt no rompió silenciosamente los cinco incidentes que ya habías arreglado una vez:
deepeval test run test_agent.py
Paso 4 — Bloqueá cada merge en CI
Un programa de evals que no bloquea un merge es asesoría para siempre. Conectá la suite a GitHub Actions para que un eval fallido bloquee el PR. Alertá en casos borderline a 2 puntos del umbral de aceptación:
jobs:
agent-evals:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: pip install deepeval pytest
- run: deepeval test run test_agent.pyPaso 5 — Observá producción con tracing de LangSmith
CI bloquea el merge, el tracing vigila lo que el gate no vio. Activá el tracing de LangSmith con dos variables de entorno, anotá las trazas fallidas de producción y promovelas de vuelta al dataset dorado cada semana. Ese loop cerrado es lo que convierte incidentes en cobertura de regresión:
LANGSMITH_TRACING=true LANGSMITH_API_KEY=lsv2_your_key_here
Cuándo sumar Braintrust o Inspect AI
Sumá Braintrust cuando el overhead de gestión de datasets justifique su tier Pro y quieras scoring agnóstico de modelo con scorers custom en sandbox. Usá Inspect AI cuando operes en entornos regulados o del sector público y necesites comparar cinco o más proveedores de modelos en una sola corrida. La mayoría de los equipos converge en dos herramientas: una librería CLI para velocidad en CI más un dashboard hosteado para auditoría y revisión.
4. Errores Comunes Que Matan Programas de Evals
Vi los mismos cinco errores terminar más programas de evals que cualquier limitación técnica. Todos son fallos de proceso disfrazados de problemas de herramientas.
✅ Hacé esto
- • Construí el dataset dorado desde incidentes de producción, estratificado por tipo de tarea
- • Calibrá el juez contra 500+ casos etiquetados por humanos primero
- • Puntuá trayectorias: herramientas, argumentos, adherencia al plan, razonamiento
- • Bloqueá merges en CI cuando fallan los evals
- • Miná trazas de producción cada semana y promovelas al dataset
❌ Dejá de hacer esto
- • Confiar en benchmarks públicos como proxy de tus workflows
- • Correr un juez sin calibrar y citar sus scores como verdad
- • Chequear solo la respuesta final de un agente de 12 pasos
- • Mantener los evals como asesoría para que las regresiones igual deployen
- • Tratar el eval como proyecto único en vez de loop semanal
Regla de oro
Los benchmarks comparan modelos. Los evals protegen tu producto. SWE-bench y WebArena te dicen qué modelo es más fuerte en general; solo tu dataset derivado de incidentes te dice si el cambio de prompt del jueves rompió los reembolsos. Shipeá siete cosas: set dorado, juez calibrado, piso determinista, gate en CI, matemática estadística en deltas, observabilidad en producción, loop cerrado. Refiná después.
Conclusión
La brecha entre agentes demo y agentes en producción no es elección de framework. Es disciplina de evaluación. Chequeos deterministas en cada request, un juez calibrado para semántica, scoring de trayectoria en vez de chequeo de respuestas, un gate en CI que realmente bloquee, y un loop semanal de fallos de producción de vuelta al dataset.
Empezá esta semana: instalá DeepEval, convertí tus últimos cinco incidentes de producción en casos de test, y conectá un job de CI. Esa sola tarde te compra más confiabilidad que cualquier upgrade de modelo. Después sumá tracing, después calibración, después el resto de las siete.
Tu checklist de 5 pasos
Construí
- • pip install deepeval + pytest
- • Set dorado desde incidentes reales
- • Tests de trayectoria, no de respuestas
Bloqueá
- • deepeval test run en CI
- • Eval fallido bloquea el merge
- • Alerta en scores borderline
Observá
- • Tracing LangSmith en prod
- • Calibrá el juez (500+ etiquetas)
- • Loop semanal traza-a-dataset
