Migrar para um novo modelo

Neste documento, descrevemos como migrar um aplicativo de agente do CX Agent Studio para um modelo de fundação diferente, validar a qualidade do agente e implantar a configuração atualizada em etapas sem interromper o tráfego de produção em tempo real.

Visão geral do fluxo de trabalho de migração

Uma migração de modelo completa segue quatro etapas:

1. Isole as mudanças: crie uma versão imutável do aplicativo do agente de produção ou exporte e importe o aplicativo para um ambiente de teste separado.
2. Atualizar as configurações do modelo: mude o modelo global, revise as substituições de modelo de subagente e ferramenta e verifique as configurações de nova tentativa e substituição usando o console, os arquivos de configuração exportados ou a API REST.
3. Avaliar e refinar o desempenho: teste conversas no simulador, execute avaliações com Encontrar problemas com a IA e use o AI Co-Builder: Arc para ajustar as instruções até que as métricas de qualidade atinjam os limites desejados.
4. Implante em etapas: salve a configuração validada como uma versão e use a divisão de tráfego no canal de implantação para mudar o tráfego em tempo real gradualmente enquanto monitora os resultados.

Etapa 1: isolar as mudanças

Antes de mudar as configurações do modelo, isole seu trabalho para que as atualizações e os testes não afetem as conversas em tempo real com os clientes. É possível isolar as mudanças usando versões no mesmo aplicativo de agente ou exportando o aplicativo para um ambiente de sandbox separado.

Usar versões no mesmo aplicativo de agente

Quando os canais de implantação apontam para uma versão imutável específica, as edições feitas no aplicativo de agente de rascunho não afetam o tráfego ativo até que você crie uma versão e a atribua a um canal de implantação.

Para salvar um snapshot de referência da sua configuração atual:

1. Abra o console do CX Agent Studio e selecione o aplicativo do agente.
2. Abra o painel Versões no criador de agentes.
3. Clique em + Criar versão.
4. Insira um nome descritivo, como pre-model-migration-baseline, e uma descrição opcional. Em seguida, clique em Criar.
5. Abra a guia Implantar e verifique se os canais de implantação ativos apontam para uma versão imutável (indicada por um selo Ativo no painel Versões) em vez do rascunho mutável.

Exportar e importar para um ambiente de sandbox

Se você preferir testar as mudanças no modelo em um projeto ou aplicativo de preparo separado, exporte o aplicativo do agente e importe-o para o ambiente de teste:

1. Abra o console do CX Agent Studio e selecione seu projeto.
2. Na lista de aplicativos de agente, abra o menu do seu aplicativo e selecione Exportar.
3. Se o ambiente de sandbox usar dependências externas diferentes, como repositórios de dados ou endpoints de serviço, extraia o arquivo baixado, atualize o arquivo environment.json e compacte o diretório em um arquivo ZIP. Para mais informações, consulte Arquivo de ambiente.
4. No projeto de sandbox ou aplicativo de teste, abra o menu do aplicativo, selecione Importar e faça upload do arquivo.
5. Opcional: exporte os casos de teste de avaliação do aplicativo de origem e importe-os para o aplicativo de sandbox para executar testes de regressão.

Etapa 2: atualizar as configurações do modelo

Analise a lista de modelos compatíveis para escolher um modelo do Gemini de destino que corresponda à modalidade do seu agente (texto ou voz). É possível atualizar as configurações do modelo usando o console, os arquivos de configuração exportados ou a API REST.

Atualizar modelos usando o console

Ao migrar um aplicativo de agente no console, verifique o modelo global de aplicativo, as substituições de agentes individuais, os modelos de ferramentas de repositório de dados e as configurações de fallback:

1. Mudar o modelo global:
   1. No Agent Builder, abra Configurações para ver as configurações do aplicativo do agente.
   2. Em Básico > Interações, selecione o modelo de destino no campo Modelo global. Esse modelo serve como padrão para todos os agentes no aplicativo que não especificam uma substituição.
2. Verifique as substituições de modelo de raiz e subagente:
   1. No criador de agentes, abra o menu na barra de título do agente raiz e selecione Editar configuração para ver as configurações do agente.
   2. Verifique o campo Modelo. Se o agente substituir o modelo global, selecione o modelo de destino ou limpe a substituição para que o agente herde o modelo global.
   3. Repita essa verificação para cada subagente na hierarquia de agentes.
3. Verificar os modelos de ferramentas do repositório de dados:
   1. Se o aplicativo usa ferramentas de repositório de dados, abra o painel Ferramentas e selecione cada ferramenta de repositório de dados.
   2. Abra Avançado > Modalidades e verifique as seleções de Modelo de reescrita e Modelo de resumo para as configurações de Texto e Voz.
4. Revise as configurações de nova tentativa e substituição:
   1. Abra as Configurações do aplicativo do agente e acesse Básico > Comportamento > Comportamento de fallback.
   2. Verifique se as opções Tentativas, Resposta do agente e Fallback estão configuradas corretamente para o tratamento de erros durante a geração do modelo.

Observação: se você estiver migrando um agente de voz do gemini-composite-v1 para o gemini-composite-v2, revise também o comando de estilo de fala e converta as tags inline entre colchetes em colchetes angulares. Para mais informações, consulte Migrar do Composite V1.

Atualizar modelos usando arquivos de configuração exportados

Se você gerencia o aplicativo do agente usando o controle de versões ou pipelines de CI/CD, atualize as configurações do modelo no arquivo exportado e importe o pacote novamente:

1. Extraia o arquivo ZIP do aplicativo do agente exportado.

2. Para cada diretório de agente em agents/<var>AGENT_NAME</var>/, abra o arquivo agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml e atualize o campo modelSettings.model para o ID do modelo de destino:

   displayName: "AGENT_NAME"
   modelSettings:
     model: "MODEL_ID"
   instruction: "agents/AGENT_NAME/instruction.txt"
   

   Substitua:

   • <var>AGENT_NAME</var>: o nome de exibição do agente.
   • <var>MODEL_ID</var>: o identificador do modelo de destino, como gemini-3.5-flash ou gemini-composite-v2.

3. Compacte o diretório raiz em um arquivo ZIP e importe o arquivo atualizado para o CX Agent Studio.

Atualizar modelos usando a API REST

É possível atualizar de forma programática o ModelSettings no aplicativo do agente e em agentes individuais usando a API REST do CX Agent Studio.

Antes de chamar a API, colete os seguintes valores:

• <var>PROJECT_ID</var>: o ID do projeto Google Cloud .
• <var>LOCATION_ID</var>: a região do aplicativo do agente, como us ou eu.
• <var>APP_ID</var>: o ID do recurso do aplicativo do agente.
• <var>AGENT_ID</var>: o ID do recurso de um agente raiz ou subagente específico.
• <var>MODEL_ID</var>: o identificador do modelo de destino, como gemini-3.5-flash.

Para atualizar o modelo global padrão do aplicativo do agente, envie uma solicitação PATCH ao método projects.locations.apps.patch com updateMask=modelSettings:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

Para atualizar a substituição de modelo em um agente raiz ou subagente individual, envie uma solicitação PATCH ao método projects.locations.apps.agents.patch com updateMask=modelSettings:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/agents/AGENT_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

Etapa 3: avaliar e refinar o desempenho do agente

Os modelos de fundação podem variar em estilo de raciocínio, adesão a instruções, verbosidade e comportamento de chamada de ferramenta. Depois de trocar de modelo, teste o agente e refine as instruções dele antes de encaminhar o tráfego de clientes em tempo real para a configuração atualizada.

Testar de forma interativa no simulador

Faça as verificações iniciais de sanidade no simulador do agente de pré-lançamento:

1. Abra o simulador no criador de agentes e clique em Iniciar nova conversa.
2. Teste interações de texto ou áudio representativas e verifique se o agente segue as instruções, invoca ferramentas com argumentos válidos e faz a transição entre subagentes conforme o esperado.
3. Abra os detalhes do rastro de cada turno para inspecionar a latência da etapa, as entradas e saídas da ferramenta e as respostas JSON brutas.
4. Opcional: para adicionar uma conversa ao seu pacote de regressão, abra o menu do simulador e selecione Salvar como golden.

Executar avaliações e diagnosticar problemas com IA

Use avaliações para medir o desempenho nos casos de teste de referência, cenário e simulação e comparar os resultados com a versão de referência:

1. Clique em Avaliar na parte de cima do criador de agentes.
2. Selecione os casos de teste que abrangem as jornadas ideais do usuário e as variantes do agente e clique em Executar selecionados.
3. Na caixa de diálogo de execução, selecione Encontrar problemas com a IA, defina a contagem de execuções como 3 ou mais para uma análise de IA ideal e inicie a execução. Para mais informações, consulte Usar a IA para melhorar os casos de teste.
4. Quando a execução terminar, revise as métricas de avaliação, incluindo correção da ferramenta, correspondência semântica, satisfação da meta do usuário, conclusões de meta, alucinações e conclusão da tarefa, e inspecione as rodadas com falha ou as metas não concluídas.
5. Na página de resultados, clique em Peça ao Gemini para analisar o loss_report gerado, resumir as causas raiz das execuções com falha e conferir as correções de instrução ou configuração sugeridas.

Instruções de subida de colina com o Criador de IA: Arc

Se os resultados da avaliação mostrarem regressões ou mudanças de comportamento no modelo de destino, use o AI Co-Builder: Arc e o assistente de avaliação para refinar os comandos de forma iterativa:

1. Clique em Arc na parte de cima do criador de agentes para abrir o AI Co-Builder.
2. Clique em Selecionar contexto e escolha os agentes ou as instruções específicas que precisam de ajuste ou anexe transcrições com falha e relatórios de perda.
3. Peça ao Arc para atualizar suas instruções ou descrições de ferramentas para resolver as falhas observadas, preservando o comportamento em outros casos de teste. Também é possível usar o recurso reestruturar instruções para organizar as instruções em um formato estruturado.
4. Execute novamente o pacote de avaliação depois de aplicar as correções e repita até que todos os casos de teste atendam aos critérios de aprovação. Para mais orientações, consulte Práticas recomendadas de avaliações e hill climbing.

Etapa 4: implantar em etapas com a divisão de tráfego

Depois que o agente atualizado passar nas avaliações, lance-o gradualmente usando versões e divisão de tráfego de implantação.

Criar uma versão para o agente migrado

Salve um snapshot imutável da configuração validada:

1. Se você testou as mudanças em um aplicativo de sandbox separado, exporte o pacote do aplicativo validado e importe-o para o aplicativo de produção.
2. No aplicativo de produção, abra o painel Versões e clique em + Criar versão.
3. Insira um nome e uma descrição que identifiquem o modelo de destino, como v2-gemini-3-5-flash, e clique em Criar.

Mudar gradualmente o tráfego em tempo real

Use a divisão de tráfego para encaminhar uma pequena porcentagem de conversas em tempo real para a versão migrada antes de promovê-la para 100% do tráfego:

1. Clique na guia Implantar na parte de cima do criador de agentes e selecione o canal de implantação.
2. Em Versão do agente, clique em Adicionar versão e inclua a versão de produção de referência e a versão candidata migrada.
3. Atribua uma pequena porcentagem de tráfego inicial à versão candidata (por exemplo, 90% para a versão de referência e 10% para a versão candidata, totalizando 100%) e salve a configuração do canal. Também é possível configurar o experimentConfig.versionRelease.trafficAllocations de maneira programática usando a API REST.
4. Monitore o desempenho em tempo real em todas as versões:
   • Verifique o volume de sessões, a latência e as taxas de encaminhamento no painel de monitoramento.
   • Inspecione as transcrições instantâneas no histórico de conversas.
   • Consulte os registros de interação exportados por app_version_id no BigQuery para comparar as taxas de execução e resultado das ferramentas entre as versões. Para ver exemplos de consultas SQL, consulte Analisar o desempenho da versão no BigQuery.
5. À medida que você confirma a estabilidade e a qualidade, aumente a porcentagem de tráfego da versão migrada em etapas até que ela atenda a 100% do tráfego em tempo real. Se você detectar problemas inesperados durante o lançamento, encaminhe 100% do tráfego de volta para a versão de referência ou restaure a versão anterior no painel Versões.