Diseñar agentes LLM con contratos verificables

Un agente LLM puede parecer muy capaz durante una demostración y volverse dificil de operar cuando empieza a llamar APIs, crear tickets o consultar datos reales. El problema no suele ser que el modelo “no sepa” la respuesta. Es que el sistema no define con precisión qué puede hacer una herramienta, qué debe devolver y cuándo hay que detenerse.

En mis flujos de automatización trato cada herramienta como una frontera de software, no como una sugerencia dentro del prompt. Esa decisión cambia el diseño: el modelo decide el siguiente paso, pero un contrato verificable decide si ese paso puede ejecutarse.

El contrato es más importante que el prompt

Imagina un agente que recibe una petición de soporte y puede consultar el estado de un onboarding. El prompt puede pedirle que sea cuidadoso, pero “cuidadoso” no es una regla ejecutable. Un contrato sí puede decir:

• qué campos son obligatorios;
• qué valores tienen un formato permitido;
• qué alcance de datos puede leer la herramienta;
• cuánto tiempo puede tardar;
• qué errores son reintentables.

El flujo se puede dibujar así: usuario → agente → validador → herramienta → resultado validado → agente. El validador aparece en ambos lados de la herramienta. Si solo validamos la entrada, una API externa todavía puede devolver un objeto inesperado y contaminar el contexto del modelo.

Esto también evita decisiones ambiguas con datos de prueba. Una dirección de correo desechable puede ser válida para un entorno aislado, pero no debería pasar automáticamente a un flujo de producción o a una lista de clientes. El contrato debe conocer el entorno y rechazar la operación cuando la combinación no corresponda.

Una arquitectura mínima en cuatro capas

1. Intención estructurada

Conviene convertir la petición del usuario en una intención pequeña, con un identificador y un objetivo explícito. Por ejemplo:

{
  "intent": "review_onboarding_email",
  "account_id": "acct_123",
  "environment": "staging",
  "request_id": "req_456"
}

El modelo puede proponer estos campos, pero el servidor debe comprobarlos. Nunca conviene aceptar que el agente elija libremente un account_id sin verificar que la identidad que inició la sesión tiene acceso.

2. Catálogo de herramientas

Cada herramienta necesita una descripción corta, un esquema de entrada y un resultado tipado. También necesita una política: lectura o escritura, entorno permitido, límite de llamadas y nivel de aprobación humana. El catálogo debe ser versionado junto con el código; dejarlo solo en una configuración manual acaba generando drift.

3. Ejecutor aislado

El ejecutor recibe una llamada válida y añade contexto que el modelo no controla, como el tenant autenticado, el timeout y la traza. Así el agente no puede elevar privilegios cambiando un campo del JSON. Para acciones con efectos externos, separo “preparar” de “confirmar”, aunque el segundo paso haga el flujo un poco más largo.

4. Registro de evidencia

Cada llamada debe producir un recibo mínimo: request_id, versión de la herramienta, resultado, duración, motivo de rechazo y un hash de los parámetros sensibles. No guardaría el prompt completo por defecto. La trazabilidad útil no es acumular texto, es poder explicar por qué una acción fue permitida o bloqueada.

Para flujos de soporte, es útil estudiar cómo dejar el soporte preparado para emails de trial sin mezclar eventos de producto con conversaciones del agente.

Qué validar antes y después de cada herramienta

La validación de entrada debe comprobar tipo, rango, pertenencia al tenant y relación entre campos. Un environment de production combinado con una fixture de prueba debe fallar antes de tocar la red. También conviene limitar la longitud de texto que se entrega a una consulta, porque un agente puede repetir accidentalmente una instrucción recibida de una fuente externa.

La validación de salida debe comprobar que existen los campos esperados y que los estados forman un conjunto cerrado. Si el proveedor devuelve maybe_done, el adaptador debe traducirlo a un error controlado, no pasarlo al modelo como si fuera una verdad. Este corte es pequeño, pero evita que el agente improvise una transición que la API no soporta.

En la práctica, los errores de esquema y permisos no se reintentan. Los timeouts y algunos errores temporales sí, pero con un límite. Mezclar ambos grupos es una receta para repetir una escritura o para ocultar un bug de integración. A veces un log pone “fallo de herramienta” aunque el problema real es una respuesta incompleta del adaptador; separar las categorias acelera bastante el diagnóstico.

Reintentos, límites y trazabilidad

Un agente necesita un presupuesto de pasos. Por ejemplo, cinco llamadas de lectura y una acción de escritura por solicitud. Cuando se consume, debe explicar que necesita revisión, no buscar otra herramienta equivalente sin avisar. El presupuesto evita bucles de planificación que parecen razonables por separado y son caros en conjunto.

Para reintentos de escritura usa una clave idempotente basada en request_id y en la operación normalizada. La herramienta debe devolver el mismo resultado lógico si recibe dos veces la misma clave. Para una verificación de email, esto puede impedir que un reintento cree dos tokens o dos notificaciones.

También separaría tres tiempos en la evidencia: cuando el agente decidió, cuando el ejecutor aceptó y cuando el proveedor confirmó. Si el flujo se degrada, un runbook para investigar emails lentos ayuda a no confundir la latencia de la aplicación con la de entrega.

Preguntas frecuentes

¿Un contrato vuelve determinista a un agente?

No. Reduce el espacio de acciones inválidas y hace observables las decisiones, pero el modelo aún puede elegir una herramienta poco útil. Por eso hacen falta presupuestos, pruebas de regresión y una ruta de revisión humana.

¿Debo poner todos los detalles de seguridad en el prompt?

No. El prompt puede orientar, pero autenticación, autorización, límites y validación deben vivir en código o en políticas verificables. Si una regla importa, debe poder fallar de forma explícita.

¿Qué pruebo primero?

Empieza con casos de frontera: tenant incorrecto, timeout, respuesta parcial, doble reintento y cambio de versión del esquema. Son más informativos que una demo feliz con una sola llamada.

Checklist de implementación

• ¿Cada herramienta tiene entrada y salida versionadas?
• ¿El ejecutor añade identidad y entorno fuera del control del modelo?
• ¿Se distinguen errores reintentables de errores de contrato?
• ¿Existe un presupuesto de pasos y de coste?
• ¿Las escrituras tienen una clave idempotente?
• ¿El recibo permite reconstruir la decisión sin guardar datos innecesarios?
• ¿Las pruebas cubren respuestas parciales y cambios de esquema?

El objetivo no es quitar autonomía al agente, sino darle límites que el equipo pueda entender y mantener. Cuando una herramienta tiene un contrato claro, el prompt puede concentrarse en la intención y el sistema puede concentrarse en la seguridad. Esa división hace que una automatización basada en LLM sea menos espectacular en la demo, pero mucho más confiable el martes por la mañana.