> 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/concepts/agents/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rightbrain.ai/_mcp/server.

# Agents

> How Rightbrain agents use independently managed primitives.

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](/docs/concepts/tasks), [Skills](/docs/concepts/skills), [Connections](/docs/concepts/connections), Collection-backed [knowledge](/docs/concepts/collections), 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](/docs/concepts/tasks) 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.

> **Tip**
>
> A good rule of thumb: **start with a [Task](/docs/concepts/tasks), and promote to an agent when execution becomes conditional, multi-step, or conversational.** An agent costs more LLM calls, more latency, and more credits per run than a single Task — so reach for one because the work genuinely needs runtime decisions, not because it feels more powerful.

## 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.

```mermaid
graph LR
  A["Agent<br />goal · instruction · model"]
  subgraph AV["Made available to the agent — each versioned independently"]
    T["Tasks<br />specialized, reliable operations"]
    S["Skills<br />how to approach focused work"]
    N["Connections<br />integrations and MCP servers"]
    RT["Built-in tools"]
  end
  C["Collections<br />knowledge bases"]
  A -. "chooses at run time" .-> T
  A -. "chooses at run time" .-> S
  A -. "chooses at run time" .-> N
  A -. "chooses at run time" .-> RT
  T -- "retrieves from (RAG)" --> C
  T -. "can call" .-> N
```

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:

| Resource             | What the agent can do with it                      | Concept                                   |
| -------------------- | -------------------------------------------------- | ----------------------------------------- |
| **Task tools**       | Call your Tasks as reliable, typed functions       | [Tasks](/docs/concepts/tasks)             |
| **MCP servers**      | Use tools from external MCP servers                | [Connections](/docs/concepts/connections) |
| **Integrations**     | Act in connected services (Gmail, Slack, HubSpot…) | [Connections](/docs/concepts/connections) |
| **Registered tools** | Use platform built-ins                             | —                                         |

[Skills](/docs/concepts/skills) are attached separately. The agent activates their instructions and reference material in context instead of invoking them for a result.

> **Note**
>
> Collections don't attach to an agent directly. An agent gets knowledge-base retrieval through a **Task tool** whose revision has a [Collection](/docs/concepts/collections) wired into its RAG config.

### 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](/docs/production/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](/docs/production/fallbacks) 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](/docs/concepts/memory-and-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](/docs/concepts/connections).
* **Gate side effects.** Leave safe reads automatic and require [approval](/docs/production/approvals) 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](/docs/concepts/triggers-and-runs). A run moves through these statuses:

* `running` — the model is reasoning and calling tools.
* `waiting_for_human` — a tool gated by [approval](/docs/production/approvals) 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](/docs/concepts/triggers-and-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](/docs/production/sharing).

## Minimal example

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

**`Create an agent`**

```bash title="Create an agent"
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
  }'
```

**`Run it (streams SSE)`**

```bash title="Run it (streams SSE)"
curl -N -X POST https://app.rightbrain.ai/api/v1/org/{org_id}/project/{project_id}/task-agent/{agent_id}/run \
  -H "Authorization: Bearer $RB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Customer says their export is failing with a 500 error." }'
```

> **Tip**
>
> For a guided walkthrough of making a Task available, running an agent, and consuming its event stream, see [Build your first agent](/docs/quickstart/first-agent).

## Related

#### [Run agents via API](/docs/api/run-agents)

Streaming runs, SSE events, and file handling.

#### [Approvals (HITL)](/docs/production/approvals)

Gate sensitive tool calls behind human review.

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

Publish, pin, and roll back agent revisions.

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

Control session history and inspect context attribution.

#### [API Reference — Agents](/api-reference/api-reference/agents)

Full endpoint reference for agents.

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