User guide › Apps › AI agents
An agent is a saved mission plus a set of rails. The mission is written in plain language — "check sales vs stock and propose a purchase within our budget". The rails are yours: when it runs, which tables it may read, whether it may propose changes, how long it may think for and how much it may spend.
When it runs, it isn't following a script you drew. It decides which data to pull, pulls it, reasons about what it found, pulls more if it needs to, and finishes by writing a report. Every one of those steps is recorded so you can see how it got there.
| Use | When |
|---|---|
| Automations | You know the exact steps. "When status becomes Won, send the contract." Deterministic, free, instant. |
| An agent | You know the goal but not the steps, and the answer needs judgement. "Look at the month and tell me what's going to run out." |
They compose: an automation can invoke an agent as one of its actions, handing over the record that triggered it.
Building one
Agents in the menu (/agents) lists what exists, with each
agent's trigger, autonomy, status and last run. New agent opens the
editor. It's one long form in five sections.
1 · Mission
Name, an optional Description, and the Mission — the part that matters. The hint is the whole philosophy: Describe the goal in plain language. The agent plans and executes the steps using the data it can read.
The editor's own example shows the register you're aiming for:
"Check this month's sales per product, compare against current stock, and propose purchase orders for anything that will run out within 3 weeks — stay within our monthly purchasing budget."
Note what that does: it names the data, names the comparison, names the output, and names a constraint. A mission of "keep an eye on stock" gives you a vague report, because you asked a vague question.
Status is Draft, Active or Paused. Only Active agents are picked up by schedules and events — a draft can still be run by hand, which is how you test one before letting it loose.
2 · Trigger
| Trigger | Fires |
|---|---|
| Manual | Only when you press Run now. |
| Scheduled | On a recurring schedule. |
| On record event | When a record is created or updated. |
Scheduled takes a 5-field crontab with presets to save you the syntax — Hourly, Daily 8:00, Mondays 9:00, 1st of month — plus a Timezone. Set the timezone: it's what makes "daily 8:00" mean eight in the morning where you are rather than in UTC.
A scheduled agent then runs in one of three modes:
| Mode | What fires |
|---|---|
| Single run | One agent run per fire. The default. Good for digests and sweeps. |
| Per matching record | One run per matching record, each with that record as context. "For every overdue invoice, chase it." You pick the entity to scan, a filter, and a Max runs per fire cap. |
| Only when records match | One run, fired only when enough records match the filter. Set Fire when at least N. Nothing matches, nothing runs, nothing is spent. |
Each run in a fan-out is a separate billed AI job. That's exactly why Max runs per fire exists — each run is a billed AI job (default 25, max 100). Set a monthly spend cap as well before you point one of these at a big table.
On record event asks for the entity (When this entity changes), whether it's Record created or Record updated, and an optional Only when filter. With no filter it fires on every matching record event, which on a busy table is a lot of runs. The filter builder has the full operator set — equals, contains, greater than, between, is empty, matches regex, and for updates the two that need history: has changed (update) and was (before update).
3 · Access & autonomy
This section is the safety model. Two decisions.
| Autonomy | Means |
|---|---|
| Read-only | Analyse + report. Never writes. |
| Gated write | Proposes record writes for your approval. |
There is no third option, and that's the design: Gated agents stage writes as proposals you approve before anything is saved. An agent never edits your data directly. The most it can do is put a change in a queue with a reason attached.
Can read is the list of entities it may look at. Leave it as All entities and the agent can read every entity in this workspace — convenient, and worth narrowing for anything sensitive. Can propose writes to is the separate list of entities it may stage changes into. If you leave it empty on a gated agent the editor warns you: With no write target the agent gets no propose tools and runs read-only — it can only report, not stage proposals.
Both grants are enforced on the server, in the tools the agent is given and again when a proposal is applied. An agent cannot read or write its way outside them.
4 · Delivery
By default a report sits in the run history waiting to be read. Delivery gets it out to people. Three opt-in channels:
| Channel | Does |
|---|---|
| Post to internal chat | Send a message to a team room — e.g. a morning digest. Needs the Internal Chat app installed. |
| Email a workspace member | Send the report to a member's inbox. Never sends outside the workspace. |
| In-app notification | Ping a member's notification bell with a headline + link to the agent. |
Delivery is immediate — it isn't gated by approval, because sending a report isn't changing your data. The hard limit is who it can reach: always limited to this workspace — team rooms and members only. An agent cannot email an outside address or post into a direct message, no matter what the data it read tells it to do. Messages an agent posts to chat are labelled with the agent's name so nobody mistakes them for a colleague.
5 · Guardrails
| Guardrail | Does |
|---|---|
| Max steps | Tool iterations before the agent must finish (default 14). Stops an agent circling forever. |
| Max records per scan | Cap on rows any single read pulls (default 5000). |
| Max spend per run (US cents) | Hard stop-loss: the run aborts once its estimated LLM spend crosses this. Empty = no cap. |
| Max spend per month (US cents) | Hard cap on this agent's total run spend per calendar month (UTC). Empty = no cap. |
| Budget / scope note | Free-form rail spliced into the agent's instructions. e.g. "Stay under a 50,000 GEL monthly purchasing budget." |
| Output format | How you want the report structured. Ask for a table, bullets, a specific set of headings. |
Budget / scope note goes into the agent's instructions and is respected the way instructions are respected. The two Max spend fields are mechanical — the run is stopped. Use the note for business constraints ("don't order past our credit limit") and the caps to bound what the agent itself costs. A per-run cap is a stop-loss, not a precise ceiling: a step's cost is only known once it has run, so the run stops just after the line is crossed, not just before. When a run is stopped this way its staged proposals are discarded — they never reach you for approval.
One checkbox sits apart: Allow the agent to search the web and read public pages during a run (adds cost; workspace data never leaves). Off by default. Turn it on when the mission genuinely needs outside information — a supplier's public price list, a published rate.
Running it
- Test (dry run) — Preview the mission: reads and reports only — no proposals, no chat/email/notifications. This is how you check a mission does what you meant before it can touch anything. Dry runs are tagged dry run in the history.
- Run now — a real run, on demand, from the list or the editor.
- Scheduled and event agents fire on their own, but only while Active.
Runs happen in the background. Starting one doesn't hold up your screen, and closing the tab doesn't cancel it — the run appears in the history and updates as it goes.
A mission is a prompt, and prompts are iterative. Expect two or three passes before a report looks the way you want. Do that on dry runs while the agent is still a draft — it costs less, changes nothing, and stops a badly-worded mission from generating a queue of proposals you have to reject one by one.
Reading a run
Every run is kept. An agent's own runs are listed in the Runs section of
its editor; the cross-agent view is Runs from the list page
(/agents/runs).
| Run status | Means |
|---|---|
| Running | In progress — The agent is working… |
| Needs approval | It finished and staged changes. Nothing has been saved yet. |
| Done | Finished. Either it had nothing to propose, or its proposals were approved. |
| Error | It failed, or hit a spend cap. |
| Rejected | You turned its proposals down. |
| Cancelled | Someone stopped it mid-flight. |
Open a run and you get four things:
- A one-line summary, or (no summary) if it didn't write one.
- Report — the written findings, formatted.
- The step trace — every tool call the agent made and what came back. This is where you look when a report says something surprising: you can see exactly which records it read to get there.
- Tokens and cost for that run.
If the agent was edited after a run, the run shows Mission at run time (agent edited since) — each run keeps a copy of the definition it actually executed, so old history stays honest.
While a run is going you can Cancel it; whatever it had done up to that point is kept. Failed and cancelled runs get a Retry, which starts a fresh run with the same context.
The Runs dashboard
/agents/runs is the overview across every agent: tiles for
Runs (month), Errors (month), Tokens (month),
Cost (month) and Cost (all time); a
Per agent — this month table; and a Recent runs feed with a
status filter. Click any run to jump to the agent where the full report lives.
Check it weekly. An agent quietly erroring on every schedule tick, or one whose cost is drifting up, shows here long before anyone notices the reports stopped arriving.
Approving what an agent proposes
A gated agent that wants to change something ends its run at Needs approval and the run shows N proposed change(s) — review before applying. Each proposal is listed as a create or an update, on which entity, with the values and the agent's reason for it.
- Approve & apply — the changes are written. Once applied the run reports N change(s) applied and moves to Done. Approved writes are real record changes: any automation, SLA or notification that watches those records fires exactly as if a person had typed them.
- Reject — nothing is written and the run ends Rejected. Both outcomes record who decided and when.
It's all-or-nothing per run — you approve the batch, not individual lines. If most of a batch is right and one entry isn't, reject it, tighten the mission, and run again.
The agent's author gets a notification when a run needs approval. That's the only notification the app raises by itself, apart from failures — everything else is deliberately quiet.
Who can do what
Access to the app opens the agents list, the editor and the run history. Two further capabilities are granted per role under Settings → Module Access; admins pass everything.
| Capability | Unlocks |
|---|---|
| Run agents | Executing agents, plus cancelling and retrying runs. Without it a member can view agents and their runs but not run them. |
| Approve agent runs | Applying or rejecting an agent's staged record changes — separate, because it's higher-stakes than running one. |
Split these two. A team lead who can run agents but not approve their writes is a perfectly good arrangement — reports flow, and changes still cross a second desk. How grants stack is in Permissions & access.
Agents also run under the workspace's overall AI allowance, alongside every other AI feature — see AI in BackOffice for how that's plan-gated and metered.
Why didn't my agent run?
| Symptom | Check |
|---|---|
| A scheduled agent never fires | Its status. Only Active agents are picked up — Draft and Paused ones are skipped. Then check the timezone: the cron is evaluated in the timezone you set, and left at UTC it fires at a different local hour. |
| An event agent doesn't react | The Only when filter. A condition that never matches means the agent never fires. Also confirm you picked the right event — Record created won't fire on an edit. |
| Per-record mode ran fewer times than there are matching records | Max runs per fire. It stops at the cap (default 25) and leaves the rest. |
| Only when records match mode did nothing | Working as intended if fewer than Fire when at least N records matched. That's the point — no matches, no spend. |
| Runs land on Error | Open the run: the failure is recorded on it. Spend caps are the common cause — a run that crossed its per-run cap, or an agent that has used up its month. |
| Runs stopped happening partway through the month | Max spend per month is exhausted. It's checked before a run starts, so once it's hit the agent fails fast without spending anything. |
| Every run is refused before it starts | The workspace's AI allowance, not the agent. See AI in BackOffice. |
| The report says it couldn't find data you know exists | Can read. If the entity isn't granted, the agent genuinely can't see it. |
| A gated agent reports but never proposes anything | Can propose writes to is empty. Without a write target it gets no proposal tools and behaves read-only. |
| A dry run proposed nothing and sent nothing | Correct — a dry run strips the proposal and delivery tools by design. Use Run now for the real thing. |
| Chat delivery fails | The internal chat channel needs the Internal Chat app installed. Without it the tool reports an error rather than silently dropping the message. |
When a run fails, the agent's author is notified. If a scheduled agent then fails every minute, you get one notification, not hundreds — the alert re-arms after the next run that succeeds. Silence after the first alert doesn't mean it fixed itself; check the Runs dashboard.
Agents and the rest of your workspace
- Automations can call an agent. A rule can invoke one with the record that triggered it as context — "deal crossed 50k → run the risk-review agent." Building rules is Automations & logic.
- Approved writes behave like human edits. They fire the same downstream rules, so an agent proposing a purchase order can kick off your normal approval chain.
- What an agent can see depends on your schema. Clear entity and field names give better missions and better reports — see Building your workspace.
- Everything an agent spends is metered with the rest of your AI usage — AI in BackOffice.