> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rightbrain.ai/v-1/docs/getting-started/how-it-works/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# How Rightbrain works

> How a Rightbrain agent uses the primitives you make available to it, how triggers start runs, and how runs stream, get observed, and roll back.

Rightbrain has one top-level unit, the **agent**, and a small set of primitives you make available to it. Once you have that model, everything else, from a single API call to a scheduled production workflow, is the same shape.

## An agent, and what you make available to it

An agent is a goal-directed reasoner on the model of your choice. It works with nothing attached — an instruction and a model are enough to run it. The leverage comes from **making primitives available** to it: at run time the agent decides which to use, picking a task for a specialized operation, drawing on a skill for how to approach a piece of work, reaching an external system through a connection.

* **Tasks** are structured AI functions the agent can call when it needs a specialized, reliable operation with typed output. One task tool can be the agent's output formatter, terminating the run with structured output.
* **Skills** are reusable, versioned abilities the agent draws on to shape focused work. A Skill can declare required registered tools, Integrations, or MCP dependencies, which Rightbrain provisions onto the agent revision.
* **Connections** give external reach, through native integrations (HubSpot, Salesforce, Slack, Google Sheets, Gmail) and MCP servers. Connections aren't agent-only: a task can carry an integration or MCP tool and call the external service as part of its own run.
* **Collections** are the knowledge layer. An agent does not attach a collection directly; a task retrieves from a collection through its RAG configuration, and the agent calls that task.

Every primitive is created, managed, and **versioned independently** of the agents that use it. That separation is the point: improve a task and every agent following its active revision picks it up; roll a skill back without touching any agent; share one connection across a whole fleet.

```mermaid
flowchart TD
  A["Agent<br />goal · instruction · model"]
  subgraph C["Connections"]
    I[Integrations]
    M[MCP servers]
  end
  A -. "uses at run time" .-> T[Tasks]
  A -. "uses at run time" .-> S[Skills]
  A -. "uses at run time" .-> C
  T -. "can call" .-> C
  T -->|RAG config| COL[Collections]
  S -.provisions.-> C
```

> **Note**
>
> An agent revision can make executable tools available from four sources: Tasks, MCP servers, Integrations, and platform-registered tools. Skills are declarative: the agent activates their instructions and knowledge in context instead of calling them for a result. **Connections** is the umbrella over Integrations and MCP servers.

## Choose what to build

Start with the smallest runtime that can own the job:

| Need                                                     | Use                                                       |
| -------------------------------------------------------- | --------------------------------------------------------- |
| One bounded model operation with typed input and output  | A [Task](/docs/concepts/tasks)                            |
| Runtime decisions, multiple tools, or conversation state | An [agent](/docs/concepts/agents)                         |
| Reusable procedure or domain guidance                    | A [Skill](/docs/concepts/skills)                          |
| Retrieval from a controlled document corpus              | A [Collection](/docs/concepts/collections) through a Task |
| Live reads or actions in another system                  | A [Connection](/docs/concepts/connections)                |
| Transformation before a Task prompt is rendered          | An [input processor](/docs/concepts/input-processors)     |
| Automatic execution from an event or schedule            | A [trigger](/docs/concepts/triggers-and-runs)             |

A task is, in effect, a **deterministic agent**: one thing, done very well, run after run. Each task carries its own model, so an agent can delegate a bounded operation to a model selected for that job. Promote to an agent only when conditional, multi-step, tool-driven, or conversational execution justifies additional model calls, latency, and cost.

For external data, attach an MCP server or Integration directly when the agent needs the raw result. Put the connection behind a Task when the result needs a reusable prompt, transformation, or typed contract. Use a Skill for guidance the model should apply itself, not for an operation that must return a result.

## A trigger starts a run

A **run** is a single execution of an agent (or a standalone task). Every run follows the same arc, whatever starts it.

#### Trigger

Something kicks off the run: an API call, a webhook, a scheduled job, an inbound Gmail message, a form submission, or a Slack message.

#### Receive

The trigger passes input to the agent, which can include text, structured data, and uploaded files.

#### Run

The agent reasons over the input and calls its tools. A tool call can pause for human approval before it executes.

#### Respond

The agent returns its result, ready to store, display, or feed into the next step of your workflow.

## Runs stream and get observed

Agent runs stream over Server-Sent Events, so your application sees the work as it happens rather than waiting for a single blocking response: each tool call and result arrives as an event, incremental text streams in, and a terminal event closes the run. The full event reference is in [Run agents via API](/docs/api/run-agents).

A run moves through the statuses `running`, `waiting_for_human` (paused for an approval), `completed`, and `failed`. Every run is recorded. Run and event endpoints expose its telemetry, timing, credits, execution source, and failure metadata.

> **Tip**
>
> Standalone tasks run as a single request/response over HTTP rather than a stream. See [Run tasks via API](/docs/api/run-tasks) and [Run agents via API](/docs/api/run-agents).

## Predictable by design

Operational integrity means knowing what an agent will return and how it will get there.

* **Typed outputs.** A Task response schema constrains the fields and value types returned by a successful run.
* **Execution order.** An agent runs in one of two modes. In **agentic** mode the model decides which tools to call and when. In **sequential** mode more than one Task tool runs in a fixed order.

You also choose the model each task runs on, frontier or open-source, and can give it a [fallback model](/docs/production/fallbacks) that takes over mid-run if the primary fails.

Agent context grows with instructions, messages, files, tool declarations and results, and activated Skills. Use a focused tool surface and a [memory strategy](/docs/concepts/memory-and-context) that matches the expected session length.

## Revisions let you change safely

Agents and Tasks are both **revisioned**. Each revision is an immutable snapshot: for an agent, it captures the exact wiring of every tool; for a Task, the prompt, model, and output schema. An agent serves one active revision. A Task can split traffic across multiple active revisions with weights.

* **Roll back** by repointing the active revision to a previous one.
* **A/B test** a task by giving two revisions weighted shares of traffic.
* **Pin or follow** for task tools: an agent's task tool can pin a specific task revision, or follow whatever revision the task itself has active.

## Where to go next

#### [Agents](/docs/concepts/agents)

The orchestrator in depth.

#### [Triggers and runs](/docs/concepts/triggers-and-runs)

Every way to start a run, and how runs are recorded.

#### [Build your first agent](/docs/quickstart/first-agent)

Make a Task available to an agent and stream the run.

#### [Versioning and revisions](/docs/production/revisions)

How revisions, rollback, and A/B testing work.

#### [Memory and context](/docs/concepts/memory-and-context)

Control session history and inspect what reaches the model.

> Build reliable AI agents that run inside your existing tools and workflows. Rightbrain developer documentation.