# Versions

> Publish an agent as a numbered version, read the version history, compare any two versions, and roll back to an earlier one.

Source: https://docs.amomic.in/build/versions

---

A version is a numbered record of an agent's whole setup at one moment: its persona, its per-channel personas, its knowledge and its tools. The **Versions** tab in the agent studio lets you publish a new version, read every version you have published, compare any two, and roll back.

**Who can do this:** workspace **owners** and **admins**.

![The Versions tab: an Unpublished changes card expanded to show one added instruction line and booking turned on, above four published versions](https://docs.amomic.in/screens/agents/versions-history.light.webp)

*Saved edits since Version 4, shown above the version history.*

## What a version is, and what it is not

Customers are always served the agent's **saved** settings. A version does not hold changes back until you publish. Saving on the Persona tab, flipping a tool switch or attaching a knowledge base is live from the next message, whether or not you publish. See [When your changes reach customers](/build/agents#when-your-changes-reach-customers).

What publishing gives you:

- **A record.** Each version keeps exactly what the agent was set to, who published it and when, so you can see what was live on a given day.
- **A point to come back to.** You can compare against any version and roll the agent back to it.
- **The first deployment.** An agent must be published once before it can be deployed to any channel.

A version records:

| Part | What is recorded |
|---|---|
| Persona | Name, purpose, instructions, language, grounding policy, knowledge requirement |
| Per-channel personas | The Phone, WhatsApp and Web chat overrides |
| Knowledge | Which knowledge bases are attached, and which content revision of each |
| Tools | Every tool switch and its settings: WhatsApp sender and approved templates, booking calendar, and so on |

A version never changes once it is written. To change anything you publish another one.

## Publish a version

You can publish from the **Overview** tab (**Publish first version** or **Publish new version**) or from **Versions** (**Publish**, **Publish new version**, or **Review & publish** on the **Unpublished changes** card). All of them open the same dialog.

::: steps

::: step Pass the readiness checks

Publishing is disabled until the agent is ready. The Versions tab shows *This agent isn’t ready to publish yet. Resolve the readiness checks first.* with a **Review checks** link. What blocks and what only recommends is listed in [Readiness checks](/build/testing#readiness-checks).
:::

::: step Write a heading

The dialog title says which version you are about to write, for example **Publish Version 5**. Type a **Version heading** of up to 120 characters. It is optional, but `Stopped quoting AMC prices in chat` is far more useful three months from now than `Untitled version`.
:::

::: step Check what changes

Under **Changes since Version 4** the dialog shows exactly what this version changes compared with the current one. For a first version it shows **What this version starts with**.
:::

::: step Publish

Choose **Publish**. The console confirms *Version 5 published.*
:::

:::

![The Publish Version 5 dialog with a version heading typed, one added instruction line and three tool changes listed](https://docs.amomic.in/screens/agents/versions-publish-dialog.light.webp)

### Publishing something you already published

If the agent's setup matches an earlier version exactly, no duplicate is written. The dialog is titled **Make Version 2 current** and says *This is exactly Version 2. Publishing makes it current again; no new version is written.* After publishing, the toast reads *This matches Version 2, so that version is live again.*

If nothing differs from the current version, the dialog says *Nothing has changed since Version 4.* and **Publish** is disabled.

When knowledge content has refreshed but nothing you typed has changed, the dialog says *No visible changes. Knowledge content has been refreshed since the last version.* Publishing then records the new content revisions.

## Unpublished changes

When you have saved anything since the current version, an **Unpublished changes** card sits at the top of the Versions tab. It reads *Saved edits since Version 4. They're already live, but not yet recorded as a version.*

- Open the card to see the changes, in the same layout as the version history.
- **Review & publish** opens the publish dialog.
- **Discard** puts the agent back to exactly the current version. The dialog is titled **Discard unpublished changes?** and confirms with **Discard changes**. Because your saved edits are live, discarding also changes what customers get, straight away.

## Read the version history

Versions are listed newest first, like a commit log. Each row shows:

- the heading, or *Untitled version*
- `Current` on the version the agent is on, and `Rollback of v2` on a version a rollback created
- the version number (`v4`), who published it, and when
- the first seven characters of its configuration hash. Two versions with the same hash have identical setups.
- how much it changed from the version before it, as added and removed lines plus a count of changed settings, or *First version*
- **Roll back**, on versions you can roll back to

Open a row to see *Changes from Version 3 to Version 4*.

### How changes are shown

| Section | Shown as |
|---|---|
| **Name**, **Purpose**, **Instructions** | A line-by-line diff. Unchanged stretches fold down, with a link to show them. |
| **Settings** | Language, Grounding policy and Knowledge requirement, with the old value struck through beside the new one. |
| **Knowledge** | Each knowledge base marked **Added** or **Removed**. A knowledge base deleted since then shows as *Deleted knowledge base*. |
| **Tools** | Each switch drawn as `Off → On`, with its settings indented beneath: **Sends from**, **Approved templates**, **May message someone other than the customer**, **Calendar**, **May reschedule**, **May cancel**. |
| **Phone persona**, **WhatsApp persona**, **Web chat persona** | A line diff of each channel's purpose and instructions. A channel that uses the default reads *(uses the agent's default)*. |

Only what changed is shown. A **Show 3 unchanged settings** link (the number varies) reveals the rest of a section.

## Compare any two versions

Choose **Compare** at the top of the tab. It appears once there are at least two versions.

![Compare open with Version 2 as the base and the Unpublished draft as the comparison, showing two sections changed](https://docs.amomic.in/screens/agents/versions-compare.light.webp)

Pick a **base** on the left and a version to **compare** on the right. **Unpublished draft** is available on either side when you have unpublished changes, so you can answer "what is different between Version 2 and what customers get today?". The panel shows how many sections changed. If you pick the same version twice it says *Pick two different versions to compare.*, and two identical versions read *These two are identical.*

## Roll back to an earlier version

Rollback is how you undo a change that went wrong.

::: steps

::: step Choose the version

On the version you want back, choose **Roll back**.
:::

::: step Check what will change

The dialog, **Roll back to Version 1?**, shows **What will change**: the difference between the agent as it is now (including unpublished edits) and that version.
:::

::: step Confirm

Optionally change the heading (the default is *Rolled back to Version 1*), then choose **Roll back to Version 1**.
:::

:::

![The Roll back to Version 1 dialog listing removed instruction lines, a language change and a removed knowledge base](https://docs.amomic.in/screens/agents/versions-rollback-dialog.light.webp)

What happens:

- That version's instructions, persona, per-channel personas, settings, tools and knowledge are copied back onto the agent and published as a **new** version. History only moves forward: rolling back to Version 2 from Version 4 writes Version 5, marked `Rollback of v2`. You can roll forward again the same way.
- **It takes effect on every channel straight away**, and it replaces any unpublished edits.
- Deployments keep serving the agent. You do not need to redeploy.
- The toast reads *Rolled back. Version 5 is live, restored from Version 2.*

Limits:

- A knowledge base **deleted** since that version cannot come back. It is skipped and the console warns *1 knowledge base was deleted since then and couldn’t be restored.*
- If that version required knowledge and **none** of its knowledge bases are left ready, the rollback is refused before anything changes: *Version 1 answers from knowledge that is no longer available. Attach a ready knowledge base instead.*
- Rolling back to the version that is already live, with nothing unpublished, is refused with *Version 4 is already live.* The console hides **Roll back** in that case.
- A rollback restores the agent. It does not change a deployment's own settings, such as a phone number's greeting or voice. Those are edited on the deployment. See [Deployments](/build/deployments#edit-a-deployment-s-settings).

## Troubleshooting

| What you see | Why | What to do |
|---|---|---|
| **Publish** is greyed out | A readiness check is failing. | Choose **Review checks** and fix what is *Required before publishing*. |
| *Agent is not ready to publish.* | A blocker appeared after you opened the dialog, for example a knowledge base stopped being ready. | Open **Overview** and resolve it. |
| *Agent changed since it was loaded.* | Someone saved the agent after you opened the tab. | Reload and try again. |
| Publishing did not create a new number | The setup matched an earlier version, so that version was made current. | Nothing to do. Check the toast. |
| A rollback "did nothing" to a phone call | The difference was in the deployment's voice settings, which versions do not hold. | Edit the deployment's **Voice settings**. |
| *Version history couldn’t be loaded.* | The history request failed. | Reload the page. |

## Where to go next

::: cards

::: card Edit the agent
[Agents](/build/agents): persona, channel personas and knowledge.
:::

::: card Check before you publish
[Testing & publishing](/build/testing): the test tab and readiness checks.
:::

::: card Put a version on a channel
[Deployments](/build/deployments): deploy, edit and disable.
:::

:::