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.
:::warning No published 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
:::tip Version safety Locked versions are immutable, so you can always restore a known-good configuration from the version history. :::
Version status pill
The agent editor header displays a status pill with two segments:
- Left segment: Shows either "Editing draft: vN" (when editing the draft) or "Viewing: vN" (when browsing a locked version)
- Right segment: Shows "Published: vN" or "Not published" if no version has been published yet
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.
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.