Evaluación de la Calidad de Agentes: Una Lista de Verificación para la Preparación de Producción

Una lista de verificación para puntuar la tasa de éxito de tareas, el costo y los modos de fallo de un sistema de agente orquestado antes de que llegue a producción. Este no es un marco general de evaluación de LLM: se centra específicamente en las cosas que fallan en un sistema multiagente, como un subagente que produce un resultado plausible pero incorrecto, un paso de fusión que pierde información o un enrutador que clasifica mal una tarea.

Cómo Usar Esta Lista de Verificación

• Recorre la lista antes del primer lanzamiento a producción, y de nuevo antes de cualquier cambio en un prompt, configuración de subagente o lógica de enrutamiento.
• Para cada elemento, registra la métrica o el artefacto que produce (una puntuación, un registro, un umbral) para que el próximo revisor no comience desde cero.
• Trata el nivel "Go/No-Go" como una puerta de control: no envíes más allá de él basándote solo en el juicio.
• Vuelve a ejecutar toda la lista de verificación, no solo la parte modificada, cada vez que cambie el prompt de un subagente o su acceso a herramientas. Los sistemas multiagente fallan de maneras que no permanecen locales a la pieza que tocaste.

Construcción del Conjunto de Evaluación

1. Tasa de éxito de tareas en un conjunto de evaluación fijo: puntúa contra un conjunto curado de tareas representativas, no comprobaciones puntuales ad hoc.

   • Ad hoc: ejecutar el agente en lo que se te ocurra ese día y observar la salida.
   • Conjunto de evaluación fijo: 30-100+ tareas representativas con una respuesta "correcta" definida o criterios de aceptación, ejecutadas de la misma manera cada vez.
   • Un conjunto fijo es lo que hace que una puntuación sea comparable entre ejecuciones; las comprobaciones ad hoc solo te informan sobre las entradas de hoy.

2. Cubre casos extremos y entradas adversarias en el conjunto de evaluación, no solo el camino feliz. Incluye entradas mal formadas, solicitudes ambiguas que podrían enrutarse de dos maneras y entradas diseñadas para activar el punto ciego de un subagente.

   • Los conjuntos de evaluación que solo cubren el camino feliz exageran sistemáticamente la calidad, porque el tráfico de producción nunca es solo el camino feliz.
   • Extrae casos extremos reales de cualquier QA manual existente, tickets de soporte o uso beta temprano en lugar de inventarlos desde cero.

3. Define los criterios de aprobación/fallo por tarea antes de ejecutar la evaluación, no después. Escribe los criterios de aceptación en el propio conjunto de evaluación (campos esperados, hechos requeridos, frases prohibidas) para que la puntuación no varíe según quién lea la transcripción ese día.

   • Los criterios escritos después del hecho tienden a inclinarse hacia lo que sea que el modelo produjo realmente.
   • Una rúbrica con 3-5 comprobaciones concretas por tarea puntúa de manera más consistente que una única decisión de "¿fue esto bueno?".

4. Automatiza la puntuación siempre que sea posible, y utiliza una segunda llamada a Claude como juez LLM para el resto. Las comprobaciones deterministas (validación de esquemas, presencia de campos requeridos, hechos de coincidencia exacta) nunca deben depender de un humano que lea transcripciones.

   import asyncio
   from claude_agent_sdk import query
    
   async def judge_result(task: str, expected: str, actual: str) -> bool:
       prompt = (
           f"Tarea: {task}\nEsperado: {expected}\nResultado real: {actual}\n\n"
           "¿El resultado real satisface la tarea, permitiendo diferencias de redacción "
           "pero no hechos faltantes o incorrectos? Responde solo 'pass' o 'fail'."
       )
       verdict = ""
       async for message in query(prompt=prompt):
           if message.get("type") == "text":
               verdict += message["text"]
       return "pass" in verdict.lower()

   • Un juez LLM es más rápido que un revisor humano y más consistente que "¿esto parece correcto?", pero no es gratuito: presupuesta su propio costo de tokens y audita periódicamente sus veredictos contra una muestra humana.
   • Reserva la revisión humana para las categorías del punto 10, no para todo el conjunto de evaluación.

Medición de Costo y Latencia

5. Costo por tarea, incluida la sobrecarga de delegación, no solo la llamada final al modelo. Una sola tarea orquestada puede gastar tokens en la llamada de clasificación del enrutador, el contexto propio de cada subagente y un paso de fusión que relee la salida de cada subagente.

   • Suma el uso de tokens de cada llamada query() para una tarea de extremo a extremo, no solo la respuesta de nivel superior que ve el usuario.
   • Una tarea que "cuesta $0.02" contando solo la respuesta final puede costar en realidad $0.11 una vez incluida la sobrecarga de delegación; esa diferencia es el número que importa para una decisión de precios o márgenes.

6. Compara el costo por tarea entre niveles de modelos antes de usar por defecto el modelo más capaz en todas partes. Ejecuta el mismo conjunto de evaluación con un subagente más económico (Claude Haiku 4.5) en lugar de uno más caro (Claude Sonnet 5 o Claude Opus 4.8) en tareas que no necesitan la capacidad adicional.

   • Enrutar sub-tareas sencillas (clasificación, extracción, formato) a un modelo más económico suele ser la mayor palanca de costos en un sistema multiagente.
   • No rebajes el modelo de un subagente sin volver a ejecutar el conjunto de evaluación contra él; un modelo más económico puede aprobar en el camino feliz y fallar en los casos extremos que añadiste en el punto 2.

7. Latencia y tiempo de reloj de pared por tarea, no solo por llamada al modelo. Las cadenas secuenciales de subagentes se suman: tres subagentes a 4 segundos cada uno más un paso de fusión suman una tarea de 15+ segundos, incluso si ninguna llamada individual es lenta.

   • Mide el tiempo total de reloj de pared en el conjunto de evaluación, incluidas las reintentos.
   • Si la latencia es visible para el usuario, decide de antemano si las subtareas independientes deben ejecutarse en paralelo (ver el patrón de abanico en Conceptos básicos de orquestación de agentes) en lugar de descubrir el costo serial en producción.

8. Rastrea el crecimiento del uso de tokens a medida que aumenta la complejidad de la conversación o la tarea. Un subagente que funciona bien en una tarea corta puede superar su presupuesto de contexto en una más larga, truncando silenciosamente las instrucciones anteriores.

   • Incluye al menos algunas tareas de larga duración o de varios pasos en el conjunto de evaluación específicamente para detectar esto.
   • Un número de costo o latencia que solo proviene de tareas de evaluación cortas no predecirá lo que sucede una vez que el uso real incluya sesiones más largas.

Nombramiento de Modos de Fallo

9. Crea una taxonomía de modos de fallo: nombra lo que se rompió específicamente, no solo "falló". Como mínimo, rastrea estas categorías por separado, porque cada una tiene una solución diferente:

   Modo de fallo	Qué parece	Solución típica
   Resultado de subagente plausible pero incorrecto	El subagente devuelve una respuesta segura y bien formateada que es factualmente incorrecta	Añade criterios de verificación de hechos al conjunto de evaluación; considera un subagente de verificación
   Paso de fusión perdiendo información	El orquestador combina las salidas de los subagentes pero omite un detalle que uno de ellos devolvió	Registra el resultado crudo de cada subagente junto con la salida fusionada; prueba el paso de fusión de forma aislada
   Mala clasificación del enrutador	La tarea se envía al subagente incorrecto (informe de error enviado al clasificador de funciones, o viceversa)	Añade casos de enrutamiento ambiguo al conjunto de evaluación; registra la decisión de enrutamiento por separado del resultado final
   Fallo de llamada a herramienta	La llamada a una herramienta de un subagente falla (argumentos incorrectos, permisos, dependencia inestable) y el orquestador no se da cuenta	Envuelve las llamadas a herramientas con lógica de reintento y disyuntor (ver Estrategias de Recuperación de Errores y Reintentos en Bucles de Agente)
   Delegación descontrolada	Un subagente genera subagentes adicionales más allá de la profundidad prevista, inflando el costo y la latencia	Limita explícitamente la profundidad de delegación en SubagentConfig, no confíes en que el modelo se auto limite

   • Un contador de "fallos" genérico te dice que algo está mal; una taxonomía te dice qué arreglar y aproximadamente qué tan urgente es.
   • Etiqueta cada tarea de evaluación fallida con una de estas categorías (o una específica del proyecto) para que la taxonomía siga siendo un artefacto vivo, no una lista única.

10. Muestra revisión humana de un porcentaje fijo de salidas de producción, no solo de salidas del conjunto de evaluación. Un conjunto de evaluación, por bueno que sea, sigue siendo una instantánea; el tráfico de producción fluctúa.

    • Elige una tasa fija (1-5% de las tareas es un punto de partida razonable para la mayoría de las cargas de trabajo) y revisa esa muestra de forma regular, no solo cuando algo parezca roto.
    • Alimenta cualquier cosa que un revisor humano marque como incorrecta de nuevo en el conjunto de evaluación como un nuevo caso de prueba, para que el conjunto de evaluación crezca para cubrir los modos de fallo que el uso real presenta.

Pruebas de Regresión y Puertas de Lanzamiento

11. Vuelve a ejecutar todo el conjunto de evaluación antes de enviar cualquier cambio en el prompt o la configuración del subagente, no solo la parte que cambiaste. Un ajuste de prompt a un subagente puede cambiar el comportamiento de clasificación del enrutador o modificar lo que recibe el paso de fusión.

    • Compara los resultados de aprobación/fallo de la nueva ejecución con la ejecución anterior por tarea, no solo la puntuación agregada, para que una regresión en una categoría de tarea específica no se promedie.
    • Almacena los resultados de la evaluación por ejecución (marca de tiempo, versión de configuración, puntuación) para que una regresión sea rastreable al cambio que la causó.

12. Establece un umbral explícito de aprobación/rechazo antes del lanzamiento, y escríbelo. Esperar hasta que los resultados estén disponibles para decidir qué significa "suficientemente bueno" invita a mover el poste de la portería para que coincida con la puntuación que obtuviste.

    • Una barra de inicio razonable: tasa de éxito de tareas por encima de un porcentaje definido en el conjunto de evaluación, con cero fallos en cualquier categoría que hayas marcado como de alta gravedad (pérdida de datos, acción incorrecta tomada, salida insegura).
    • Documenta el umbral y quién es responsable de la decisión de anularlo, ya que la presión de producción eventualmente producirá un caso para enviar por debajo de la barra.

13. Monitorea la tasa de éxito de tareas, el costo y la taxonomía de fallos después del lanzamiento, no solo antes. La evaluación previa al lanzamiento te dice cómo se comporta el sistema con las entradas que pensaste; el monitoreo te dice cómo se comporta con las entradas reales de producción, que fluctúan.

    • Rastrea los mismos tres números de esta lista de verificación (tasa de éxito, costo por tarea, desglose de modos de fallo) como métricas continuas de producción, idealmente en el mismo panel utilizado para la evaluación previa al lanzamiento.
    • Alerta sobre una caída en la tasa de éxito o un pico en una categoría de fallo específica, de la misma manera que alertarías sobre una tasa de error para un servicio tradicional. Consulta Instrumentación de Bucles de Agente con Trazas OpenTelemetry para configurar esto.

Aplicación de la Lista de Verificación en Orden

• Fundación de la evaluación (1-4): construye y define el conjunto de evaluación primero. Cada número posterior depende de tener un conjunto fijo y puntuado de tareas para ejecutar.
• Costo y latencia (5-8): mide el costo real del sistema tal como está construido, incluida la sobrecarga de delegación, antes de optimizar nada.
• Taxonomía de fallos (9-10): nombra los modos de fallo con la precisión suficiente para que una solución sea obvia a partir de la categoría, y mantén una muestra de revisión humana fluyendo de regreso al conjunto de evaluación.
• Control y monitoreo (11-13): convierte el conjunto de evaluación en una puerta de regresión repetible, y luego continúa midiendo los mismos números después del lanzamiento.

Trampas Comunes

• Puntuar solo el camino feliz - Un conjunto de evaluación construido a partir de tareas fáciles y obviamente correctas informará una tasa de éxito que la producción nunca iguala. Solución: siembra deliberadamente el conjunto de evaluación con casos extremos y entradas adversarias (punto 2).
• Contar solo la llamada final al modelo - La sobrecarga de delegación de enrutamiento y pasos de fusión es invisible si solo registras el uso de tokens de la respuesta de nivel superior. Solución: suma cada llamada query() dentro de una tarea (punto 5).
• Tratar "fallido" como un solo grupo - Un contador de fallos genérico no puede decirte si la solución es un cambio de prompt, una política de reintentos o una regla de enrutamiento. Solución: etiqueta cada fallo con una categoría de la taxonomía (punto 9).
• Omitir ejecuciones de regresión en cambios "pequeños" de prompt - Una edición de prompt de una línea a un subagente puede cambiar el comportamiento de clasificación de un enrutador de maneras que solo aparecen en tareas de evaluación específicas. Solución: vuelve a ejecutar todo el conjunto de evaluación, no una comprobación puntual, antes de enviar cualquier cambio de configuración (punto 11).
• Detener la evaluación en el lanzamiento - El tráfico de producción se desvía de lo que cubría el conjunto de evaluación el primer día. Solución: continúa monitoreando los mismos tres números (tasa de éxito, costo, taxonomía de fallos) después del lanzamiento, y alimenta los hallazgos de la revisión humana de nuevo al conjunto de evaluación (puntos 10 y 13).

Preguntas Frecuentes

Relacionados

• Plantilla ADR: Agente Único vs. Orquestador para un Nuevo Flujo de Trabajo - decidir si la orquestación está justificada antes de tener que evaluarla
• Orquestación de Agentes y Mejores Prácticas Multiagente - prácticas de diseño más amplias que asume esta lista de verificación
• Instrumentación de Bucles de Agente con Trazas OpenTelemetry - conectar los números de monitoreo post-lanzamiento a trazas reales
• Plantilla de Análisis de Causa Raíz para Fallos de Agente - una plantilla para investigar un fallo específico una vez que la taxonomía lo señala

Versiones de la pila: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y el SDK de Agente Claude (última versión). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.