La arquitectura separa coordinación, razonamiento y ejecución para que una respuesta del modelo no se convierta, por sí sola, en una operación autorizada. Toda acción debe conservar la identidad de origen, usar una capacidad habilitada y superar la validación de sus parámetros antes de llegar a un sistema externo. Por ejemplo, si una persona pide por Slack crear una oportunidad en el CRM, el modelo puede interpretar la intención y preparar los campos, pero la oportunidad solo se crea si esa identidad puede usar la herramienta, la operación de escritura está habilitada y el CRM acepta los datos y las credenciales correspondientes.
Capas del sistema
Una solicitud avanza por capas con responsabilidades acotadas. Las primeras seis forman el recorrido operativo; identidad, credenciales y estado aportan información confiable al recorrido sin quedar bajo el control del modelo.
- Canales autorizados Originan eventos —por ejemplo, desde WhatsApp o Slack— con los datos necesarios para correlacionar la conversación y recibir la respuesta.
- Gateway de aplicación El servicio Node.js normaliza el evento, resuelve la ruta y la sesión, y coordina el intercambio entre el canal y el agente.
- Runtime del agente Construye el contexto permitido, aplica la jerarquía de instrucciones y decide si debe responder, usar una herramienta, pedir aprobación o escalar.
- Entorno de ejecución Ejecuta las tareas que requieren aislamiento dentro de límites de recursos y acceso definidos para la implementación.
- Herramientas e integraciones Convierten una intención en una operación determinista: validan parámetros, comprueban autorización y devuelven un resultado estructurado.
- Sistemas externos Aplican sus propios permisos y reglas de negocio, conservan el registro definitivo y responden con el resultado de la operación.
Capa transversal: identidad, credenciales y estado. La identidad de la sesión, la autorización de la integración, la memoria y el estado de los flujos se resuelven fuera del razonamiento y tienen ciclos de vida independientes.
Contratos entre capas
Un contrato define qué puede entregar una capa a la siguiente, qué respuesta debe recibir y dónde termina la autoridad de cada componente. Así, una salida útil sigue siendo verificable antes de producir un efecto externo.
Canal → gateway
El gateway recibe un evento y metadatos confiables del canal; devuelve una solicitud normalizada con ruta, identidad y sesión. Ejemplo: un mensaje de Slack se asocia al agente y al hilo correctos antes de incorporar su texto al contexto.
Gateway → runtime del agente
El runtime recibe instrucciones, políticas y contexto ya asociados a la sesión; puede interpretar y planificar, pero no inventar herramientas ni permisos. Ejemplo: puede proponer consultar una orden, pero solo solicitar la herramienta de consulta si está habilitada.
Runtime → entorno de ejecución
El entorno recibe una tarea estructurada y la ejecuta dentro de límites predefinidos; no hereda acceso general al host. Ejemplo: generar un archivo temporal utiliza únicamente el espacio y los recursos asignados a esa tarea.
Runtime → herramienta
La herramienta recibe una operación conocida con parámetros tipados; valida alcance, datos y aprobaciones antes de actuar. Ejemplo: “crear oportunidad” exige campos válidos y permiso de escritura; texto libre que pida saltarse una aprobación no modifica el contrato.
Herramienta → sistema externo
La integración envía una petición autenticada y acotada; el sistema de registro conserva la decisión final según sus propias reglas. Ejemplo: el CRM puede rechazar una moneda no admitida aunque la solicitud ya haya superado la validación local.
Cómo viaja una solicitud
Los errores también tienen contrato
Un fallo debe indicar qué ocurrió y si la operación llegó a ejecutarse. Esta distinción evita que el agente confunda “sin autorización” con “sin resultados”, repita una escritura incierta o anuncie éxito cuando el sistema externo nunca confirmó la acción. También permite decidir de forma segura si corresponde corregir datos, pedir aprobación, reintentar o escalar.
Ejemplo. Una persona solicita por Slack cambiar la cuenta bancaria de un proveedor. Los parámetros son válidos, pero falta la aprobación requerida. La herramienta devuelve aprobación pendiente y no llama al ERP; el agente informa qué falta sin afirmar que el cambio ocurrió. Después de la aprobación se crea una nueva ejecución. Si entonces el ERP no está disponible, el resultado cambia a dependencia no disponible y queda claro que la operación sigue sin confirmarse.
- Aprobación pendiente: la operación se detiene sin producir el efecto externo.
- Solicitud rechazada: una identidad, capacidad o validación impide continuar.
- Dependencia no disponible: el sistema externo no pudo confirmar la operación; el contrato define si el reintento es seguro.
- Resultado confirmado: la herramienta devuelve los identificadores y el estado necesarios para comunicar el efecto real.
Arquitectura pública y arquitectura real. Esta página describe el patrón común. La topología, los sistemas conectados, las cuentas, los alcances y los flujos de datos de cada implementación se documentan de forma privada.