监控

智能体版本控制

使用分支、版本和流量部署，安全地试验智能体配置

智能体版本控制让你可以试验不同的智能体配置，而不会影响生产环境设置。创建隔离分支、测试更改，并使用按流量百分比分配逐步发布更新。

想运行 A/B 测试？请查看实验，了解针对实时流量测试智能体更改的推荐工作流程。

概述

版本控制系统提供：

  • 任意时间点智能体配置的 不可变快照
  • 用于在上线前测试更改的 隔离分支
  • 将更改逐步发布给一定比例用户的 流量拆分
  • 将任意分支的更改引入其他任意分支的 合并
  • 将主分支最新更改拉取到某个分支的 变基

在智能体上启用版本控制后，无法关闭。为现有智能体启用版本控制前请考虑清楚。

核心概念

版本

版本是某个时间点智能体配置的不可变快照。每个版本都有唯一 ID（格式：agtvrsn_xxxx），包含：

  • conversation_config - 系统提示词、LLM 设置、音色配置、工具、知识库
  • platform_settings - 包含评估、组件、数据收集和安全设置在内的已版本化子集
  • workflow - 包含节点和边的完整工作流程定义

保存已启用版本控制的智能体更改时，系统会自动创建版本。版本一经创建，便无法修改。

分支

分支是命名的开发线，类似 git 分支。它让你可以在隔离环境中处理更改，然后再合并回主分支。

  • 每个已启用版本控制的智能体都有一个不可删除或归档的 主分支
  • 可从任何现有分支上的任意版本创建额外分支，不限于主分支
  • 分支可合并到其他任意分支；非主分支可变基到主分支，以拉取其最新更改
  • 每个分支包含：id（agtbrch_xxxx）、名称、描述和版本列表
  • 分支名称可包含：字母、数字和 () [] {} - / .（最多 140 个字符）

流量部署

可按百分比将流量拆分到多个分支，从而实现逐步发布和 A/B 测试。

  • 百分比总和必须始终恰好为 100%
  • 流量路由会根据对话 ID 确定性地 分配（同一用户会始终路由到同一分支）
  • 只有流量为 0% 的未归档分支才能归档

草稿

未保存的更改会存储为草稿，让你无需立即创建新版本也能处理更改。

  • 草稿按 用户和分支 区分（每位团队成员都有自己的草稿）
  • 提交新版本时会自动丢弃草稿
  • 合并到分支时也会丢弃草稿

启用版本控制

版本控制为选择性启用功能，必须明确开启。你可以在创建新智能体时启用，也可在现有智能体上启用。

版本控制一经启用，便无法关闭。这是对智能体的永久更改。

创建智能体时启用

在控制台中打开智能体，进入 设置，然后启用版本控制。启用后，版本控制 标签页可用于管理分支、草稿、版本和流量部署。

在现有智能体上启用

在控制台中打开智能体，前往 设置，然后开启版本控制。

启用版本控制会创建初始“主分支”，其中首个版本包含当前智能体配置。

使用分支

创建分支

可从任意分支上的任何版本创建分支，不限于主分支。还可以选择包含将应用到新分支初始版本的配置更改。

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

列出分支

branches = client.conversational_ai.agents.branches.list(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
for branch in branches.branches:
print(f"{branch.name}: {branch.id}")

获取分支详情

branch = client.conversational_ai.agents.branches.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)
print(f"Branch: {branch.name}")
print(f"Versions: {len(branch.versions)}")

提交更改

更新已启用版本控制的智能体时，请指定 branch_id，以便在该分支上创建新版本。

打开智能体的 版本控制 标签页，切换到目标分支，编辑配置后保存，即可创建新版本。

系统会在指定分支上自动创建新版本，并丢弃该用户在此分支上的所有现有草稿。

部署流量

使用 deployments 端点将流量分配到各个分支，从而实现逐步发布和 A/B 测试。

deployment = client.conversational_ai.agents.deployments.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    deployments=[
        {"branch_id": "agtbrch_main", "percentage": 90},
        {"branch_id": "agtbrch_xxxx", "percentage": 10}
    ]
)
所有百分比的总和必须恰好为 100%。否则部署会失败。

流量路由会根据对话 ID 确定性地分配，确保同一用户跨会话时始终访问同一分支。

合并分支

当你满意某个分支上的更改时，可将其合并到另一分支。任何未归档分支都可合并到其他任意未归档分支，不限于合并到主分支。

若要在合并前审查分支更改，或要合并到你没有写入权限的分支，请创建合并提案，而非直接合并。

merge = client.conversational_ai.agents.branches.merge(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    source_branch_id="agtbrch_xxxx",
    target_branch_id="agtbrch_main",
    archive_source_branch=True,  # Default: true
    force=False  # Default: false
)

合并会：

  • 使用源分支配置在目标分支上创建新版本
  • 可选择归档源分支（默认行为）
  • 自动将流量从源分支转移到目标分支

如果源分支是从目标分支创建的（且没有超出目标分支的新提交），合并会因 no_new_changes_to_merge 而失败；如果该分支已合并到该目标分支，则会因 branch_already_merged 而失败。

解决合并冲突

如果源分支和目标分支在分叉后都更改了某项设置，默认会保留最近更新分支中的值。设置 force=True 可始终改用源分支的值，不受时间戳影响。

提交前可预览合并结果，包括所有会被覆盖的字段：

preview = client.conversational_ai.agents.branches.preview_merge(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    source_branch_id="agtbrch_xxxx",
    target_branch_id="agtbrch_main",
    force=False
)
print(preview.overridden_fields)
print(preview.conflicts)

将分支变基到 main

变基会将 main 分支的最新更改拉取到另一个分支，类似于 git rebase。这样可以让长期存在的分支与 main 保持同步，而无需立即将分支自身的更改合并回去。

client.conversational_ai.agents.branches.rebase(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)

变基会：

  • 在分支上创建一个包含 main 最新更改的新版本
  • 保留分支自身的更改：如果某项设置同时在分支和 main 中被编辑，始终保留分支的值
  • 如果分支已包含 main 的所有更改，则返回 branch_already_up_to_date 错误

只有非 main 分支可以变基，且只能变基到 main。对 main 分支本身变基会 返回 cannot_rebase_main 错误。

提交前可先预览变基结果：

preview = client.conversational_ai.agents.branches.preview_rebase(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)
print(preview.overridden_fields)

归档分支

归档不再需要的分支，有助于保持分支列表整洁。

client.conversational_ai.agents.branches.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    archived=True
)

无法归档已分配流量的分支。归档前请移除所有流量。

将 archived=False 即可取消归档分支。

获取特定版本

可以获取指定版本或分支最新提交的智能体。

获取指定版本的智能体

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    version_id="agtvrsn_xxxx"
)

获取分支最新提交的智能体

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx"
)

包含草稿更改

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbrch_xxxx",
    include_draft=True
)

设置参考

版本化设置

这些设置可因版本和分支而异：

类别设置
对话配置系统提示词、智能体个性、LLM 选择和参数、语音设置（TTS 模型、音色 ID）、工具配置、知识库、首条消息、语言设置、轮次检测、打断设置
版本化平台设置evaluation - 评估标准、widget - 小组件外观和行为、data_collection - 结构化数据提取、overrides - 对话启动覆盖项、workspace_overrides - Webhook 配置、testing - 测试配置、safety - 安全护栏（IVC/非 IVC 设置）
工作流完整工作流定义（节点和边）

每个智能体的设置

这些设置在所有版本间共享：

设置描述
name, tags智能体名称和标签（仅在提交到 main 分支时更新）
auth身份验证设置和允许列表
call_limits并发和每日限制
privacy保留设置和零保留模式
ban封禁状态（仅管理员）

在非 main 分支上更改名称和标签，需合并到 main 后才会保存到智能体。

最佳实践

1

创建分支前先编写测试

创建新分支前，先设置用于捕捉预期行为的自动化测试。这能建立 基准，并帮助你在迭代实验时尽早发现回归问题。

2

使用描述性分支名称

选择能清楚说明实验目的的分支名称。加入功能名称、假设或工单编号，方便参考（例如 feature/new-greeting-flow 或 experiment/shorter-responses）。

3

记录分支用途

使用分支描述字段说明正在测试的假设、衡量成功的指标，以及任何依赖项或注意事项。这有助于团队成员了解正在进行的 实验。

4

使用草稿保存进行中的工作

迭代更改时请经常保存草稿。这样可以保留工作成果，避免创建 不必要的版本。准备好测试或部署后再提交。

5

先从小比例流量开始

部署新分支时，先从 5-10% 的流量开始。这样在出现问题时可限制 影响范围，同时仍能获得有意义的数据。

6

增加流量前监测关键指标

使用分析仪表板比较分支性能。 查看通话完成率、平均对话时长、成功评估分数和 工具执行率。仅当指标达到或超过 main 分支 基准时，才增加流量。

7

逐步增加流量

随着信心提升，逐步扩大流量（10% → 25% → 50% → 100%）。这种方法 可在每个阶段验证性能的同时降低风险。

8

保持分支短期存在

及时合并成功的实验，避免配置漂移。对于需要 长期保持开放的分支，定期将其变基到 main，以免偏离过远并导致 更难合并。

后续步骤

实验

使用分支和流量部署运行 A/B 测试

测试

为智能体版本设置自动化测试

分析

监测不同分支的性能

CLI

通过命令行管理版本