Evalúa tus agentes: métricas y puntos de referencia
En esta página
Evalúa tus agentes: métricas y puntos de referencia
Un agente que funciona en desarrollo puede fallar en producción. La evaluación sistemática es la única forma de garantizar la calidad antes y después del despliegue. En esta lección, aprenderás a definir métricas, crear conjuntos de pruebas y automatizar la evaluación.
¿Por qué evaluar?
Sin una evaluación formal, vas a ciegas. Reformulas una instrucción porque un usuario se ha quejado, pero nada te indica si el agente ha mejorado o si acabas de romper otros tres escenarios. Dudas entre Terra y Luna para tu caso de uso, o entre dos niveles de razonamiento en el mismo modelo, y sin medición, la decisión se basa en una corazonada tras cinco pruebas manuales. Cambias el esquema de una herramienta, el agente deja de llamarla en un caso concreto y nadie se da cuenta hasta que el volumen de tickets se dispara. Un conjunto de evaluación convierte cada una de estas situaciones en un número comparable de una versión a la siguiente.
Métricas principales
Precisión
La primera pregunta es la más directa: ¿da el agente la respuesta correcta? Reproduces un conjunto de preguntas donde conoces la respuesta y verificas su presencia en la salida. La coincidencia de subcadenas sin distinguir mayúsculas de minúsculas es intencionadamente gruesa: tolera «El portátil Pro cuesta 1.299 € IVA incluido» donde la igualdad estricta fallaría, pero basta para hechos verificables y se calcula en un segundo.
from agents import Agent, Runner
async def evaluate_accuracy(agent, test_cases):
results = []
for case in test_cases:
result = await Runner.run(agent, case["question"])
# Verificación automática o basada en LLM
is_correct = case["expected_answer"].lower() in result.final_output.lower()
results.append({
"question": case["question"],
"answer": result.final_output,
"expected": case["expected_answer"],
"correct": is_correct,
})
rate = sum(1 for r in results if r["correct"]) / len(results)
print(f"Precisión: {rate:.1%} ({sum(1 for r in results if r['correct'])}/{len(results)})")
return results
# Conjunto de pruebas
test_cases = [
{"question": "¿Cuál es el precio del portátil Pro?", "expected_answer": "1299"},
{"question": "¿Cuántos portátiles hay en stock?", "expected_answer": "45"},
{"question": "¿Cuál es el producto más barato?", "expected_answer": "tablet"},
]
Uso correcto de las herramientas
Una respuesta correcta obtenida por azar sigue siendo un problema. Un agente que recita un precio memorizado en lugar de consultar el catálogo aprobará la prueba de precisión hoy y dará una tarifa obsoleta mañana. La segunda métrica observa por tanto el camino, no el resultado: ¿llama el agente a las herramientas correctas con los argumentos adecuados? Lees las llamadas en raw_responses, filtrando las salidas function_call, y la comparación utiliza conjuntos para permanecer indiferente al orden.
async def evaluate_tools(agent, test_cases):
results = []
for case in test_cases:
result = await Runner.run(agent, case["question"])
# Extraer herramientas llamadas de las respuestas brutas
called_tools = []
for response in result.raw_responses:
for output in getattr(response, "output", []):
if hasattr(output, "type") and output.type == "function_call":
called_tools.append(output.name)
tools_correct = set(case["expected_tools"]) == set(called_tools)
results.append({
"question": case["question"],
"called_tools": called_tools,
"expected_tools": case["expected_tools"],
"correct": tools_correct,
})
rate = sum(1 for r in results if r["correct"]) / len(results)
print(f"Herramientas correctas: {rate:.1%}")
return results
tool_cases = [
{
"question": "¿Cuál es el precio del portátil?",
"expected_tools": ["search_product"],
},
{
"question": "Precio del portátil con un 10 % de descuento",
"expected_tools": ["search_product", "calculate_discount"],
},
]
El segundo caso de prueba es el más instructivo: la pregunta requiere encadenar dos herramientas, y este es exactamente el tipo de composición que un cambio en la descripción puede romper silenciosamente.
Latencia y coste
Finalmente, está la dimensión operativa. Una media no dice nada sobre la experiencia real: es la cola de la distribución la que ahuyenta a los usuarios, cuando una solicitud de cada cien tarda veinte segundos. Al repetir cada mensaje varias veces, obtienes una distribución utilizable y lees la mediana como el comportamiento típico, y el P99 como tu peor escenario habitual.
import time
async def evaluate_performance(agent, messages, iterations=10):
latencies = []
for message in messages:
for _ in range(iterations):
start = time.perf_counter()
result = await Runner.run(agent, message)
duration = time.perf_counter() - start
latencies.append(duration)
import statistics
print(f"Latencia media: {statistics.mean(latencies):.2f} s")
print(f"Latencia P50: {statistics.median(latencies):.2f} s")
print(f"Latencia P99: {sorted(latencies)[int(len(latencies) * 0.99)]:.2f} s")
Evaluación con LLM (LLM-as-Judge)
Estas tres métricas dejan fuera cualquier cosa que no tenga una única respuesta correcta: una explicación de una política de devoluciones, una reformulación de ventas, un mensaje de disculpa. Para estas respuestas abiertas, utiliza un modelo para evaluar la calidad. El juez recibe la pregunta y la respuesta, aplica criterios que has escrito —precisión, relevancia, profesionalidad— y devuelve una puntuación estructurada gracias a un output_type de Pydantic. La restricción de formato es lo que hace utilizable el proceso: obtienes un entero agregable, no un comentario que volver a leer.
from pydantic import BaseModel
class Evaluation(BaseModel):
score: int # 1-5
reason: str
is_correct: bool
is_relevant: bool
is_professional: bool
evaluator_agent = Agent(
name="Evaluator",
instructions="""Evalúa la calidad de la respuesta del agente.
Criterios:
- Precisión: ¿Es la respuesta factual y correcta?
- Relevancia: ¿Responde la respuesta a la pregunta formulada?
- Profesionalidad: ¿Es el tono apropiado?
Puntuación de 1 (muy mala) a 5 (excelente).""",
model="gpt-5.6-sol",
output_type=Evaluation,
)
async def evaluate_quality(question, agent_response):
prompt = f"""Pregunta formulada: {question}
Respuesta del agente: {agent_response}
Evalúa esta respuesta."""
result = await Runner.run(evaluator_agent, prompt)
return result.final_output
El campo reason merece tu atención durante las revisiones: aquí es donde el juez explica por qué ha dado un 3 sobre 5, y a menudo es la formulación de un defecto que no habías conseguido nombrar.
Conjuntos de pruebas estructurados
Una evaluación que no es reproducible es inútil. Organiza tus casos de prueba en un formato estable donde cada entrada lleve un ID, una categoría, la pregunta, la respuesta esperada, las herramientas esperadas y los criterios cualitativos. La categoría hace todo el trabajo aquí: una puntuación global de 4,2 sobre 5 es engañosamente tranquilizadora, mientras que una puntuación detallada revela que la categoría «stock» se desploma a 2,8 mientras que «precio» eleva la media.
import json
# evaluation_dataset.json
DATASET = [
{
"id": "test_001",
"category": "price",
"question": "¿Cuál es el precio del portátil Pro?",
"expected_answer": "1.299 €",
"expected_tools": ["search_product"],
"criteria": ["contains_price", "professional_tone"],
},
{
"id": "test_002",
"category": "stock",
"question": "¿Está el Tablet Air en stock?",
"expected_answer": "sí",
"expected_tools": ["search_product"],
"criteria": ["clear_answer", "stock_information"],
},
]
async def run_complete_evaluation(agent):
results = []
for case in DATASET:
result = await Runner.run(agent, case["question"])
eval_result = await evaluate_quality(case["question"], result.final_output)
results.append({
**case,
"agent_response": result.final_output,
"score": eval_result.score,
"evaluation": eval_result.reason,
})
# Informe
average_score = sum(r["score"] for r in results) / len(results)
print(f"\nPuntuación media: {average_score:.1f}/5")
for cat in set(r["category"] for r in results):
cat_scores = [r["score"] for r in results if r["category"] == cat]
print(f" {cat}: {sum(cat_scores)/len(cat_scores):.1f}/5")
return results
Ejecuta esta evaluación en tu canalización de integración continua, igual que tus pruebas unitarias, y establece un umbral por debajo del cual se bloquee la entrega. A partir de entonces, cada cambio —nuevo modelo, instrucciones ajustadas, herramienta añadida— se compara con la anterior en los mismos casos, y la discusión deja de girar en torno a impresiones.
Puntos clave
- Evalúa la precisión, el uso de herramientas, la latencia y el coste
- La evaluación con LLM (LLM-as-Judge) gestiona respuestas abiertas
- Crea conjuntos de pruebas estructurados y reproducibles
- Automatiza la evaluación en tu CI/CD para detectar regresiones
- Compara sistemáticamente los cambios (modelo, instrucciones, herramientas)