# Version Control

The platform supports a simple version control workflow using the expected environments: Development, Staging, and Production. Use **Clone Agent** and **Replace Agent Content** from the Actions column in the Agents table to move changes through each stage.

<div data-with-frame="true"><figure><img src="https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2FlMWkh78uZktAf94qSCAH%2FVersion-Control-Action-Buttons.png?alt=media&#x26;token=08216954-6595-4859-bcff-5a018bb5788c" alt=""><figcaption></figcaption></figure></div>

### Clone and Replace Agent

Clone Agent and Replace Agent Content are the two actions that power the version control procedure. Cloning creates an identical copy of your agent, including all associated data. This allows you to experiment with new workflows and logic without affecting your live production environment. You can also replace one agent with another to promote configurations—such as moving from Dev to Prod. This action overwrites the current agent's content with content from another agent.

{% tabs %}
{% tab title="Clone an agent" %}
To create an identical copy:

* Go to **Workspace > Agents**
* Click the clone button in the Action column
* Select the current workspace and enter a new name to reflect its environment.
* Click **Clone Agent** to confirm

{% hint style="success" %}
The cloned agent is now available in **Workspace > Agents**.
{% endhint %}
{% endtab %}

{% tab title="Replace an agent" %}
To replace a selected agent with another:&#x20;

1. Go to **Workspace > Agents**
2. Click the replace icon in the Action column for the target agent
3. Select the **From** agent from the dropdown
4. The **To** agent is pre-filled and locked to the agent you clicked on&#x20;
5. Click **Replace**

{% hint style="danger" %}
Replacing agent content will overwrite all currently existing content of selected agent. It is a non-reversible action. Always verify you have selected the correct source and target agent before confirming.
{% endhint %}
{% endtab %}
{% endtabs %}

### How Agent Version Control Works

Version control relies on maintaining three separate copies of your agent, each representing an environment:

* Dev: Where you build and iterate freely
* Staging: Where you test changes before going live
* Production: The live agent your end-users interact with

Changes flow in one direction: Dev → Staging → Production. You never edit Staging or Production directly. To reset the process you clone the Production back to Dev.

```mermaid
flowchart LR
    Dev["🔧 Dev Agent"]
    Stage["🧪 Staging Agent"]
    Prod["🚀 Production Agent"]

    Dev -->|"Replace Content"| Stage
    Stage -->|"Replace Content"| Prod
    Prod -->|"Clone"| Dev

    style Dev fill:#e8f4fd,stroke:#1890ff,color:#000
    style Stage fill:#fff7e6,stroke:#faad14,color:#000
    style Prod fill:#f6ffed,stroke:#52c41a,color:#000
```

### Setting Up Your Environments

{% hint style="info" %}
You only need to do this once per agent. After the initial setup, you promote changes using **Replace Agent Content**.
{% endhint %}

{% stepper %}
{% step %}

#### Create Your Dev Agent

Go to **Workspace > Agents** and click **Create New Agent**. Name it with a clear prefix, e.g., `[DEV] Customer Support`. Build your workflows, automated answers, and configurations here.
{% endstep %}

{% step %}

#### Clone to Staging

Once your Dev agent is ready for testing, click the **Clone agent** icon (copy) in the **Actions** column on the Dev agent row. Name the clone `[STAGING] Customer Support`.
{% endstep %}

{% step %}

#### Clone to Production

After testing passes in Staging, click the **Clone agent** icon on the Staging agent row. Rename the clone to `[PROD] Customer Support`. Deploy this agent to your live channels.
{% endstep %}
{% endstepper %}

### Promoting Changes

After the initial setup, use **Replace Agent Content** to push updates from one environment to the next.

{% stepper %}
{% step %}

#### Make Changes in Dev

Edit workflows, update automated answers, or adjust settings in the `[DEV]` agent only. Never modify Staging or Production directly.
{% endstep %}

{% step %}

#### Promote Dev to Staging

Click the **Replace Agent Content** icon in the **Actions** column on the `[STAGING]` agent row. In the dialog, select the `[DEV]` agent from the **From** dropdown. The **To** field is locked to the Staging agent. Review the confirmation screen, then click **Replace**.
{% endstep %}

{% step %}

#### Test in Staging

Validate the changes in Staging using the built-in testing tools or manual conversation testing. Confirm everything works as expected.
{% endstep %}

{% step %}

#### Promote Staging to Production

Click the **Replace Agent Content** icon on the `[PROD]` agent row. Select the `[STAGING]` agent from the **From** dropdown. Review and click **Replace**.
{% endstep %}
{% endstepper %}

```mermaid
flowchart TD
    A["Make changes in DEV agent"] --> B["Replace content: DEV → STAGING"]
    B --> C{"Tests pass?"}
    C -- Yes --> D["Replace content: STAGING → PROD"]
    C -- No --> E["Fix issues in DEV"]
    E --> B
    D --> F["Changes are live"]

    style A fill:#e8f4fd,stroke:#1890ff,color:#000
    style B fill:#fff7e6,stroke:#faad14,color:#000
    style C fill:#fff1f0,stroke:#ff4d4f,color:#000
    style D fill:#f6ffed,stroke:#52c41a,color:#000
    style E fill:#e8f4fd,stroke:#1890ff,color:#000
    style F fill:#f6ffed,stroke:#52c41a,color:#000
```

### Resetting the Cycle

After a successful promotion to Production, reset the cycle by cloning your Production agent back to Dev. This re-baselines Dev to match exactly what is live, giving you a clean starting point for the next round of changes.

Click the copy action icon on the `[PROD]` agent row and name the new `[DEV]` agent. All three environments are now in sync and you can begin developing new changes in Dev.

{% hint style="info" %}
Resetting the cycle is optional but recommended. It prevents drift between environments and ensures Dev always starts from the current production state.
{% endhint %}

### What Gets Replaced

Replacing Agent content will overwrite all currently existing content of selected Agent including all worfklows, variables and plugins.

### Naming Convention

Use a consistent naming convention to keep your agents organized:

| Environment | Naming Pattern         | Example                      |
| ----------- | ---------------------- | ---------------------------- |
| Development | `[DEV] Agent Name`     | `[DEV] Customer Support`     |
| Staging     | `[STAGING] Agent Name` | `[STAGING] Customer Support` |
| Production  | `[PROD] Agent Name`    | `[PROD] Customer Support`    |

### Best Practices

* Respect version control rules: Never edit Staging or Production agents directly — all changes start in Dev
* Sync environments: Reset the cycle after every production deployment to keep environments in sync
* Choose appropriate naming: Use consistent naming prefixes (`[DEV]`, `[STAGING]`, `[PROD]`) and tags so any team member can identify each environment at a glance
* Backups before replacing: Create a backup for each environment in **Designer > Backups** before replacing content in Production, giving you a rollback option if needed
* Replace with care: Review the confirmation screen carefully during **Replace Agent Content** — the action is non-reversible


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helvia.ai/build/version-control.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.