Contratos de email para agentes LLM

Cuando un agente LLM dispara correos, el prompt suele llevarse toda la atención. En la práctica, el punto fragil casi siempre está en otro sitio: la frontera entre la decisión del agente y el ejecutor que realmente envía el mensaje. Si ese borde es ambiguo, aparecen bugs raros, retries confusos y una trazabilidad que se deshace cuando más la necesitas.

Llevo un tiempo viendo el mismo patrón en automatización interna: el equipo describe muy bien la intención, pero el comando final llega medio abierto. Entonces el agente "parece listo" en demo, pero operar el sistema se vuelve cansado. Para mí, la mejora más rentable no fue un prompt más largo. Fue diseñar un contrato de email pequeño, versionado y muy aburrido. Aburrido en el buen sentido.

Donde suelen romperse los agentes que envían correo

Pienso en el flujo como un diagrama en palabras: evento, contexto reducido, decisión del agente, contrato de acción, ejecutor determinista y verificación. Si una capa interpreta demasiado a la otra, ya tienes un hueco de diseño.

Los sintomas que más veo son estos:

• Un mismo tipo de correo sale con campos distintos según el prompt.
• El ejecutor acepta payloads medio inventados "por flexibilidad".
• Las pruebas leen cualquier inbox compartida y creen que validaron algo.
• Nadie puede responder rápido si el error vino del agente, de la plantilla o del worker.

Ese último punto pesa mucho. Según el reporte DORA 2024, los equipos con ciclos de feedback más claros y mejor calidad operativa entregan cambios con menos fricción y mejor estabilidad, no solo con más velocidad source. En sistemas con IA, eso también aplica al correo transaccional.

El contrato que me dio menos incidentes

El patrón que mejor me funcionó fue cerrar la acción en un payload versionado. El agente no "redacta instrucciones para mandar un correo". Elige una acción válida. El ejecutor solo valida y materializa.

Mi contrato mínimo suele incluir:

• action_type
• action_version
• template_id
• recipient_scope
• trace_id
• safety_checks

Ejemplo simple:

{
  "action_type": "send_trial_reactivation",
  "action_version": "v2",
  "template_id": "trial_reactivation_v4",
  "recipient_scope": "single_user",
  "trace_id": "run_7b31",
  "safety_checks": ["tenant_match", "cooldown_ok"]
}

La ventaja es muy concreta. Si algo falla, no reconstruyes una novela de intención. Comparas el contrato emitido con el correo real y con las validaciones del worker. Esa diferencia parece menor, pero cambia por completo el tiempo de debug.

También ayuda a mantener ordenados los aliases y los fixtures. En muchos equipos se cuelan textos como dummy e mail o tem email en seeds, tickets o notas de QA. No rompen el sistema por si solos, pero sí delatan que el borde operativo está un poco flojo. Si el contrato es estricto, esas rarezas quedan en datos de prueba y no se filtran al motor de ejecución.

Cómo probarlo sin mezclar evidencia

El contrato por sí solo no basta. Hace falta una verificación que no reuse una inbox compartida ni mezcle corridas. Ahí me sirve mucho usar un trace_id único por escenario y registrar el payload normalizado antes del envío.

Mi secuencia favorita es esta:

1. El evento genera contexto mínimo y seguro.
2. El agente elige una acción y versión concretas.
3. El ejecutor rechaza campos de más y valida permisos.
4. El envío persiste trace_id, template_id y destino lógico.
5. La prueba consulta una inbox aislada y compara contenido con el contrato.

Ese enfoque se parece bastante a los checks de correo en ventanas de mantenimiento, donde la señal mejora mucho cuando cada revisión conserva su propia evidencia. También conecta con validar correos de reactivación sin mezclar cohortes: si mezclas usuarios, retries y campañas, la lectura del resultado se vuelve peor y peor.

Cuando necesito una bandeja efímera para pruebas de bajo riesgo, un servicio tipo temp mail so puede encajar bien como apoyo puntual. No reemplaza los contratos ni la observabilidad, pero reduce ruido cuando solo quieres comprobar que la acción correcta produjo el mensaje correcto.

Tradeoffs reales del enfoque

Sí, este diseño mete más estructura. Hay más ids, más rechazos tempranos y menos libertad para "resolverlo sobre la marcha". Para mí, ese coste vale la pena.

• Pierdes algo de flexibilidad textual, pero ganas auditoría.
• Añades disciplina al payload, pero eliminas clases enteras de bugs.
• Las pruebas exigen más preparación, pero luego mienten menos.
• La demo se ve un poco menos magica, aunque la operación diaria mejora bastante.

Si tuviera que dejar un checklist corto para empezar hoy, sería este:

• Toda acción de correo tiene tipo y versión.
• El ejecutor rechaza campos ambiguos o sobrantes.
• Cada escenario guarda un trace_id estable.
• La prueba valida efecto de negocio, no solo "se envió".
• La evidencia del run queda separada por entorno y por caso.

No hace falta una plataforma enorme. Hace falta que el borde entre agente y herramienta sea legible, estable y facil de revisar cuando algo sale mal. Es un cambio pequeño en diseño, pero se nota un monton en operación real.

Preguntas rápidas

¿Cuándo subo la versión de una acción?

Cuando cambia la semántica del comando, sus validaciones o la shape del payload. Si solo cambias copy menor, quizá no hace falta.

¿Esto sirve si uso otro proveedor de inbox de pruebas?

Sí. Lo importante no es la marca del proveedor. Es el aislamiento por escenario y la capacidad de consultar evidencia de forma determinista.

¿Y si el agente necesita más libertad?

Dásela antes del contrato, no en el ejecutor. El agente puede elegir entre acciones válidas, pero el borde de ejecución conviene que sea estable. Parece menos cool, pero opera bastante mejor.