On Belay

Custom agents

Custom agents are AI workers you define once and run on demand or on a schedule. Each one runs as a principal whose group memberships gate exactly what it can touch — so an agent can do real work without ever exceeding the access you've granted.

What custom agents are

A custom agent is a reusable AI task. It has a name, a system prompt, a model, a set of permitted integrations, and a run-as principal that determines what it can access. You build it in a guided wizard, then run it yourself or let it run on a schedule.

Agents live at Dashboard → Agents. Every run is recorded, so you always have a history of what the agent did, how long it took, and what it produced.

Before you start

Two things need to be in place:

  1. At least one connected integration. The wizard can't build a useful agent with no tools to call. Connect what the agent needs first — see Integrations overview.
  2. A principal for unattended runs. To deploy a scheduled agent, you (as an admin) first create a Service Identity at Dashboard → People → Service Identities and add it to the groups that hold the integration access the agent needs. Without a run-as principal, deploy is blocked. (See Core concepts for what a Service Identity is.)

The build wizard

Building an agent walks through five steps. It does not ask for the agent's name or goal up front — those come at the Build step.

Step 1 — Outcome category

Pick what kind of work this agent does: Reporting, Analysis, Recommendations, or Actions. This is a category choice only — you do not name the agent here. The category steers the integrations and prompt templates you'll see next.

Step 2 — Choose your tools

Select which integrations the agent may use. This is an integration-level choice — there's no per-operation picker in the wizard. Integrations your groups can't reach show as locked or greyed out; connect and grant them first if you need them.

Step 3 — Starting prompt

Pick a starting prompt. You can choose a prebuilt template, a template matched to your outcome and selected tools, or an AI-generated suggestion. You'll refine the prompt in the next step.

Step 4 — Build

This is where the agent takes shape. You set:

  • Name — what the agent is called.
  • System prompt — the agent's instructions. An AI Prompt Helper panel can draft or improve it. A safety check blocks deploy if it detects credentials (keys, tokens, passwords) pasted into the prompt — credentials belong in integrations, never in prompt text.
  • Model — see Models below.
  • Approval gates — per-integration toggles for human-in-the-loop approval.
  • Run-as principal — the identity the agent acts as (admins only; see below).
  • Output delivery — where results are sent (optional).
  • Run settings — Rich HTML reports, Max price per run, and Visibility.

Step 5 — Schedule & deploy

Choose a trigger and schedule, run Test this agent (a one-off dry run so you can see the output before committing), and confirm deploy.

To begin, go to Dashboard → Agents and start a new agent to launch the wizard.

Run-as principal

A principal is the identity the agent acts as — the User or Service Identity whose permissions the agent borrows when it runs. Every active agent runs as exactly one principal: a real User or a Service Identity, never both and never neither. On Belay enforces this at the database level — an agent can't deploy without precisely one set.

The principal's group memberships are what gate the agent's access. When the agent calls an integration, the proxy authorizes the call as that principal — so the agent can only reach the integrations and operations the principal's groups permit. Put the principal in the right groups and the agent inherits exactly that scope, no more.

Only admins can choose the run-as principal. A member who builds an agent has it forced to run as themselves. Assigning a Service Identity automatically adds that identity to the groups that own the agent's selected integrations, so the access lines up.

Service Identities are non-human principals built for unattended runs. Create and manage them at Dashboard → People → Service Identities.

Models

The wizard lets you pick the model the agent runs on:

  • Haiku (claude-haiku-4-5-20251001) — "Fast & economical." Good for high-frequency, lightweight runs.
  • Sonnet (claude-sonnet-4-6) — "Balanced." The recommended default for most agents.
  • Opus (claude-opus-4-8) — "Most capable." Use it for complex analysis or multi-step synthesis.

Pick the lightest tier that does the job well; you can change it later.

Triggers and schedules

  • Manual — run the agent on demand from its page whenever you need it.
  • Scheduled — run it automatically on a schedule.
  • Event-triggered — coming soon; this option is currently disabled.

Schedule presets are: Every hour, Daily at 9am, Weekdays, Weekly, or a custom cron expression. All schedules run in America/New_York (ET).

Approval gates

In the Build step you can flag specific integrations for human approval with the per-integration approval-gate toggles — a way to mark the integrations whose actions should get a person's sign-off rather than running unattended. If you enable no gates, the deploy confirmation warns that the agent will run without asking first.

Approvals across On Belay are reviewed by your Owner group, at Dashboard → Approvals or with the Approve / Deny buttons in Slack when the Slack bot is installed. For exactly what an approval does — and what it doesn't do to a task already in flight — see Governance & approvals.

Output delivery

An agent can deliver its output to one or more destinations:

  • Slack — post to a channel.
  • Notion — append to a page.
  • Google Drive — upload as a file.
  • Webhook — POST the output to a URL.
  • Email (owner) — email the result to the org owner. (Email goes to the org owner, not an arbitrary recipient.)

Delivery is optional. With no destination set, results are viewable only in the Run Log.

Run settings

Visibility

  • Private — only admins and you (the creator) can see and manage the agent.
  • Company — shared with the whole org, so colleagues can view the agent's run outputs and artifacts (they still can't edit, delete, or run it unless they're the creator or an admin).

Visibility is an admin-only control. A member's agent is forced to Company.

Max price per run

A per-run cost cap, between $0.50 and $100. Leave it blank to use the $10 default. A run hard-aborts when it reaches 100% of the cap, and does a graceful wrap-up at around 80% so you still get partial output rather than an abrupt stop.

Rich HTML reports

Optional. When enabled, each run ends with a branded, self-contained HTML report attached to the run, alongside the plain output.

Execution and the run log

Agent jobs are dispatched by a background scheduler roughly every minute. Each execution becomes a run — On Belay calls Claude with the agent's system prompt and permitted tools, then records the result.

Open an agent at Dashboard → Agents and select it to see its Run Log. Each run records its status, start and finish time (which gives you the duration), the output it produced, and its cost. The exact per-run dollar cost is shown to the platform owner or on failed runs; customers otherwise see a "Billed" amount.

Related