Automations — Technical Reference
This page describes how automations work beneath the builder, in technical terms, for developers and technically-inclined users. It focuses on observable behavior and the model automations follow, rather than implementation internals.
Architecture model
An automation is a graph of steps that starts from a trigger. Two concerns are kept separate:
- Design — building the automation (with the AI designer or the manual editor). This produces a draft definition.
- Execution — actually running the automation. This happens as a separate job (see below).
Each automation has a definition (its steps and trigger), and each time it runs it produces a run record.
Step model
A definition is an ordered set of nodes. Each node has an index, the node(s) it follows, a type, and type-specific fields.
| Node type | What it does | Key fields |
|---|---|---|
| Trigger (auto-generated, index 0) | Marks how the automation starts | trigger type + trigger settings |
| Agent step | Runs one of your agents with an instruction, optionally writing output to a file | the agent, an input prompt, an output file, success/failure notes |
| Router step | Branches the flow based on a condition | a set of routes, each with a condition and the next step to go to |
- A step's output can be written to a file that later steps read, so data flows along the chain.
- Step consolidation: when the same agent handles several sequential actions, they're combined into one step with a detailed instruction, rather than many tiny steps. Separate steps are used for different agents, branches, or parallel work.
Triggers
| Trigger | Starts the automation when… | Notes |
|---|---|---|
| Schedule | A time/recurrence is reached | Defined as a cron expression with a timezone |
| Webhook | An external service sends an HTTP request | Secured by a secret key that must accompany each request |
| Manual | You run it on demand | — |
Why design and execution are separate
The conversational designer runs within a time limit, and a full automation can run longer than that (it may call several agents, each doing real work). So the designer never executes the automation itself — it produces a verified draft, and execution runs as a separate job that isn't bound by the designer's limit.
This is why the flow is design → test → activate: you test the finished draft (a real run you can watch step by step), then activate it so it runs on its trigger.
Execution model
- Steps run in order; a router step sends the flow down one of its branches based on the result.
- Each run is recorded as a run record that stores, per step: status, a result summary, any output files, and which tools were used.
- A run moves through these statuses:
- Test runs vs production runs are recorded the same way; a test run lets you verify the automation before activating it.
- While a run is in progress, its status is polled so the interface can show step-by-step progress live.
Execution modes
Each automation runs in one of two modes:
| Mode | Trade-off |
|---|---|
| Agile | Faster and more cost-efficient — good for most automations |
| Intensive | More thorough analysis per step — for complex work |
Limits & guarantees
- Steps execute sequentially; routers are the only branching mechanism.
- Every run is recorded with per-step results you can review afterward.
- Each design conversation is an isolated session; one session can design multiple automations.
- Webhook triggers require a secret key — requests without it are rejected.
- Usage is metered as credits per run.
What's next
- Choosing a trigger — schedule, webhook, or manual
- Agent steps & routers — configure what each step does
- Testing & runs — test, activate, and monitor executions