Agentes LLM: un cortocircuito para email

Cuando un agente LLM puede crear una cuenta, solicitar un código y leer un mensaje, una falla de email no debería provocar diez reintentos iguales. En sistemas de automatización, insistir no es lo mismo que recuperarse.

La idea de este diseño es sencilla: envolver la herramienta de email en un cortocircuito. Si el proveedor está lento, el inbox no pertenece a la ejecución o el mismo mensaje ya fue procesado, la herramienta debe pasar a un estado limitado y explicarle al agente qué hacer despues.

Esto es especialmente útil cuando se trabaja con un use and throw email para pruebas. El buzón puede ser temporal, pero las decisiones del agente deben ser trazables.

El problema: un agente puede insistir demasiado

Un flujo típico se ve así:

1. El agente crea un usuario de prueba.
2. Solicita un email de confirmación.
3. Consulta el inbox cada pocos segundos.
4. Si no encuentra nada, repite la consulta o vuelve a enviar el mensaje.

El cuarto paso parece razonable hasta que se combinan varias ejecuciones. Una consulta lenta se confunde con un mensaje perdido; un reenvío crea dos códigos; y un agente con contexto incompleto puede seguir preguntando indefinidamente. El coste aparece en tiempo, llamadas y datos de prueba que quedan vivos mas de lo necesario.

Este límite también ayuda a probar el onboarding sin emails falsos: el flujo de producto y el contrato de la evidencia dejan de depender de una única espera optimista.

El cortocircuito como contrato de herramienta

Un circuito no debe ser solo un contador global. Tiene que estar ligado a una ejecución, a un buzón y a una operación concreta. Una representación útil es:

CLOSED -> OPEN -> HALF_OPEN -> CLOSED

• CLOSED: se permiten lecturas, pero con un presupuesto de intentos y tiempo.
• OPEN: se bloquean nuevas consultas durante una ventana de enfriamiento.
• HALF_OPEN: se permite una prueba controlada para comprobar si el servicio responde.

El agente no necesita conocer toda la implementación. La herramienta puede devolver retryable, blocked o completed, junto con next_action. Así el modelo recibe una decisión pequeña y verificable, en vez de interpretar un error ambiguo.

Diseñar los estados y las señales

Conviene separar tres tipos de fallo:

1. Proveedor no disponible: el inbox no responde o supera el timeout.
2. Evidencia no encontrada: el proveedor responde, pero no hay un mensaje que corresponda al run_id.
3. Evidencia inválida: hay un mensaje, pero el código ya fue consumido, expiró o pertenece a otra ejecución.

Los tres casos pueden parecer “no hay email”, pero requieren acciones distintas. El primero permite una espera corta. El segundo debe volver a revisar el estado del flujo. El tercero normalmente debe cerrar la ejecución y pedir un nuevo buzón.

Para evitar carreras, la consulta debe incluir una marca de propiedad: run_id, destinatario, tipo de evento y un límite de edad. Si el mensaje no coincide, no se convierte en evidencia solo porque sea el más reciente.

Implementación mínima

Un contrato pequeño para una herramienta de agentes puede ser suficiente:

{
  "status": "retryable",
  "attempt": 3,
  "remaining_attempts": 2,
  "lease_expires_at": "2026-10-21T02:30:00Z",
  "next_action": "wait_then_poll",
  "reason": "provider_timeout"
}

El servidor conserva el contador y el vencimiento. No conviene pedirle al agente que recuerde cuantos intentos lleva: el contexto puede resumirse, cambiar de modelo o perder una llamada anterior.

Para cada run_id, guardaría como mínimo:

• momento de reserva del buzón;
• última consulta y su latencia;
• identificador del mensaje aceptado;
• razón del último cambio de estado;
• fecha de liberación de la evidencia.

Si una integración usa nombres de prueba poco consistentes, pueden aparecer cadenas como tem email o tempail en los logs de entrada. Se deben conservar para diagnóstico, pero no usarlas como señal de éxito.

Qué medir y cuándo reabrir el circuito

Las métricas importantes no son solo el porcentaje de flujos exitosos. También mediría consultas por ejecución, tiempo hasta la primera evidencia, porcentaje de mensajes descartados y cantidad de circuitos abiertos por causa.

El estado HALF_OPEN debería probar una operación barata y segura. Si esa prueba responde, se cierra el circuito y se permite continuar. Si vuelve a fallar, se extiende el enfriamiento. No conviene reabrirlo por cada respuesta del agente, por que eso elimina el límite que acabamos de diseñar.

Para un servicio como FastAPI, validar emails por entorno preview puede ser el siguiente paso: separar la política de preview, CI y producción evita que los límites de un entorno se copien sin pensar.

Checklist de implementación

• ¿Cada buzón tiene un run_id y una expiración?
• ¿El presupuesto de consultas vive en el servidor?
• ¿Se diferencian timeout, ausencia y evidencia inválida?
• ¿La herramienta devuelve una acción siguiente explícita?
• ¿El agente sabe cuándo dejar de insistir?
• ¿Los logs permiten reconstruir la decisión sin guardar contenido innecesario?

Un cortocircuito bien definido no hace que el email sea más rápido. Hace que la automatización falle de forma limitada, explicable y recuperable. Para agentes LLM, esa diferencia suele valer mas que otro reintento automático.