Conceptos de Runia Nexus

Esta página asienta los conceptos que todas las demás asumen. Si vas a trabajar sobre Runia Nexus, leela una vez y te ahorra preguntas después.

Canvas

Un canvas es la definición visual de un agente: los nodos y las flechas que los conectan. Es lo que ves en el editor cuando abrís un agente para diseñarlo.

Un canvas siempre está asociado a una empresa (la del cliente final) y tiene un nombre y un estado. Cada empresa puede tener varios canvases (por ejemplo, uno por producto, uno por canal, uno para cobranzas).

Versiones

Cada vez que publicás un canvas, se crea una versión nueva y pasa a ser la activa. Las versiones anteriores no se pierden: quedan archivadas por si querés volver atrás.

El flujo típico:

1. Editás el canvas. Los cambios viven en un borrador (no afecta producción).
2. Probás el borrador.
3. Cuando está listo, tocás publicar. Se crea la versión nueva y pasa a ser la que atiende.
4. Las versiones viejas quedan como histórico.

Nodos

Un nodo es una unidad de trabajo adentro del canvas: cuando la ejecución llega a un nodo, pasa algo (se manda un mensaje, el LLM responde, se hace una consulta a una integración, se bifurca el flow).

Los nodos están agrupados en cinco categorías:

• Triggers: puntos de entrada. Arrancan la ejecución cuando pasa algo (mensaje entrante, webhook, evento de integración, scheduled).
• Agents: nodos de IA conversacionales. El corazón del canvas. Tienen prompt, modelo, flow tools, política de memoria.
• Lógica: router, switch, reglas, fork/join, delay, channel switch. Para ramificar y controlar el flow.
• Acciones: send message, voice message, inject message, set variable, transfer to human, close session, http request, send template.
• Integraciones: nodos que ejecutan una acción de una integración conectada (consultar disponibilidad en Calendly, crear evento en Google Calendar, buscar en KB).

La referencia completa de cada nodo está en la sección Nodos.

Sesiones

Una sesión es una conversación en curso entre un contacto y un canal. Cada sesión tiene un contacto (por ejemplo, el número de WhatsApp del cliente), un canal (el número desde el que contesta el negocio) y un historial de mensajes.

Las sesiones expiran por inactividad. El tiempo se configura por cliente, según el tipo de negocio (una consulta médica puede necesitar 20 minutos de espera, un helpdesk puede aguantar una hora). Cuando expira, si el canvas tiene un trigger session_timeout, podés dispararle un flow (tipo "¿seguís ahí?" o cerrarla con un mensaje de despedida).

Ownership

Toda sesión tiene un owner: la IA o un humano específico. El owner define quién está contestando desde el lado del negocio.

• Owner IA: el canvas se ejecuta en cada mensaje entrante. El agente responde.
• Owner humano: el canvas no se ejecuta. La conversación la maneja ese operador desde la bandeja de entrada hasta que la cierra o la devuelve a la IA.

El cambio de owner lo puede disparar el agente (llamando al flow tool ft_transfer_to_human) o un operador humano (respondiendo desde la bandeja, lo que toma la sesión automáticamente).

Dual history

Concepto crítico y fácil de confundir. Cada sesión tiene dos historiales separados:

1. Historial del inbox — los mensajes que ve el operador humano en la bandeja de entrada. Es lo real, lo que el cliente mandó y lo que el bot contestó.
2. Historial del LLM — lo que el agente de IA "recuerda" como contexto de la conversación.

Por qué dos historiales

Porque a veces el canvas necesita manipular lo que el agente recuerda sin tocar lo que el operador ve. Ejemplos:

• Inyectar contexto oculto al agente (resultado de una llamada a una API, data de un webhook, una nota interna) sin que aparezca como mensaje en el inbox.
• Compactar la memoria del agente cuando se pone larga, sin perder los mensajes que el operador necesita para auditar.
• Limpiar la memoria del agente para que arranque "de cero" en una parte del flow, sin borrar la conversación real.

Qué nodo toca cada historial

Regla de oro: si querés que el cliente lo vea, send_message. Si querés que solo el agente lo recuerde, inject_message.

Triggers

Un trigger es el punto de entrada al canvas. Cuando pasa el evento que matchea el trigger, Nexus arranca la ejecución por ese nodo.

Los triggers disponibles:

• session_start: llega un mensaje entrante. El más común.
• session_close: se cierra una sesión (manualmente o por timeout).
• session_timeout: sesión expira por inactividad.
• template_reply: el cliente responde a una plantilla de WhatsApp.
• webhook: un sistema externo le pega a una URL del canvas para avisar que pasó algo (un pago, un envío).
• scheduled: corre en horarios programados (todos los lunes a las 9, una vez al día, etc).
• tag_added: se le agrega un tag a un contacto.
• manual: lo dispara un operador desde el panel.
• integration_event: eventos de integraciones (ej: Calendly confirma un turno, Stripe cobra un pago).

Un canvas puede tener varios triggers. Cada uno arranca un flow distinto según el evento. Por ejemplo, un canvas de turnos puede tener:

• session_start → atiende consultas de disponibilidad por WhatsApp.
• integration_event (Calendly, booking_created) → manda confirmación cuando alguien reserva por la web.

Integraciones

Las integraciones son servicios externos que la empresa conecta al panel (Calendly, Google Calendar, Knowledge Bases, Stripe, Google Sheets, etc.). Cuando se conecta una integración, sus acciones quedan disponibles como nodos arrastrables en el editor.

Por ejemplo, al conectar Calendly aparecen 4 nodos nuevos en el editor: consultar_disponibilidad, agendar_turno, cancelar_turno, listar_turnos. Al conectar Google Calendar aparecen 3 similares. Al conectar una KB aparece un nodo kb_search.

Integration events vs integration tools

Dos cosas distintas en el mismo ecosistema:

• Integration tools (acciones): nodos que el canvas ejecuta como parte del flow. Ej: el agente decide "necesito ver qué turnos están libres", el canvas llama al nodo consultar_disponibilidad.
• Integration events (triggers): el provider emite un evento y Nexus dispara un canvas. Ej: Calendly confirma una reserva → arranca el flow que manda la confirmación por WhatsApp.

Un flow de ejemplo que usa todo junto

Un agente de turnos típico:

1. Un mensaje entrante dispara session_start. Se crea una sesión con owner IA.
2. El trigger pasa al nodo agent, que entiende que el cliente quiere un turno.
3. El agente llama al flow tool ft_consultar_disponibilidad. La ejecución salta al nodo de integración de Calendly.
4. El nodo responde con horarios libres. El agente los usa en su siguiente respuesta.
5. send_message manda la respuesta al cliente. El mensaje queda en el inbox y en la memoria del agente.
6. El cliente responde con un horario. El agente decide reservar y llama a ft_agendar_turno. El nodo correspondiente crea la reserva.
7. Más tarde, Calendly emite el evento booking_created. Ese evento dispara un segundo flow (o el mismo canvas con otro trigger) que manda un recordatorio 24hs antes del turno.

Trace IDs (para cuando algo falla)

Cada mensaje que entra al sistema recibe un trace_id único. Todos los logs de ese mensaje (en Gateway, Session Core, Nexus, Backend CRM) quedan etiquetados con el mismo trace_id.

Es la herramienta de debugging principal. Si un cliente reporta "a las 15:03 le escribí al bot y no me respondió", buscás en los logs por ese trace_id y ves el recorrido completo: dónde entró, qué nodo se ejecutó, qué respondió el LLM, si hubo algún error, cuánto tardó cada paso.

No necesitás usarlo todos los días, pero la primera vez que debuggees un caso raro va a ser tu mejor amigo.

Próximo paso

Con los conceptos claros, el paso natural es conectar el MCP al editor para empezar a trabajar conversacionalmente con el canvas desde Claude o Cursor.