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.
- Published: The version that handles new conversations by default. Any locked version can be published to become the live version.
If an agent has no published version, it will not handle new conversations. Make sure to publish a version before deploying your agent to production.
Version actions
The agent editor header contains the following controls:
| Control | What it does |
|---|---|
| Save | Saves changes to the current draft version. Only enabled when the draft has unsaved changes. |
| Save & lock version | Available from the Save dropdown menu. Saves the current working draft as an immutable locked snapshot version, to allow always going back to this specific version, and automatically creates a new draft version for continued editing. Allows optionally adding version notes for the locked version. |
| Publish | Sets the current version as published, making it the live version used for handling new conversations. |
| History | Opens the version history drawer, where you can browse previous versions that were saved using 'Save & lock version', view any version's configuration, and restore a previous version. |
| Restore | Available in the version history drawer on each locked version. Overwrites the current draft with the configuration from the selected locked version. |
Typical edit & save workflow
- While editing your agent's Draft version
- When ready to test your changes, use the Save button to ensure your work is saved and testable and click the Test button to go to the testing Playground
- When satisfied with your agent configuration and ready to deploy it to end users, select Save & lock version from the Save dropdown to create an immutable snapshot
- Click Publish to make the locked snapshot the version that will be accessible by end users
Locked versions are immutable, so you can always restore a known-good configuration from the version history.
Version meta line
Below the agent name, the editor header shows a meta line with the version you're working on and the live version, separated by a dot (for example, "Editing V1 · Published V1"):
- The first label shows Editing VN when you're editing the draft, or Viewing VN when you're browsing a locked version.
- The second label shows Published VN for the live version. If no version has been published yet, this label is omitted.
Version history drawer
Click the History button to open the version history drawer. It contains two sections:
- Current draft: Your active, editable version. Click to switch back to editing the draft.
- Locked versions: A chronological list of all locked snapshots, showing the version number, version notes (if provided), and date. Click any version to view its read-only configuration.
Each locked version has a Restore button that overwrites the current draft with that version's configuration. A confirmation dialog appears before the restore is applied.
Restoring does not roll back the shape of shared actions the version was using. If a linked shared action has changed or been deleted since the version was last published, Stellar surfaces the differences before and after restore so you can react. See Restore behavior for the full flow.
Best practices
- Lock before publishing: Publishing the draft directly means any subsequent edits will immediately affect production. Lock it first to create an immutable snapshot, then publish the locked version.
- 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.
- Add version notes: When locking a version, include descriptive notes so you can easily identify what changed in each snapshot.