# Versioning

### What is Versioning?

Versioning helps you track and manage changes to an Agent configuration over time.

In WorkfxAI:

* **Draft** is your working copy (editable).
* **Versions** are immutable snapshots created when you **Publish**.
* You can **Restore** any version back into your current Draft.
* You can **Export Config** for a specific version to get its DSL (YAML) for auditing, backup, or migration.

***

### Key Concepts

#### Draft (single editable workspace)

* Each Agent has **exactly one Draft** at any time.
* Draft is where you edit:
  * prompts/instructions
  * workflows (ChatFlow / JobFlow)
  * tools and tool parameters
  * variables and bindings
  * model settings
  * other configuration

> Think of Draft as “the current working state”.

#### Published Version (immutable snapshot)

* Every time you **Publish**, WorkfxAI creates a new **Version**.
* Versions are **read-only snapshots** of your Agent configuration at the time of publishing.
* Versions give you:
  * traceability (what changed, when)
  * rollback options
  * stable checkpoints for production use

***

### How Publishing Creates Versions

When you click **Publish**:

1. WorkfxAI validates your configuration (based on your Agent type).
2. A **new Version** is created and added to **Version History**.
3. Your “latest published version” updates.

<figure><img src="https://4046886348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYf4L4Z4IuV1CQn3whQYb%2Fuploads%2F4HN0UjdV4296GH26uHWm%2Fimage.png?alt=media&#x26;token=ae0846ac-db8a-4b52-a41a-72f72f95f332" alt=""><figcaption></figcaption></figure>

***

### Version History UI (Versions Panel)

In the Versions panel, you can typically:

* See the list of versions with timestamps
* Identify the **Latest** version
* Open a version menu (⋯) for actions

<figure><img src="https://4046886348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYf4L4Z4IuV1CQn3whQYb%2Fuploads%2Fh8nVbkjhEteBhL0wm6br%2Fimage.png?alt=media&#x26;token=de0163c1-dcdc-41fc-b04a-fe2f9d1a400d" alt=""><figcaption></figcaption></figure>

***

### Restore: Put a Historical Version Into Current Draft

**Restore** copies the selected Version’s configuration into your current Draft.

#### What Restore does

* Replaces your current Draft configuration with the selected Version’s configuration.
* Lets you safely roll back, experiment, or recover a known-good state.

#### What Restore does *not* do

* It does **not** publish automatically.
* It does **not** modify the historical Version.
* It does **not** delete other versions.

#### Typical workflow

1. Choose a version in Version History
2. Click **Restore**
3. Confirm the Draft now matches that version
4. Optionally adjust the Draft
5. Click **Publish** to create a new version

📌 Best practice: After Restore, **Publish** to create a new version so you have a clear “rollback + republish” checkpoint.

### Export Config: Export DSL for a Specific Version

**Export Config** exports the selected version’s configuration as **DSL (YAML)**.

Use Export Config when you want:

* a backup of a known-good release
* an audit artifact (exact released configuration)
* to migrate/copy configuration into another workspace
* to compare changes between versions in Git

<figure><img src="https://4046886348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FYf4L4Z4IuV1CQn3whQYb%2Fuploads%2Fctei8OzjFUULIQRAi4Zw%2Fimage.png?alt=media&#x26;token=a1f58f65-f04f-4c95-ba7f-8c619d08e453" alt=""><figcaption></figcaption></figure>

***

### Draft vs Version Export (Important)

Depending on your UI, you may have export entry points in two places:

* **Export as DSL (from editor)** → exports the **current Draft**
* **Export Config (from Versions panel)** → exports a **specific published Version**

This difference matters for compliance and reproducibility:

* Draft can be mid-edit
* Versions are immutable and reflect released state

***

### Common Workflows

#### Workflow A: Safe iteration and rollback

1. Make changes in Draft
2. Publish → creates Version
3. If issues occur → Restore previous Version
4. Publish again → creates a new “rollback” Version

#### Workflow B: Export a released configuration

1. Open Versions panel
2. Select the release you want
3. Export Config → save the DSL

#### Workflow C: Audit a change

1. Export Config for Version A and Version B
2. Compare the two YAML files in Git

***

### FAQ

#### Does Restore overwrite my current Draft?

Yes. Restore replaces the current Draft configuration with the selected version’s configuration.

#### Can I have multiple Drafts?

No. Each Agent has one Draft.

#### Is every Version published?

Yes—Versions are created on Publish.

###