Automatizaciones — Referencia Técnica

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

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, code, for_each, loop. Ejecución puramente basada en reglas, nunca facturada. for_each y loop solo aceptan sub-pasos deterministas — esa restricción es lo que hace posible su garantía de costo.

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.

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.

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
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
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