Arquitectura

Recorrido de un mensaje

Cliente en WhatsApp
   │
   ▼
Meta Cloud API ──(callback override por WABA)──► Lema Engine  agentes.lemabot.com
                                                  │  valida firma de Meta
                                                  │  re-firma con la signing key de la conexión
                                                  ▼
                              Proyecto  POST /api/public/whatsapp-webhook
                                 1. verificarRelay()  (HMAC + ±5 min)
                                 2. normalizarWebhook() → guardar idempotente por wamid
                                 3. responder 200  (Engine devuelve 502 a Meta si fallas → Meta reintenta)
                                 4. en segundo plano (waitUntil / after):
                                      esperar ráfaga (6 s) → reclamar turno
                                      ejecutarMotor()  ◄── config + conocimiento + adaptadores
                                      revalidar (¿asesor tomó? ¿llegó otro mensaje?)
                                      enviarTexto() por Graph API con el token de la conexión

Dentro de `ejecutarMotor()`

último mensaje
  ├─ revisarEntrada():  opt-out │ pide humano │ queja │ audio/imagen │ reacción   → respuesta fija (sin LLM)
  ├─ saludo puro al iniciar                                                     → bienvenida configurada
  └─ construirInstrucciones()  (capas)
        └─ ToolLoopAgent (AI SDK 7)
              herramientas: buscar_catalogo · buscar_documentos · guardar_datos_lead · traspasar_a_humano
              parada: 6 pasos o al traspasar · timeout 9 s por intento
        └─ revisarSalida()   precio · descuento · promesa · enlace · teléfono · fuga · longitud
              ok → enviar │ falla → 1 reparación │ falla otra vez → no se envía, traspaso a asesor

Responsabilidades

Capa	Dueño	Cambia entre proyectos
Motor (`src/`)	agent-core	No: se sincroniza
Canal (`src/canal/`)	agent-core	No
Adaptadores (catálogo, documentos, leads)	Proyecto	Sí
Casos del negocio	Proyecto	Sí
Configuración (`ia_agentes`, `ia_conocimiento`)	Cliente, desde el panel	Sí
Conexión WhatsApp	Engine + Conecta	Una por cliente

Límites de la plataforma que condicionan el diseño

Cloudflare Workers da ~30 s de waitUntil después de responder. Por eso: ráfaga 6 s + intentos de 9 s + envío. Si se excede, la tarea se corta (ver Problemas).
Meta reintenta el webhook hasta 7 días si recibe error: guardar idempotente por wamid es obligatorio.
NaN permite 7 peticiones en paralelo y 60 por minuto por key.