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

# Versioning & revisions

> How Rightbrain versions tasks and agents with revisions, selects revisions at run time, runs weighted A/B tests, and rolls back.

Tasks and agents version their execution configuration as **revisions**. Configuration changes create a new snapshot and keep the old ones. Metadata changes, such as a name or description, and changes to the active revision do not by themselves create a new snapshot. Promote a new revision when you're confident, and roll back to a known-good one if something regresses.

```mermaid
flowchart LR
  ACT(["Active pointer<br />serves all traffic"])
  R1["Revision 1<br />immutable"]
  R2["Revision 2<br />immutable"]
  R3["Revision 3<br />new — created inactive"]
  ACT --> R2
  ACT -. "rollback = repoint" .-> R1
  ACT -. "promote when ready" .-> R3
```

## Task revisions

A task is a definition (its name, output modality, and settings) plus a list of **revisions**. A revision holds the actual configuration — system prompt, user prompt, model, fallback model, output format, and RAG settings.

* **Configuration updates create revisions.** Calling `POST …/task/{id}` with changed revision settings creates a new inactive revision. The response's `revisions` array contains revision IDs; the top-level `id` is the task ID. `X-New-Revision-Created` reports whether the update created a revision, and `X-New-Revision-ID` identifies it when one was created.
* **The active revision serves traffic.** A task has one or more active revisions. When more than one is active, each carries a `weight` — this is how you run [A/B tests](#ab-testing-with-weighted-revisions) (weights sum to 1.0).
* **Runs report which revision answered.** Task run responses include an `x-task-revision-id` header so you always know which configuration produced a result.

### Selecting a revision at run time

By default a task run uses the active revision. You can target a specific revision with query parameters on the run endpoint:

**`revision_id`** `string`

Run a specific revision by its ID, regardless of which one is active.

---

**`revision_tag`** `string`

Run the revision carrying a given tag. Useful for pinning a caller to a named version like `stable`.

---

**`Run a specific task revision by tag`**

```bash title="Run a specific task revision by tag"
curl -X POST \
  "https://app.rightbrain.ai/api/v1/org/$ORG_ID/project/$PROJECT_ID/task/$TASK_ID/run?revision_tag=stable" \
  -H "Authorization: Bearer $RB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "task_input": { "text": "hello" } }'
```

### A/B testing with weighted revisions

To split traffic between two revisions, make both active and give each a weight. A revision with weight `0.9` receives roughly 90% of runs, the other `0.1` receives the rest. Because every run records the revision that served it, you can compare their outputs and promote the winner. Weights across active revisions sum to 1.0.

**`Promote or roll back a task revision`**

```bash title="Promote or roll back a task revision"
curl --fail-with-body -X POST \
  "https://app.rightbrain.ai/api/v1/org/$ORG_ID/project/$PROJECT_ID/task/$TASK_ID" \
  -H "Authorization: Bearer $RB_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"active_revisions\":[{\"task_revision_id\":\"$REVISION_ID\",\"weight\":1.0}]}"
```

Use `test: false` when creating a task revision you intend to promote. A revision marked `test: true` can be run explicitly or evaluated, but promotion returns `422`. An inactive revision with `test: false` can be evaluated before activation too.

### How agents pin task tools

When a task is attached to an agent as a tool, the agent chooses how it tracks the task's revisions:

* **`pinned`** — the agent always calls one fixed task revision. Updating the task does not change the agent's behavior until you re-pin.
* **`follow_active`** — the agent always calls whatever revision is currently active on the task. Updating the task's active revision flows through to the agent immediately.

Use `pinned` for reproducibility and `follow_active` when you want agents to pick up task improvements automatically.

## Agent revisions

Agents are versioned the same way, but an agent revision snapshots more: the full tool wiring. A `TaskAgentRevision` is an **immutable** record of the agent's instruction, mode, model and fallback, memory settings, and every attached tool — Tasks, Skills, MCP servers, Integrations, and registered tools — along with their approval policies.

* **One revision is active at a time.** The active revision is what runs serve.
* **New configurations are created inactive.** Changing an agent's revision settings creates a new revision but does not switch traffic to it. Explicitly promote it with `active_revision_id` when ready.
* **Revisions are immutable.** Existing revisions never change; every edit is a fresh snapshot.
* **Rollback is a repoint.** You don't rebuild an old configuration — you set `active_revision_id` back to a previous revision.

List and inspect an agent's revisions:

**`List agent revisions`**

```bash title="List agent revisions"
curl https://app.rightbrain.ai/api/v1/org/$ORG_ID/project/$PROJECT_ID/task-agent/$AGENT_ID/revision \
  -H "Authorization: Bearer $RB_API_KEY"
```

Fetch a single revision with `GET …/task-agent/{id}/revision/{revision_id}` to see exactly which tools and policies it captured.

**`Promote or roll back an agent revision`**

```bash title="Promote or roll back an agent revision"
curl --fail-with-body -X POST \
  "https://app.rightbrain.ai/api/v1/org/$ORG_ID/project/$PROJECT_ID/task-agent/$AGENT_ID" \
  -H "Authorization: Bearer $RB_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"active_revision_id\":\"$REVISION_ID\"}"
```

Activation and rollback affect **new sessions**. An existing session stays pinned to the agent revision it started with. Supplying a conflicting explicit revision for that session returns `409`; start a new session to use the promoted revision. A session's pinned agent revision can still contain `follow_active` task tools, which resolve the task's active revision on subsequent runs. Use pinned task tools when those must remain reproducible too.

## Rolling back

#### Find the good revision

For an agent, list revisions with `GET …/task-agent/{id}/revision` and identify the last one that behaved correctly. For a task, identify the target revision or its tag.

#### Repoint the active revision

Make the known-good revision active again. For agents this changes which snapshot runs serve; for tasks it changes which revision (or weighted set) serves traffic.

#### Confirm

Trigger a run and check the returned revision ID matches the one you rolled back to. See [Observability & audit](/docs/production/observability).

Because approval policies, fallback models, and tool wiring all live on the revision, rolling back restores all of them together — you're never left with a half-reverted configuration.

## Related

#### [Evals](/docs/production/evals)

Test a new revision before you activate it.

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

Approval policies are captured in the agent revision.

#### [Fallbacks & reliability](/docs/production/fallbacks)

Fallback models are versioned with the revision.

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

Memory strategy and configuration are part of the agent revision.

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

Agent revision endpoints.

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