> ## Documentation Index
> Fetch the complete documentation index at: https://botsify.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Versions: Iterate Safely on AI Configurations

> Botsify supports named, versioned agent configurations so you can iterate safely and roll back changes without affecting live users.

When you're working on an AI agent that's already serving real users, making changes directly to the live configuration is risky. A prompt edit that seems harmless can change your agent's personality, break a flow, or cause unexpected responses. Botsify's versioning system solves this problem by letting you maintain multiple named snapshots of your agent's configuration simultaneously — only one of which is ever "active" and serving live traffic.

***

## What Is a Version?

A **version** is a complete, named snapshot of an agent's configuration at a point in time. It captures everything that defines how your agent thinks and behaves. You can have as many versions as you need, edit them independently, and promote any one of them to the active state when you're ready.

<Note>
  Only **one version is active at a time**. Active means it is the configuration being used for all live conversations on that bot. Changes you make to any inactive version have zero effect on users until you explicitly activate that version.
</Note>

### Version Fields

Each version contains the following configurable fields:

| Field | Description |
| - | - |
| `name` | A human-readable label for the version (e.g. `"v1-launch"`, `"experiment-empathetic-tone"`). |
| `agent` | Core agent settings, including the underlying AI model and behavioral parameters. |
| `chat_flow` | The structured conversation flow definition — decision trees, prompts, and branching logic. |
| `memory` | Configuration for what the agent remembers across sessions and how long-term context is managed. |
| `soul` | The agent's emotional tone, values, and personality traits that guide how it expresses itself. |
| `identity` | Who the agent presents itself as — name, role, persona, and background. |
| `user_info` | How the agent collects, stores, and references information about the specific user it's talking to. |

***

## Working with Versions

### Creating a Version

You can create a new version from the Botsify dashboard or via the API. When you create a version, you give it a unique name within that bot and define its initial configuration. A good practice is to clone your current active version as a starting point, then modify the clone.

<Tip>
  Use descriptive version names that capture the intent of the change — for example, `"v2-shorter-replies"` or `"q4-promotion-flow"` — so your team can understand the history at a glance.
</Tip>

### Editing a Version

You can edit any inactive version freely without any risk to live users. Modify prompts, adjust memory settings, restructure chat flows, or rewrite the agent's identity — none of these changes take effect until you activate the version.

<Warning>
  Editing the **active** version will affect live conversations immediately. If you need to make changes safely, create or edit an inactive version first, test it, and then activate it.
</Warning>

### Setting the Active Version

Activating a version promotes it to live status, replacing whatever was previously active. The transition is immediate — the next conversation turn on any channel will use the newly activated version's configuration.

You can activate a version through the dashboard or via the API. Before activating, consider:

* Have you tested the version against representative user inputs?
* Does it handle edge cases your current active version handles?
* Is your team aware of the change?

### Deploying a Version

"Deploying" a version is synonymous with activating it. Once active, the version's configuration is automatically applied across all channels (web, Messenger, WhatsApp) that the bot is connected to — no per-channel deployment step is required.

### Deleting a Version

You can delete any **inactive** version that you no longer need. Deletion is permanent — the version's configuration cannot be recovered. The active version cannot be deleted; you must activate a different version first.

<Note>
  Before deleting a version, consider whether it might serve as a useful reference or rollback target in the future. Storage is not a concern with Botsify, so there's rarely a strong reason to delete old versions unless you want to keep the version list clean.
</Note>

***

## Version Lifecycle Summary

```
Create version  →  Configure & test  →  Activate  →  (Live traffic served)
                                             ↑
                        Roll back by activating a previous version
```

The key safety guarantee is simple: **inactive versions are completely inert**. You can experiment, make breaking changes, and iterate freely on any inactive version knowing that your live users are unaffected until you make an explicit activation decision.

***

## Best Practices

* **Always keep a "known good" version** — before activating a new version, ensure the previous stable version still exists and is not deleted, so you can roll back in one step.
* **Name versions semantically** — use names that describe the change, not just sequential numbers.
* **Test before activating** — use the Botsify dashboard's preview/test interface to validate a version against real conversation scenarios before promoting it to live.
* **Communicate changes to your team** — activating a version is a deployment event. Treat it like one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.