A divisão de tráfego permite dividir as conversas dos usuários em diferentes versões do aplicativo de agente do CX Agent Studio em um único canal de implantação. É possível usar a divisão de tráfego para realizar testes A/B ou implantar atualizações com segurança em etapas, roteando uma porcentagem especificada de tráfego para cada versão.
Este guia descreve como configurar a divisão de tráfego usando o console do CX Agent Studio ou a API REST do CX Agent Studio e analisar o desempenho da versão usando os registros do BigQuery depois que o experimento receber tráfego de clientes em tempo real.
Visão geral do fluxo de trabalho
- Criar versões do aplicativo: crie snapshots imutáveis (versões) do aplicativo de agente para comparar.
- Configurar a divisão de tráfego em um canal de implantação: atribua porcentagens de tráfego a várias versões do aplicativo usando o console ou a API REST.
- Analisar o desempenho no BigQuery: depois que o experimento estiver em execução e tiver processado tráfego de clientes suficiente, consulte os registros de conversas exportados no BigQuery para avaliar as métricas em todas as versões.
Configurar a divisão de tráfego
É possível configurar alocações de tráfego em diferentes versões do aplicativo usando o console ou a API REST. Cada alocação precisa apontar para uma versão do aplicativo de agente existente e a soma de todas as porcentagens de tráfego na implantação precisa ser igual a 100.
Como usar o console
Para configurar a divisão de tráfego no console do criador de agentes:
- Abra o console do CX Agent Studio e selecione o aplicativo de agente.
- Clique na guia Implantar na parte de cima da página.
- Selecione um canal de implantação ou clique em Novo canal para criar um (por exemplo, acesso à API).
- Em Versão do agente, clique em Adicionar versão e selecione as versões do aplicativo de agente que você quer incluir no experimento.
- Insira a Porcentagem de tráfego para cada versão (por exemplo,
90% para a versão A e10% para a versão B). Verifique se as porcentagens totalizam 100%. - Clique em Criar canal para aplicar a configuração.
Como usar a API REST
É possível configurar a divisão de tráfego de maneira programática chamando o patch método no recurso de implantação e definindo experimentConfig.versionRelease.trafficAllocations.
Antes de chamar a API, verifique se você tem os seguintes identificadores:
PROJECT_ID: o ID do Google Cloud projeto do.LOCATION_ID: a região do aplicativo de agente (por exemplo,us-east1).APP_ID: o ID do aplicativo de agente.DEPLOYMENT_ID: o ID do canal de implantação.VERSION_A_UUID/VERSION_B_UUID: os identificadores exclusivos das versões do aplicativo.
Envie uma solicitação PATCH para atualizar a configuração de implantação:
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://ces.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/deployments/DEPLOYMENT_ID?updateMask=experimentConfig" \
-d '{
"experimentConfig": {
"versionRelease": {
"trafficAllocations": [
{
"appVersion": "projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/versions/VERSION_A_UUID",
"trafficPercentage": 90
},
{
"appVersion": "projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/versions/VERSION_B_UUID",
"trafficPercentage": 10
}
]
}
}
}'
Verificar a configuração de implantação
Para verificar se as alocações de tráfego estão ativas:
Como usar o console
- Abra a página Implantar no console do CX Agent Studio.
- Localize o canal na lista de implantações.
- Verifique se a coluna Versão mostra a divisão configurada (por exemplo,
Version A (90%), Version B (10%)).
Como usar a API REST
Envie uma solicitação GET para recuperar os detalhes do recurso de implantação:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ces.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/deployments/DEPLOYMENT_ID"
O JSON de resposta inclui o experimentConfig ativo, confirmando as porcentagens de tráfego atribuídas a cada versão e mostrando "state": "RUNNING" dentro de versionRelease.
Analisar o desempenho da versão no BigQuery
Depois que o experimento de divisão de tráfego estiver em execução e tiver processado um volume suficiente de conversas de clientes em tempo real, será possível analisar o desempenho da versão usando os registros do BigQuery.
Antes de analisar os registros, verifique se você ativou a exportação do BigQuery para seu aplicativo navegando no console do CX Agent Studio até Criar > Configurações > Avançado e ativando a opção Exportar registros para o BigQuery. Quando a exportação está ativada, os registros de interação, incluindo o app_version_id específico processado por cada rodada, são gravados no conjunto de dados do BigQuery.
É possível executar consultas SQL para avaliar e comparar as respostas geradas por cada versão durante a janela de divisão de tráfego.
- No Google Cloud console, acesse o BigQuery.
Execute a consulta de exemplo na tabela de registros de interação, substituindo os detalhes do projeto e a janela de avaliação (
START_TIMEeEND_TIME):SELECT app_version_id, tool_call.name AS tool_name, tool_call.output AS tool_result_message, COUNT(1) AS count FROM `PROJECT_ID.conversational_agents_logs.v1beta_logs`, UNNEST(json_payload.query_result.generations) AS generation, UNNEST(generation.tool_calls) AS tool_call WHERE json_payload.resource = 'projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID' AND timestamp >= TIMESTAMP('START_TIME_YYYY-MM-DD HH:MM:SS', 'TIMEZONE') AND timestamp <= TIMESTAMP('END_TIME_YYYY-MM-DD HH:MM:SS', 'TIMEZONE') GROUP BY app_version_id, tool_name, tool_result_message ORDER BY app_version_id, count DESCAvaliar métricas:
- Identificar versões: mapeie as linhas de saída para os UUIDs de versão ou execuções de ferramentas específicas (por exemplo, comparando respostas da versão A com a versão B).
- Calcular a taxa de sucesso: compare a proporção de resultados com erros ou respostas desatualizadas nas duas versões para decidir se a versão candidata será promovida a 100% do tráfego.