用途:当用户希望现在完成智能体改动,但改动在发布时刻之前不得影响线上流量时,用分支方式暂存。所有工作发生在非线上分支,main 继续提供当前配置,只有用户在发布时合并分支(或把流量逐步切到该分支)后改动才上线。这里没有定时器,所谓“排期”指在分支上暂存并保持不合并,直到用户准备好。需明确告知用户:不会自动发布,需由用户在发布时执行合并或放量。
主要能力与用法:接口主机为 https://api.elevenlabs.io,请求头 xi-api-key: $API_KEY,由工程师提供 $API_KEY 与 $AGENT_ID。先确认改动内容(提示词/配置编辑、新工具、知识库文档新增或重新抓取、智能体应知道的事实)与上线时刻,并确认由用户自己触发合并或放量。写入前先读取分支列表(GET /v1/convai/agents/$AGENT_ID/branches)获取 id、current_live_percentage、protection_status、parent_branch_id、draft_exists,并读取当前活动分支配置(GET /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID)。从 main 创建发布分支,parent_version_id 设为 main 的 HEAD 版本,新分支初始为 0% 线上流量。所有编辑都带 ?branch_id=<新分支id>,配置/提示词/工具用 PATCH /v1/convai/agents/$AGENT_ID?branch_id=<新分支id>;知识库新增或重新抓取用 POST /v1/convai/knowledge-base/text 或 POST /v1/convai/knowledge-base/url,并在该分支上挂载。事实类内容没有记忆端点,且智能体记忆是全局而非按分支隔离,必须放在分支作用域的系统提示词或知识库文档中。可在分支上发布版本做验证,不影响 main。发布时由用户执行合并 POST /v1/convai/agents/$AGENT_ID/branches/<launch-branch-id>/merge,建议先做合并预览;若 main 为 admin_perms_required 且用户非管理员,合并会因权限失败,应提前提示。也可用流量拆分逐步放量(如 10→50→100),单次调用中各活动分支流量之和须恰好为 100。
适用场景:产品发布、营销上线、解禁、定时公告等需要“先准备、后生效”的智能体变更。多人同时工作时,每人从 main 各建分支避免冲突;两个分支修改同一字段并都合并时,平台会提示冲突并保留较新的值,应让用户查看合并预览。
限制:没有定时器,不会自动发布;合并或放量由用户触发;权限不足时合并失败;流量拆分必须合计 100;事实类内容无法按分支隔离,需改用分支作用域提示词或知识库文档。具体分支机制、错误恢复与流量拆分规则应遵循 branches、versions、merging 相关技能。