Core Concepts

Triggers & runs

What starts work, and what a single execution looks like

A trigger is what starts a run. A run is a single execution of a Task or an agent. Triggers are the front door; runs are the record of what happened. Together they’re how Rightbrain moves from “a thing I built” to “a thing that operates.”

Triggers

Anything that can fire an event can start a run. A trigger targets a Task or an agent.

TriggerHow it fires
API callA direct POST .../run request.
WebhookAn inbound HTTP call to a public endpoint.
ScheduleA cron expression runs it on a timer.
Gmail inboxA new email in a connected inbox.
SlackA message in a connected workspace.
DashboardA manual run from the UI.

Webhook triggers

A webhook trigger has a public invoke endpoint:

POST /api/v1/public/webhook/{project_id}/{endpoint_id}

Authentication is either hmac_sha256 (the caller signs the payload with a shared secret, sent in the X-Signature header) or bearer_token (a bearer token). The auth method is fixed at creation — to switch methods, create a new trigger. Webhook triggers support optional payload mapping and idempotency, and you can rotate the secret or regenerate the endpoint.

Response behavior depends on the target. A task-targeted webhook runs synchronously: the invoke call returns 200 with the run result in the body. An agent-targeted webhook is accepted and processed in the background, so long-running agent work never blocks the caller. Either way the invocation is recorded as a trigger event you can list and inspect.

Schedule and inbox triggers

  • Schedule — a cron trigger that fires on a recurring timer.
  • Gmail inbox — fires an agent (or Task) when mail arrives in a connected Gmail inbox, passing the message through as input.

Each trigger type records its own events, so you can see every firing and its outcome.

Runs

A run captures one execution end to end: inputs, tool calls, output, token counts, timing, and credits.

Statuses

Agent runs move through running → waiting_for_human (paused for an approval) → completed or failed. Task runs are request/response — they return the TaskRun directly.

Streaming (agents)

Agent runs stream Server-Sent Events so you can render progress live. The event stream is:

EventMeaning
session_idEmitted on stream start; identifies the session.
textIncremental model text.
tool_callThe model is calling a tool.
tool_resultA tool returned.
approval_requiredA gated tool needs human sign-off; the run pauses (waiting_for_human).
formatted_outputThe final structured output (from the output-formatter Task).
errorThe run errored.
doneThe stream is complete.

See Run agents via API for handling the stream.

Files in and out

Runs handle files through a runtime file registry. Agents accept uploaded input files (multipart or base64), pass them between tools within a single run, and track generated files with provenance (whether a file was an input or was generated, and by which Task). A paused run resumes with its file manager intact. Files are retrievable per run:

GET .../task-agent/{agent_id}/run/{run_id}/file/{file_name}

Observability, logs, and usage

Every run is recorded for observability: the Logs view and the agent Observe page show the runs table, the trigger that started each run, failure reasons (surfaced from SSE error codes), and per-model telemetry. Runs are metered in credits, and token/credit/timing/usage reports are available per Task, per agent, and project-wide. Sensitive audit events are recorded in the tamper-evident audit log.

Minimal example

Create a webhook trigger for an agent, then invoke it from anywhere.

$curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/trigger/webhook \
>  -H "Authorization: Bearer $RB_TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "New signup webhook",
>    "target_type": "task_agent",
>    "target_id": "{agent_id}",
>    "auth_method": "hmac_sha256"
>  }'
Webhooks & forwarders

Webhook and email forwarding for run results.

Observability & audit

Logs, telemetry, failure reasons, and the audit log.

Run agents via API

Consume the SSE event stream.

API Reference — Triggers

Webhook, schedule, and Gmail trigger endpoints.