Version Management
Stellar uses version management to help you safely iterate on your agents. Each agent maintains multiple versions with a draft-lock-publish workflow, allowing you to test changes before they go live.
Version Types
Versions are named sequentially: v1, v2, v3, and so on. Each version has one of the following states:
- Draft: A mutable, work-in-progress version. Every agent has exactly one draft at any time. This is where you make changes to your agent configuration.
- Locked: An immutable snapshot of your agent at a specific point in time. Locked versions cannot be edited, ensuring a stable record of past configurations.
- Live: The version that handles new conversations by default. Any version (including the current draft) can be published to become "live".
If an agent has no published (live) version, incoming calls to that agent will not be accepted. Make sure to publish a version before connecting your agent to production phone numbers.
Version Actions
The agent editor header contains buttons for version actions:
| Button | What It Does |
|---|---|
| Lock | Creates an immutable snapshot from the current draft and automatically creates a new draft for continued editing. Only appears when viewing the draft. |
| Publish | Sets a version as "live", making it the default version used for handling new conversations. Only appears when viewing a version that is not live. |
| Unpublish | Removes the live status from a version. Only appears when viewing the live version. |
| Revert | Resets the current draft to match the configuration of the version it was forked from. Only appears for draft versions. |
Typical Workflow
- Edit your agent in the Draft version
- Test changes in the Playground
- When satisfied, click the Lock button to create an immutable snapshot
- Click the Publish button to make the locked version live
- Continue iterating on the new draft for future improvements
Locked versions are immutable, so you can always roll back to a known-good configuration by publishing a previous locked version.
Using the Version Selector
The version selector is a dropdown in the agent editor header. It displays the current version number (e.g., "v2") along with status chips indicating whether it's a "Draft", "Locked", or "Live" version.
Click the dropdown to open a menu with two sections:
- Quick select: Shortcuts to jump to "Draft (latest)" or "Live" versions
- Version history: A list of all versions with their status and last updated date
Use the version selector to inspect any version. When viewing the draft, you can edit the agent configuration. Locked versions are read-only.
In the Playground, the version selector allows you to pick which agent version to test.
Best Practices
- Test before publishing: Always test your changes in the Playground before making a version live.
- Lock regularly: Create locked versions at meaningful milestones to maintain a history of working configurations.
Coming Soon
- Version targeting via connectors: In the future, you'll be able to target specific agent versions through connector configuration (e.g., SIP). This will enable advanced deployment patterns such as A/B testing and gradual rollouts across different phone numbers or SIP endpoints.