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. What makes an agent genuinely powerful is what you make available to it: Tasks, Skills, Collections (via Tasks), Connections, and the platform’s built-in tools. At run time the agent uses them intelligently — picking the task or tasks it needs for a specialized operation, drawing on a skill to shape how it composes output, retrieving knowledge, or acting in an external system.

Each of those primitives is created, managed, and versioned independently of the agents that use it. Improve a task and every agent following its active revision benefits; roll a skill back without touching the agent at all.

It’s easy to build a compelling agent demo. It’s incredibly hard to get one into production. Agents give you the operational controls that make that possible: 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.

You don’t have to use an agent. When the job is extremely well-defined and you need structured output reliably — one thing, done very well, run after run — use a Task directly. A task is, in effect, a deterministic agent: same shape of reasoning, none of the runtime freedom. Tasks are first-class and callable on their own via the API.

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. See Versioning & revisions.

Task tools: pinned vs. follow-active

When you attach a Task to an agent, you choose a revision strategy:

• pinned — the agent always calls one specific, frozen Task revision.
• follow_active — the agent calls whatever revision is currently active on that Task, so improvements to the Task flow through automatically.

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. Over the API, set revision_strategy ("pinned" or "follow_active") on the task tool when creating or updating the agent; if you omit it, the tool pins to the task’s current revision.

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 pauses until someone approves, rejects, or resumes it.
• 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