Automations and AI agents
Automations and AI agents
Who can do this: Owner to build, run from the Automations page, read run history, and undo. Edit to open Agents; Manage Members (which an owner has) to see the AI-key panel inside it. Editors can still start the rules a table button or the table's Run menu offers. See the .
What it's for
An automation says "when this happens to a row, do that". It can fill fields, create rows, send email or messages, call outside services, issue payment links and more. An AI agent is an assistant you configure once and then use in three ways: it answers customers, it processes a row from an automation, or a portal app calls it. Both can send things to real people and spend AI credit, so this chapter also covers testing and undoing.
Every setting, trigger and action is listed in the . This page is the order to do things in.
Before you start
The space needs at least one data table. With none, New rule is disabled and the page says so.
A rule is saved enabled. It starts acting as soon as you press Create. Build risky rules with the Manual trigger first (see step 5).
Email, messages, payment links and AI calls depend on things outside your space. Ask your administrator when they are missing:
Needs your administrator: outgoing email from the Platform mailbox (default) needs the installation's email sending (SMTP or Resend) set up under
/system/config. AI calls through the Platform key need an AI provider enabled for the agent role there. Exchange-rate sources in Import FX rates are limited to those an administrator activated, and scanned documents in Extract text from document need an OCR provider. Open the run in Run history and read its action rows to see which one is missing:•Email. Send email shows Failed with the mail error. The platform's own messages, in English, are
SMTP user / from address is not configured.(SMTP with neither a From address nor an SMTP user set),Email "From" address is not configured. Set "From address" in System → Config → Email.andResend API key is not configured. Set it in System → Config → Email.(Resend). A wrong host or password shows the mail server's own error text, which differs by server.•AI key. There is no "key missing" message. With no AI provider enabled for the agent role, the platform falls back to the installation's default AI settings. If that default has no working key, Run agent shows Failed with
agent run <number> failed:followed by the AI provider's own error. When every provider is busy it shows[AiProviderPool] No available provider slots for role="agent".•Exchange rates. The source list in Import FX rates offers only activated sources (plus one already saved on the rule). Saving a rule whose source has been deactivated is refused with
the "<source>" FX provider is deactivated on this platformand says an administrator enables it in System / Config → Data Providers. If the source is deactivated after you saved, the action shows Failed withfetch_fx_rates failed: provider_disabled. The CurrencyFreaks source without the installation's key fails withfetch failed: CurrencyFreaks API key is not set — add it in System / Config → Data Providers.•Scans (OCR). Extract text from document reads the file in the background, so the action itself shows Succeeded with "text extraction queued". The result is written to the row: choose Status column (optional) (it moves to a state named "Extraction failed", in the language of the rule's author) and Error / notes column (optional) in the action to see it. For a scan without OCR the note reads
"<file name>": no text layer — likely a scan. OCR is not configured (assign a provider the OCR role).It is written in the language of the person who created the rule. With no error column chosen, nothing tells you.
Steps
1. Open Automations
Open the space's admin menu and choose Automations. You get four tabs: Rules, Run history, Webhook deliveries, Limits. From a table, the toolbar Run button opens a list titled Automations with links Manage and Run history that land here filtered to that table (owners only).
2. Create a rule
On Rules, press New rule.
Fill Name and Table. Pick the table in the tree picker. The Description is optional and shows as the tooltip on a Button column that runs the rule.
Under Trigger, choose one of the six kinds (step 3).
Under Conditions, add filters if the rule should apply to some rows only. Match all or Match any sets how they combine. With no conditions it fires on every matching event.
Under Actions (run in order), press Add action and configure each one (step 4).
Choose Stop on error or Continue on error (bottom of the editor). The default is Stop on error.
Press Create.
3. Choose a trigger
Trigger | Fires when | Notes |
|---|---|---|
On event | A row is Created, Updated or Deleted | Only when these columns change narrows it. Computed columns (formula, rollup, lookup) cannot be picked, because the table calculates them |
On status change | A Status column moves from a From state to a To state | Fires once on entering the state. On event with Updated fires on every update while the row sits in it |
On schedule | The clock matches | Presets such as Every minute, Daily at, Weekly on, or Custom expression…. Choose the Timezone |
Manual | Only when someone runs it | Never fires by itself |
Inbound webhook | An outside system posts to the rule's URL | See step 8 |
Customer message | A customer writes in an Inbox conversation linked to a row of this table | Pick Channels or leave all. Your own replies never fire it |
Schedule extras:
Run can be For each filtered row (one run per matching row each time) or Once for the table (one run, no row, conditions ignored).
Relative to makes a row fire a set time before or after a date column, once per row. The schedule then only sets how often the check happens. Rows that became due while the rule was off are not replayed.
4. Add actions
The picker offers about 25 actions. The ones owners use most:
To do this | Action |
|---|---|
Change data | Set fields on this row, Create a row, Move this row to a status, Update related rows |
Tell someone | Send email, Send external message, Notify person column |
Talk to other systems | Call webhook, Fetch URL (write back), Call connector action, Import FX rates |
Use AI | Run agent, Transcribe audio, Extract text from document |
Take money | |
Chain rules | Run another automation |
Actions run top to bottom. Use Add stage to group actions and run the group only if a condition holds (Run this stage only if). Use Add branch with Add arm when exactly one of several paths should run; the first arm whose conditions match wins and otherwise catches the rest. Values and messages accept fields from the row: type {{ in a text box to pick a column.
5. Test before it goes live
For anything that sends or spends, build the rule with Manual first.
In the rules list press the play icon (tooltip Run / test).
Pick a row under Choose a row to test against.
Leave Mode on Preview (no changes) and press Preview. The dialog shows each request and the cells it would write. Nothing is saved and no email, message, webhook, agent call or payment link is sent. (A GET in Fetch URL (write back) still runs so you see the live answer.)
Switch Mode to Run & save and run once on a test row.
Edit the rule, change the Trigger to the real one, and Save.
For schedule and fan-out rules the dialog also offers Run against: All matching rows (same as the next tick, capped at 500) or One row.
6. Run by hand from a table
Editors use the table's Run button (or a Button column). Sections Table actions and Row actions list the rules marked Manual, or marked Show in table Run menu. If a rule has Inputs or Guards, a dialog first asks for the values. A Block guard stops the run and explains why. A Confirm guard needs a tick.
7. Read run history, retry, undo
Open Run history. Filter by All rules, From, To, then Reset filters; Load more for older runs. Press a row to see each action's result.
Status | Meaning |
|---|---|
Pending, Running, Succeeded | Normal |
Failed | An action failed and the policy was Stop on error (or it failed anyway) |
Skipped | Conditions did not match, a guard blocked it, or a protection tripped. Open the row for the reason |
Waiting | An earlier run in the same cascade is still writing rows this one would read. It starts when that finishes |
Retry | Parked for another try, shown as |
Reverted | You undid it |
The retry icon (tooltip "Try again now, resuming at the action that failed") appears on Failed and Retry runs. It continues from the failing action; steps that succeeded are not repeated.
The undo icon (tooltip "Undo the data changes this run made") appears on Succeeded runs. It restores table data. It cannot unsend email or messages, withdraw a webhook or a payment link.
To undo a whole cascade from selected rows: select rows in the table, press Run, choose Roll back automation runs…. The Roll back automation runs dialog lists the chains by rule under Rules whose chains to roll back, previews the data changes, then Roll back. If it refuses because another run blocks it, Add to rollback includes that run too.
Automatic retry only covers Run agent actions that fail because the AI provider is busy or down. They are tried again after 1 minute, 5 minutes, 20 minutes, then 1 hour, five attempts in all. Other failures stay Failed until you press retry.
8. Webhooks
Inbound webhook: save the rule, then copy the Webhook URL. Anyone with it can fire the rule, so treat it like a password. Use {{webhook.field}} in actions to read the posted JSON. Add a Signing secret (optional) if the sender signs requests. Regenerate the URL kills the old one at once. Send test payload posts a sample; Recent deliveries lists what arrived.
Call webhook sends from your rule. The Webhook deliveries tab lists them with HTTP status and has Replay. A delivery that fails with a timeout, 408, 429 or 5xx is retried with growing delays (up to 6 hours), five attempts in all, then marked Abandoned. Other 4xx answers fail at once.
9. Limits
Limits shows Current usage against Max executions per hour and Max executions per day. Defaults are 1,000 an hour and 10,000 a day. Leave a field empty for the default; press Save limits. Runs over the limit are not started and show as Skipped with "Automation quota exhausted for this project".
10. Loops and cascades
Rules can trigger each other. New On event and On status change rules have Allow this rule to run on changes made by automation switched on, so chains work. Three protections stop runaways, each recorded as a Skipped run with the reason:
"Loop detected": the same rule already ran on the same row earlier in the chain.
"Loop guard" with a depth: more than 8 automation hops from the original change.
"Loop guard" with a run count: one change caused more than 500 runs in the last hour.
The reason names the rules involved. Fix it by narrowing Only when these columns change on one rule, or by switching off the Allow this rule to run on changes made by automation option on the other. You cannot change the depth and 500-run limits on screen.
Careful: the loop protections stop a runaway; they do not undo it. Anything sent before the stop (messages, webhooks, agent calls) stays sent.
11. Copying or importing a space
Rules that send email or messages, call outside addresses, run agents, issue payment links or access links, or import from outside are left switched off in a copy made with Duplicate project (or Use as a template). The dialog says "automation(s) were left switched off" and why. Rules that only change data in the space keep their state.
Export / Import has the checkbox Leave automations and connectors switched off. Unchecked, every rule comes back on as it was in the source, including ones that email people or call the source's addresses.
Careful: when moving a live space, tick Leave automations and connectors switched off, import, switch the old space's rules off, then switch the new ones on one by one. A copy that keeps a Call webhook or Send email rule running starts contacting the same people as the original.
12. AI agents
Open Agents in the admin menu. The page lists agents on the left and an editor on the right.
Conversational: answers customers in chat. Set Audience (portal or public), Inbound channels (trigger), Max reply length and an Escalation group.
Row processor: works on one row when a rule runs it. Run mode: One call mode (fills this row only, safest), Field extraction (fills fixed fields from text), or Agent loop mode (reads and writes other tables).
Generic data: works over a whole table, normally from a schedule rule.
Portal completion: one model call a portal app makes by Portal key. No tools; it reads and writes nothing.
Fill Name and Instructions (its system prompt). For tool-using agents, limit Document scope; public agents may use published documents only.
For conversational agents, Mutations is the approval setting: ask confirms with the customer before writing, auto does not.
Press Create. Data agents are then used from a rule: add the action Run agent, pick the agent, write the task.
Switches that must be on: Edit the space and under Space features switch Agents on for conversational and completion agents (the server ignores them otherwise); also switch Portal AI on, since the customer-chat runner builds on it. Row-processor and generic-data agents run from the Run agent action without the Agents switch: the server checks it for customer-message and portal completion agents, not when a rule runs a data agent. The warning banner on the Agents page says the same: chat agents (replying to inbound messages) and portal completion agents won't run until agents is added to the project's features, while row-processor and data agents started by the Run agent action run without it. The switch still matters for data agents in two places: the AI assistant and MCP tools that create or change agents are unavailable without it, and importing a project file that carries agents is refused until the destination space has it.
Whose AI key. Agents use the platform's AI pool by default (the Platform badge) and count against your plan's AI credit. To use your own, open Agent AI provider, press Configure, tick Use our own AI key for agents in this project, choose the Provider (OpenRouter, Z.ai, MiniMax, Alibaba (Qwen) or Custom (self-hosted / OpenAI-compatible)), enter Model and API key, press Save, then Test connection. The badge becomes Your key. The setting covers every agent in the space and the Portal AI assistant. Own-key usage is not metered against your plan; the provider bills you.
Careful: a Custom endpoint receives your agents' full prompts, including row data. It must be a public https address. If Provider enabled is off, or Fall back to the platform pool if our key is unavailable is on and your key fails, agents quietly use the platform pool and its credit.
Portal AI gives signed-in portal users a chat assistant that can read and search only what they can already access, and writes nothing. It is off by default. Turn it on with Portal AI under Space features, or with the AI assistant switch in External Portals. See .
How to check it worked
A new rule appears in Rules with the right table, trigger badge and Enabled on.
Press Preview on a real row: the dialog says "Preview — nothing was saved." and each action's detail reads "Would ...".
After the real event, Run history shows Succeeded and the action rows show what was done.
For an agent, open it in Agents and read Recent runs and History. The Agent AI provider badge shows Your key or Platform.
Undo / what can go wrong
Problem | What to do |
|---|---|
A rule sent something wrong | Switch Enabled off in the list first. Sent messages cannot be recalled |
Data was changed wrongly | Undo the data changes this run made, or Roll back automation runs… for a cascade. Cells edited since stay as they are, and a count is shown |
Runs show Skipped with a loop or quota reason | See steps 9 and 10 |
Rule never fires | Check Enabled, the conditions, and that the table is the right one. A schedule rule also skips rows that became due while it was off |
A deleted rule | Delete automation asks for confirmation and deletes the rule for good. Its run history and inbound-webhook deliveries are deleted with it, and there is no way to restore it. Changes it already made to your data stay, but they can no longer be undone from Run history. Switch Enabled off instead if you may want it back |
Agent does nothing | Check the agent's Enabled tick, the Agents space feature, and the key badge |
Related
· · · · · · Depth: stages, loop protection, retry.