Arquitectura multinodo

Descripción general

La arquitectura multinodo permite que varios dispositivos trabajen de forma coordinada, logrando una experiencia distribuida de "el dispositivo A conversa, el dispositivo B ejecuta". El Gateway actúa como el centro de coordinación central, gestionando el registro, el descubrimiento y el enrutamiento inteligente de todos los nodos.

Panorama general de la arquitectura

                      
                      ┌─────────┐   WebSocket   ┌─────────────┐   WebSocket   ┌──────────┐
│ Web      │ ◄────────────► │   Gateway    │ ◄────────────► │ Nodo APP A│
│(Browser) │               │  (Node.js)   │               │ (macOS)  │
└─────────┘               │              │               └──────────┘
                          │  - Registro de nodos │
                          │  - Enrutamiento inteligente │               ┌──────────┐
                          │  - Reenvío de mensajes │ ◄────────────► │ Nodo APP B│
                          │  - Verificación de permisos │               │(Windows) │
                          └─────────────┘               └──────────┘

                    

Tipos de nodo

Información de registro de nodos

Cada nodo registra la siguiente información al conectarse al Gateway:

Rango de visibilidad de los nodos

Nodos de nivel account: el usuario inicia sesión en varios dispositivos y puede programar tareas entre cualquiera de ellos.

Nodos de nivel enterprise: recursos de ejecución compartidos dentro de la organización, que todos los miembros pueden usar a través del Gateway.

Enrutamiento inteligente del Gateway

Cuando un usuario del lado Web inicia una conversación, el Gateway utiliza una estrategia de degradación en tres niveles para seleccionar el nodo de ejecución más adecuado:

Primer nivel: enrutamiento semántico con LLM

Utiliza la API de OpenAI para analizar la intención del usuario y encontrar el mejor nodo:

El LLM devuelve: {nodeId, confidence, reason}

Medidas de seguridad:

• La descripción del nodo se trata como DATA y no se ejecuta como instrucción
• Evita la inyección de prompts a través de la descripción del nodo

Nota: el enrutamiento LLM actual aún no tiene un modelo configurado, por lo que se degradará automáticamente al segundo nivel.

Segundo nivel: coincidencia de palabras clave con BM25

Realiza una coincidencia de palabras clave entre la consulta del usuario y la descripción del nodo basándose en el algoritmo BM25:

Devuelve el nodo con la puntuación más alta, o null (sin coincidencias).

Tercer nivel: respaldo por conexión más reciente

Selecciona el nodo conectado más recientemente según la marca de tiempo connectedAtMs, garantizando que siempre haya un resultado de respaldo.

Ejecución remota

Flujo de conversación

                      
                      1. El lado Web envía chat.send al Gateway
2. El Gateway ejecuta el enrutamiento inteligente y selecciona el nodo de destino
3. El Gateway reenvía el mensaje al nodo APP
4. El nodo APP inicia el Agent Loop para ejecutar la tarea
5. Los eventos de streaming durante la ejecución se devuelven mediante chat.event
6. El lado Web renderiza el proceso de ejecución en tiempo real

                    

Llamada remota a herramientas

                      
                      1. El Agent principal especifica el nodo remoto mediante dispatch_multi_node_agent
2. El Gateway envía node.invoke.request al nodo de destino
3. El nodo remoto inicia un Agent Loop independiente
4. Al finalizar, devuelve el resultado mediante node.invoke.result

                    

Hoisting de adjuntos (actualización 2026-04) NEW

Al despachar entre nodos, si el mensaje contiene adjuntos base64 en línea (imágenes, documentos, etc.), el sistema los sube automáticamente al almacenamiento en la nube y los reemplaza por una referencia URL:

• Motivo: evitar que un mensaje RPC del Gateway demasiado grande cause fallos de transmisión
• Momento: se ejecuta automáticamente antes del despacho remoto, de forma imperceptible para el usuario
• Normalización de rutas del SO: al despachar entre sistemas operativos (macOS/Windows/Linux), convierte automáticamente los separadores de ruta

Reglas de distribución de las ventanas emergentes de permisos

Durante la ejecución entre nodos, "en qué extremo se muestra" la ventana emergente de permisos de herramientas es una decisión de producto clave: es necesario equilibrar entre "que el usuario pueda responder a tiempo" y "evitar que se activen operaciones sensibles sin autorización".

Escenario de la misma cuenta (el llamador y el ejecutor son la misma cuenta)

Escenario de cuentas distintas (llamada entre cuentas a un enterprise node)

• node-D es un nodo de tipo enterprise (puede ser descubierto por otros usuarios dentro de la misma organización), con la sesión actual de user001
• node-E (con sesión de user002, ya sea en APP o Web) envía un mensaje a node-D a través del Gateway
• Si node-D necesita permisos de herramientas durante la ejecución:
  • La ventana emergente se muestra únicamente en la interfaz local de node-D, no se distribuye entre extremos hacia node-E
  • Si nadie responde durante más de 5 minutos, se rechaza por defecto

Motivación del diseño

Recordatorio de implementación: la ruta de distribución entre extremos de la misma cuenta node-A APP → node-B APP actualmente no existe. Los requisitos que involucren esta ruta necesitan añadir enrutamiento en el Gateway + lógica de recepción/visualización en el lado APP; no asuma que ya está disponible.

Aislamiento del Gateway entre cuentas NEW

Además de las reglas de ubicación de la ventana emergente de permisos, el acceso a los datos en sí también está aislado:

Aislamiento de la memoria personal

Cuando un nodo es llamado entre cuentas con el rango enterprise:

• Memoria de nivel de cuenta (vinculada a userId): ❌ No accesible
• Memoria de nivel empresarial (vinculada a orgId): ✅ Accesible
• Memoria de nivel de sesión (esta sesión): ✅ Accesible

Mediante el indicador isRemoteSession se aplica un filtrado forzado en las consultas de memoria: el llamador entre cuentas no puede leer la memoria personal del propietario del nodo de destino mediante memory_query.

Por qué se diseña así

• Protección de la privacidad: tus preferencias personales, hábitos de trabajo e información de la cuenta no pueden ser leídos por un compañero al llamar a tu nodo
• Compartición empresarial: el conocimiento empresarial de la organización, como la pila tecnológica y las normas, sigue compartiéndose con normalidad, sin afectar la colaboración
• Requisitos de cumplimiento: satisface las exigencias de "privilegio mínimo" de normativas de privacidad como el GDPR

Diferenciación de iconos de conversación

En la lista de sesiones, las conversaciones de distintas procedencias muestran iconos diferentes:

Se determina en función de los campos isLocalInitiated, targetNodeId y sourceChannel.

Protocolo WebSocket

Handshake de conexión

                      
                      1. Client → Gateway: connect.challenge
2. Gateway → Client: challenge (con nonce)
3. Client → Gateway: connect (con el JWT firmado)
4. Gateway → Client: hello-ok (confirmación de conexión)

                    

Mantenimiento de la conexión (heartbeat)

• Mecanismo tick: heartbeat periódico para mantener la conexión
• Reconexión tras desconexión: reintento con retroceso exponencial
• Limpieza de caducados: el Gateway limpia periódicamente las sesiones de nodos caducadas

Control de flujo

• Throttling de Delta: los eventos de streaming SSE se agregan cada 150 ms, reduciendo el número de tramas WebSocket
• Run TTL: tiempo de espera de 10 minutos, con limpieza de los Run caducados cada hora

Qué significa esto para el usuario

La arquitectura multinodo te permite iniciar tareas desde cualquier lugar y dejar que el dispositivo más adecuado las ejecute.

Escenarios típicos:

• En una cafetería, iniciar desde el navegador del móvil (lado Web) una tarea que necesita acceder a archivos del ordenador de la oficina → el Gateway enruta automáticamente la tarea al nodo APP de la oficina para su ejecución
• Un servidor de alto rendimiento del equipo (macOS Pro) siempre con la APP abierta y configurado como enterprise → todos los miembros del equipo pueden despachar el trabajo pesado desde su propio navegador

La experiencia que puedes percibir:

• Al iniciar una conversación en el lado Web, el sistema selecciona automáticamente un nodo APP en línea para ejecutarla
• La lista de sesiones muestra distintos iconos, para que sepas si la conversación se ejecuta localmente o de forma remota
• Si no hay ningún nodo APP en línea, el lado Web indicará que no puede ejecutar tareas que requieren capacidades de Agent
• Cuando varios ordenadores tienen la APP instalada, puedes seleccionar manualmente en qué ordenador ejecutar

Lo que debes tener en cuenta:

• El lado Web no puede ejecutar tareas de Agent de forma independiente; necesita al menos un nodo APP en línea
• Las conversaciones de ejecución remota tienen latencia de red (depende de la calidad de la red entre el Gateway y el nodo)
• Al configurar un nodo con el rango enterprise, los miembros del equipo pueden despachar tareas a tu dispositivo, pero tu memoria personal no será accesible

Documentos relacionados

• Gestión de nodos Work — ver los nodos en línea desde la interfaz de gestión
• Seguridad en tiempo de ejecución — nodos — configuración de seguridad de los nodos
• Subagente — despacho entre nodos — dispatch_multi_node_agent
• Sistema de memoria tridimensional — aislamiento de memoria entre cuentas