Agents

An Agent is the top-level unit in Rightbrain: a goal-directed reasoner on the model of your choice. It works out of the box with nothing attached — give it an instruction and run it. An agent becomes more useful when it can use Tasks, Skills, Connections, Collection-backed knowledge, and the platform’s built-in tools. At run time the agent uses them intelligently. Tasks and Skills are versioned independently of the agents that use them, while Connections and Collections are managed separately.

Agents also carry the operational controls production demands: versioned revisions, human-in-the-loop approvals, fallback models, evals, and full run observability.

When to use an agent

Reach for an agent when a single Task isn’t enough — when the work needs multiple steps, tool calls, external systems, or decisions the model makes at runtime:

• Reason over a request, then call the right tools in the right order.
• Combine several Tasks, a Collection’s knowledge, and an external service (Slack, Gmail, an MCP server) in one run.
• Pause for human approval before a sensitive action, then resume.
• Hold multi-turn conversation state across a session.

How an agent is structured

The agent itself needs only a goal, an instruction, and a model. Around it sit the primitives you’ve made available — each with its own lifecycle and version history, none owned by the agent. At run time the agent decides which of them to use, in what order, based on what the request actually needs.

An agent is revisioned, exactly like a Task. The agent itself is a stable handle (name, run visibility); the executable configuration lives in immutable revisions. Each revision is a snapshot of what was available to the agent and how it was set up: the instruction, execution mode, primary and fallback model, memory strategy, max_turns, and the set of tools the agent may call. A revision makes tools available from five sources:

Active revision and rollback

Exactly one revision is active at a time and serves all traffic. Publishing a new revision repoints the active pointer; rolling back is repointing it to an earlier one. Nothing is edited in place, so a rollback is instant and lossless.

Task tools

Task tools are ordered and individually enabled. Each appears to the model as a callable function whose parameters are the {placeholders} in the Task’s user prompt. Each carries a revision_strategy — "pinned" (one frozen Task revision) or "follow_active" (whatever revision the Task currently has active); if you omit it, the tool pins to the task’s current revision. See Versioning & revisions for choosing between them.

Output formatter

One Task tool per agent may be marked the output formatter. When the model calls it, the run terminates with that Task’s structured output — the agent’s final, typed result rather than free-form text.

Execution mode, models, and memory

An agent runs in one of two modes, set on the revision:

• agentic — the model decides which tools to call, whether to call them, and in what order. It can call tools in parallel, use MCP servers, and its reasoning is visible in the event stream. This is the default and the right choice for most agents.
• sequential — a fixed pipeline where the output of one step feeds the input of the next through session state. It requires at least two Skills, does not support MCP, and filters out intermediate reasoning. Use it only when you want a deterministic, ordered chain rather than a model that decides at runtime.

The tradeoff is concrete. Take a customer-support agent: in agentic mode a billing complaint that needs three tools ran in about 3,072 tokens, while a plain “what are your hours?” resolved with one tool in roughly 1,088 tokens — the agent scales its effort to the request. The same workload forced through a fixed sequential pipeline used about 16,292 tokens, because every step runs every time. Agentic mode adapts; sequential mode is predictable but pays for steps it doesn’t need.

The rest of the revision config:

• Model + fallback — a primary model, plus an optional fallback model used if the primary fails.
• Memory — a memory_strategy (sliding_window or compaction) and its config control how conversation history is retained and compacted across turns; max_turns caps a single run’s tool-calling loop.

The run lifecycle

Calling an agent starts a run that streams Server-Sent Events. A run moves through these statuses:

• running — the model is reasoning and calling tools.
• waiting_for_human — a tool gated by approval was called; the run waits for a decision and, after approval, an explicit resume.
• completed — the run finished (with formatted output, if a formatter was set).
• failed — the run errored; the reason is captured in the logs.

Runs are multi-turn and resumable. Sessions persist state (encrypted), and a paused run resumes with its runtime files intact. See Triggers & runs for events, files, and observability.

Sharing and cloning

An agent can be shared as a public, read-only view of a pinned revision (with an optional description and expiry). Anyone with the link can clone it into their own project as a starting point.

Minimal example

Create an agent, then run it. Runs stream SSE, so request the stream and read events as they arrive.

$
curl -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task-agent \
>
  -H "Authorization: Bearer $RB_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Support triage agent",
>
    "instruction": "Triage inbound support email. Look up the customer, then draft a reply.",
>
    "llm_model_id": "<model-id>",
>
    "max_turns": 10
>
  }'

Related