WebRobot
App Builder · pages

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.

FieldWhat it does
keyThe agent's name inside the app (lower case, digits, _, -). Other parts of the manifest point at it.
rolemain (default), designer, setup, analyst, helper, scheduled. The run form starts a main agent (see Choosing the agent of a run).
descriptionWhat the agent does. It is also the profile description at publish, and it appears in the ask_<agent> tool other agents get.
profileExactly one of ref or inline.
goalTemplateThe task the agent receives. See Goal templates.
contextExtra values resolved when a run starts. See Context.
appToolsThe tools the app gives this agent. See App tools.
mcpServersExternal services as MCP servers (up to 10), added to the agent at publish.
delegates, awaits, memoryEdges to other agents, approvals and persistent memory. They generate tools.
writesToTurns each finished scheduled, triggered or template run into a record.
variables, startOptionsValues passed to the platform when the agent starts.

Profile: ref or inline

  • profile.ref points at an agentic profile that already exists on the platform, by id or by name.
  • profile.inline holds the whole agent definition (the Agent Studio contract). The manifest only checks that it has crews. 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

  • variables sets profile variables. Each value is a template filled with the form values, {lang} and {user}.
  • startOptions adds fields to the platform's start call. The keys forceReauthor, llmProvider, engine, camoufoxMode, ttlSeconds, activeDeadlineSeconds and clusterSelector go 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.

SyntaxMeaning
{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 context entries 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, _), except userId; 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 memory gets 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.

fromValue
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

actionWhat the agent sendsWhat it gets
readid (optional)With an id: that record, or null. Without: the records it may read, newest first, at most 50.
searchwhere (fields that must be equal), text (looked for in any field), limit (1–100, default 20)Matching records, newest first.
showsame as searchSame as search: records meant to be shown in the reply.
writefields, id (optional)With an id: updates that record (only if the user may write it). Without: creates a record. Returns the record.
appendfieldsAlways creates a record.
read_filefile (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.
callargsRuns the Python slot named in slot, with {args, userId}. Returns the slot's output.
httpquery, path (only with allowPath), body (JSON, not for GET/DELETE)One request to an external HTTPS API. See Messaging and egress.
delegatetaskGenerated from delegates.
approvalsummary, requestGenerated from awaits.
remembernotesGenerated from memory.

Details:

  • fields must be an object of at most 32,000 characters (as JSON). id and userId in it are ignored. A new record gets the collection's field defaults, the user's id, createdAt and updatedAt.
  • 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 extension is implemented by code outside the manifest. It is not served.
  • A call tool 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 instance shows 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 write or append tool on a collection owned by app or shared;
  • an http tool 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 tool ask_<other> (dashes become _). The agent sends a task (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 tool request_<approval>. See Approvals.
  • memory: user | instance gives the tool remember. Memory is one text per user (or per template instance with instance), 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):". remember replaces the whole text. memory: instance needs 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

  1. The user submits the form. The runtime checks the values: required fields, types, maxLength, options, a choice parent, and plans (gatedBy answers 402 "needs the plan …").
  2. File fields keep only files this user uploaded. A select fed by a collection must hold a record the user may read.
  3. Slots and context entries are resolved.
  4. Limits are checked (run, agent:<key>), then the plan the cost needs (requiresPlan).
  5. Hold. The estimated credits are taken from the balance. Without enough credits the start fails with 402 "not enough credits". Admins run for free.
  6. 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.
  7. Poll. The run page (/r/<id>) asks for the run's state every 5 seconds. The user can leave: the report stays there.
  8. 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 history view 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 report view sets printable: false. Only the user who started the run and the app's admins can open it.
  • The admin view 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 its estimate); 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 — steps run one after the other; a step with after runs after the steps it names. The steps must not form a cycle, and an agent may appear once.
  • mode: swarm — a lead plans and closes the work; members share 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)

SourceFires 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.
cronA 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: trueSomeone calls POST /api/hooks/<trigger key> with the hook secret.
paymentA 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

ActionWhat happens
start: {agent | team | job}Starts one agent, team or data job. The goal is built as in Goal templates.
notifySends a plain-text email (and a push notification on the phone app). See Messaging.
writeSaves the event's data as a record, without an agent.
chargeTakes 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 }
actionWithWhat the runtime does
run (default)agentStarts the agent.
digestagentSame as run.
run, ingestjobStarts 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: platform schedules 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 writesTo collection. parse decides how: whole (default, the report), markdown_sections (one field per ## heading), json_last or final_block (the final JSON block's fields). keyBy takes the record id from a field (for example date), so a rerun updates the same record. A run still not finished after 6 hours is marked as failed ("timed out").
  • deliver emails 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 agent or team. Its params are form fields: checked for required, number, boolean, url (must start with http:// or https://), options, length (default 2,000 characters).
  • An instances view 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". roles limits who may create one.
  • The user may set their own cron when schedule.userCanChange is not false. 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 one name: value line per parameter.
  • cost.perRun credits 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.perMonth is not charged yet.
  • Collections owned by instance keep each instance's records apart. One record per run goes to the agent's writesTo collection.
  • deliver emails 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

  1. The agent calls request_<key> with a one-line summary (up to 500 characters) and the request details (up to 32,000 characters as JSON).
  2. The tool answers at once with status: pending. The agent tells the user the request is waiting; its run then ends normally.
  3. A person opens an approvals view, sees the pending requests they may decide (with the fields of the request) and approves or rejects, with an optional note (up to 1,000 characters).
  4. 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, summary and note. With asUser (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's role, 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 no role.
  • 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.

actionCountsperApplies to
runall of a user's form runsuser (default)runs started from the form
agent:<key>a user's form runs of that agentuser (default)runs started from the form
agentsevery agent start by eventsapp or useragents started by triggers
agent:<key>starts of that agent by eventsapp or useragents started by triggers
create:<collection>records a user createsuser (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) or total (ever). Windows are sliding: "the last day" counts back from now.
  • plans gives a plan or pack its own max; -1 = unlimited. A user with several plans gets the highest.
  • roles limits a form-run limit to those roles.
  • For event starts, per: app counts every start of the app and per: user the starts on that user's events; per must be written explicitly, and total is not counted. An agent:<key> limit with per: user therefore caps the user's form runs and, separately, the starts on their events; with per: app it 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 at plans: everyone gets max.

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).