Agent versioning

Agent versioning allows you to experiment with different configurations of your agent without risking your production setup. Create isolated branches, test changes, and gradually roll out updates using traffic percentage deployment.

Overview

The versioning system provides:

• Immutable snapshots of your agent configuration at any point in time
• Isolated branches for testing changes before going live
• Traffic splitting to gradually roll out changes to a percentage of users
• Merging to bring successful experiments back to main

Core concepts

Versions

A version is an immutable snapshot of an agent’s configuration at a specific point in time. Each version has a unique ID (format: agtvrsn_xxxx) and contains:

• conversation_config - System prompt, LLM settings, voice configuration, tools, knowledge base
• platform_settings - Versioned subset including evaluation, widget, data collection, and safety settings
• workflow - Complete workflow definition with nodes and edges

Versions are created automatically when you save changes to a versioned agent. Once created, a version cannot be modified.

Branches

Branches are named lines of development, similar to git branches. They allow you to work on changes in isolation before merging back to the main branch.

• Every versioned agent has a Main branch that cannot be deleted or archived
• Additional branches can be created from any version on the main branch
• Each branch has: id (agtbrch_xxxx), name, description, and a list of versions
• Branch names can contain: letters, numbers, and () [] {} - / . (max 140 characters)

Traffic deployment

Traffic can be split across multiple branches by percentage, enabling gradual rollouts and A/B testing.

• Percentages must always total exactly 100%
• Traffic routing is deterministic based on conversation ID (the same user consistently routes to the same branch)
• Only non-archived branches with 0% traffic can be archived

Drafts

Unsaved changes are stored as drafts, allowing you to work on changes without immediately creating a new version.

• Drafts are per-user, per-branch (each team member has their own draft)
• Drafts are automatically discarded when a new version is committed
• Drafts are also discarded when merging into a branch

Enabling versioning

Versioning is opt-in and must be explicitly enabled. You can enable it when creating a new agent or on an existing agent.

Enable when creating an agent

Enable on an existing agent

Enabling versioning creates the initial “Main” branch with the first version containing the current agent configuration.

Working with branches

Creating a branch

Branches can only be created from versions on the main branch. You can optionally include configuration changes that will be applied to the new branch’s initial version.

1
branch = client.conversational_ai.agents.branches.create(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
3
    parent_version_id="agtvrsn_xxxx",
4
    name="experiment-v2",
5
    description="Testing new prompt and voice settings"
6
)
7
8
print(f"Created branch: {branch.created_branch_id}")
9
print(f"Initial version: {branch.created_version_id}")

Listing branches

1
branches = client.conversational_ai.agents.branches.list(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
3
)
4
5
for branch in branches.branches:
6
print(f"{branch.name}: {branch.id}")

Getting branch details

1
branch = client.conversational_ai.agents.branches.get(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
3
    branch_id="agtbrch_xxxx"
4
)
5
6
print(f"Branch: {branch.name}")
7
print(f"Versions: {len(branch.versions)}")

Committing changes

When you update an agent with versioning enabled, specify the branch_id to create a new version on that branch.

A new version is automatically created on the specified branch, and any existing draft for that user on that branch is discarded.

Deploying traffic

Use the deployments endpoint to distribute traffic across branches. This enables gradual rollouts and A/B testing.

1
deployment = client.conversational_ai.agents.deployments.create(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
3
    deployments=[
4
        {"branch_id": "agtbrch_main", "percentage": 90},
5
        {"branch_id": "agtbrch_xxxx", "percentage": 10}
6
    ]
7
)

Traffic routing is deterministic based on the conversation ID, ensuring the same user consistently reaches the same branch across sessions.

Merging branches

When you’re satisfied with changes on a branch, merge them back to the main branch.

1
merge = client.conversational_ai.agents.branches.merge(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
3
    source_branch_id="agtbrch_xxxx",
4
    target_branch_id="agtbrch_main",
5
    archive_source_branch=True  # Default: true
6
)

Merging:

• Creates a new version on the main branch with the source branch’s configuration
• Optionally archives the source branch (default behavior)
• Automatically transfers traffic from the source branch to main

Archiving branches

Archive branches you no longer need. This helps keep your branch list organized.

1
client.conversational_ai.agents.branches.update(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
3
    branch_id="agtbrch_xxxx",
4
    archived=True
5
)

Archived branches can be unarchived by setting archived=False.

Retrieving specific versions

You can retrieve an agent at a specific version or branch tip.

Get agent at specific version

1
agent = client.conversational_ai.agents.get(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
3
    version_id="agtvrsn_xxxx"
4
)

Get agent at branch tip

1
agent = client.conversational_ai.agents.get(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
3
    branch_id="agtbrch_xxxx"
4
)

Include draft changes

1
agent = client.conversational_ai.agents.get(
2
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
3
    branch_id="agtbrch_xxxx",
4
    include_draft=True
5
)

Settings reference

Versioned settings

These settings can differ between versions and branches:

Per-agent settings

These settings are shared across all versions:

Best practices

Next steps