Versioning & revisions

Tasks and agents are versioned. Every time you change one, Rightbrain snapshots the new configuration as a revision and keeps the old ones. That gives you a safe way to change production behavior: promote a new revision when you’re confident, and roll straight back to a known-good one if something regresses.

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.

• Every update creates a revision. Calling POST …/task/{id} to update a task produces a new revision rather than mutating the old one. Nothing you have already shipped changes underneath you.
• 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 (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:

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

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 revisions are created inactive. Editing an agent snapshots a new revision but does not switch traffic to it — in-flight and new runs keep using the current active revision until you explicitly promote the new one by setting active_revision_id. Editing is therefore safe: you can stage a change and test it without touching production behavior.
• 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:

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

Rolling back

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