Arquitectura mínima de un agente en producción: webhooks, colas, memoria y handoff
Los bloques basicos que necesita un agente antes de recibir usuarios reales: entrada, cola, orquestacion, herramientas, memoria y auditoria.
Por qué importa
Esta nota se enfoca en la decisión práctica para builders: qué cambia, qué riesgo agrega y cómo aplicarlo sin romper operación.
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.