Versioning

Every change to an agent is captured as an immutable revision. Production runs hit whichever revision is deployed. You can roll forward and back without downtime.

Revisions

A revision is a complete snapshot of an agent at a moment in time:

• The full flow (every node and connection)
• All prompts and step configurations
• Attached tools, sub-agents, knowledge, memory bindings
• AI provider selection per step

Saving in Studio creates a draft of your changes. Drafts let you iterate freely without affecting anything live. When you're ready, deploying a draft promotes it to a published revision that production traffic can reach. Published revisions are immutable and never silently pruned.

Deployments

The deployed revision is the one production traffic hits — API calls, connectors, scheduled runs, and sub-agent calls from other agents all route to the deployed revision unless they explicitly request a different one.

Important properties:

• Editing doesn't affect production. Saves go into a draft. Production keeps serving the deployed revision until you publish.
• One-click switch. Deploying a different revision instantly changes which one new traffic hits.
• Rollbacks are just deploys. Roll back by re-deploying an earlier revision.
• History is preserved. Past deployments are recorded with timestamp and actor.

Compare two revisions

Open Revisions in Studio and pick any two to see a structural diff:

• Nodes added, removed, or moved
• Prompt and parameter changes
• Tool / knowledge / sub-agent attachments that changed
• AI provider swaps

Use this to review your own changes before deploying, or to investigate "what changed" when behavior shifts.

Deploy a revision

1. In Studio, open Revisions.
2. Select the candidate.
3. Click Deploy.
4. Review the diff against the current deployed revision.
5. Confirm.

The change is live as soon as you confirm.

Roll back

1. Open Revisions.
2. Find the last known-good revision (the deployment history is annotated).
3. Click Deploy on it.
4. Confirm.

There's no separate rollback verb — re-deploying any prior revision is the rollback.

Calling a specific revision

API callers normally hit the deployed revision. To target a specific revision (for canary tests or regression replays), put the revision in the URL path:

POST /v1/{tenant}/agents/{agent}/{revision}:execute
X-API-KEY: ...
Content-Type: application/json

{
  "input": { ... }
}

The default :execute endpoint without a revision in the path always routes to the currently deployed revision.

Patterns

• Canary before promote. Save a draft, run an evaluation, inspect the diff, then deploy.
• Branchy iteration. Multiple teammates can save drafts in parallel; the deployed revision is unaffected until one of them is published.

What's not yet supported

• Named branches — revisions are linear and immutable.
• Per-step pinning of sub-agent revisions — sub-agent steps always invoke the deployed revision of the target.
• Auto-rollback on alert. For now, configure budget alerts and roll back manually.

Next steps

• Evaluations — score candidate revisions before deploy
• Monitoring — watch the deployed revision in production
• Deployment — production checklist and rollout patterns