Versioning & deployment
How drafts become frozen versions, and how deploying publishes a version your team can run.
Everything you build in Compass moves through the same three stages, whether it's an agent or a workflow:
- Draft — the editable copy you change in the builder. There's one per agent or workflow, and editing only ever touches the draft.
- Version — an immutable, numbered snapshot (v1, v2, …) created when you deploy. Versions never change.
- Deployment — a movable pointer to the one version that's currently live.
This separation means you can keep editing safely while a stable version runs, and always trace any execution back to the exact version that produced it.
What deploying does
Clicking Deploy takes the current draft, freezes it into the next numbered version, and points the deployment at it — making it live. The draft stays editable for your next round of changes; the version you just published is locked. If nothing has changed since the last version, deploying reuses it rather than minting a new number.
A version is fully reproducible
Deploying also freezes everything your work depends on — the sub-workflows and agents it calls, at their current drafts — and pins those exact versions to the version you're publishing. A deployed version therefore runs the same way every time, even if you later change those pieces. When a newer version of one is available, the deployment's Overview flags it; deploy again to adopt it.
The deploy dialog
When you deploy from the builder, the Deploy workflow (or Deploy agent) dialog confirms the details and runs a final check:
- Name and description — you can refine them one last time before publishing. The description is shown in lists and to agents that call this one as a tool.
- Version context — "First deployment — this publishes v1.", or "Currently at vN — deploying publishes this as the next version."
- Validation — any errors are listed and must be fixed first ("Fix N issues before deploying"); warnings don't block you ("Ready to deploy").
Confirm to publish; a toast confirms Deployed · vN.
Where you deploy from
You can deploy in two places:
- From the builder — the Deploy button in the agent builder or the canvas toolbar, while you're working on something.
- From the Deployments page — Deploy lists the agents and workflows that aren't live yet, and deploys the one you pick from its current draft.
Draft ahead of live
After you deploy, you'll often keep editing — and the draft moves ahead of the live version. Compass marks this so it's clear there are unpublished changes: draft ahead under the Live · vN badge in the Workflows and Agents lists, and Changes not deployed with Review and deploy on Studio Home. Those changes don't affect anything running until you deploy again, creating the next version.
What a sub-workflow runs
A workflow or agent called by another follows its caller:
- A deployed parent runs each child at the version pinned when the parent was deployed.
- A draft run — a test, or a run from Compass Chat set to Draft — runs each child's draft.
- In Compass Chat, a tool set to Live runs its own current deployment.
Changing connections doesn't need a version
Which connection a deployment's models and integrations use is set on the deployment itself, not frozen into the version. You can point a live deployment at a different connection at any time, without deploying anything — see Managing deployments.
Solution workflows
Workflows and agents shipped by a solution are versioned by the solution's releases, not deployed from the builder.