Controle de versão do agente | ElevenLabs Documentation

O controle de versão de agentes permite experimentar diferentes configurações do seu agente sem colocar em risco a configuração de produção. Crie branches isoladas, teste alterações e implemente atualizações gradualmente usando distribuição por porcentagem de tráfego.

Quer executar testes A/B? Consulte Experimentos para ver o workflow recomendado para testar alterações no agente com tráfego real.

Visão geral

O sistema de controle de versão oferece:

Snapshots imutáveis da configuração do seu agente a qualquer momento
Branches isoladas para testar alterações antes de entrar em produção
Divisão de tráfego para implementar alterações gradualmente para uma porcentagem dos usuários
Merge para levar alterações de qualquer branch a qualquer outra branch
Rebase para trazer as alterações mais recentes da branch principal para uma branch

Depois que o controle de versão é ativado em um agente, ele não pode ser desativado. Considere isso antes de ativar o controle de versão em agentes existentes.

Conceitos principais

Versões

Uma versão é um snapshot imutável da configuração de um agente em um momento específico. Cada versão tem um ID único (formato: agtvrsn_xxxx) e contém:

conversation_config - Prompt de sistema, configurações de LLM, configuração de voz, ferramentas, base de conhecimento
platform_settings - Subconjunto versionado que inclui configurações de avaliação, widget, coleta de dados e segurança
workflow - Definição completa do workflow com nós e conexões

As versões são criadas automaticamente quando você salva alterações em um agente com controle de versão. Depois de criada, uma versão não pode ser modificada.

Branches

Branches são linhas de desenvolvimento nomeadas, semelhantes a branches do git. Elas permitem trabalhar em alterações de forma isolada antes de fazer o merge de volta na branch principal.

Todo agente com controle de versão tem uma branch Main que não pode ser excluída nem arquivada
Branches adicionais podem ser criadas a partir de qualquer versão em qualquer branch existente, não apenas da principal
Branches podem receber merge em qualquer outra branch, e branches que não são a principal podem receber rebase sobre a principal para incorporar suas alterações mais recentes
Cada branch tem: ID (agtbrch_xxxx), nome, descrição e uma lista de versões
Os nomes de branches podem conter: letras, números e () [] {} - / . (máximo de 140 caracteres)

Distribuição de tráfego

O tráfego pode ser dividido entre várias branches por porcentagem, permitindo implementações graduais e testes A/B.

As porcentagens devem sempre totalizar exatamente 100%
O roteamento de tráfego é determinístico com base no ID da conversa (o mesmo usuário é sempre direcionado à mesma branch)
Apenas branches não arquivadas com 0% de tráfego podem ser arquivadas

Rascunhos

As alterações não salvas são armazenadas como rascunhos, permitindo trabalhar em alterações sem criar imediatamente uma nova versão.

Os rascunhos são por usuário e por branch (cada membro da equipe tem seu próprio rascunho)
Os rascunhos são descartados automaticamente quando uma nova versão é confirmada
Os rascunhos também são descartados ao fazer merge em uma branch

Ativar o controle de versão

O controle de versão é opcional e precisa ser ativado explicitamente. Você pode ativá-lo ao criar um novo agente ou em um agente existente.

Depois de ativado, o controle de versão não pode ser desativado. Esta é uma alteração permanente no seu agente.

Ativar ao criar um agente

Ativar pelo dashboard

Ativar pela API

Abra seu agente no dashboard, acesse Configurações e ative o controle de versão. Depois de ativado, a aba Controle de versão fica disponível para gerenciar branches, rascunhos, versões e distribuição de tráfego.

Ativar em um agente existente

Ativar pelo dashboard

Ativar pela API

Abra seu agente no dashboard, acesse Configurações e ative o controle de versão.

Ativar o controle de versão cria a branch inicial “Main” com a primeira versão que contém a configuração atual do agente.

Trabalhar com branches

Criar uma branch

Branches podem ser criadas a partir de qualquer versão em qualquer branch, não apenas da principal. Opcionalmente, você pode incluir alterações de configuração que serão aplicadas à versão inicial da nova branch.

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}")

Listar branches

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

Ver detalhes de uma branch

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)}")

Confirmando alterações

Ao atualizar um agente com o versionamento ativado, especifique o branch_id para criar uma nova versão nessa ramificação.

Atualizar pelo painel

Atualizar pela CLI

Atualizar pela API

Abra a aba Versionamento do agente, mude para a ramificação de destino, edite a configuração e salve para criar uma nova versão.

Uma nova versão é criada automaticamente na ramificação especificada, e qualquer rascunho existente desse usuário nessa ramificação é descartado.

Distribuindo tráfego

Use o endpoint de implantações para distribuir o tráfego entre ramificações. Isso permite lançamentos graduais e testes 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}
    ]
)

Todas as porcentagens devem somar exatamente 100%. A implantação falhará caso não somem.

O roteamento de tráfego é determinístico com base no ID da conversa, garantindo que o mesmo usuário acesse sempre a mesma ramificação entre sessões.

Mesclando ramificações

Quando estiver satisfeito com as alterações em uma ramificação, mescle-as em outra. Qualquer ramificação não arquivada pode ser mesclada a qualquer outra ramificação não arquivada, não apenas à principal.

Para que as alterações de uma ramificação sejam revisadas antes da mesclagem ou para acessar uma ramificação para a qual você não tem permissão de escrita, abra uma proposta de mesclagem em vez de mesclar diretamente.

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
)

A mesclagem:

Cria uma nova versão na ramificação de destino com a configuração da ramificação de origem
Opcionalmente arquiva a ramificação de origem (comportamento padrão)
Transfere automaticamente o tráfego da ramificação de origem para a ramificação de destino

A mesclagem falha com no_new_changes_to_merge se a ramificação de origem foi criada a partir da ramificação de destino (e não tem novos commits além dela), e com branch_already_merged se ela já tiver sido mesclada nesse destino.

Resolvendo conflitos de mesclagem

Se uma configuração tiver sido alterada tanto na ramificação de origem quanto na de destino desde que se separaram, o valor da ramificação atualizada mais recentemente será mantido por padrão. Defina force=True para sempre usar o valor da ramificação de origem, independentemente dos registros de data e hora.

Visualize o resultado de uma mesclagem, incluindo os campos que seriam substituídos, antes de confirmá-la:

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)

Rebaseando ramificações na principal

O rebase incorpora as alterações mais recentes da ramificação principal em outra ramificação, de forma semelhante a um rebase do git. Isso mantém uma ramificação de longa duração atualizada com a principal sem ainda mesclar de volta as próprias alterações da ramificação.

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

O rebase:

Cria uma nova versão na ramificação que incorpora as alterações mais recentes da principal
Preserva as próprias alterações da ramificação: se uma configuração foi editada tanto na ramificação quanto na principal, o valor da ramificação é sempre mantido
Falha com branch_already_up_to_date se a ramificação já incluir todas as alterações da principal

Somente ramificações que não são a principal podem receber rebase, e apenas a partir da principal. Fazer rebase da própria ramificação principal retorna um erro cannot_rebase_main.

Visualize o resultado de um rebase antes de confirmá-lo:

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

Arquivando ramificações

Arquive as ramificações de que você não precisa mais. Isso ajuda a manter sua lista de ramificações organizada.

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

Você não pode arquivar uma ramificação que tenha tráfego alocado. Remova todo o tráfego antes de arquivá-la.

Ramificações arquivadas podem ser desarquivadas definindo archived=False.

Recuperando versões específicas

Você pode recuperar um agente em uma versão específica ou no ponto mais recente de uma ramificação.

Obter agente em uma versão específica

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

Obter agente no ponto mais recente da ramificação

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

Incluir alterações de rascunho

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

Referência de configurações

Configurações versionadas

Estas configurações podem variar entre versões e ramificações:

Categoria	Configurações
Configuração da conversa	Prompt de sistema, personalidade do agente, seleção e parâmetros do LLM, configurações de voz (modelo de TTS, ID da voz), configuração de ferramentas, base de conhecimento, primeira mensagem, configurações de idioma, detecção de turno, configurações de interrupção
Configurações versionadas da plataforma	`evaluation` - critérios de avaliação, `widget` - aparência e comportamento do widget, `data_collection` - extração de dados estruturados, `overrides` - substituições de início de conversa, `workspace_overrides` - configuração de webhooks, `testing` - configurações de teste, `safety` - proteções (configurações IVC/não IVC)
Workflow	Definição completa do workflow (nós e conexões)

Configurações por agente

Estas configurações são compartilhadas entre todas as versões:

Configuração	Descrição
`name`, `tags`	Nome e tags do agente (atualizados apenas ao confirmar alterações na ramificação principal)
`auth`	Configurações de autenticação e lista de permissões
`call_limits`	Limites de simultaneidade e diários
`privacy`	Configurações de retenção e modo de retenção zero
`ban`	Status de banimento (somente administrador)

Alterações de nome e tags em ramificações que não são a principal não persistem no agente até serem mescladas à principal.

Boas práticas

Crie testes antes de criar uma ramificação

Configure testes automatizados que capturem o comportamento esperado antes de criar uma nova ramificação. Isso estabelece uma referência e ajuda a identificar regressões logo no início ao iterar sobre seu experimento.

Use nomes descritivos para as ramificações

Escolha nomes de ramificações que comuniquem claramente o objetivo do experimento. Inclua o nome do recurso, a hipótese ou o número do ticket para facilitar a referência (por exemplo, feature/new-greeting-flow ou experiment/shorter-responses).

Documente os objetivos das ramificações

Use o campo de descrição da ramificação para explicar qual hipótese você está testando, quais métricas definem o sucesso e quais são as dependências ou considerações. Isso ajuda os membros da equipe a entender os experimentos em andamento.

Use rascunhos para trabalhos em andamento

Salve rascunhos com frequência enquanto itera sobre as alterações. Isso preserva seu trabalho sem criar versões desnecessárias. Confirme as alterações apenas quando estiver pronto para testar ou implantar.

Comece com pequenas porcentagens de tráfego

Ao implantar uma nova ramificação, comece com 5 a 10% do tráfego. Isso limita a exposição caso surjam problemas, sem deixar de fornecer dados relevantes.

Monitore métricas importantes antes de aumentar o tráfego

Use o painel de análises para comparar o desempenho das ramificações. Observe as taxas de conclusão de chamadas, a duração média das conversas, as pontuações de avaliação de sucesso e as taxas de execução de ferramentas. Aumente o tráfego apenas quando as métricas atingirem ou superarem a referência da sua ramificação principal.

Aumente o tráfego gradualmente

Amplie o tráfego em incrementos (10% → 25% → 50% → 100%) à medida que a confiança aumentar. Essa abordagem minimiza os riscos enquanto valida o desempenho em cada etapa.

Mantenha as ramificações por pouco tempo

Mescle experimentos bem-sucedidos rapidamente para evitar desvios de configuração. Para ramificações que precisam permanecer abertas por mais tempo, faça rebase delas periodicamente na principal para que não se distanciem demais e se tornem mais difíceis de mesclar.

Próximas etapas

Experimentos

Execute testes A/B usando ramificações e implantação de tráfego

Testes

Configure testes automatizados para as versões do seu agente

Análises

Monitore o desempenho entre diferentes ramificações

CLI

Gerencie o versionamento pela linha de comando