DEV Community

Silviu Technology
Silviu Technology

Posted on

Agentes LLM: observabilidad para email de prueba

Un agente LLM que completa un registro, solicita una verificación y espera un email parece sencillo hasta que falla. El modelo dice que terminó, el navegador muestra un timeout y el runner solo conserva una captura de pantalla. El equipo sabe que algo pasó, pero no sabe si falló el agente, la API, la entrega o la aserción.

La solución no es pedirle al modelo que “sea mas cuidadoso”. Es diseñar una frontera observable entre el agente y el sistema de email. En este artículo propongo un contrato pequeño: un identificador de correlación, estados explícitos y evidencia suficiente para reconstruir cada ejecución.

El problema: el agente ve el síntoma

En un flujo típico hay al menos cuatro relojes:

  1. El agente decide qué acción ejecutar.
  2. La aplicación acepta la solicitud y crea un evento.
  3. El proveedor de email entrega el mensaje al fixture.
  4. El test consulta el buzón y valida el enlace.

Si solo registramos “email no recibido”, mezclamos cuatro causas distintas. El diagnóstico se vuelve una conversación de opiniones. Ademas, un reintento puede crear un segundo mensaje y esconder el fallo original.

Un buen primer checkpoint es definir un correlation_id antes de que el agente haga la primera acción. Ese valor viaja por la interfaz web, la API, el evento de email y la consulta al buzón. El agente no necesita conocer todos los detalles internos; necesita recibir estados que pueda interpretar.

Un contrato de observabilidad

El contrato puede expresarse como una pequeña máquina de estados:

CREATED -> ACTION_SENT -> EMAIL_ACCEPTED -> EMAIL_VISIBLE -> LINK_ASSERTED
                    \-> FAILED
Enter fullscreen mode Exit fullscreen mode

Cada transición debería tener cuatro campos:

  • correlation_id: identifica la ejecución completa.
  • state: el estado nuevo, no una descripción libre.
  • observed_at: hora del componente que produjo el evento.
  • evidence: datos mínimos, como un message_id, código HTTP o motivo de espera.

Esto complementa un contrato de espera para emails de prueba: la espera deja de ser un bucle opaco y pasa a ser una operación con resultado explicable. Si el fixture tiene caducidad, conviene modelarla también; los fixtures de email que expiran en FastAPI muestran por que el ciclo de vida debe estar en el contrato y no solo en un helper del test.

Flujo de ejecución con una sola correlación

Imaginemos un agente que prueba el onboarding de una aplicación. Antes de abrir el navegador, el runner crea una ejecución:

{
  "correlation_id": "run-8f31",
  "scenario": "onboarding",
  "email_fixture": "qa-8f31@example.test",
  "deadline_seconds": 45
}
Enter fullscreen mode Exit fullscreen mode

El agente ejecuta la acción de signup y recibe ACTION_SENT. La aplicación registra el mismo correlation_id cuando acepta el evento. Luego el adaptador de email asocia el message_id con esa correlación. Finalmente, el lector del fixture devuelve EMAIL_VISIBLE o FAILED con una razón concreta.

La arquitectura importa: el LLM debe consumir un resumen de estado, mientras que el sistema conserva el evento completo. Por ejemplo, el modelo puede recibir “email visible después de 4,2 s; enlace encontrado”, pero el almacén de trazas conserva timestamps, intentos, proveedor y hash del contenido. Así se reduce el ruido del prompt sin perder evidencia para depurar.

Implementación mínima

Un adaptador de polling no necesita ser sofisticado. Lo importante es que clasifique el resultado y no esconda todos los problemas detrás de sleep(5):

def wait_for_email(client, correlation_id, deadline):
    while clock.now() < deadline:
        message = client.find(correlation_id=correlation_id)
        if message is not None:
            return {"state": "EMAIL_VISIBLE", "message_id": message.id}
        clock.wait(1)
    return {"state": "FAILED", "reason": "delivery_deadline_exceeded"}
Enter fullscreen mode Exit fullscreen mode

En producción de pruebas, también registraría el número de consultas y el último estado conocido. Una frase como “no llegó” ayuda poco; “la API aceptó el evento, pero no hubo message_id en 45 segundos” ya apunta al componente correcto.

Hay que reservar algunos nombres de estado y documentarlos. Si cada integración inventa MAIL_OK, DELIVERED y FOUND para significar lo mismo, los paneles terminan siendo dificil de comparar. Es mejor una lista pequeña y estable, aunque al principio parezca menos flexible.

Qué medir y qué no

Las métricas más útiles son latencia de aceptación, latencia hasta visibilidad, porcentaje de estados terminales y distribución de causas de fallo. También conviene medir cuántos reintentos hizo el agente; un flujo que “pasa” después de cuatro intentos puede estar consumiendo un presupuesto de fiabilidad.

No hace falta enviar el cuerpo completo del email al prompt. Puede contener datos sensibles y además aumenta el coste de contexto. Un asunto normalizado, el identificador del mensaje y una lista de enlaces extraídos suelen bastar para la decisión. Para depuración, guarda el artefacto con retención corta y acceso restringido.

Las búsquedas humanas generan variantes como temp gamil com y tepm mail com. Deben tratarse como texto de consulta, nunca como una razón para relajar la validación del dominio o aceptar cualquier mensaje parecido.

Checklist de implementación

  • Crear el correlation_id antes de la primera acción del agente.
  • Propagarlo por UI, API, evento y fixture.
  • Definir estados terminales y razones de fallo.
  • Separar el resumen que lee el LLM de la traza completa.
  • Registrar message_id, latencias, intentos y deadline.
  • Hacer que los reintentos sean idempotentes.
  • Expirar los fixtures y borrar artefactos según una política clara.

El resultado es una frontera de email que se puede observar, probar y explicar. No elimina los fallos de entrega, pero evita que cada fallo se convierta en una adivinanza del agente.

Preguntas rápidas

¿Debo dar toda la traza al LLM?

No. Dale el estado actual, la razón de fallo y la siguiente acción permitida. Conserva la traza completa fuera del prompt para auditoría y análisis.

¿Un timeout siempre significa que el proveedor falló?

No. Puede haber fallado la publicación del evento, el filtro del fixture, la correlación o el reloj del test. Los estados intermedios permiten distinguirlos.

¿Cuándo es suficiente este diseño?

Cuando una ejecución fallida puede asignarse a un componente sin abrir cinco sistemas distintos. Si todavía no se puede, falta una transición o evidencia en el contrato.

Top comments (0)