Desarrollo impulsado por evaluaciones para agentes de IA: contratos, rastreos y evaluadores
Trate las evaluaciones como CI/CD para los agentes: considere las instrucciones de versión como contratos, rastree las ejecuciones con OpenTelemetry y Tempo, y luego realice pruebas con verificaciones deterministas y un evaluador basado en LLM.
Fuentes: **Eval-Driven Development: A Software Engineering Approach to Production-Grade AI Agents**
La mayoría de los equipos que desarrollan IA agente caen pronto en la trampa de los frameworks. La búsqueda del orquestador perfecto parece ser el primer paso obvio, pero los frameworks pesados y abstractos resultan no ser la solución, y algunos de ellos degradan rápidamente entre versiones. Una automatización de revisión de código creada sin ningún framework demostró cuán poco se necesita. Lo que faltaba era algo tomado de la ingeniería de software tradicional: evaluaciones, que funcionan como CI/CD para los agentes.
Las evaluaciones no son universales, ni se limitan a usar modelos de lenguaje grandes como jueces. Implementarlas correctamente marca la diferencia entre un sistema frágil y uno de calidad para producción.
La pila aquí es deliberadamente de código abierto y no está vinculada a los servicios gestionados por ningún proveedor en particular. Pydantic AI es el marco de agentes, una biblioteca ligera basada en esquemas que no interfiere y trata las evaluaciones como una característica de primera clase. Grafana Tempo con almacenamiento en S3 almacena las trazas, en lugar de una plataforma de observabilidad gestionada, y el código generado por IA consulta y filtra esas trazas para cada tipo de evaluación.
Por qué la mayoría de los agentes no sobreviven en producción
La señal más clara de que un sistema de agentes no durará es la falta de prácticas de ingeniería fundamentales, y no el modelo, el marco o la ingeniosidad de sus instrucciones. Si un agente no cuenta con trazado estructurado, sin evaluaciones, sin control de versiones de instrucciones ni medidas de seguridad, se trata de un prototipo basado en intuiciones que tiene grandes probabilidades de fallar.
El software tradicional obtiene una calidad continua a través de pipelines CI/CD, pruebas unitarias, pruebas de integración y pruebas de regresión. En el mundo no determinista de los agentes, la brecha fatal habitual es la falta de un marco de evaluación automatizado además de la ausencia de medidas de control operativo. Para desarrollar agentes maduros es necesario volver a los principios fundamentales: una infraestructura abierta y un flujo de trabajo basado en el desarrollo impulsado por evaluaciones (Eval-Driven Development, EDD) que pueda escalar.
El pipeline de producción
1. El contrato: versionar el prompt por separado
Los prompts y sus artefactos relacionados son la parte más importante de un sistema de agentes, por lo que no deberían quedar ocultos dentro del código del agente. El código es solo el cuerpo del sistema, que es bastante fácil de estabilizar y versionar, mientras que los prompts siguen evolucionando a medida que mejoran los modelos.
El pipeline comienza con un contrato versionado que especifica qué debe ejecutarse: el agente, la instrucción, el modelo y la política de evaluación.
[
{
"agent_id": "financial_market_headlines",
"version": 1,
"agent_model": "openai:gpt-4",
"prompt": "What are today's major financial market headlines?",
"eval": {
"contains": ["market"],
"max_model_requests": 3,
"min_tool_calls": 1,
"max_tool_calls": 5,
"judge_rubric": "The answer should be a useful response to the user's financial markets question. It should summarize market-relevant information, avoid obviously unrelated content, avoid investment advice, and avoid claiming certainty beyond what the retrieved information supports."
}
}
]
El prompt y la rúbrica son deliberadamente cortos aquí con fines de demostración, ya que los prompts de producción suelen ser largos y detallados. El contrato vincula el prompt con un prompt de evaluación que utiliza un LLM como juez, así como con verificaciones que no involucran LLM, como la coincidencia de palabras clave mediante “contains” y un número mínimo o máximo de llamadas a herramientas.
2. El tiempo de ejecución: el motor de ejecución
El tiempo de ejecución del agente se encarga de cumplir con el contrato. Llama al modelo, invoca herramientas externas a través de MCP cuando es necesario y realiza el trabajo real.
La elección se decantó principalmente entre LangGraph y Pydantic AI. Python no es la única opción; incluso Rust cuenta con una biblioteca en Rig. Pero la velocidad pura del lenguaje apenas importa frente al tiempo de espera de la inferencia del LLM y a las llamadas de red a las herramientas de MCP, por lo que gana el amplio y maduro ecosistema de IA de Python. Pydantic AI fue elegido gracias a su soporte de primera clase para las evaluaciones.
En producción, el entorno de ejecución suele basarse en Kubernetes. Es tentador sobreproyectar el sistema modelando cada agente como un recurso personalizado, pero los bucles de reconciliación para solicitudes que cambian rápidamente reducirán su velocidad de trabajo. Mantenga el entorno de ejecución lo más ligero posible.
3. La capa de observabilidad: sin puntos ciegos
El entorno de ejecución emite registros de trazas, logs, contadores de uso, llamadas a modelos y herramientas, datos de latencia y errores; todo esto se captura con OpenTelemetry y se almacena en sistemas como Tempo, Loki y Prometheus. Grafana, a su vez, muestra qué está haciendo el sistema en producción.
4. La capa de evaluación: CI/CD para IA
Aquí es donde todo se integra. Los registros de ejecución de la capa de observabilidad fluyen directamente a la fase de evaluación, donde se realizan dos tipos de pruebas contra registros reales: reglas deterministas y juicios no deterministas.
El ciclo nunca se detiene: definir, ejecutar, observar, evaluar, mejorar, repetir.
Forzar el determinismo en un sistema no determinista
Las evaluaciones se dividen en dos grupos. Las deterministas pueden probarse con precisión mediante código sencillo. Un ejemplo deliberadamente simplista sería pedirle a un LLM que sume dos números y verificar la respuesta con una prueba unitaria.
En este caso de uso, la instrucción solicita las noticias del mercado financiero de hoy, lo que implica que el modelo debe utilizar la herramienta de búsqueda en la web proporcionada al menos una vez. Esa parte es determinista y constituye una prueba útil. Además, si el resultado debe contener ciertas cadenas de texto, se puede verificar mediante una comprobación de “Contiene”.
Capa 1: pruebas deterministas en tiempo real
El conjunto de pruebas en tiempo real ejecuta al agente actual contra el contrato versionado. Pydantic Evals incluye MaxToolCalls y un verificador de texto Contains. Las funcionalidades faltantes como MinToolCalls se añaden como envoltorios simples.
uv run python tests/unittest_eval_agent.py
Los evaluadores se seleccionan según cada caso:
evaluators=[
*[Contains(value, case_sensitive=False) for value in case.eval.contains],
MaxModelRequests(case.eval.max_model_requests),
MinToolCalls(case.eval.min_tool_calls),
MaxToolCalls(case.eval.max_tool_calls),
]
Cada caso se ejecuta varias veces, ya que los modelos son no deterministas. El mismo modelo con un prompt e configuraciones idénticos puede utilizar la herramienta en una ejecución y omitirla en otra. Esto es especialmente evidente con modelos más económicos y de menor capacidad; si alguna de, digamos, diez ejecuciones falla, es una señal de que el prompt necesita más detalles. Una ejecución con tres repeticiones se ve así:
(financial-agent2) alex@pop-os:/ssd/ai_works/financial_agent2$ uv run python tests/unittest_eval_agent.py
Running each eval case 3 time(s)
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Metrics ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_headlines_v1 [1/3] │ tool_calls: 1 │ ✔✔✔✔ │ 18.8s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,325 │ │ │
│ │ output_tokens: 278 │ │ │
│ │ cost: 0.0564 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ financial_market_headlines_v1 [2/3] │ tool_calls: 1 │ ✔✔✔✔ │ 8.8s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,195 │ │ │
│ │ output_tokens: 82 │ │ │
│ │ cost: 0.0408 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ financial_market_headlines_v1 [3/3] │ tool_calls: 1 │ ✔✔✔✔ │ 13.5s │
│ │ requests: 2 │ │ │
│ │ input_tokens: 1,292 │ │ │
│ │ output_tokens: 388 │ │ │
│ │ cost: 0.0620 │ │ │
├─────────────────────────────────────┼───────────────────────┼────────────┼──────────┤
│ Averages │ requests: 2.00 │ 100.0% ✔ │ 13.7s │
│ │ output_tokens: 249.3 │ │ │
│ │ tool_calls: 1.00 │ │ │
│ │ cost: 0.0531 │ │ │
│ │ input_tokens: 1,270.7 │ │ │
└─────────────────────────────────────┴───────────────────────┴────────────┴──────────┘
Capa 2: regresión determinística a partir de huellas
El segundo conjunto no ejecuta nuevamente al agente. Lee las huellas completas de Tempo:
uv run python tests/regression_eval_traces.py
Extrae el resultado final, cuenta los intervalos del modelo y de la herramienta, localiza el contrato registrado y aplica las mismas reglas deterministas de antes: que contenga, y que la herramienta sea llamada al menos una vez. Una ejecución registrada podría indicar:
Trace: ff5a53e3392dc26cd0a2890782be70ec
Eval case: financial_market_headlines v1
Status: PASS
Model requests: 2
Tool calls: 1
contains('market'): PASS
MaxModelRequests: PASS
MaxToolCalls: PASS
Eso es económico y reproducible, ya que vuelve a evaluar las pruebas que ya se han recopilado.
Nivel 3: pruebas no deterministas con un juez basado en LLM
El contrato también incluye una rúbrica para probar el prompt. Es de nuevo el mismo contrato breve:
[
{
"agent_id": "financial_market_headlines",
"version": 1,
"agent_model": "openai:gpt-4",
"prompt": "What are today's major financial market headlines?",
"eval": {
"contains": ["market"],
"max_model_requests": 3,
"min_tool_calls": 1,
"max_tool_calls": 5,
"judge_rubric": "The answer should be a useful response to the user's financial markets question. It should summarize market-relevant information, avoid obviously unrelated content, avoid investment advice, and avoid claiming certainty beyond what the retrieved information supports."
}
}
]
Dado que el propio agente funciona con GPT-4, el juez necesita un modelo más potente, y GPT-5 cumple esa función aquí. Él decide si la respuesta fue útil y relevante, si exageró lo que respaldan los materiales obtenidos y si incluyó consejos de inversión.
Dividir la evaluación en varios niveles ofrece otra alternativa. Las verificaciones simples de tipo NLP pueden realizarse con modelos menos potentes o incluso con aquellos pequeños y autohospedados, y un conjunto de pruebas de este tipo puede sumarse para obtener un resultado similar al juicio de nivel superior mencionado anteriormente. Lo que sea mejor depende del caso de uso y de cómo estén diseñadas las pruebas.
Para mayor profundidad, el artículo de revisión “A Survey on LLM-as-a-Judge” (arXiv 2411.15594) es una lectura recomendada. Dependiendo del caso de uso, eventualmente se necesitarán sistemas que evalúen al juez, utilizando retroalimentación humana u otros medios.
La suite carga el mismo resultado final almacenado y ejecuta Pydantic Evals LLMJudge con la rúbrica del contrato:
LLMJudge(
rubric=case.eval_case.eval.judge_rubric,
model=args.judge_model,
include_input=True,
score={"evaluation_name": "judge_score", "include_reason": True},
assertion={"evaluation_name": "judge_pass", "include_reason": True},
)
He aquí un caso clásico de error detectado por el juez, causado por una instrucción breve y vaga. En lugar de llamar a la herramienta y resumir los resultados, el modelo respondió con un mensaje indicando al usuario que consultara los medios de noticias financieras.
uv run python tests/regression_llm_judge_traces.py --sample-percent 50
Trace selection: fetched=1 sampled=1 judging=1 lookback_minutes=1440 sample_percent=50 max_traces=5
Trace case: trace_id=3891f0b8432c9bbcb00e5e8adce1600b agent_id=financial_market_headlines prompt_version=1 answer_chars=207
Judging 1 trace(s) with openai:gpt-5.4
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Inputs ┃ Outputs ┃ Scores ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_he… │ {'trace_id': │ Today's major │ judge_score: 0.000 │ judge_pass: ✗ │ 469µs │
│ │ '3891f0b8432c9bbcb00 │ financial market │ Reason: The │ Reason: The │ │
│ │ e5e8adce1600b', │ headlines can be │ response does not │ response does not │ │
│ │ 'agent_id': │ found on major │ summarize any actual │ summarize any │ │
│ │ 'financial_market_he │ business and finance │ market headlines or │ actual market │ │
│ │ adlines', │ news outlets │ provide │ headlines or │ │
│ │ 'prompt_version': 1, │ including CNBC, │ market-relevant │ provide │ │
│ │ 'agent_model': │ Yahoo Finance, │ information; it only │ market-relevant │ │
│ │ 'openai:gpt-4', │ Reuters, and │ redirects the user │ information; it │ │
│ │ 'judge_model': │ Bloomberg. For more │ to news websites. It │ only redirects the │ │
│ │ 'openai:gpt-5.4', │ specific stories, │ avoids investment │ user to news │ │
│ │ 'prompt': "What are │ please visit their │ advice, but it is │ websites. It avoids │ │
│ │ today's major │ websites. │ not a useful answer │ investment advice, │ │
│ │ financial market │ │ to the user's │ but it is not a │ │
│ │ headlines?"} │ │ question. │ useful answer to │ │
│ │ │ │ │ the user's │ │
│ │ │ │ │ question. │ │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
├──────────────────────┼──────────────────────┼──────────────────────┼──────────────────────┼─────────────────────┼──────────┤
│ Averages │ │ │ judge_score: 0.000 │ 0.0% ✔ │ 469µs │
└──────────────────────┴──────────────────────┴──────────────────────┴──────────────────────┴─────────────────────┴──────────┘
A continuación se muestra un segundo caso de fallo. En este caso, el juez podría haber tomado una decisión errónea, o la rúbrica podría ser demasiado vaga, ya que el modelo sí utilizó el MCP de búsqueda y obtuvo resultados decentes.
uv run python tests/regression_llm_judge_traces.py --sample-percent 10 --lookback-minutes 30
Trace selection: fetched=1 sampled=1 judging=1 lookback_minutes=30 sample_percent=10 max_traces=5
Trace case: trace_id=38fa3a54134d8818c7d7a5afbf50967e agent_id=financial_market_headlines prompt_version=1 answer_chars=654
Judging 1 trace(s) with openai:gpt-5.4
Evaluating task ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Evaluation Summary: task
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Case ID ┃ Inputs ┃ Outputs ┃ Scores ┃ Assertions ┃ Duration ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ financial_market_… │ {'trace_id': │ Here are today's │ judge_score: 0.450 │ judge_pass: ✗ │ 441µs │
│ │ '38fa3a54134d8818c │ major financial │ Reason: The │ Reason: The │ │
│ │ 7d7a5afbf50967e', │ market headlines: │ response is │ response is │ │
│ │ 'agent_id': │ │ market-related and │ market-related │ │
│ │ 'financial_market_ │ 1. Wall Street's │ avoids investment │ and avoids │ │
│ │ headlines', │ riskiest trades │ advice, but it │ investment │ │
│ │ 'prompt_version': │ are suddenly back │ mostly lists │ advice, but it │ │
│ │ 1, 'agent_model': │ on top: Chart of │ article headlines │ mostly lists │ │
│ │ 'openai:gpt-4', │ the Day - Yahoo │ and links rather │ article headlines │ │
│ │ 'judge_model': │ Finance │ than providing a │ and links rather │ │
│ │ 'openai:gpt-5.4', │ [Link](https://fi │ useful summary of │ than providing a │ │
│ │ 'prompt': "What │ nance.yahoo.com/) │ the key financial │ useful summary of │ │
│ │ are today's major │ 2. S&P 500 │ market │ the key financial │ │
│ │ financial market │ notches │ developments. │ market │ │
│ │ headlines?"} │ record-high close │ │ developments. │ │
│ │ │ as rate-hike │ │ │ │
│ │ │ worries ease - │ │ │ │
│ │ │ Reuters │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.reuters.com/mar │ │ │ │
│ │ │ kets/us/) │ │ │ │
│ │ │ 3. Treasury │ │ │ │
│ │ │ yields rise as │ │ │ │
│ │ │ U.S. threatens │ │ │ │
│ │ │ Iran with more │ │ │ │
│ │ │ economic │ │ │ │
│ │ │ sanctions - CNBC │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.cnbc.com/) │ │ │ │
│ │ │ 4. Latest stock │ │ │ │
│ │ │ market, financial │ │ │ │
│ │ │ and business news │ │ │ │
│ │ │ - MarketWatch │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.marketwatch.com │ │ │ │
│ │ │ /) │ │ │ │
│ │ │ 5. Latest finance │ │ │ │
│ │ │ and stock market │ │ │ │
│ │ │ news covering the │ │ │ │
│ │ │ Dow, S&P 500, │ │ │ │
│ │ │ banking, │ │ │ │
│ │ │ investing and │ │ │ │
│ │ │ regulation - WSJ │ │ │ │
│ │ │ [Link](https://ww │ │ │ │
│ │ │ w.wsj.com/finance │ │ │ │
│ │ │ ) │ │ │ │
├────────────────────┼────────────────────┼───────────────────┼────────────────────┼───────────────────┼──────────┤
│ Averages │ │ │ judge_score: 0.450 │ 0.0% ✔ │ 441µs │
└────────────────────┴────────────────────┴───────────────────┴────────────────────┴───────────────────┴──────────┘mar
Ejecutar este tipo de pruebas en cada traza puede resultar demasiado costoso y lento. La toma de muestras aleatorias es una opción mejor. Cuando el producto ofrece una forma de recopilar comentarios de los usuarios, el ID de la traza puede llevar directamente a los componentes del flujo que presentaron problemas, y solo esos se prueban. Productos comerciales como LangSmith y Arize Phoenix cubren esto, pero un backend S3 junto con esta estructura también brinda la misma capacidad, y existe una configuración con docker compose para ello.
Después de las pruebas unitarias iniciales, queda claro que tanto el prompt como la rúbrica necesitan una actualización, y el contrato pasa a la versión 2:
{
"id": "financial_market_headlines",
"version": 2,
"agent": "websearch",
"prompt": "Use the web-search tool to find and verify today's major financial-market headlines. Report the 3 to 5 most consequential developments across equities, rates, currencies, commodities, or macroeconomic policy. For each item, state what happened, identify the affected market or region, explain briefly why it matters, and name the source with a link when available. Include the relevant date and units for numerical claims. Cross-check any surprising index level, percentage move, policy decision, or economic release against a second reliable source; if it cannot be verified, omit it or clearly label it as unconfirmed. State when the information was current, distinguish facts from developing reports or interpretation, and say when reliable current information is insufficient. Do not invent facts, present stale information as today's news, or give personalized investment advice.",
"contains": ["market"],
"max_model_requests": 4,
"min_tool_calls": 1,
"max_tool_calls": 7,
"judge_rubric": "The response should provide 3 to 5 current, consequential financial-market developments based on web research. Each item should identify what happened, the affected market or region, why it matters, and its source, preferably with a link. Numerical claims should include meaningful dates and units; surprising figures should be corroborated by a second reliable source or explicitly marked unconfirmed. The answer should state when the information was current, distinguish verified facts from developing reports or interpretation, and acknowledge insufficient evidence rather than inventing details. It must stay relevant, avoid stale news presented as current, avoid unsupported certainty, and avoid personalized investment advice. A polished but uncited answer containing an implausible or unverifiable market figure should fail."
},
De el patrón a la pipeline de lanzamiento
Cuando cada traza remite a su contrato, una pipeline de lanzamiento puede recopilar diferentes tipos de evidencia en cada etapa, lo cual dice más que una simple tasa de éxito. Un lanzamiento debe evaluarse en varias dimensiones:
- si la tarea tuvo éxito
- qué tan buena es la salida desde el punto de vista semántico
- si las herramientas se utilizaron correctamente
- conformidad con las normas de seguridad
- costo en solicitudes y tokens
- latencia y fiabilidad
Leer más
El blog de ingeniería de Anthropic tiene un artículo sobre cómo funcionan las evaluaciones para agentes de IA, en https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents, que aborda el tema de manera más amplia.
Leer relacionado
- Desarrollo Dirigido por Especificaciones con Agentes de Programación AI: Una Guía Práctica — Cómo mantener a los agentes de programación AI alineados con las especificaciones: el flujo de trabajo de cuatro fases, los archivos AGENTS.md y SPEC.md, los roles de los múltiples agentes, los niveles de madurez y la deriva de intenciones.
- Engineering Agencial en Cinco Capas: Desde Especificaciones y Agentes Paralelos hasta Reglas y Supervisión — Karpathy habla del cambio respecto al coding basado en intuiciones. Conoce las cinco capas del engineering agencial: especificaciones, orquestación, reglas codificadas, revisión humana y observabilidad, además de un plan semanal.