Arquitectura mínima de un agente en producción: webhooks, colas, memoria y handoff

Un agente de producción no empieza en el prompt. Empieza en la arquitectura que decide que eventos entran, que acciones son posibles y como se audita cada decision.

La version mínima deberia tener seis bloques: entrada, cola, orquestador, herramientas, memoria y handoff humano.

1. Entrada

La entrada puede ser un webhook de WhatsApp, Telegram, Slack, email o formulario web. Su trabajo no es resolver la conversacion. Su trabajo es validar, normalizar y aceptar el evento.

El webhook debe responder rapido. Si espera a que el modelo termine, vas a tener timeouts y mensajes duplicados.

2. Cola

La cola separa recepcion y procesamiento. Tambien permite reintentos, priorizacion y pausas. Si una API externa falla, la cola evita perder el mensaje.

Para una primera version puedes usar una cola administrada o incluso una tabla de jobs si el volumen es bajo. Lo importante es que el evento no dependa de una sola request larga.

3. Orquestador

El orquestador decide que modelo usar, que herramientas estan permitidas, que memoria cargar y cuando terminar. Es el cerebro operacional del agente.

No metas toda la logica en el prompt. El prompt debe orientar conducta; el orquestador debe imponer reglas.

4. Herramientas

Cada herramienta debe tener contrato claro: parametros, permisos, errores posibles y datos que devuelve. Una herramienta que acepta texto libre para "hacer cualquier cosa" es una puerta abierta a errores.

Ejemplos de herramientas:

• Buscar cliente.
• Crear ticket.
• Consultar inventario.
• Enviar resumen al humano.
• Agendar cita.

5. Memoria

La memoria debe guardar hechos utiles, no todo el chat sin filtro. Separa memoria de corto plazo, preferencias verificadas y datos sensibles.

Nunca uses memoria como excusa para saltarte autenticacion. Que el usuario dijo algo ayer no significa que hoy tenga permiso para ejecutar una acción.

6. Handoff humano

El handoff no es fracaso. Es una funcion de seguridad. Define reglas para pasar a humano:

• Reclamos fuertes.
• Riesgo legal.
• Datos de salud o finanzas.
• Baja confianza.
• Usuario pide una excepcion.
• Herramienta devuelve datos contradictorios.

Diagrama simple

Canal -> Webhook -> Cola -> Orquestador -> Modelo
 | |
 | +-> Herramientas
 | +-> Memoria
 | +-> Evals/logs
 +-> Handoff humano

Un agente con esta arquitectura todavía puede ser pequeno. Pero ya tiene lugares claros para seguridad, escalabilidad y auditoria. Eso es lo que separa un tutorial útil de una automatizacion fragil.