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, executable tools, and declarative Skills. Executable tools come from four sources:

Skills are attached separately. The agent activates their instructions and reference material in context instead of invoking them for a result.

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. Calls can branch, repeat, or run in parallel. This mode supports all executable tool sources and declarative Skills, and is the default.
• sequential — more than one enabled Task tool runs in a fixed order, with each result passed to the next step through session state. Declarative Skills, Integrations, MCP servers, and registered tools are not supported. If a Task is the output formatter, it must be the final step.

Use agentic when the request determines the path. Use sequential when every input must traverse the same Task pipeline. Sequential mode runs every configured step, while agentic mode can avoid work that the request does not 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 across a session; max_turns caps the number of runs that may continue the same session. See Memory & context.

Design an effective agent

• Keep the tool surface focused. Every tool declaration consumes context and gives the model another choice. Expose the minimum set needed for the goal.
• Define decisions, not a transcript. State the goal, boundaries, dependencies, freshness rules, escalation policy, and stopping condition. Let an agentic run choose the path inside those constraints.
• Make dependencies explicit. Identify which operations are independent and may run in parallel, and which require an earlier result. Parallel execution is model-selected behavior, not a guarantee.
• Use Tasks for stable contracts. Put reusable transformations and schema-constrained intermediate results behind Tasks. Mark one Task tool as the output formatter when the final result must be typed.
• Plan for incomplete evidence. Specify whether a failed lookup should stop the run, allow a clearly marked partial result, or trigger a bounded retry. A completed status proves the run ended successfully; it does not prove every optional source returned data.
• Separate capability from identity. allowed_tool_ids controls which Integration operations are available. The binding’s credential_policy controls which connected account executes them. See Connections.
• Gate side effects. Leave safe reads automatic and require approval for consequential writes.
• Inspect before expanding. Use run events, invocation records, phase timing, and context attribution to find missing evidence or expensive context before adding more tools or turns.

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 its run record and events.

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. An authenticated user with create access can clone that revision and its supported dependencies into another Project. Credentials are never copied. See Sharing and cloning.

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