Documentation · App Builder
Agents and automation
An app does its work through agents. A person starts one by filling the run form or writing in a chat. The app starts one by itself when something happens: a record is saved, a webhook arrives, a purchase completes, a date comes near, a person decides an approval. This page explains each part and how they fit together. The field-by-field list is in the reference.
Before agents can start: the AI provider
Agents run on the WebRobot platform, on the organisation that owns the app, with the app's own API key. The organisation needs an AI provider: its own LLM credential (in the console, under Credentials) or a managed plan.
If the organisation has none, the platform refuses the start:
- A run or a chat message started by a user fails with the platform's error message.
- An agent started by a trigger does not start. The refusal is recorded and the app's admins see it on the data page (
/admin/data), under Agents that did not start. When the reason is a missing AI provider, the page says so: "The organization has no AI provider: add one in the console (Credentials) or switch to a managed plan, then try again."
Agents
Each entry of spec.agents is one agent. At least one is required.
| Field | What it does |
|---|---|
key | The agent's name inside the app (lower case, digits, _, -). Other parts of the manifest point at it. |
role | main (default), designer, setup, analyst, helper, scheduled. The run form starts a main agent (see Choosing the agent of a run). |
description | What the agent does. It is also the profile description at publish, and it appears in the ask_<agent> tool other agents get. |
profile | Exactly one of ref or inline. |
goalTemplate | The task the agent receives. See Goal templates. |
context | Extra values resolved when a run starts. See Context. |
appTools | The tools the app gives this agent. See App tools. |
mcpServers | External services as MCP servers (up to 10), added to the agent at publish. |
delegates, awaits, memory | Edges to other agents, approvals and persistent memory. They generate tools. |
writesTo | Turns each finished scheduled, triggered or template run into a record. |
variables, startOptions | Values passed to the platform when the agent starts. |
Profile: ref or inline
profile.refpoints at an agentic profile that already exists on the platform, by id or by name.profile.inlineholds the whole agent definition (the Agent Studio contract). The manifest only checks that it hascrews. Each crew carries its model, its prompt and its own limits:
agents:
- key: waiter
description: Takes orders at the table
profile:
inline:
display_name: Trattoria waiter
crews:
- id: waiter
engine: agent_sdk
model: claude-sonnet-5-5
max_turns: 12
system_prompt: |-
You are the waiter of the trattoria. Answer briefly, in the customer's language.
The manifest has no model field of its own: the model is part of the profile.
Publishing creates (or updates) one platform profile per inline agent, named <slug>-<agent key>, in the app's organisation. The published manifest then carries ref instead of inline. Until you publish, an inline agent cannot run: a run or chat answers "agent <key> has an inline profile: publish the app first".
When an agent is the source of a chat view, publishing sets it to answer with its last message only, so its working notes between tool calls never reach the user.
Fields the runtime does not use yet
output, resultSchema and the agent-level limits (maxTurns, maxBudgetUsd, timeoutSeconds) are accepted by the schema, but the runtime does not apply them. Set the model's limits inside the inline profile instead.
variables and startOptions
variablessets profile variables. Each value is a template filled with the form values,{lang}and{user}.startOptionsadds fields to the platform's start call. The keysforceReauthor,llmProvider,engine,camoufoxMode,ttlSeconds,activeDeadlineSecondsandclusterSelectorgo as start options; any other key travels as an input next to the goal.
Goal templates
goalTemplate is the text the agent receives as its task. The runtime fills it before the start.
| Syntax | Meaning |
|---|---|
{name} | Replaced by the value. A list becomes a, b, c; an object becomes JSON; an empty value becomes nothing. |
{?name}…{/name} | The block is kept only when name is not empty. |
{!name}…{/name} | The block is kept only when name is empty (the "else" of an optional block). |
A value is empty when it is missing, "", false or an empty list. Blocks can be nested and can span lines. A line left blank because its blocks were dropped is removed. Every {?x} and {!x} must be closed with {/x}, or validation fails.
goalTemplate: |-
Write a city brief for {city} ({country_label}).
{?focus}Focus on: {focus}{/focus}
{!focus}Cover transport, housing and safety.{/focus}
Answer in {lang}. Today is {date}.
Which values a goal can use
What fills the template depends on what started the agent.
A run from the form
- every form field, by name; for a field with options,
{<field>_label}is the label of the chosen option(s) in the run's language - for a file field,
{<field>}is the file names (with their ids) and{<field>_text}the text extracted from them - the values of
contextentries and of slots {date}(YYYY-MM-DD, UTC),{lang},{user}(the user's email),{role}
Without a goalTemplate, the goal is one Label: value line per filled form field.
A chat message
{message} (the new message), {history} (the conversation so far), {session}, {date}, {lang}, {user}, {role}. The default template is:
{?history}Conversation so far:
{history}
{/history}New message:
{message}
A trigger (see Triggers)
- every field of the event's record whose name is lower case (letters, digits,
_), exceptuserId; an object field becomes JSON, cut at 4,000 characters {record.<field>}, the same fields under the record's name{event}, the whole event as JSON, cut at 8,000 characters{date}
The text used is the trigger's goal, else the started agent's goalTemplate, else An event happened in the app: {event}. Do your task for it.
The app's tools find a record by its id. So when the goal names neither {event}, {id} nor {record.id}, the runtime adds a last line with the record's reference: (The record: collection <name>, id <id>.).
A schedule or a timer trigger (on.cron): {date} and {lang}. A schedule uses its goal, else the agent's goalTemplate, else Run your scheduled task for {date}. A timer trigger uses its goal, else Run your scheduled task for {date}.
A template instance: its parameters by name, {instance} (the instance's title), {date}, {lang}, {user}.
A placeholder nothing fills becomes an empty string. Validation refuses a placeholder that is not a form field, a context key, an option label, a file text or a built-in, except in agents started by a trigger, where the record decides which fields exist.
What the runtime adds after the goal
- The app session. An agent that has app tools gets a last paragraph:
App session for this task: s_… — pass it as "session" to the app's tools.The session belongs to the user the work is for and lasts 3 hours. It is how the tools know whose records they may touch. - The memory. An agent with
memorygets what it remembers about the user (see Memory).
Context
context entries add values to the goal, resolved when a run starts. The value goes under the entry's key.
from | Value |
|---|---|
collection:<name>.<field> | That field of one record: the record chosen in a form field fed by optionsFrom: collection:<name>, else the user's latest record of that collection (for a collection owned by user). |
collection:<name> | The records of that collection the user may read, as one JSON line each: at most 30 records and 8,000 characters. |
user.<field> | A field of the signed-in user (email, …). |
slot:<key> | The output of a Python slot run on the form values. An object adds its fields to the values; anything else goes under the key. A failing slot stops the run before any credit is held. |
Records reach the agent only if the user may read them (the same rule as views and tools), without internal fields. The schema also lists session, page and derived:<extension>: the runtime does not resolve them yet.
App tools
appTools are the tools the app serves to the agent. The runtime serves them over the app's own MCP endpoint; publishing wires each agent to it with its own address and token. An agent sees and can call only its own tools and the ones its edges generate, never another agent's.
appTools:
- { name: find_dishes, description: "Dishes of the menu", action: search, collection: menu }
- { name: save_order, description: "Create or update an order", action: write, collection: orders }
- { name: company_lookup, description: "Company register", action: http,
http: { url: "https://api.example.org/companies", allowPath: true, attribution: "Example register, CC BY 4.0" } }
Tool names are lower case (^[a-z][a-z0-9_]*$). Two agents may declare a tool with the same name only if it does the same thing (same action, target and limits); the description may differ.
Every action
action | What the agent sends | What it gets |
|---|---|---|
read | id (optional) | With an id: that record, or null. Without: the records it may read, newest first, at most 50. |
search | where (fields that must be equal), text (looked for in any field), limit (1–100, default 20) | Matching records, newest first. |
show | same as search | Same as search: records meant to be shown in the reply. |
write | fields, id (optional) | With an id: updates that record (only if the user may write it). Without: creates a record. Returns the record. |
append | fields | Always creates a record. |
read_file | file (a file id f_… from the task) | The user's own file: its text, or for an image the image itself (up to 5 MB), handed to the model as an image. |
call | args | Runs the Python slot named in slot, with {args, userId}. Returns the slot's output. |
http | query, path (only with allowPath), body (JSON, not for GET/DELETE) | One request to an external HTTPS API. See Messaging and egress. |
delegate | task | Generated from delegates. |
approval | summary, request | Generated from awaits. |
remember | notes | Generated from memory. |
Details:
fieldsmust be an object of at most 32,000 characters (as JSON).idanduserIdin it are ignored. A new record gets the collection's field defaults, the user's id,createdAtandupdatedAt.- A record created or updated by a tool is an event: the app's triggers fire on it.
- A
create:<collection>limit applies to records a user creates through tools (see Limits on agent starts). - A tool with
extensionis implemented by code outside the manifest. It is not served. - A
calltool needs the runtime's slot runner. Where it is missing the tool answers "slots are not available on this runtime". - Errors go back to the agent as a tool result it can read (for example "no such record", "fields too large").
Whose records a tool reaches
A tool needs the app session when its scope is user or session, when it is read_file, when it is an http tool with a user's credential, or when its collection is owned by user or instance. Then:
- the user reaches their own records, and the records the collection's access rules give their role (with
can: [write]for writes); - the app's admins reach every record;
- in a template instance's run, a collection owned by
instanceshows only that instance's records, and new records carry the instance.
A tool on an app, shared or org collection without a session reaches every record of that collection. Collection ownership is explained in Data.
Agents visitors use without signing in
auth.anonymous.agents names agents meant for visitors. Such an agent may not have:
- a tool on a collection owned by
org(the owner's back office); - a
writeorappendtool on a collection owned byapporshared; - an
httptool with a method other than GET, or with a user's own credential.
Validation refuses these, and the runtime refuses the call too. Note: today every chat message and every run needs a signed-in user, whatever auth.anonymous.agents says.
Delegation, approvals and memory
These three edges generate tools for the agent that declares them.
delegates: [other]gives the toolask_<other>(dashes become_). The agent sends atask(up to 8,000 characters); the runtime starts the other agent with the same user's session and waits up to 150 seconds. It returns{answer},{error}, or{status: "still working", runId}. An agent cannot delegate to itself, and delegation cannot loop.awaits: [approval]gives the toolrequest_<approval>. See Approvals.memory: user | instancegives the toolremember. Memory is one text per user (or per template instance withinstance), at most 4,000 characters. It is added to every task of the agent under "What you remember about this user (update it with the remember tool):".rememberreplaces the whole text.memory: instanceneeds a template that uses the agent.
Runs
A run is one background execution of an agent started from the run form (spec.inputForm). This is how the report pattern works.
Choosing the agent of a run
The run form starts a main agent. If several agents have role main, the first whose when condition matches the form values runs (for example when: "mode == 'market'"); else the first main agent.
From start to report
- The user submits the form. The runtime checks the values: required fields, types,
maxLength, options, a choiceparent, and plans (gatedByanswers 402 "needs the plan …"). - File fields keep only files this user uploaded. A select fed by a collection must hold a record the user may read.
- Slots and context entries are resolved.
- Limits are checked (
run,agent:<key>), then the plan the cost needs (requiresPlan). - Hold. The estimated credits are taken from the balance. Without enough credits the start fails with 402 "not enough credits". Admins run for free.
- The goal is built, with the app session and the memory, and the agent starts on the platform. If the start fails, the hold is returned.
- Poll. The run page (
/r/<id>) asks for the run's state every 5 seconds. The user can leave: the report stays there. - Settle. When the agent ends, its final text becomes the report, kept from its first
#heading; that heading is the run's title. Credits are settled once: no report, full refund; a fixed price, the hold is the price; a metered price, the real usage (see Billing).
A run without a report ends as error with the platform's error, or "the agent ended without a report".
With notifications.emailOnRunDone: true, the user gets an email when the run ends, and the scheduler collects runs nobody is watching. See Messaging.
History and report
- A
historyview lists the user's runs, newest first, with title, status and date. - The run page shows progress, then the report. It is printable unless the
reportview setsprintable: false. Only the user who started the run and the app's admins can open it. - The
adminview lists the latest 30 runs of all users.
writesTo does not apply to form runs: a form run's result is its report.
Chat
A chat view is a conversation with one agent: the view's source: agent:<key>, else the first main agent.
- Only signed-in users can chat. A visitor is asked to sign in.
- A message is at most 2,000 characters. The agent gets the last 8 turns of the conversation (
{history}, each message cut at 800 characters) and the new{message}. - One reply at a time: a second message while the agent is answering gets "the assistant is still answering". A reply that does not come within 10 minutes is given up.
- The browser checks for the reply every 3 seconds.
- If the agent fails, the user sees "I could not answer that, please try again." and any credits taken for the message are returned.
- Each message costs the agent's fixed cost (
billing.costs["agent:<key>"], or itsestimate); admins chat for free. - Rate limit: 30 messages an hour per user and 60 an hour per IP address.
Service hours. With spec.serviceHours, the organisation's dedicated chat server is turned on during those hours (from leadMinutes before each opening, default 10). Inside them, a message is answered within the same request and the server keeps the conversation. Outside them, or when that server is not ready, each message is one agent run as above. Today, messages answered by the chat server are not charged in credits to the user; their usage is metered to your organisation.
Teams
spec.teams groups agents into one unit, published as one agentic profile.
mode: sequence—stepsrun one after the other; a step withafterruns after the steps it names. The steps must not form a cycle, and an agent may appear once.mode: swarm— aleadplans and closes the work;membersshare a task board.maxMinutes(1–180) bounds the swarm.
Every member must have an inline profile (the team's profile is built from their crews). A team's key cannot be an agent's key. Triggers and templates start a team with start.team / team; writesTo turns its result into a record.
Triggers
A trigger connects an event to an action. It has exactly one source (on) and exactly one action.
triggers:
- key: to_kitchen
description: Every confirmed order goes to the kitchen
on: { collection: orders, op: any, where: { status: confirmed } }
start: { agent: kitchen }
asUser: false
Sources (on)
| Source | Fires when |
|---|---|
collection (+ op, where) | A record of the collection is created (op: insert, default), updated (update) or either (any), and every where field is equal. |
cron | A 5-field cron expression (UTC) matches. |
date (collection, field, offsetDays, hour) | Once a day from hour UTC (default 7): for each record whose date field, moved by offsetDays (−365…365, default 0), is today. Each record fires once per date. where filters the records. |
webhook: true | Someone calls POST /api/hooks/<trigger key> with the hook secret. |
payment | A purchase of that plan or pack completes; * for any purchase. |
approval (+ decision) | A person decides that approval: approved, rejected or any (default). |
call (+ callEvent, where) | A phone channel's call. Not available yet: see Messaging. |
A record becomes a collection event when it is saved by a form or booking view, on the admins' data page (not a CSV import), by an agent's write/append tool, by a trigger's write, or by writesTo.
Webhooks. The console shows each webhook trigger's address and secret to the app's organisation. Send the secret in the X-Hook-Secret header. A sender that can sign may add X-Hook-Timestamp (Unix seconds, within 5 minutes) and X-Hook-Signature (hex HMAC-SHA256 of <timestamp>.<raw body> with the secret); a wrong or stale signature is refused. The body is at most 64,000 characters; JSON is parsed, anything else is kept as text. The answer is 202 with what started. Webhooks do not work on the preview address.
Actions
| Action | What happens |
|---|---|
start: {agent | team | job} | Starts one agent, team or data job. The goal is built as in Goal templates. |
notify | Sends a plain-text email (and a push notification on the phone app). See Messaging. |
write | Saves the event's data as a record, without an agent. |
charge | Takes credits from the event's user. See Billing. |
asUser (default true): the started agent works with the app session of the user the event belongs to (the record's userId, the requester of an approval, the buyer) and reaches only their records and their memory. With false, or when the event has no user (a webhook, a timer), it runs without a user.
write. Saves into write.collection: with fields, each record field takes the value at that dot path of the event's data; without, the event's fields the collection declares. With keyBy, the record's id comes from that field, so the same event saved twice updates the same record. A collection owned by user needs an event with a user; a collection owned by instance cannot be written. The record is at most 32,000 characters and is an event in turn.
Agents and jobs started by triggers are tracked like scheduled runs: when they finish, the scheduler turns the result into a record of the agent's (or team's) writesTo collection. A job needs to be linked (published); otherwise nothing starts ("not linked").
Loop protection. One app starts at most 20 trigger actions a minute; the rest are skipped. An agent that writes the collection that starts it needs a where filter (validation).
Schedules
spec.schedules runs work on a timer.
schedules:
- cron: "0 6 * * 1-5"
agent: daily_signal
goal: "Write today's signal for {date}."
deliver: { to: admins, onlyIfNew: true }
action | With | What the runtime does |
|---|---|---|
run (default) | agent | Starts the agent. |
digest | agent | Same as run. |
run, ingest | job | Starts the linked data job. |
settle | — | Checks up to 50 runs that are still running or not settled. |
sync | — | Not run by the runtime. |
owner: app(default) schedules are run by the runtime's scheduler.owner: platformschedules are left alone by the runtime.- Cron expressions have 5 fields, in UTC:
*, lists, ranges and steps. Sunday is 0 or 7. - The scheduler ticks every few minutes. Each schedule fires once per matching minute since the last tick. After an outage it catches up at most the last 3 hours.
- A scheduled run has no user: no app session, no credits charged.
- When the run finishes, its result becomes a record of the agent's
writesTocollection.parsedecides how:whole(default, the report),markdown_sections(one field per##heading),json_lastorfinal_block(the final JSON block's fields).keyBytakes the record id from a field (for exampledate), so a rerun updates the same record. A run still not finished after 6 hours is marked as failed ("timed out"). deliveremails the report. See Messaging.
Templates and instances
A template is an agent the app's users create for themselves, with their own parameters, schedule, data and memory. Each copy is an instance.
templates:
- key: watch
title: Price watch
agent: watcher
params:
- { name: product_url, type: url, required: true }
- { name: threshold, type: number }
schedule: { cron: "0 8 * * *", userCanChange: true }
maxPerUser: 5
cost: { perRun: 3 }
deliver: { onlyIfNew: true }
views:
- { key: my_watches, type: instances, template: watch, title: My watches }
- A template names exactly one
agentorteam. Its params are form fields: checked for required, number, boolean,url(must start withhttp://orhttps://), options, length (default 2,000 characters). - An
instancesview lets the user create, run, pause, resume, update and delete their instances, and shows the latest result of each. maxPerUser(1–1000, default 5): beyond it, "you can have at most N".roleslimits who may create one.- The user may set their own cron when
schedule.userCanChangeis notfalse. The cron must have 5 fields made of digits,*,,,/,-. - Every active instance with a cron runs when it is due. The goal is the template's
goal, else the agent's (or team's)goalTemplate, else onename: valueline per parameter. cost.perRuncredits are taken from the instance's owner before the start. Without enough credits nothing starts and the instance shows "no credits". A run that produces no result gives the credits back. An admin running their own instance by hand pays nothing.cost.perMonthis not charged yet.- Collections owned by
instancekeep each instance's records apart. One record per run goes to the agent'swritesTocollection. deliveremails each report to the instance's owner by default.- Instances cannot be created on the preview address.
Approvals
An approval is a checkpoint where a person decides before the work goes on.
approvals:
- key: refund
title: Refund over 100 €
role: manager
fields: [order_id, amount]
timeoutMinutes: 1440
onTimeout: reject
agents:
- key: support
awaits: [refund]
# ...
triggers:
- key: refund_approved
on: { approval: refund, decision: approved }
start: { agent: refunds }
views:
- { key: approvals, type: approvals, roles: [manager] }
How it works
- The agent calls
request_<key>with a one-linesummary(up to 500 characters) and therequestdetails (up to 32,000 characters as JSON). - The tool answers at once with
status: pending. The agent tells the user the request is waiting; its run then ends normally. - A person opens an
approvalsview, sees the pending requests they may decide (with thefieldsof the request) and approves or rejects, with an optional note (up to 1,000 characters). - The decision is an event. The work resumes only through a trigger on that approval: it starts an agent (the same or another one) whose record is the request's fields plus
approvalId,summaryandnote. WithasUser(default), that agent works for the user who asked.
An approval that no agent awaits is refused by validation.
Who decides
decidedBy: role(default): people with the approval'srole, and the app's admins. The role must be a staff role (assigned from admin emails, by invite or derived), never the role anyone gets at signup.- Nobody decides their own request — admins included: "you cannot decide your own request".
decidedBy: requester: only the user whose agent asked confirms it (for example a shortlist the agent proposed to them). It takes norole.- A request is decided once; a second decision gets "already decided".
Timeout
With timeoutMinutes (1–10,080), a request still pending at the deadline is decided by the scheduler with onTimeout: reject (default) or approve. The decision is recorded as made by timeout, and the triggers fire with approved or rejected.
Limits on agent starts
spec.limits caps how often agents start and how many records users create.
action | Counts | per | Applies to |
|---|---|---|---|
run | all of a user's form runs | user (default) | runs started from the form |
agent:<key> | a user's form runs of that agent | user (default) | runs started from the form |
agents | every agent start by events | app or user | agents started by triggers |
agent:<key> | starts of that agent by events | app or user | agents started by triggers |
create:<collection> | records a user creates | user (default) | agent tools and form views |
limits:
- { action: run, max: 3, window: day, plans: { pro: 50, business: -1 } }
- { action: agents, per: app, max: 200, window: day }
- { action: "agent:kitchen", per: user, max: 10, window: hour }
window:minute,hour,day,month(30 days) ortotal(ever). Windows are sliding: "the last day" counts back from now.plansgives a plan or pack its own max;-1= unlimited. A user with several plans gets the highest.roleslimits a form-run limit to those roles.- For event starts,
per: appcounts every start of the app andper: userthe starts on that user's events;permust be written explicitly, andtotalis not counted. Anagent:<key>limit withper: usertherefore caps the user's form runs and, separately, the starts on their events; withper: appit caps only starts by events. - The app's admins are not limited on form runs and on the records they create. Limits on starts by events count every start, whoever the event's user is.
create:limits on form views do not look atplans: everyone getsmax.
When a limit is reached, a form run gets 429 "limit reached: N per day" (or "N in your plan" for total). A start by an event is refused with "limit reached: N agent starts per hour for the app" (or "for this user"); the refusal is recorded and shown to the admins under Agents that did not start on the data page. The page shows the newest 8; the app keeps the newest 30.
per: ip and per: org are accepted by the schema but not enforced. The chat and login actions are not read from spec.limits: chat and sign-in have fixed limits (see Runtime).