Automations

An automation decides when your agents run without anyone sending them a message. It runs them on a schedule, or when something happens in a connected service, such as a new email or a GitHub issue. Automations belong to an Application. Open the Application and choose Automations in the sidebar.

Every automation is a trigger, so it uses the same trigger API, event catalog, and content filters. This page covers what the Automations pages add on top of triggers: work shapes, the item ledger, and the tools for running them.

Two kinds of automation

An automation either runs its bound agents directly, or sends each record through a work shape:

Bound agents suit work where each event is a one-off turn, such as posting a daily summary. A work shape suits work where each record has to be seen through to the end: triaging every incoming invoice, filing every approved request, or working through a backlog.

Create an automation

On Automations, click New trigger and choose one of two options:

• Schedule creates an automation that runs daily at 09:00 in your browser's timezone. Pick at least one agent here. You change the frequency, time, and timezone on the automation's page.
• Integration event asks for the integration, the Event, and the Config to listen on. Under What happens to each event, choose Run the agents below to bind agents, or Process each event through stages to give it a work shape.

An event automation created with stages starts with no stages at all. It starts watching straight away, so you can see what actually arrives before an agent touches anything. The items it admits wait for the stages you add.

To give a schedule a work shape, open it, click Edit, and fill in Work on the Overview tab. Once it has a work shape, the agent you bound when you created it runs nothing. The field is relabelled Bound agents (not used by this automation), and you can remove the agent.

Only schedule and integration-event automations can have a work shape. A schedule needs a source to fetch records from. An event automation can't have one, because each event it receives is the record.

A new automation is active as soon as you create it. To keep it from running while you build it, click Pause on its page.

Shape the work

Edit the work shape under Work on the Overview tab, after clicking Edit. It has four parts: what the automation watches, the values it uses, its stages, and its limits.

What it watches

An event automation has nothing to configure here. Each event becomes one item, de-duplicated by the provider's own id.

A schedule fetches its records from a Source, a ready-made way of listing items from a connector, such as an inbox or a spreadsheet. Pick the source, then fill in its fields:

Click See what this returns to list what the source returns right now. Nothing is recorded, and the automation's position doesn't move. Each record is marked Would be admitted, Already here, Skipped by filter, or No id — skipped, so this is also how you check a skip filter. Turn on Only what the next pass would see to list only records newer than the automation's current position (its cursor). A caught-up automation shows nothing when this is on, and that's the healthy state.

Values it uses

Values it uses are named values that your stages refer to as {{name}} in their instructions, such as a spreadsheet id or a folder. Declaring them on the automation keeps the agent reusable. A stage can override a value under its own Advanced section.

Stages

Under What happens to each item, add stages with Add stage. Items move down the list one stage at a time, unless a stage sends an item to a later stage instead. Items only ever move forward, so the stages can't loop.

The last stage must be a Done stage. A shape with no stages is valid too. The automation then records items without processing them, which is a safe way to watch a source before acting on it.

Each stage has a Name, which you can change at any time, and an Id under Advanced. The id is filled in from the name. Items record the id, not the stage's position or name. Removing a stage, or changing its id, is refused while items are still live at it (any status except DONE, IGNORED, or DEAD).

Process stages

Items per pass at this stage and Running at once are under Advanced. See Limits and concurrency.

Ask a person stages

An Ask a person stage doesn't run an agent itself. It sends one question about a set of items to a person, and each item waits until its answer arrives.

Questions sent as messages are answered in Inbox → Questions.

Limits

The Limits block applies to the whole automation. Leave a field empty to use the platform default. You can lower each value, but not raise it above the default:

Two more settings sit next to the limits:

• What each finished item counts as names the unit of work, such as invoice and invoices. The Work tab counts items in that unit.
• Reporting sends a summary of what the automation finished and set aside Every day, Once a week, or Never. It goes to the people in the Application who receive outcome emails, and nobody is subscribed by default. It can also go to one contact, as a note written by an agent you choose.

Test a stage before you turn it on

Once the automation is saved, every Process stage that has an agent shows a Test this stage button. So does every Ask stage that has an Answered when this field is filled key. The button opens the Debug drawer on that stage and runs it with your unsaved changes. Nothing on the ledger is claimed or written.

• Input. Start from a real item waiting at the stage, from JSON you type, or from a record that See what this returns lists. On that record, click Debug with this.
• Process stages run the stage agent's deployed revision once in the sandbox. The run counts against the agent's test budget. Reads are real and writes are simulated. Under Connections, you can choose how each connection is routed, but you can't route one to live. A batch stage treats the item as a batch of one.
• Ask stages take the Reply a person would send. Nothing is sent to anyone. A reply written in prose is read by a model, the same way a real reply is.

The result says what the ledger would have done with the item. Examples are Would advance to stage, Would be excluded by the stage, and The answer lacks a field this stage promises — it would be retried. It also shows What this stage added, the agent's input, and its answer.

From the result, you can:

• Continue to stage: send the result on to the next stage, following any route the agent chose.
• Run again: rerun the step, with edited input if you changed it.
• View run: open the trace of the run.

The drawer header shows what the walk has cost so far.

When you debug a real item, Leave out what this stage and the stages after it add is on by default. It removes those keys from the item's data, so the test doesn't see output the item already got from those stages.

You can also debug any item from the Work tab. Open the item and click Debug, or click Debug from here on one step of its history. You can copy a link to a walk, and stage tests are deleted after 7 days.

A stage can't be tested while its agent has a tool that reaches a real person, such as asking for human approval. Each person can have at most 3 tests running at once.

Turn it on

Use Pause and Resume in the page header, or the Enabled switch in the list, to control whether the automation runs on its own:

• Active. A schedule runs on time, and an event automation runs on matching events.
• Paused. Nothing runs on its own. The schedule doesn't run and matching events are ignored. Items already in the ledger stay where they are. Questions can still expire.

The ▶ button runs the automation once by hand, even while it's paused:

• On an automation with bound agents, it's Fire now: a real run of every bound agent.
• On a work shape, it's Sweep now: the same pass the schedule runs. It scans the source for new items, then starts a run for every item that's ready to move, side effects included.

On a paused automation, ▶ asks you to confirm first. Only one pass runs at a time, so if a pass is already running, the new sweep is skipped.

The status chip reads Active, Paused, or Error. Error means the automation can't do anything useful yet, for example:

• no stage runs an agent;
• a schedule has never run, or is overdue;
• an event automation is still waiting for its first event.

Hover over the chip to see the exact reason.

Watch it work

Overview

The Overview starts with health tiles. Each one links to the tab that explains it:

• Schedule: On time, Overdue, Never fired, or Paused.
• Last pass, or Last fire on an automation with bound agents.
• Items stuck: how many items are FAILED or DEAD.
• Stage agents: whether every agent a stage names exists and is deployed.

Below the tiles, Work draws the stages in the order items travel through them. Each stage shows what's in it right now, such as 2 need attention, 5 waiting, 12 backlog · 3 processing, or 40 finished. Click a count to open the Work tab filtered to those items.

On a schedule, the Passes tab lists every pass, with what it admitted, dispatched, finished, and spent. A pass with 0 runs had nothing to do. An event automation has an Events tab instead.

The Work tab

The Work tab is the item ledger. From top to bottom it shows:

• The summary row: whether the source scan is current (Up to date, Scanning, Scan is stale, Never scanned, or Not scanning while paused) and when it last ran. It also shows the number of items, the total spend with the cost per finished item, and how many items need attention.
• Paused stages, Cohorts, open questions, and batch stages, when there are any. Each is covered below.
• One row per stage: its total, cost, and spend limit, and a chip for each status. Click a status chip to filter the grid to that stage and status.
• The item grid, newest first. Filter it by Stage and Status, and click a row to open the item's history.

If the Work tab says Nothing admitted yet, the automation hasn't run since you saved it. Run it with ▶, or check the source with See what this returns.

Items and their states

The attempt count resets when an item moves on to its next stage, so the attempt limit applies to each stage separately. A failed item's row says when its next attempt is due and whether that attempt is its last.

An item's history

Click an item to open Item history. At the top are the item's data, with contact details masked, and its cost across every run. Below that, What happened, and when lists every step in the item's life: when it was admitted, picked up, moved on, failed, or excluded. Each step shows its stage, agent, attempt, duration, and cost. View run opens the trace of the run behind the step. Together, these steps show the item's runs across all of its stages. The API returns the same runs, grouped by attempt, from GET …/ledger/items/{item}/runs.

What it did outside Fruxon appears when a stage's agent declares a durable side effect, such as filing a row. It lists each effect and whether it landed. If an earlier attempt didn't record how an effect ended, the effect shows as unknown. The platform won't repeat it, so the item can't move on. To fix this:

1. Check the external system.
2. Click Settle and answer Did this actually happen?.
3. Re-drive the item.

Re-drive and ignore items

To act on one item, use the actions on its row or in its history. To act on several, select their rows and use the bar above the grid. Under a status filter, Select all N selects every matching item, including those beyond the current page. Items that a pass has picked up are never changed.

A bulk action is checked against the item count you saw. If the matching set has changed by the time you act, the action is refused and the current count is returned. Re-driving exclusions has to name a reason or specific items, because each one costs an agent run.

Batch stages

Turn on Process in batches on a Process stage when the agent has to see several items together, for example to merge similar questions into one article. The stage hands each group of items to a single run, and the agent returns one outcome per item.

A batch stage doesn't take an Items per pass at this stage limit. Use Running at once to cap how many batches run together. The automation must allow at least 2 attempts, because an item on its last attempt always runs alone.

On the Work tab, the batch panel shows:

• each group that's gathering, and when it will run;
• each batch running now, and its cost.

Run gathered groups now runs every gathering group without waiting. Cancel on a running batch sends its items back to gathering and refunds their attempt.

Cohorts

A cohort is a set of items admitted together, such as one backfill, followed to the end as a single unit. A cohort can measure the cost on a sample before the rest of the source is admitted, and it can run follow-up steps once every item has finished.

On the Work tab, click Start a cohort. This runs one pass now, even if the automation is paused. Every item that pass admits joins the cohort, and so does every item later passes admit, until the source has been listed to the end.

• Name: shown on the Work tab. Leave it empty to name the cohort by its date.
• Estimate the cost from a sample first: admits only Sample size items (3 to 500, default 20) and runs them for real. The rest of the source stays unread until you confirm the estimate. Event automations don't offer this, because they have no source to hold back.
• Keep taking items until I seal it: keeps the cohort open after the source has been listed to the end.

Click a cohort to open it. Once the estimate is ready, the cohort shows what the rest of the source should cost, based on what the sample cost. It also lists which agents' spend limits that cost would cross. You have two choices:

• Confirm and run the rest admits the rest of the source and starts working through it, even on a paused automation.
• Keep only the sample seals the cohort with only the items that already ran.

If the estimate changes while you're reading it, the confirm is refused and the cohort shows the new numbers.

You declare follow-ups through the API, in the cohorts block of the work shape. They run once, in order, when the cohort finishes. A follow-up step can email people, run a platform hook, or run an agent over the cohort's summary. A step that stops partway, with no record of whether it happened, isn't retried on its own. Check whether it happened, then mark it done or not done in the cohort.

The same block can also:

• open one cohort per day (window: "DAY");
• set a deadline after sealing (settleWithinHours);
• confirm an estimate automatically when it's under a credit amount (confirmAboveCredits).

Spend limits and paused stages

A stage has no budget of its own. Its runs count against the spend limits of the agent it runs: the agent's production limits that cover every environment. Every production run of that agent counts toward them, not only this automation's runs. New agents start with enforced limits of $5 a day, $20 a week, and $50 a month, so a busy automation can reach them quickly.

Each Process stage row on the Work tab has a chip showing what the agent has spent against its tightest enforced limit. If you're an admin of the agent, click the chip to change the limits. See Cost & Budgets for how agent spend is counted.

When the agent goes over an enforced limit, the stage's next run is refused before it starts. The item that run was for is marked FAILED with its attempt refunded, and Fruxon pauses the whole stage instead of retrying item by item. The Work tab shows stage is paused, with when it starts again, and the stage's row shows paused until a time or date. While a stage is paused:

• Its items wait at that stage, and nothing is lost. Refused runs never use up attempts, so they can't push an item to DEAD.
• Other stages keep running.
• The stage starts again on its own when the limit's period resets. Periods are calendar days, weeks, and months in UTC. If the daily and weekly limits are both used up, the stage waits for both to reset.

To restart it sooner, click Raise limit, then Resume now. Resume now runs a pass that only picks up items at that stage and admits nothing new. While the agent is still over its limit, Resume now is disabled, because the first run would be refused and the stage paused again.

Runs refused for other reasons, such as a workspace running out of credits, pause the stage in the same way. The stage tries again after 15 minutes, and the wait doubles with each refusal, up to 24 hours. The banner names the reason, and Resume now tries again immediately.

Limits and concurrency

Three different limits decide how much an automation does at once, and they're easy to confuse:

The pickup limits don't stop a stage from running alongside itself. On an active automation, every item that finishes a stage starts another pass, and each pass picks up as many items as its limit allows. Use Running at once when only a fixed number of runs may be in progress.

Other limits you might run into:

• One pass at a time. The schedule, ▶, and Start a cohort all run the same kind of pass under one lock. A pass started while another is running is skipped.
• No backlog cap. A pass admits everything new that the source lists. To limit the first run, use Start from, Skip records when…, or a cohort with a sample.
• Bounded passes (API). You can limit a sweep with maxAdmit (stop admitting after this many new items; 0 admits nothing), maxDispatch (cap how many items the whole pass picks up), and stageIds (pick up items only at these stages). The limits apply to that pass only.

Reset the cursor or purge the ledger

You can only reset the cursor or purge the ledger through the API. Both actions are rare and destructive, so the Work tab has no buttons for them. Before either one, read the current cursor and item count with GET …/ledger/cursor and GET …/ledger/funnel. Neither action works on an automation that Knowledge manages.

Cursor reset only applies if the cursor hasn't moved since you read it. Send the version you read as expectedVersion. If a pass moved the cursor in the meantime, the reset is refused with 409, so it never undoes a pass.

Purge starts the ledger over. The automation doesn't need to be paused. Send the ledger's current item count as confirmItems, plus a reason. The purge is refused with 409 if the count doesn't match, or while a running pass holds an item. Open questions are cancelled before the cursor moves. So if a pass moves the cursor during the purge, the questions stay cancelled even though nothing is deleted.

API

All endpoints live under /v1/tenants/{tenant}/triggers/{trigger}. Reads need the triggers:read scope and Viewer access to the Application. Ledger, cohort, and stage-test actions need triggers:write and Editor access. :fire needs triggers:fire.

Two tenant-level endpoints help while you build an automation:

• GET /v1/tenants/{tenant}/workShapeDoors lists the sources a schedule can watch.
• POST /v1/tenants/{tenant}/triggers:testWorkShapeSource lists what a source returns, without recording anything.

Next steps

• Agent Network → Triggers: trigger kinds, payload namespaces, and content filters
• Knowledge Sources: sources that Fruxon builds on an automation and its ledger
• Cost & Budgets: how agent spend is counted
• Collection Pipelines: one agent run over every item in a list
• Observability: the traces behind each item's runs