Automatizaciones

Automatizaciones — Referencia Técnica

El modelo de ejecución de automatizaciones — tipos de paso, el modelo de condiciones, resolución de variables, ejecuciones, reintentos, versiones y límites

Referencia para lectores con perfil técnico. Guías en lenguaje sencillo: comienza por Construir en el lienzo.

Modelo

Una automatización es un grafo dirigido de pasos tipados representado en un lienzo. El disparador es el paso 0; todos los demás pasos declaran a qué paso(s) siguen. Existen dos familias de pasos:

• Pasos de IA — agent y router. Cada uno ejecuta un turno completo de agente (herramientas, archivos, razonamiento) y se factura en créditos. El agente se selecciona por paso; un paso solo puede ejecutar un agente al que el propietario de la automatización tenga acceso.
• Pasos deterministas — condition, filter, switch, tool, database, project (Archivos del proyecto), code, for_each, loop. Ejecución puramente basada en reglas, nunca facturada. loop solo acepta sub-pasos deterministas. for_each también puede contener pasos agent, que se ejecutan una vez por elemento y se facturan por elemento; ese for_each debe definir un tope de elementos por ejecución, y los que lo superan esperan a la próxima ejecución.

Los datos pasan entre pasos como listas de elementos JSON. Las variables ({{trigger.*}}, {{steps.N.output.*}}, {{item.*}}, {{loop.*}}) se resuelven contra esas salidas en tiempo de ejecución; una expresión que ocupa el campo completo se resuelve al valor nativo (lista, objeto, número), mientras que una expresión incrustada en texto se interpola como cadena. Cuando una lista de salida contiene exactamente un elemento, {{steps.N.output.field}} se resuelve contra ese elemento; con varios elementos el índice es obligatorio ({{steps.N.output[0].field}}).

Modelo de condiciones

Los filtros de eventos y los pasos de condición/filtro/selector/bucle comparten un único motor de condiciones: un combinador (and/or) sobre comparaciones tipadas — cadena (igual, contiene, empieza/termina con, regex, comprobaciones de vacío), número (igualdad y orden), booleano, fecha-hora (antes/después), lista (contiene, longitud), objeto (existe, vacío). La sensibilidad a mayúsculas y la verificación de tipos laxa/estricta son opciones. Las reglas de coincidencia del paso de base de datos son independientes y más simples: columna / operación / valor contra las columnas reales de la base de datos seleccionada.

Disparadores

Modo	Entrega
Manual	Iniciado desde la UI, por agentes o vía Nirvai Connect; entrada JSON opcional, sobreescribible por ejecución
Horario	Basado en cron
Webhook	Una dirección HTTPS por automatización asegurada con una cabecera de clave privada
Disparador de app	Plantillas declarativas por proveedor: suscripción automática de webhook, sondeo periódico con semántica de cursor + deduplicación, o registro de pegar-la-URL

Los eventos de app entrantes pasan por una tubería fija: verificación de firma → coincidencia de evento (exacta, lista separada por comas, *, comodín de prefijo) → normalización en elementos → el filtro de eventos. Un fallo en cualquier etapa confirma la entrega y la descarta en silencio — nunca se devuelve una respuesta de error a los proveedores, y los eventos descartados nunca crean una ejecución ni facturan nada. Las entregas en lote se comparan elemento por elemento.

Ejecución

El runtime calcula oleadas de pasos cuyas dependencias están satisfechas y ejecuta cada oleada en paralelo. Los pasos de ramificación toman decisiones vinculantes: la clausura descendente de la rama no tomada se marca como omitida con un motivo. Un paso fallido hace fallar la ejecución y omite su clausura descendente; las ramas independientes aun así terminan. Las pasadas de bucle se ejecutan secuencialmente (cada pasada puede depender de la anterior); las iteraciones de bucle sobre elementos se ejecutan con concurrencia acotada.

Cada ejecución se registra paso a paso: estado, tiempos, entradas, salidas, detalle por tipo (conteos de entrada/salida del filtro, coincidencia del selector, filas de la base de datos, stdout del código, pasadas del bucle) y advertencias — incluidas las expresiones de variable sin resolver en pasos de herramienta/base de datos.

El reintento desde un paso crea una nueva ejecución que reutiliza literalmente las entradas de la ejecución original y todos los resultados previos — los pasos de agente previos no se vuelven a ejecutar ni a facturar — y re-ejecuta únicamente la clausura descendente del paso elegido.

Valores de archivo

Las lecturas de base de datos (columnas de archivo) y obtener de Archivos del proyecto emiten referencias de archivo — nombre, tamaño, tipo MIME — no el contenido del archivo. Una referencia se materializa solo cuando se ejecuta un paso que la consume, según el campo de destino:

Campo de destino	Materialización
Campo de adjunto de una herramienta de envío de Gmail / Outlook / SMTP	Se adjuntan los bytes del archivo (Gmail: 25 MB en total; Outlook: 3 MB en total por mensaje)
Campo de herramienta de tipo URL (p. ej. la URL de imagen de Instagram)	Una URL pública temporal válida por 7 días; las imágenes destinadas a Instagram se transcodifican a JPEG
Columna de archivo de base de datos (insertar / actualizar)	El archivo se copia en el registro
Guardar de Archivos del proyecto	El archivo se escribe en la ruta de destino de un proyecto propio, reemplazando cualquier archivo que ya esté ahí
Texto	No se materializa — usa .name, .size, .mime

Las referencias se autorizan contra el propietario de la automatización: sus bases de datos, los proyectos que le pertenecen o que están compartidos con su organización, y los archivos producidos antes en la misma ejecución. Cualquier otra cosa hace fallar el paso con No access to '…'; un archivo que supera el límite del proveedor hace fallar el paso con un mensaje explícito. Cada materialización queda registrada como una nota por archivo en el detalle de ejecución del paso.

Datos de demo

Cada automatización guarda un único valor de datos de demo (un objeto JSON o una lista de objetos) junto con su disparador, para todos los modos de disparador. Si no está definido, el editor lo inicializa a partir de las rutas {{trigger.*}} que referencian los pasos; capturar un evento de prueba lo sobrescribe. Orden de resolución de la entrada del disparador de una ejecución: una entrada explícita (edición en Test Run, llamada por API / agente / MCP, un evento real) siempre gana; los datos de demo se usan solo cuando la ejecución no trae ninguna — que es siempre el caso de las ejecuciones programadas. Las automatizaciones creadas por el diseñador de AI Automations o vía MCP siempre los incluyen.

Versiones y concurrencia

Las versiones son instantáneas explícitas e inmutables con alias opcionales, guardadas bajo demanda. Restaurar reemplaza el borrador (sin eliminar nunca versiones más recientes); los pasos de cada versión pueden validarse contra los agentes, herramientas y bases de datos existentes actualmente. Los guardados del editor usan concurrencia optimista: un guardado que lleva un token obsoleto se rechaza y se presenta como un diálogo de conflicto en lugar de sobrescribir.

Límites y garantías

Límite / garantía	Valor
Pasos deterministas facturados	Nunca, incluidos los contenedores de bucle sobre elementos/bucle y los eventos filtrados (los pasos de agente dentro de un bucle sobre elementos se facturan por elemento)
Pasadas de bucle	Limitadas a 100; alcanzar el límite termina el bucle como una finalización normal, marcada en los resultados
Lectura de base de datos	Hasta 500 filas por lectura
Obtener de Archivos del proyecto	1–100 archivos por paso, los más recientes primero
Adjuntos de correo	Gmail 25 MB en total; Outlook 3 MB en total por mensaje
Enlaces temporales de archivo	Válidos por 7 días
Actualización/eliminación en base de datos	Requieren reglas de coincidencia no vacías
Variables sin resolver	Nunca hacen fallar una ejecución; se reportan como advertencias, excluidas de las escrituras en base de datos
Retrocompatibilidad de webhooks	Las direcciones de webhook preexistentes y las automatizaciones programadas siguen funcionando sin cambios

Qué sigue

• Bloques de Lógica y Acción — configuración por tipo
• Datos entre pasos — resolución de variables en la práctica