Cómo Evaluar AI Agents en 2026: El Harness de 4 Buckets que Detecta Errores Silenciosos
Aprende a construir un harness de evaluación para AI Agents que detecta errores silenciosos. Sistema de 4 buckets, decoradores de validación y checkpoints humanos. Guía práctica con código.
El Error Silencioso de un AI Agent No lo Detecta Ningún Test Unitario
Tu agente acaba de responder con un 99% de confianza. Está seguro. Ha ejecutado la tool call, modificado la base de datos, y enviado la respuesta al cliente.
*El problema: su decisión fue catastróficamente incorrecta. *
Y ningún try-catch del mundo lo va a detectar.
Porque un AI Agent no falla como falla el software tradicional. No lanza una excepción. No devuelve un código de error. Simplemente toma una decisión errónea con la misma confianza que una correcta.
*El error silencioso — ese momento en que el agente cree firmemente haber hecho lo correcto — es el modo de fallo dominante en producción. *
Y casi todos los harnesses de evaluación siguen midiendo cobertura de código como si esto fuera Java en 2005.
Si estáis aprendiendo how to build ai agents 2026, este artículo es la primera parada antes de desplegar nada en producción.
---
Por Qué el Try-Catch Es un Error Categorial
La industria asume que evaluar un AI Agent es igual que evaluar software tradicional. Métricas de cobertura. Tests unitarios. Manejo de errores con try-catch.
*Esto es estructuralmente incorrecto. *
❌ Software tradicional: Una función falla → lanza excepción → la capturas → registras el error.
✅ AI Agent: Un agente decide incorrectamente → no lanza nada → continúa ejecutando → empeora el estado del sistema.
La diferencia no es técnica. Es ontológica.
El software tradicional falla haciendo ruido. El AI Agent falla en silencio. Y como no genera señal de error, tus métricas tradicionales de "tasa de error" subestiman drásticamente los fallos reales.
He visto agentes en producción con un 0% de errores de ejecución y un 40% de errores silenciosos. El dashboard mostraba verde. El sistema estaba ardiendo.
---
La Evidencia: Por Qué los 4 Buckets Cambian Todo
Tras años construyendo y rompiendo agents en producción — desde gestorías hasta fontaneros de emergencia — el patrón que emerge es siempre el mismo.
La recuperación de errores en AI Agents no es un tema de manejo de excepciones. Es un tema de arquitectura de clasificación.
Los decoradores de validación permiten interceptar y clasificar outputs del agente antes de que se ejecuten acciones. Funcionan como puntos de medición estructurados.
Y los checkpoints humanos no son botones de pánico. Son puntos de recolección de datos para entrenar al clasificador.
La evidencia es clara: un harness basado en clasificación de 4 buckets revela errores silenciosos que el try-catch jamás detecta. Y esos errores silenciosos son los que realmente queman el presupuesto y la confianza del cliente.
---
El Sistema de 4 Buckets para Evaluación de AI Agents
Aquí está el framework. Es modular, componible, y lo podéis implementar esta tarde.
1. Diseñar la Taxonomía de Fallos Específica para tu Dominio
Olvida las métricas genéricas. Necesitas 4 buckets con criterios semánticos, no sintácticos:
| Bucket | Definición | Señal |
|--------|-----------|-------|
| Correcto | El agente tomó la decisión óptima | Output válido + semánticamente correcto |
| Incorrecto detectable | El error es visible (JSON inválido, tool call fallida) | Excepción o validación sintáctica |
| Incorrecto silencioso | El error no es visible, pero la decisión es mala | Sin excepción, pero semánticamente erróneo |
| Ambiguo | No se puede determinar sin intervención humana | Baja confianza o colisión de criterios |
El bucket más importante es el incorrecto silencioso. Es el que no tiene señal de error. Es el que destruye sistemas sin hacer ruido.
2. Implementar Decoradores de Validación como Middleware
Cada output del agente pasa por un decorador que lo clasifica antes de ejecutar la acción. Aquí tenéis el código:
```python
from enum import Enum
from dataclasses import dataclass
from typing import Any, Callable
class OutputBucket(Enum):
CORRECT = "correcto"
DETECTABLE_ERROR = "incorrecto_detectable"
SILENT_ERROR = "incorrecto_silencioso"
AMBIGUOUS = "ambiguo"
@dataclass
class ClassifiedOutput:
raw_output: Any
bucket: OutputBucket
confidence: float
reason: str
def validation_decorator(
syntactic_validator: Callable,
semantic_validator: Callable,
domain_validator: Callable
):
def decorator(agent_fn: Callable):
def wrapper(args, *kwargs):
El agente produce su output
output = agent_fn(args, *kwargs)
Validación sintáctica: ¿es JSON válido?
if not syntactic_validator(output):
return ClassifiedOutput(
raw_output=output,
bucket=OutputBucket.DETECTABLE_ERROR,
confidence=0.0,
reason="Validación sintáctica fallida"
)
Validación semántica: ¿tiene sentido?
semantic_result = semantic_validator(output)
if not semantic_result.is_valid:
return ClassifiedOutput(
raw_output=output,
bucket=OutputBucket.SILENT_ERROR,
confidence=semantic_result.confidence,
reason=semantic_result.reason
)
Validación de dominio: ¿los valores tienen sentido en contexto?
domain_result = domain_validator(output)
if domain_result.requires_human:
return ClassifiedOutput(
raw_output=output,
bucket=OutputBucket.AMBIGUOUS,
confidence=domain_result.confidence,
reason=domain_result.reason
)
return ClassifiedOutput(
raw_output=output,
bucket=OutputBucket.CORRECT,
confidence=1.0,
reason="Todas las validaciones pasadas"
)
return wrapper
return decorator
```
Los decoradores tienen una ventaja crítica: pueden ser compuestos y jerárquicos. Un decorador sintáctico se compone con uno semántico y otro de dominio. Así el harness es modular, reutilizable y específico por tarea.
3. Integrar Checkpoints Humanos como Datos de Entrenamiento
Esta es la parte que casi todo el mundo hace mal.
Un checkpoint humano no es un botón de pánico. Es un punto de recolección de datos estructurado. Cuando el agente clasifica un output como ambiguo (bucket 4), el humano no solo decide — también etiqueta *por qué* lo consideró ambiguo.
```python
@dataclass
class HumanCheckpoint:
agent_output: ClassifiedOutput
human_decision: OutputBucket
human_reason: str
context_snapshot: dict
timestamp: float
class HumanCheckpointCollector:
def __init__(self):
self.checkpoints: list[HumanCheckpoint] = []
def request_checkpoint(self, classified: ClassifiedOutput, context: dict) -> HumanCheckpoint:
En producción, esto enviaría una notificación a un dashboard
Por ahora, simulamos la decisión humana
print(f"⚠️ CHECKPOINT HUMANO REQUERIDO")
print(f"Output: {classified.raw_output}")
print(f"Razón de ambigüedad: {classified.reason}")
print(f"Confianza del agente: {classified.confidence}")
El humano decide y etiqueta
human_decision = input("Bucket correcto (1-4): ")
human_reason = input("¿Por qué? (etiqueta para entrenamiento): ")
checkpoint = HumanCheckpoint(
agent_output=classified,
human_decision=OutputBucket(human_decision),
human_reason=human_reason,
context_snapshot=context,
timestamp=time.time()
)
self.checkpoints.append(checkpoint)
Cada checkpoint es datos de entrenamiento para reducir
la tasa de ambigüedad en futuras ejecuciones
self._send_to_training_pipeline(checkpoint)
return checkpoint
def _send_to_training_pipeline(self, checkpoint: HumanCheckpoint):
Aquí enviarías el checkpoint a tu pipeline de fine-tuning
o a tu base de datos de evaluación
pass
```
El dato recolectado en esos checkpoints sirve para mejorar el clasificador y reducir la tasa de ambigüedad. Es un bucle de mejora continua, no una muleta.
4. Construir el Dashboard de Evaluación con Dos Paneles
Tu dashboard necesita dos paneles. Uno para métricas tradicionales. Otro para métricas de agente.
Panel 1 — Métricas tradicionales:
Latencia media por decisión
Tokens consumidos
Tasa de error de ejecución (excepciones)
Panel 2 — Métricas de agente:
Distribución de buckets (porcentaje en cada uno)
Tasa de error silencioso (la métrica más importante)
Ratio de ambigüedad (idealmente decreciente)
Precisión de decisión (correcto / total)
```python
@dataclass
class EvaluationMetrics:
Métricas tradicionales
avg_latency_ms: float
total_tokens: int
execution_error_rate: float
Métricas de agente
bucket_distribution: dict[OutputBucket, float]
silent_error_rate: float
ambiguity_ratio: float
decision_accuracy: float
def compute_metrics(classifications: list[ClassifiedOutput]) -> EvaluationMetrics:
total = len(classifications)
if total == 0:
return EvaluationMetrics(0, 0, 0, {}, 0, 0, 0)
bucket_counts = {bucket: 0 for bucket in OutputBucket}
for c in classifications:
bucket_counts[c.bucket] += 1
return EvaluationMetrics(
avg_latency_ms=sum(c.latency for c in classifications) / total,
total_tokens=sum(c.tokens for c in classifications),
execution_error_rate=bucket_counts[OutputBucket.DETECTABLE_ERROR] / total,
bucket_distribution={b: count/total for b, count in bucket_counts.items()},
silent_error_rate=bucket_counts[OutputBucket.SILENT_ERROR] / total,
ambiguity_ratio=bucket_counts[OutputBucket.AMBIGUOUS] / total,
decision_accuracy=bucket_counts[OutputBucket.CORRECT] / total
)
```
5. Ejecutar Evaluaciones Ciegas Comparativas
El test definitivo. Mismo task set. Dos harnesses.
Harness A: Try-catch tradicional. Captura excepciones, registra errores, sigue adelante.
Harness B: Sistema de 4 buckets. Clasifica cada output antes de ejecutar la acción.
```python
Harness A: Try-catch tradicional
def evaluate_with_try_catch(agent, tasks):
results = []
for task in tasks:
try:
output = agent.run(task)
results.append({"task": task, "output": output, "error": None})
except Exception as e:
results.append({"task": task, "output": None, "error": str(e)})
return results
❌ Los errores silenciosos NO aparecen aquí
Harness B: Sistema de 4 buckets
def evaluate_with_buckets(agent, tasks, validator):
results = []
for task in tasks:
output = agent.run(task)
classified = validator(output)
results.append({
"task": task,
"output": output,
"bucket": classified.bucket.value,
"silent_error": classified.bucket == OutputBucket.SILENT_ERROR
})
return results
✅ Los errores silenciosos aparecen como métrica medible
```
La diferencia es abismal. El primer harness te dirá "100% tasa de éxito". El segundo te dirá "65% correcto, 20% silencioso, 10% detectable, 5% ambiguo".
Uno miente. El otro mide.
---
Objeción: "Esto es más lento y caro"
Sí. Los decoradores de validación y los checkpoints humanos añaden latencia y coste tokens.
*La pregunta no es si podéis permitiros esta latencia. Es si podéis permitiros el coste de un error silencioso no detectado. *
Un error silencioso en producción puede:
Corromper datos que cuestan días restaurar
Enviar comunicaciones incorrectas a clientes
Tomar decisiones financieras erróneas
Destruir la confianza en vuestro sistema
La latencia de evaluación es un coste asumible. Los decoradores pueden ejecutarse en paralelo o de forma asíncrona. El coste de un error silencioso no tiene reparación.
Objeción: "Los checkpoints humanos destruyen la autonomía del agente"
Esta es la objeción más común. Y la que requiere más matiz.
Los checkpoints humanos no son para cada decisión. Son solo para el bucket de ambigüedad. Idealmente, ese bucket es pequeño (menos del 10% de los outputs) y se reduce con el tiempo.
Cada checkpoint humano genera datos que entrenan al clasificador. La tasa de ambigüedad baja. El agente se vuelve progresivamente más autónomo.
*Paradójicamente, los checkpoints humanos son el camino hacia la autonomía real. * Sin ellos, el agente "autónomo" está condenado a repetir los mismos errores silenciosos sin saberlo.
---
La Metáfora Correcta: Línea de Producción, No Test Suite
En manufactura, no inspeccionas la calidad del producto final solo midiendo si la máquina se apagó o no. Eso sería try-catch.
Tienes puntos de control a lo largo de la línea. Clasificadores de defectos (aceptable/rework/scrap). Estaciones de inspección humana diseñadas como parte del proceso.
*Un harness de evaluación de AI Agents debería verse más como una línea de producción que como un test suite de pytest. *
La evaluación no es un paso previo al deploy. Es el sistema nervioso que mantiene al agente funcionando correctamente en producción.
---
Lo Que Llevarte
La industria sigue evaluando AI Agents como si fueran funciones de Java. Midiendo cobertura. Capturando excepciones. Ignorando el error más peligroso de todos.
*El error silencioso no se captura con try-catch. Se clasifica con buckets, se mide con decoradores, y se reduce con checkpoints humanos diseñados como datos de entrenamiento. *
El Sistema de 4 Buckets para Evaluación de AI Agents no es teoría. Es lo que uso en cada agente que despliego. En gestorías, en fontaneros, en plataformas legales. Y es lo que separa a los agents que sobreviven en producción de los que arden sin hacer ruido.
Si estáis aprendiendo how to build ai agents 2026, construid el harness de evaluación antes que el agente. Medid lo que importa. Clasificad antes de ejecutar.
Porque el error silencioso no avisa. Pero vosotros ya sabéis dónde mirar.
Lee el artículo completo en brianmenagomez.com
Más sobre mis servicios en brianmenagomez.com
Herramientas: Conversor IAE CNAE · Gestorias cerca de ti · Calculadora IRPF