Versionamento de agentes

Faça experiências com segurança usando configurações de agentes por meio de ramificações, versões e implantação de tráfego

O versionamento de agentes permite que você teste diferentes configurações do seu agente sem colocar sua configuração de produção em risco. Crie ramificações isoladas, teste alterações e implemente atualizações gradualmente usando a implantação por percentual de tráfego.

Quer realizar testes A/B? Consulte Experimentos para conhecer o workflow recomendado para testar alterações no agente com tráfego ao vivo.

Visão geral

O sistema de versionamento oferece:

Snapshots imutáveis da configuração do seu agente em qualquer momento
Ramificações isoladas para testar alterações antes de publicá-las
Divisão de tráfego para implementar alterações gradualmente para uma porcentagem dos usuários
Mesclagem para levar alterações de qualquer ramificação a qualquer outra ramificação
Rebase para trazer as alterações mais recentes da ramificação principal para uma ramificação

Depois que o versionamento é ativado em um agente, não é possível desativá-lo. Considere isso antes de ativar o versionamento 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 exclusivo (formato: agtvrsn_xxxx) e contém:

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

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

Ramificações

As ramificações são linhas de desenvolvimento nomeadas, semelhantes às ramificações do git. Elas permitem que você trabalhe em alterações de forma isolada antes de mesclá-las novamente à ramificação principal.

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

Implantação de tráfego

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

As porcentagens devem sempre somar exatamente 100%
O roteamento de tráfego é determinístico com base no ID da conversa (o mesmo usuário é sempre roteado para a mesma ramificação)
Somente ramificações não arquivadas com 0% de tráfego podem ser arquivadas

Rascunhos

As alterações não salvas são armazenadas como rascunhos, permitindo que você trabalhe nelas sem criar uma nova versão imediatamente.

Os rascunhos são por usuário e por ramificação (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 mesclar em uma ramificação

Como ativar o versionamento

O versionamento é opcional e deve ser ativado explicitamente. Você pode ativá-lo ao criar um novo agente ou em um agente existente.

Depois de ativado, o versionamento 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 versionamento. Depois de ativado, a aba Versionamento ficará disponível para gerenciar ramificações, rascunhos, versões e implantaçã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 versionamento.

Ativar o versionamento cria a ramificação inicial “Main” com a primeira versão contendo a configuração atual do agente.

Como trabalhar com ramificações

Criar uma ramificação

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

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 ramificações

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

Obter detalhes da ramificação

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

Confirmar alterações

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

Atualizar pelo dashboard

Atualizar pela CLI

Atualizar pela API

Abra a aba Versionamento do seu agente, mude para a ramificação desejada, 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.

Implantar tráfego

Use o endpoint de implantações para distribuir o tráfego entre ramificações. Isso permite implementações 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á se não somarem.

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

Mesclar 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 em qualquer outra ramificação não arquivada, não apenas na principal.

Para que as alterações de uma ramificação sejam revisadas antes da mesclagem ou para acessar uma ramificação na qual você não tem permissão de gravação, 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 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 novas confirmações além dela), e com branch_already_merged se ela já tiver sido mesclada nesse destino.

Resolver conflitos de mesclagem

Se uma configuração foi alterada nas ramificações de origem e de destino desde que elas divergiram, o valor da ramificação atualizada mais recentemente é mantido por padrão. Defina force=True para sempre usar o valor da ramificação de origem, independentemente dos carimbos 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)

Fazer rebase de ramificações sobre a principal

O rebase traz as alterações mais recentes da ramificação principal para 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 as próprias alterações da ramificação de volta.

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 alterações da própria 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 sobre a principal. Fazer rebase na 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)

Arquivar ramificações

Arquive as ramificações 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 tem tráfego alocado. Remova todo o tráfego antes de arquivá-la.

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

Duplicar um agente versionado

Duplicar um agente cria um novo agente que contém uma cópia de todas as ramificações não arquivadas do agente de origem, não apenas da ramificação principal.

duplicate = client.conversational_ai.agents.duplicate(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    name="Copy of my agent"
)
print(duplicate.agent_id)

No agente duplicado:

A ramificação principal é criada a partir da versão mais recente da ramificação principal do agente de origem
Cada outra ramificação não arquivada é recriada com o mesmo nome e descrição, começando pela versão mais recente dessa ramificação
Cada ramificação começa com uma única versão, pois o histórico de versões não é copiado
Ramificações arquivadas e rascunhos não são copiados
As implantações de tráfego não são copiadas, portanto todo o tráfego vai para a ramificação principal até que você implante tráfego em outras ramificações

Os IDs de ramificação e versão na cópia são novos, portanto atualize todas as referências aos IDs do agente de origem.

Recuperar versões específicas

Você pode recuperar um agente em uma versão específica ou no topo 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 topo 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 ser diferentes 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 de 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 arestas)

Configurações por agente

Estas configurações pertencem ao agente, e não a uma versão, portanto todas as ramificações as compartilham:

Configuração	Descrição
`name`, `tags`	Nome e tags do agente
`auth`	Configurações de autenticação e lista de permissões
`call_limits`	Limites de simultaneidade e diários
`queueing_config`	Fila de espera e áudio em espera para chamadores acima do limite de simultaneidade
`privacy`	Configurações de retenção, modo de retenção zero e memórias do usuário
`analysis_llm`	LLM usado para análise pós-chamada
`topic_discovery`, `sentiment_analysis`	Configurações de análise no nível do agente
`simulation_library`	Configurações da biblioteca de simulação
`alerting`	Webhooks de alerta e limites de monitoramento
`ban`	Status de banimento (somente administradores)

As configurações por agente só podem ser alteradas na ramificação principal. Em outras ramificações, o dashboard as mostra como somente leitura, e publicar uma versão em uma ramificação que não é a principal descarta quaisquer alterações nelas. Mesclar a ramificação na principal depois também não as aplica. Mude para a ramificação principal para alterá-las; depois de publicadas nela, a alteração se aplica a todas as ramificações.

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 base e ajuda a identificar regressões cedo durante as iterações do seu experimento.

Use nomes descritivos para as ramificações

Escolha nomes de ramificação 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 quaisquer dependências ou considerações. Isso ajuda os membros da equipe a entender os experimentos ativos.

Use rascunhos para trabalhos em andamento

Salve rascunhos com frequência enquanto itera nas alterações. Isso preserva seu trabalho sem criar versões desnecessárias. Confirme alterações somente 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, ao mesmo tempo que fornece dados relevantes.

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

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

Aumente o tráfego gradualmente

Amplie o tráfego em incrementos (10% → 25% → 50% → 100%) conforme sua confiança aumenta. Essa abordagem minimiza o risco enquanto valida o desempenho em cada etapa.

Mantenha as ramificações por pouco tempo

Mescle experimentos bem-sucedidos rapidamente para evitar a divergência de configurações. Para ramificações que precisam ficar abertas por mais tempo, faça rebase periodicamente sobre a principal para que não se distanciem muito e se tornem mais difíceis de mesclar.

Próximas etapas

Experimentos

Realize 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 em diferentes ramificações

CLI

Gerencie o versionamento pela linha de comando