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

Calificación de trazas: puntuación de ejecuciones

Lección 23 de 25 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Calificación de trazas: puntuación de ejecuciones
  2. El concepto de calificación de trazas
  3. Calificación automática con reglas
  4. Calificación basada en LLM
  5. Canalización de calificación en producción
  6. Panel de calidad
  7. Puntos clave

Calificación de trazas: puntuación de ejecuciones

El rastreo (tracing) registra lo que hace tu agente. Eso es esencial, pero no basta: nadie lee diez mil trazas al día, y los problemas se esconden precisamente en las que nunca abres. La calificación de trazas va más allá: puntúa automáticamente cada ejecución para detectar incidencias, medir la calidad a lo largo del tiempo y alimentar un bucle de mejora continua.

El concepto de calificación de trazas

Cada traza que genera tu agente contiene la ejecución completa: el mensaje del usuario, las llamadas a herramientas, las respuestas intermedias y la respuesta final. La calificación de trazas analiza estas trazas y asigna puntuaciones basándose en tus criterios. Pasas de consultar un registro a posteriori a monitorizar una métrica de forma continua, y la pregunta «¿Cómo está rindiendo el agente ahora mismo?» deja de ser una suposición.

Calificación automática con reglas

El nivel más sencillo utiliza reglas programáticas para puntuar cada traza. Cada regla parte de una puntuación perfecta de 1,0 y resta puntos según lo que observa. Una ejecución que tarda más de diez segundos pierde 0,2 puntos, no porque el resultado sea incorrecto, sino porque es probable que el usuario haya abandonado. Más de quince turnos cuesta 0,3 puntos: esa es la firma de un agente dando vueltas en círculo entre dos herramientas. Cada error de herramienta resta 0,1 puntos. Las barreras de seguridad (guardrails) activadas se marcan sin penalización —han hecho su trabajo—, pero una respuesta de menos de diez caracteres cuesta por sí sola medio punto, porque un agente silencioso es un agente inútil.

from dataclasses import dataclass

@dataclass
class GradeTrace:
    trace_id: str
    score: float  # 0.0 to 1.0
    details: dict
    alerts: list[str]

def grade_trace(trace_data: dict) -> GradeTrace:
    """Puntúa una traza basándose en reglas de negocio."""
    score = 1.0
    alerts = []
    details = {}

    # Regla 1: Latencia
    duration = trace_data.get("duration_ms", 0)
    if duration > 10000:
        score -= 0.2
        alerts.append(f"Alta latencia: {duration}ms")
    details["latency_ms"] = duration

    # Regla 2: Número de turnos
    num_turns = trace_data.get("num_turns", 0)
    if num_turns > 15:
        score -= 0.3
        alerts.append(f"Demasiados turnos: {num_turns}")
    details["num_turns"] = num_turns

    # Regla 3: Errores de herramienta
    tool_errors = trace_data.get("tool_errors", 0)
    if tool_errors > 0:
        score -= 0.1 * tool_errors
        alerts.append(f"{tool_errors} error(es) de herramienta")
    details["tool_errors"] = tool_errors

    # Regla 4: Barreras de seguridad activadas
    guardrails = trace_data.get("guardrails_triggered", 0)
    if guardrails > 0:
        alerts.append(f"{guardrails} barrera(s) de seguridad activada(s)")
    details["guardrails"] = guardrails

    # Regla 5: Respuesta vacía
    response = trace_data.get("final_output", "")
    if not response or len(response) < 10:
        score -= 0.5
        alerts.append("Respuesta vacía o demasiado corta")
    details["response_length"] = len(response)

    return GradeTrace(
        trace_id=trace_data["trace_id"],
        score=max(0.0, score),
        details=details,
        alerts=alerts,
    )

El diccionario details acompaña siempre a la puntuación: sin él, sabrías que una ejecución ha obtenido un 0,5 pero no el porqué. Estos umbrales son tuyos, no constantes universales; un agente de investigación tolera quince turnos donde un asistente de compra debe responder en tres.

Calificación basada en LLM

Las reglas no ven el contenido. Una respuesta rápida, corta y educada que no da en el clavo obtendrá un 1,0. Para una evaluación más fina, utiliza un modelo para puntuar las trazas en cuanto al fondo: relevancia, precisión y tono, cada uno del 1 al 5, junto con los problemas identificados y sugerencias de mejora. De nuevo, la salida estructurada mediante Pydantic hace que las puntuaciones sean agregables en lugar de generar comentarios en forma libre.

from pydantic import BaseModel
from agents import Agent, Runner

class GradeLLM(BaseModel):
    relevance_score: int  # 1-5
    accuracy_score: int  # 1-5
    tone_score: int  # 1-5
    issues: list[str]
    suggestions: list[str]

grader_agent = Agent(
    name="Calificador de trazas",
    instructions="""Puntuas ejecuciones de un agente de ventas.

    Analiza la traza completa (pregunta, herramientas llamadas, respuesta) y puntúa:
    - Relevancia (1-5): ¿Responde la respuesta a la pregunta?
    - Precisión (1-5): ¿Es correcta la información?
    - Tono (1-5): ¿Es el tono profesional y apropiado?

    Identifica problemas y propone mejoras.""",
    model="gpt-5.6-sol",
    output_type=GradeLLM,
)

async def grade_trace_llm(trace: dict) -> GradeLLM:
    prompt = f"""Traza de ejecución a puntuar:

    Pregunta del usuario: {trace['user_message']}
    Herramientas llamadas: {trace['tools_called']}
    Respuesta final: {trace['final_output']}
    Duración: {trace['duration_ms']}ms
    Número de turnos: {trace['num_turns']}"""

    result = await Runner.run(grader_agent, prompt)
    return result.final_output

El indicio (prompt) también pasa las herramientas llamadas y la duración: así, el juez puede penalizar al agente por responder sin consultar el catálogo, algo que la sola lectura de la respuesta no permitiría.

Canalización de calificación en producción

Ahora combina ambos enfoques sin disparar tu presupuesto. Puntuar cada traza con un LLM a volumen de producción multiplica tu factura de inferencia; usar solo reglas te deja ciego ante el fondo. La canalización (pipeline) siguiente aplica un filtro: todas las trazas pasan por la calificación programática, que es rápida y gratuita, y solo las que caen por debajo de 0,7 van al juez. La puntuación del juez, la suma de tres valoraciones de 1 a 5, se escala a 0–1 dividiendo por 15 para mantener la comparabilidad con la primera. Por debajo de 0,5, la traza se une a la lista de alertas críticas.

import asyncio
from collections import defaultdict

class GradingPipeline:
    def __init__(self):
        self.scores = defaultdict(list)
        self.critical_alerts = []

    async def grade_batch(self, traces: list[dict]):
        """Puntúa un lote de trazas."""
        for trace in traces:
            # Calificación programática (rápida)
            rule_grade = grade_trace(trace)

            # Calificación con LLM para casos límite
            if rule_grade.score < 0.7:
                llm_grade = await grade_trace_llm(trace)
                final_score = (
                    llm_grade.relevance_score +
                    llm_grade.accuracy_score +
                    llm_grade.tone_score
                ) / 15.0  # Normalizar a 0-1
            else:
                final_score = rule_grade.score

            self.scores["global"].append(final_score)

            # Alertas
            if final_score < 0.5:
                self.critical_alerts.append({
                    "trace_id": trace["trace_id"],
                    "score": final_score,
                    "alerts": rule_grade.alerts,
                })

    def report(self):
        """Genera un informe de calidad."""
        scores = self.scores["global"]
        if not scores:
            return "No se han evaluado trazas."

        import statistics
        return {
            "num_traces": len(scores),
            "avg_score": statistics.mean(scores),
            "median_score": statistics.median(scores),
            "min_score": min(scores),
            "pct_critical": len(self.critical_alerts) / len(scores),
            "critical_alerts": self.critical_alerts[:10],
        }

# Uso
pipeline = GradingPipeline()
await pipeline.grade_batch(traces_of_the_day)
print(pipeline.report())

El informe mantiene la puntuación mínima y una muestra de las diez peores trazas: ahí es donde comienza una investigación, nunca con la media.

Panel de calidad

Una única puntuación no significa nada; lo que informa es su trayectoria. Al escribir el informe diario en un archivo JSONL, construyes una serie temporal que cualquier herramienta de visualización puede leer, y puedes comparar automáticamente el último punto con el anterior. Una caída de más de 0,1 desencadena una alerta de regresión, y correlacionarla con los despliegues del día suele señalar al culpable en minutos.

import json
from datetime import datetime

def log_metrics(report: dict, file: str = "agent_metrics.jsonl"):
    """Registra métricas diarias."""
    entry = {
        "date": datetime.now().isoformat(),
        **report,
    }
    with open(file, "a") as f:
        f.write(json.dumps(entry) + "\n")

def detect_regression(recent_metrics: list[dict], threshold: float = 0.1):
    """Detecta una caída significativa de la calidad."""
    if len(recent_metrics) < 2:
        return False
    latest = recent_metrics[-1]["avg_score"]
    previous = recent_metrics[-2]["avg_score"]
    drop = previous - latest
    if drop > threshold:
        print(f"REGRESIÓN DETECTADA: la puntuación cayó de {previous:.2f} a {latest:.2f}")
        return True
    return False

Comparar dos días consecutivos sigue siendo sensible al ruido: con bajo volumen, es preferible usar una media móvil antes de gritar a la regresión, o perseguirás una fluctuación estadística.

Puntos clave

  • La calificación de trazas puntúa automáticamente cada ejecución de tu agente
  • Las reglas programáticas (latencia, errores, longitud) son rápidas y fiables
  • La calificación con LLM evalúa la relevancia, la precisión y el tono
  • Combina ambos: reglas rápidas para filtrar, LLM para casos límite
  • Rastrea las puntuaciones a lo largo del tiempo para detectar regresiones
  • Las alertas críticas (puntuación < 0,5) deben desencadenar una investigación