Evaluaciones de agentes y habilidades en la práctica: trayectorias, calificadores, pass^k y herramientas

Tarde o temprano, todo equipo que utiliza agentes y habilidades se topa con un mismo problema: la demostración es impresionante, pero el tráfico real revela fallos que nadie había notado. Las evaluaciones reemplazan las conjeturas por mediciones. A continuación se presenta una guía práctica sobre qué medir, cómo redactar casos y evaluadores, y cómo implementar un ciclo de mejora que haga que un agente sea realmente mejor.

El modelo mental

Una evaluación es un experimento reproducible. Proporcione a un agente una entrada y un entorno, y luego observe dos cosas: la trayectoria, es decir, lo que hizo el agente a lo largo del proceso, y el resultado, es decir, el producto final que generó.

Evalúe ambos aspectos:

• Resultado: ¿el producto final cumple con la tarea?
• Trayectoria: ¿el agente eligió las habilidades y herramientas adecuadas, evitó acciones peligrosas y trabajó de manera eficiente?

Una respuesta final impecable puede ocultar una trayectoria deficiente, y una trayectoria torpe aún puede llegar a un resultado aceptable. Analizar solo uno de ellos no revela toda la historia.

Las capas de evaluación

Ningún número único indica si un agente es bueno. Divida la pregunta en capas, cada una con su propia verificación:

• Enrutamiento de habilidades. ¿Se eligió la habilidad adecuada? Observe la precisión, el recuerdo y los disparos falsos.
• Adherencia a las habilidades. ¿Se siguieron realmente las instrucciones de la habilidad, incluidos los pasos requeridos y las acciones prohibidas?
• Uso de herramientas. ¿Se llamaron las herramientas correctamente, con argumentos apropiados, un orden lógico y sin llamadas innecesarias?
• Resultado de la tarea. ¿Funciona el resultado? Las pruebas, las verificaciones de esquema y las afirmaciones de comportamiento responden a esta pregunta.

Calidad. ¿Es el resultado mantenible y adecuado? Lo decide una rúbrica o un revisor.

Seguridad. ¿Se respetaron los límites en relación con los secretos, las operaciones destructivas e la inyección de comandos?

Eficiencia. ¿Cuál fue el costo del éxito en términos de tokens, latencia, llamadas y reintentos?

Una habilidad necesita dos conjuntos de evaluación

Una habilidad es más que un bloque de instrucciones. Encarna una decisión sobre cuándo activarse y un plan para lo que hacer después, por lo que necesita dos conjuntos separados de evaluación.

Evaluaciones de desencadenamiento verifican si la habilidad se activa con los prompts adecuados. Cada caso combina un prompt con la habilidad esperada, o con una habilidad que no debe activarse:

- prompt: "Patch the vulnerable npm dependencies"
  expected_skill: cve-remediation
- prompt: "Review authentication input validation"
  forbidden_skill: cve-remediation

Occulte los aspectos positivos obvios, reformule las afirmaciones positivas, presente los negativos que estuvieron cerca de ser detectados, los prompts ambiguos y los conflictos entre dos habilidades plausibles. Informe una matriz de confusión en lugar de la precisión simple, ya que un falso positivo puede causar tanto daño como un caso no detectado.

Evaluaciones de ejecución comprueban si el uso de la habilidad mejora el trabajo. Compare un agente que carece de dicha habilidad con el mismo agente equipado con ella, utilizando casos, entorno, modelo y herramientas idénticos, y repita las pruebas debido a que los agentes son no deterministas. Una habilidad solo merece su lugar cuando la mejora justifica su complejidad adicional y su costo en tokens.

Qué aspecto tiene un buen caso

Prefiera instantáneas realistas del repositorio sobre datos aislados y triviales. Un buen caso es autónomo y puede ser verificado por una máquina:

{
  "id": "fix-null-condition",
  "prompt": "Fix saving rules with a null condition",
  "fixture": "repos/null-condition",
  "setup": ["npm install"],
  "checks": [
    "npm test -- null-condition.test.js",
    "git diff --check"
  ],
  "rubric": [
    "Fixes the root cause",
    "Preserves existing behavior",
    "Adds a regression test",
    "Avoids unrelated changes"
  ],
  "forbidden": [
    "deleting existing tests",
    "hard-coded fixture-specific output"
  ]
}

Evaluadores: utilice el más potente que tenga

Prefiera el evaluador más determinista disponible, y recurra al juicio humano solo cuando sea necesario. Aproximadamente de más potente a menos potente:

1. afirmaciones exactas
2. compilación y pruebas unitarias o de integración
3. validación de esquemas o árboles sintácticos
4. verificaciones de comportamiento a través de un navegador o API
5. inspección estática de la trayectoria
6. un LLM que evalúa según una rúbrica
7. revisión humana

Los evaluadores basados en LLM son adecuados para criterios como la claridad y la adecuación arquitectónica, pero no deben sustituir a las verificaciones ejecutables. Oculte al evaluador qué variante generó un resultado y cambie el orden de las comparaciones.

Métricas que vale la pena seguir

• Tasa de éxito es la proporción de ejecuciones que superan todas las verificaciones críticas.
• Pass@k es la probabilidad de que al menos uno de los k intentos tenga éxito.
• Pass^k es la probabilidad de que todos los k intentos tengan éxito, lo cual representa la señal más fiable de fiabilidad.
• Precisión y recuerdo en el enrutamiento describen la calidad de la selección de habilidades.
• Tasa de regresión cuenta los casos que antes pasaban las pruebas pero ahora fallan.
• El costo por tarea completada con éxito, la latencia media y en los extremos, el número de llamadas a herramientas, las tasas de reintentos y la frecuencia con la que fue necesario intervenir un humano también deben incluirse en el panel de control.

Para los agentes de producción, una fiabilidad constante suele ser mejor que resultados impresionantes en los casos óptimos.

Construcción del conjunto de datos

Comience con 20 a 50 casos extraídos de trabajos reales: fallas anteriores e incidentes de soporte, tareas cotidianas, casos límite, solicitudes engañosas o hostiles, instrucciones insuficientemente detalladas, tareas que deberían ser rechazadas o aclaradas, y situaciones en las que ninguna habilidad debería activarse.

Luego divídalos en tres conjuntos:

• un conjunto de desarrollo que puede consultar mientras mejora la habilidad
• un conjunto reservado que se deja sin tocar hasta la validación
• un conjunto de regresión al que se le asignan permanentemente todas las fallas que descubra

Evite optimizar únicamente con un conjunto público fijo, ya que los agentes se sobreajustan rápidamente a su redacción.

Un ciclo de trabajo

Considérelo como un desarrollo orientado a pruebas para el comportamiento de los agentes:

1. Capte una falla real.
2. Redúzcala a un caso de prueba reproducible.
3. Escriba la evaluación antes de tocar la habilidad o el agente.
4. Ejecute varios ensayos de referencia.
5. Realice un cambio específico.
6. Vuelva a ejecutar el caso objetivo junto con todo el conjunto de pruebas de regresión.
7. Compare la calidad, fiabilidad, latencia y costo.
8. Mantenga el cambio solo si mejora el equilibrio general.

Errores comunes

• Evaluar únicamente el texto final
• Usar solo prompts de camino óptimo
• Verificar si las instrucciones se repitieron en lugar de seguirse
• Preguntar a un juez basado en LLM sobre hechos que una prueba podría verificar
• Ejecutar una sola vez y considerar el resultado como determinista
• Cambiar el prompt, el modelo, las herramientas y la habilidad al mismo tiempo
• Aceptar pruebas eliminadas o manipular la evaluadora como si fuera un éxito
• Usar casos sintéticos que no se parecen en nada al trabajo real de los usuarios
• Ignorar la inyección de comandos oculta en archivos o en la salida de herramientas

Métricas de enrutamiento en términos concretos

Supongamos que existe una habilidad de revisión de seguridad y que un evaluador decide, para cada comando, si debe activarse. Hay cuatro resultados posibles:

• Positivo verdadero (TP): debería activarse y lo hizo.
• Positivo falso (FP): no debería haberse activado pero lo hizo, es decir, una activación falsa.
• Negativo falso (FN): debería haberse activado pero no lo hizo.
• Negativo verdadero (TN): no debería haberse activado y no lo hizo.

Precisión indica con qué frecuencia la activación fue correcta: TP dividido entre (TP + FP). Si la habilidad se activó diez veces y ocho de ellas fueron correctas, la precisión es del 80 %. Una alta precisión significa pocas activaciones falsas.

Recuperación indica cuántos de los prompts que necesitaban esa habilidad realmente fueron detectados: TP dividido entre (TP + FN). Si diez prompts la necesitaban y siete fueron detectados, la recuperación es del 70 %.

Un disparo falso es simplemente un falso positivo. Un prompt como “Actualizar dependencias de React” que invoca erróneamente la revisión de seguridad es un ejemplo. Muchos disparos falsos significan baja precisión.

Una matriz de confusión registra todo. Con TP = 8, FN = 2, FP = 3 y TN = 7, los prompts que deberían activarse se dividen en 8 y 2, mientras que los que no deberían activarse se dividen en 3 y 7. La precisión es 8 / 11, aproximadamente el 72,7 %, y la recuperación es 8 / 10, es decir, el 80 %. Una alta precisión significa que la habilidad rara vez se activa por error. Una alta recuperación significa que rara vez pasa por alto una solicitud relevante. Una redacción amplia de los desencadenantes suele aumentar la recuperación y disminuir la precisión.

Por dónde empezar

Para una habilidad importante, un kit compacto es de gran utilidad. Reúna diez estímulos que deberían activarla y diez casos cercanos a ella que no deberían hacerlo, además de cinco tareas realistas para ejecutar. Añada verificaciones de resultados deterministas, de tres a cinco repeticiones de cada tarea, una ejecución de referencia sin la habilidad, y un conjunto de pruebas de regresión que registre cada fallo que se detecte.

Una configuración tan sencilla revela la mayoría de los problemas de enrutamiento y muestra si la habilidad realmente ayuda o simplemente parece sofisticada.

Un marco mínimo que puede copiar

Suficiente teoría. Un pequeño programa en Python puro, con solo la biblioteca estándar, puede evaluar tanto el enrutamiento de una habilidad como el resultado de las tareas de un agente. Con aproximadamente 70 líneas, muestra cada idea mencionada anteriormente: archivos de casos, evaluadores en capas, ejecuciones repetidas y métricas de fiabilidad.

La estructura de carpetas:

evals/
  cases/
    skills/security-review.trigger.json
    agents/fix-null-condition.json
  graders.py
  metrics.py
  runner.py
  run.py        # CLI entry1. Case files. A skill trigger case is just positives and negatives. An agent case is a prompt plus graders and a run count.

Un archivo de caso desencadenante enumera el nombre de la habilidad junto con indicaciones sobre qué situaciones deben y no deben activarla:

// cases/skills/security-review.trigger.json
{
  "skill": "security-review",
  "positives": [
    "Audit this endpoint for SQL injection",
    "Check the login flow for auth bypasses",
    "Is this file-upload handler safe?"
  ],
  "negatives": [
    "Upgrade React dependencies",
    "Rename this variable across the repo",
    "Add a loading spinner to the form"
  ]
}

Un archivo de caso de agente contiene un ID, una instrucción, un elemento fijo y las verificaciones a aplicar:

// cases/agents/fix-null-condition.json
{
  "id": "fix-null-condition",
  "prompt": "Fix saving rules with a null condition",
  "fixture": "fixtures/null-condition",
  "setup": ["npm ci"],
  "runs": 5,
  "graders": [
    { "type": "shell", "cmd": "npm test -- null-condition", "critical": true },
    { "type": "shell", "cmd": "git diff --check" },
    { "type": "forbidden", "pattern": "it\\.skip|xit\\(", "message": "must not disable tests" }
  ]
}

A continuación están los calificadores. Uno ejecuta comandos de shell como el conjunto de pruebas, otro escanea la trayectoria en busca de ediciones que estaban prohibidas, y un modelo de evaluador que no puede ver qué variante está calificando se encarga de las cualidades subjetivas.

# graders.py
import re, subprocess
def shell(step, ctx):
    r = subprocess.run(step["cmd"], cwd=ctx.workdir, shell=True,
                       capture_output=True, text=True)
    ok = r.returncode == 0
    return {"pass": ok, "score": 1 if ok else 0, "detail": r.stdout[-400:]}
def forbidden(step, ctx):
    bad = re.search(step["pattern"], ctx.diff) is not None
    return {"pass": not bad, "score": 0 if bad else 1,
            "detail": step["message"] if bad else ""}
def judge(step, ctx):
    v = ctx.llm.rate(step["rubric"], ctx.artifact)  # 0..1, blinded
    return {"pass": v >= step.get("threshold", 0.7), "score": v}
GRADERS = {"shell": shell, "forbidden": forbidden, "judge": judge}3. Metrics. Success rate, pass@k, pass^k, and the routing confusion matrix — exactly the numbers from earlier.

El módulo de métricas convierte las listas de resultados de ejecución en números:

# metrics.py
def success_rate(rs):
    return sum(1 for r in rs if r["pass"]) / len(rs)
def pass_at_k(rs):
    return 1 if any(r["pass"] for r in rs) else 0
def pass_hat_k(rs):
    return 1 if all(r["pass"] for r in rs) else 0
def routing(positives, negatives, fired):
    tp = sum(1 for p in positives if fired(p))
    fp = sum(1 for n in negatives if fired(n))
    fn = len(positives) - tp
    tn = len(negatives) - fp
    return {"tp": tp, "fp": fp, "fn": fn, "tn": tn,
            "precision": tp / (tp + fp or 1),
            "recall": tp / (tp + fn or 1)}4. The runner. One function per suite. The agent runner repeats each case so pass^k is meaningful; the skill runner just asks the router which skills fire.

Un corredor carga las cajas, llama a los calificadores, repite cada carrera e imprime las métricas:

# runner.py
import json
from graders import GRADERS
from metrics import success_rate, pass_at_k, pass_hat_k, routing
def run_agent_case(agent, path):
    c = json.load(open(path))
    runs = []
    for _ in range(c.get("runs", 3)):
        ctx = agent.run(c["prompt"], fixture=c["fixture"], setup=c["setup"])
        ok = True
        for step in c["graders"]:
            g = GRADERS[step["type"]](step, ctx)
            if step.get("critical") and not g["pass"]:
                ok = False
        runs.append({"pass": ok})
    return {"id": c["id"], "success": success_rate(runs),
            "pass_at_k": pass_at_k(runs), "pass_hat_k": pass_hat_k(runs)}
def run_skill_trigger(router, path):
    c = json.load(open(path))
    fired = lambda prompt: c["skill"] in router.route(prompt)
    return {"skill": c["skill"], **routing(c["positives"], c["negatives"], fired)}5. Run it. The CLI just dispatches on the case type and prints the metrics.

Al ejecutarlo se obtiene una salida de este tipo:

$ python run.py cases/agents/fix-null-condition.json
fix-null-condition   success=0.80   pass@5=1.00   pass^5=0.20
$ python run.py cases/skills/security-review.trigger.json
security-review      precision=0.86  recall=1.00   (tp=6 fp=1 fn=0 tn=5)

Lea esas líneas de la manera que recomienda este enfoque completo. El agente realiza cuatro ejecuciones en cinco intentos, por lo que pass@5 parece perfecto, sin embargo pass^5 con un valor de 0.20 indica que aún no es fiable. La habilidad detecta todas las solicitudes reales, con un índice de recuperación de 1.0, pero se activó una vez cuando no debería haberlo hecho, con una precisión de 0.86; por lo tanto, hay un disparo falso que debe corregirse.

Ese es el propósito de las evaluaciones: convertir la expresión “parecía funcionar” en números que se puedan mejorar. Comience con un marco como este, añada un caso cada vez que algo falle y deje que el conjunto de regresión se desarrolle hasta convertirse en su definición operativa de lo que es bueno.

Utilice un framework existente cuando sea posible

Un marco personalizado es útil para aprender los mecanismos y para tener un control total, pero los proyectos abiertos maduros ya ofrecen ejecuciones, evaluadores, conjuntos de datos y paneles de control. Échelos un vistazo antes de crear su propio sistema.

Evaluaciones generales de prompts y LLM

OpenAI Evals es el marco original de tipo registro, que define las pruebas en formato YAML con herramientas de evaluación en Python para cualquier modelo, y es adecuado para comprobaciones a nivel de salida y de clasificación. promptfoo se basa en configuraciones, muestra los prompts frente a los modelos en una matriz lado a lado, incluye afirmaciones como “contiene”, expresiones regulares, esquemas JSON y rúbricas para LLM, además cuenta con un modo de equipo rojo, lo que lo convierte en una excelente opción para la gestión de habilidades y la detección de regresiones en los prompts. DeepEval funciona como pytest para LLMs, con métricas de fidelidad, relevancia e ilusiones, además de rúbricas G-Eval personalizadas, y se integra perfectamente en los procesos CI. Ragas está dirigido específicamente a los pipelines RAG, evaluando la precisión y recuperación del contexto, la fidelidad y la relevancia de las respuestas. La evaluación de LLM de MLflow permite el seguimiento y la comparación si ya se está utilizando MLflow.

Rastreo, conjuntos de datos y plataformas de evaluación

LangSmith ofrece conjuntos de datos, seguimiento de trayectorias y herramientas de evaluación, útiles cuando es necesario inspeccionar toda la trayectoria en lugar de solo la respuesta. Langfuse es de código abierto, se puede hospedar por uno mismo y es independiente del modelo, e incluye funciones de seguimiento, evaluación y conjuntos de datos para el monitoreo en producción. Braintrust trata las evaluaciones como parte del proceso de integración continua, con funciones de puntuación, conjuntos de datos versionados y una vista de diferencias para los experimentos. Arize Phoenix se basa en el seguimiento de OpenTelemetry e incluye plantillas de evaluación, útiles para detectar regresiones en el tráfico en tiempo real. Inspect, del UK AI Safety Institute, es un marco de resolución y puntuación cuidadosamente diseñado que va ganando terreno para evaluaciones serias de agentes y seguridad.

Pruebas de rendimiento para agentes

SWE-bench y SWE-bench Verified son el estándar para determinar si un agente puede solucionar un problema real de GitHub, utilizando las pruebas propias del repositorio como criterio de evaluación. AgentBench, WebArena, GAIA y τ-bench ofrecen métricas externas para el uso de herramientas, tareas en la web y agentes de múltiples pasos. Frameworks como AutoGen y LangGraph proporcionan ganchos de prueba para verificar las llamadas a herramientas y los pasos intermedios.

Elegir

• Para prompts y enrutamiento de habilidades únicamente, promptfoo es la forma más rápida de configurarlos además de verificarlos.
• Para métricas basadas en código y compatibles con CI, considere DeepEval o Braintrust.
• Para evaluar el desempeño de agentes de múltiples pasos, examine LangSmith, Langfuse o Inspect.
• Para RAG, añada Ragas.
• Para un benchmark real de agentes de programación, utilice SWE-bench Verified.

Este patrón se aplica en todas partes: casos de uso, herramientas de evaluación, ejecuciones repetidas y seguimiento a lo largo del tiempo. Un marco de trabajo simplifica los procesos, así que mantén la disciplina y elige la herramienta que se adapte a tu conjunto tecnológico. El arnés personalizado es lo mejor para cubrir las deficiencias que dejan esas herramientas, o para proyectos que requieren cero dependencias en CI.