Agents

What an agent is

An agent bundles its Instructions (its role, also called its system prompt), a model, the tools and resources it is allowed to use (tables, workflows, interfaces, sub-agents, applications, files, skills), its limits, and the ways it can be started (chat, webhook, schedule, chat widget). Each time it is started it runs a tool-calling loop: read the request, pick a tool, run it, read the result, and repeat until it gives a final answer or hits one of its limits.

The model can be a regular API model or a CLI agent (Claude Code, Codex, Gemini CLI, Mistral Vibe, or Cursor) that runs through a bridge. Which ones you can pick depends on what your administrator has set up; see Models & providers.

The Agents page

Open Agents in the sidebar. The page has six tabs:

Delegated tasks are not on this page: they live on the task board, under Board > Tasks. See Tasks & board.

Create an agent

You can ask the assistant in the chat to create an agent for you, or use the editor. The editor has three steps:

1. 1
   Basic Info

   Give the agent a name, write its Instructions (what it does, for whom, in what tone, as you would brief a new colleague), and add a description. An example picked under Start from an example: fills in the instructions, and also the name and the description as long as you have not changed them.

   The other steps are optional: Create Agent is available from this step once the default model is chosen, and everything stays editable later. An agent with a schedule is created from the last step, where the schedule asks for the instruction it runs. After you create an agent from the Agents page, its conversation opens, with three first messages to choose from while it is empty. A message you pick is placed in the composer, not sent.

2. 2
   Configuration

   Pick the Model Provider and Model Name, the tools and resources it may use, its skills, and its Credit Budget. Open Advanced mode for, in this order: Long-term memory and Web Search (the same two rows as under Advanced mode in the composer's Options tab), temperature, reasoning effort, the run limits and timeouts, Generation, Mailbox, Code sandbox, the per-turn loop guards, and context compaction. Collapsed, it still names a non-default choice (memory set to recall only, or web search off).

3. 3
   Integration

   Optional ways to start and reach the agent: Reach me outside the app (a chat channel), Webhook, Schedule, and Chat Widget (embed a chat on your website).

How an agent is started

Model & reasoning effort

Model provider and model name are both optional. Leave them empty and the agent uses the platform default model. An unknown provider and model pair is replaced by the default and reported back as model_substituted, so saving does not fail on a model that was removed. Saving an agent on a CLI agent you are not allowed to use is refused.

Temperature goes from 0 to 2 (default 0.7): lower is more predictable, higher more creative.

Reasoning effort is an optional setting with six levels: minimal, low, medium, high, xhigh, max. It is a level, not a token budget. Four consumers honor it: Claude Code, Codex, and the direct Anthropic and OpenAI APIs. Every other provider ignores it, and the editor hides it for them. Inherit (model default) leaves the choice to the model’s own default.

When several levels are set, a per-conversation choice wins over the agent’s value, which wins over the default an administrator set for the model.

Limits & timeouts

Four independent limits can stop a run. They sit under Advanced mode, and the editor shows the same defaults the platform applies.

Three more guards, under Advanced mode, stop a runaway agent:

A sub-agent started with execute gets a timeout: the value the calling agent passes, otherwise the sub-agent's own execution timeout, otherwise 600 seconds. Whatever the source, it is kept between 10 and 7,200 seconds.

Tools & scope

Integration tools (the catalog of external APIs) are chosen with Available integration tools:

Resource Access is a separate choice. A new agent has no access to your workflows, tables, interfaces, sub-agents, or applications until you grant it, one family at a time: all of them, none, a custom list, or Project (everything of that family in the agent's project, as the project is when the agent runs; offered when the agent belongs to a project). File Access can be limited to the project's files the same way. Three capabilities start on: File Access (all workspace files, in write mode), and, under Advanced mode, Web Search and Long-term memory (Can save and delete).

Each family also has a read or write mode. write (the default) allows everything; read allows only reading actions, for example get, list, and query_rows on a table, or get, runs, get_run, and wait_run on a workflow. File Access has its own read or write mode too, and Long-term memory (under Advanced mode) offers Can save and delete or Recall only.

Three capabilities are off until you turn them on, because they act on the outside world:

The Code sandbox is a private machine for one conversation or one workflow run. The agent can install packages, download a public page or file, process data, and build charts or documents there. It never reaches your account, your other data, or the platform’s servers: files go in only when the agent imports one of your files, and come out only when it exports a result to your files. The machine is deleted after 30 minutes without use, and after 4 hours at most, so export anything you want to keep. For Orbi, turn it on in the composer's Options tab, under Advanced mode; for an agent, in its Advanced mode.

An agent that creates or edits another agent can only switch these on for it when it has them itself; otherwise it leaves them off and asks you to enable them.

Permissions: when an agent asks before acting

Some actions are sensitive: running a workflow or a catalog tool, calling a sub-agent, installing an application, sending or deleting an email, resolving a paused approval, putting a workflow live or taking it off, and giving an agent a schedule.

In the chat

In a chat with Orbi (the general assistant, no agent selected), a sensitive action shows a permission card, for example Run this action?, Send this email?, or Put this workflow live?. The action waits on the card: Authorize lets it run and the agent continues in place, Decline stops it. If you answer after the agent has stopped waiting, your answer starts its next turn.

A chat with a specific agent does not ask, unless that agent has Ask my permission before a sensitive action turned on (see below).

Each API endpoint has its own permission

Every endpoint of a catalog integration carries a permission: Allow (agents call it without asking), Ask first (it asks, as described above), or Never (no agent may call it). By default every endpoint is Ask first, which is how every API call behaved before, unless the catalog declares another default for it; each integration's public page shows these defaults. Every endpoint of a custom API (one you or a teammate registered) is Ask first by default. To change them, open Settings > Credentials & Variables, open a credential's menu and choose Agent permissions, which lists every endpoint of that integration: set them all at once, or one by one. Your choices cover every account you connected for that integration, and apply to you, in the current workspace.

Where an action would ask (a chat with Orbi, or an agent set to ask), an Allow endpoint runs without a card, and an Ask first endpoint asks for each call: approving one call does not approve the next. Where nothing asks (Don't ask again ticked, an agent that does not ask, an agent step of a workflow), Allow and Ask first both run. Never is refused to every agent, wherever it runs. A workflow's own API node is not an agent: it makes the call its author chose, whatever the permission.

Changes that always need you

Some changes let an agent act later with nobody watching, or remove the question you asked for. They need your approval whoever makes them, in the Orbi chat and in a chat with any agent alike:

• giving an agent a schedule, turning on its webhook, or turning it back on;
• setting up or re-enabling a recurring task;
• putting a workflow version live;
• turning off Ask my permission before a sensitive action for an agent.

When one request makes several of these changes, the card lists them all. When nobody is there to approve (a scheduled, webhook, task or widget run, a sub-agent, or a workflow step), the change is refused, the agent says what it was about to do, and the notification bell tells you. Make the change yourself in the agent’s settings or ask for it in the main chat. Recurring tasks can only be set up from a chat.

In runs nobody is watching

By default, an agent started by a schedule, a webhook, or a task runs its actions without asking. To make it ask, open the agent and, in Configuration, turn on Ask my permission before a sensitive action (it needs no chat channel). You can also switch it from the options of the agent’s chat. From then on:

• The request waits for you in the agent’s conversation, and the notification bell links to it.
• With Reach me outside the app on (in Integration), it is also sent with approve and reject buttons (links to a confirmation page on Microsoft Teams) to the chat channel chosen as the agent’s Destination (the workspace default if you leave it empty). Answer wherever you are: answering in the app closes the copy in the chat. See Chat channels.
• If nobody answers in time, the run ends without doing the action. A later approval authorizes that exact action (same tool, same arguments) for the agent’s next run. It does not approve other actions of the same kind.
• The agent does not send the same request twice while one is waiting. Unanswered requests expire after 24 hours, and the agent may then ask again.

Turning Reach me outside the app off keeps the permission setting: the requests then wait in the app only. In the agent’s chat, the setting is the agent’s own: switch it in the chat’s options. A request card there has no “don’t ask again”, except for the changes that always need you (other than turning this setting off), where Always allow this change in this chat stops that kind of card in this chat. Runs nobody is watching still ask, apart from the one call you approved.

Questions the agent asks you

With the ask_user tool, an agent can put one to four multiple-choice questions to you (two to four options each). You can always type your own answer instead of picking one.

Long-term memory

Long-term memory holds durable facts that agents keep between conversations and runs: your preferences, corrections, decisions about the work, useful references. It is different from conversation history and from skills: a skill says how to do something, a memory says what is true here. It is not where a client lives either: workspace memory is read in every conversation, so what concerns one client goes in that client's project instructions, which only the project's agents read.

• Each entry has a Title, a one-line Summary, optional Details, and a Type (About the user, Feedback, About the work, Reference).
• On every run, an agent sees the summaries of the active entries it uses most, grouped by type. When some do not fit, it is told how many are left out and searches before concluding a fact was never recorded. The details are read only when an agent needs them. An entry marked Always in context (pinned) sends its full details every time, so keep that for rules agents must never miss.
• Agents check memory before asking you something you may already have told them, and save a correction, a preference or a decision as soon as you give it. When a new entry looks like one that already exists, the agent is told so and keeps a single entry if both record the same fact.
• A website chat widget and an agent with no tools get no memory at all, pinned entries included: put what visitors need in the widget agent’s instructions.
• Memory belongs to the workspace: switch workspace and you see that workspace’s memory. An entry can also be private to one agent (One agent); other agents do not see it, but workspace members still do on the Memory tab.
• Agents save entries as they work. You can add, edit, or delete one on the Memory tab. Deactivate makes agents stop using an entry while keeping it; an agent saving the same fact again does not reactivate it.
• Set an agent’s Long-term memory (under Advanced mode) to Recall only for an agent that should use the workspace facts without changing them.

Context compaction

Compaction replaces the oldest part of a long conversation with a summary so it keeps fitting in the model’s context window. Three settings under Advanced mode control it, and each can inherit the default:

Credit budgets

Credit Budget caps what an agent may spend. Empty means unlimited. Credits are the real metered cost of each model call (priced per model and per token), not a fixed amount per iteration.

An agent that is already over its budget is refused before it starts, on every way of starting it (schedule, webhook, widget, workflow node), and a refused scheduled run does not count toward the schedule’s maximum number of runs.

Budgets cascade. When agent A calls sub-agent B, a reservation is taken from A and from every agent above A, and B cannot spend more than it. A parent with a budget of 100 can never let its whole tree spend more than 100. By default the reservation is the smallest free budget among the agents above B: under a parent with only 30 free, B starts with 30 reserved and stops with BUDGET_EXHAUSTED once it has spent them, even if its own budget is 50. A start is refused with BUDGET_EXHAUSTED, scope parent_reservation, when the calling agent asks for a larger reservation than an agent above it has free. When the child finishes, what it really spent is charged up the chain and the rest of the reservation is released.

Reset Mode decides when the count starts again. With Cumulative (the default) it never resets on its own; with Weekly it resets 7 days after the last reset; with Monthly it resets when the calendar month changes (in UTC). Reset Credits in the editor restarts it by hand at any time.

Task delegation

Agents can hand work to other agents, or to a shared backlog, as trackable tasks. You see and manage the same tasks on the task board (Tasks & board).

A task with no assignee goes to the backlog and is always pending. Only agents with Shared backlog participation on (off by default) and a way to wake up are offered backlog tasks and may claim them.

Every task follows the same lifecycle:

pending -> in_progress -> in_review -> completed | failed | cancelled

A finished or rejected task always goes through in_review. With a reviewer_agent_id, that agent reviews it. Without one, you are the reviewer, and the task waits in review until you act (that is expected, not stuck). After max_review_attempts rejections (1 to 20, default 3), the task fails; it is never approved automatically.

For recurring work, recurrence_create makes a cron template that creates a fresh task on each tick, without flooding missed ticks, managed with recurrence_list, recurrence_update, and recurrence_delete. A recurrence without a target agent posts to the backlog.

Guards: at most 5 assign calls per turn and a delegation depth of 5. Calls to sub-agents with execute are capped by Max per-resource / turn (5 by default). A sub-agent sees its last 20 messages by default, plus a list of the tasks in its inbox.

Skills

Skills are reusable instruction sets. An agent can have up to 10. Setting an agent’s skills from the chat replaces its whole list; use skill(action='assign') to add one without replacing the others. Skill access is write (default) or read (get, list, list_folders, help). See Skills.

Built-in tool modules

Besides catalog tools, an agent can use built-in tools, each described to it in one line of its system prompt. A module is present only when the agent has access to it.

When a tool call fails with a 401 or 403, the agent uses the credential tool (actions require, list, variables, set_variable). require shows you a card to connect or reconnect the service, with the missing scopes when the provider named them. set_variable writes a workflow variable that later steps read with {{$vars.name}}.

To wait for a run, workflow(action='wait_run') (or application(action='wait_run') for an application run) blocks until the run finishes, for up to 120 seconds by default and 240 at most. It also returns as soon as the run waits on a person (an approval or a page to fill in), with waiting_on_user=true: the agent then tells the user it is their turn instead of answering for them. On timeout it returns timed_out=true and the run keeps going; the agent calls it again.

Related AI nodes

Guardrail and Classify are AI nodes you place directly in a workflow.

See the Node reference for every parameter and output.

Metrics & inspection

Each agent keeps running totals: executions, tokens, tool calls, successes, failures, total duration, and the time of its last run. The Metrics tab charts them. In the Fleet tab, select an agent to open its recent executions, and select an execution to see its conversation and every tool call with its arguments and result. From the chat, task_get_execution with include_tool_calls=true returns the same tool calls, with secrets redacted.

Troubleshooting: why did my agent stop?

Every run ends with one of twelve stop reasons, in three outcomes:

A Success or Partial stop leaves usable output; a Failure does not.

Other common problems

Related pages