Versioning & revisions

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.

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

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:

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.

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

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