Ir al contenido principal
Español— Elegir un idioma
Menú

Evalúa tus agentes: métricas y puntos de referencia

Lección 22 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Evalúa tus agentes: métricas y puntos de referencia
  2. ¿Por qué evaluar?
  3. Métricas principales
  4. Evaluación con LLM (LLM-as-Judge)
  5. Conjuntos de pruebas estructurados
  6. Puntos clave

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)