Automations

Automations — Technical Reference

The automation execution model — step types, the condition model, variable resolution, runs, retries, versions, and limits

Reference for technically-minded readers. Plain-language guides: start at Building on the Canvas.

Model

An automation is a directed graph of typed steps rendered on a canvas. The trigger is step 0; every other step declares which step(s) it follows. Two step families:

• AI steps — agent and router. Each executes one full agent turn (tools, files, reasoning) and is billed in credits. The agent is selected per step; a step can only ever execute an agent the automation's owner has access to.
• Deterministic steps — condition, filter, switch, tool, database, project (Project files), code, for_each, loop. Pure rule-based execution, never billed. loop accepts only deterministic sub-steps. for_each may also contain agent steps, which run once per item and are billed per item; such a for_each must set a per-run item cap, and items beyond it wait for the next run.

Data passes between steps as JSON item lists. Variables ({{trigger.*}}, {{steps.N.output.*}}, {{item.*}}, {{loop.*}}) are resolved against those outputs at execution time; a whole-field expression resolves to the native value (list, object, number), while an expression embedded in text interpolates as a string. When an output list holds exactly one item, {{steps.N.output.field}} resolves against that item; with several items the index is required ({{steps.N.output[0].field}}).

Condition model

Event filters and the condition/filter/switch/loop steps share one condition engine: a combinator (and/or) over typed comparisons — string (equals, contains, starts/ends with, regex, empty checks), number (equality and ordering), boolean, date-time (before/after), list (contains, length), object (exists, empty). Case sensitivity and loose/strict type checking are options. The database step's match rules are separate and simpler: column / operation / value against the selected database's real columns.

Triggers

Mode	Delivery
Manual	Started from the UI, by agents, or via Nirvai Connect; optional JSON input, overridable per run
Schedule	Cron-based
Webhook	A per-automation HTTPS address secured with a private key header
App trigger	Declarative templates per provider: automatic webhook subscription, periodic polling with cursor + dedup semantics, or paste-the-URL registration

Inbound app events pass through a fixed pipeline: signature verification → event match (exact, comma list, *, prefix wildcard) → normalization into items → the event filter. A failure at any stage acknowledges the delivery and drops it silently — providers are never given an error response, and dropped events never create a run or bill anything. Batched deliveries are matched per element.

Execution

The runtime computes waves of steps whose dependencies are satisfied and runs each wave in parallel. Branching steps make their decision binding: the not-taken branch's downstream closure is marked skipped with a reason. A failed step fails the run and skips its downstream closure; independent branches still finish. Loop passes run sequentially (each pass may depend on the previous); for-each iterations run with bounded concurrency.

Every run is recorded step-by-step: status, timing, inputs, outputs, per-type detail (filter in/out counts, switch match, database rows, code stdout, loop passes), and warnings — including unresolved variable expressions on tool/database steps.

Retry-from-step creates a new run that reuses the original run's inputs and every upstream result verbatim — upstream agent steps are not re-executed or re-billed — and re-executes only the chosen step's downstream closure.

File values

Database reads (file columns) and Project files get emit file references — name, size, MIME type — not file content. A reference is materialized only when a consuming step runs, according to the target field:

Target field	Materialization
Attachment field of a Gmail / Outlook / SMTP send tool	The file bytes are attached (Gmail: 25 MB total; Outlook: 3 MB total per message)
URL-typed tool field (e.g. Instagram image URL)	A temporary public URL valid for 7 days; images bound for Instagram are transcoded to JPEG
Database file column (insert / update)	The file is copied into the record
Project files save	The file is written to the target path in an owned project, replacing any file already there
Text	Not materialized — use .name, .size, .mime

References are authorized against the automation owner: their databases, projects they own or that are shared with their organization, and files produced earlier in the same run. Anything else fails the step with No access to '…'; a file exceeding the provider's limit fails the step with an explicit message. Each materialization is recorded as a per-file note in the step's run detail.

Demo data

Each automation stores one demo data value (a JSON object or list of objects) with its trigger, for every trigger mode. When unset, the editor seeds it from the {{trigger.*}} paths the steps reference; capturing a test event overwrites it. Resolution order for a run's trigger input: an explicit input (Test Run edit, API / agent / MCP call, a real event) always wins; demo data is used only when the run carries none — which is always the case for scheduled runs. Automations created by the AI Automations designer or over MCP always include it.

Versions and concurrency

Versions are explicit, immutable snapshots with optional aliases, saved on demand. Restore replaces the draft (never deleting newer versions); each version's steps can be validated against currently-existing agents, tools, and databases. Editor saves use optimistic concurrency: a save carrying a stale token is rejected and surfaced as a conflict dialog rather than overwriting.

Limits & guarantees

Limit / guarantee	Value
Deterministic steps billed	Never, including for-each/loop shells and filtered-out events (agent steps inside a for-each are billed per item)
Loop passes	Capped at 100; reaching the cap ends the loop as a normal completion, flagged in results
Database read	Up to 500 rows per read
Project files get	1–100 files per step, newest first
Email attachments	Gmail 25 MB total; Outlook 3 MB total per message
Temporary file links	Valid for 7 days
Database update/delete	Require non-empty match rules
Unresolved variables	Never crash a run; reported as warnings, excluded from database writes
Webhook back-compat	Pre-existing webhook addresses and scheduled automations keep working unchanged

What's next

• Logic & Action Blocks — per-type configuration
• Data Between Steps — variable resolution in practice