Entity Versioning
Agents, tools, and hooks carry semantic version numbers as first-class fields, giving your organisation a clear audit trail of how these workspace entities evolve over time. Every change is captured automatically as a snapshot, so you can browse history, compare versions, and roll back to a previous state.
Which entities are versioned
Versioning applies to three entity types:
| Entity | Where it lives | Version field |
|---|---|---|
| Agents | Settings → Agents | agentVersion |
| Tools (functions) | Settings → Tools | functionVersion |
| Hooks (execution environments) | Settings → Hooks | customCodeExecutionEnvironmentVersion |
Other workspace entities (topics, intents, dictionaries, jobs, benchmarks, and so on) are not versioned.
Version format
Versions use semantic versioning in the form MAJOR.MINOR.PATCH — for example 1.2.3. The version field is validated against the X.Y.Z pattern, so any value you enter must follow this format.
Setting a version
The version is a normal field on the entity's editor, found near the bottom of the form above the save buttons.
- On create — The version defaults to
0.1.0if you don't enter one. - On edit — A Use suggested (vX.Y.Z) button next to the field suggests the next version by incrementing the patch number (so
1.2.3→1.2.4). - Manual entry — You can type any
X.Y.Zvalue into the field. The suggestion only ever bumps the patch segment, so major and minor version bumps must be entered manually.
Use the Use suggested button for routine edits, and manually bump the minor or major segment when you ship a meaningful change — for example 1.2.4 → 1.3.0 for a new capability, or 1.3.0 → 2.0.0 for a breaking change.
Where the version appears
- In lists — Each row shows the version inline, e.g.
Sales Assistant (v1.2.3). - In the editor — A Version field displays an orange vX.Y.Z (current) badge showing the saved version, alongside the editable text field (placeholder
1.2.3) and the Use suggested button.
Version history
Each editor has a versions history expander:
- Agent versions history — in the agent editor
- Tool versions history — in the tool editor
- Execution hook versions history — in the hook editor
Expand it to see a table of every recorded version:
| Column | Description |
|---|---|
| Date | When the change was made |
| Changes | Number of fields that changed in that version |
| Changed by | The user who made the change |
| Version | The semantic version that was current at that point (e.g. v1.2.3) |
| # | The snapshot sequence number |
A summary bar shows Total versions and total changes across the entity's lifetime.
Snapshots are captured automatically by the platform whenever an entity changes — you don't need to do anything to record history. The app shows the most recent snapshots for each entity.
Comparing versions
Click any row in the history table to open the Changes Summary for that version:
- Changes are grouped into categories such as Model Settings, Tools & Capabilities, Knowledge, Behavior, Permissions, Identity, and Code Execution.
- Use View Full Diff to open an IDE-style Version X vs Current comparison, with additions, removals, and modifications colour-coded so you can see exactly what changed.
Rolling back
From the Changes Summary you can choose Rollback. After confirming (Rollback to version X?), the editor form is populated with the values from that historical version. Review the values and save to restore that configuration.
Rollback loads the historical values into the editor — it does not delete later versions. You still need to Save to apply the rolled-back configuration, and the rollback itself will be recorded as a new version.
Availability
- The version field is available on all subscriptions, so every plan can set and display version numbers.
- The version history (snapshots, change summary, full diff, and rollback) is available for Business and Enterprise subscriptions. On Individual plans, the history expander shows "No changes recorded yet".
To upgrade to Business or Enterprise, or to modify existing Business/Enterprise workspaces, you will need to contact support.