Atualizou o Agente e piorou o atendimento? Como versionar, testar e voltar atrás sem parar a operação

Uma pequena alteração no prompt parece inofensiva. Você percebe que o Agente está deixando de fazer uma pergunta importante durante a qualificação, ajusta duas instruções e publica a nova configuração.

O problema aparentemente desaparece. Algumas horas depois, outro comportamento começa a surgir: o Agente passa a insistir na mesma pergunta, deixa de consultar uma ferramenta em determinadas situações ou começa a encaminhar para o atendimento humano conversas que antes conseguia resolver sozinho.

O erro inicial foi corrigido, mas a mudança criou novas falhas em outros pontos da operação.

Isso acontece porque um Agente IA não é apenas um texto enviado a um modelo. Seu comportamento resulta da interação entre prompt, modelo, ferramentas, regras de roteamento, memória, base de conhecimento, parâmetros, integrações e estado da conversa.

Alterar uma dessas partes pode modificar o funcionamento de todo o sistema. Como explicamos no conteúdo sobre por que prompt não é operação, uma boa instrução não sustenta sozinha um Agente conectado aos processos da empresa.

Atualizar um Agente diretamente em produção é menos parecido com editar uma mensagem e mais parecido com publicar uma nova versão de um software.

A diferença é que, em sistemas com IA, nem sempre a regressão aparece de forma determinística. A mesma configuração pode responder corretamente em um teste e falhar quando recebe uma variação da mesma solicitação.

Essa incerteza torna o versionamento, a avaliação e o rollback partes fundamentais da operação.

O que significa versionar um Agente IA

Versionar um Agente não significa apenas guardar cópias antigas do prompt.

Uma versão precisa representar uma configuração completa e reproduzível do comportamento publicado. Ela deve permitir que a equipe responda com precisão qual combinação de componentes estava sendo utilizada quando uma conversa aconteceu.

Uma versão de produção pode incluir:

* instruções e exemplos do prompt;

* modelo e versão específica do modelo;

* parâmetros de geração;

* ferramentas disponíveis;

* descrição e esquema de entrada das ferramentas;

* código executado por cada ferramenta;

* regras de roteamento e handoff;

* guardrails e políticas de segurança;

* estratégia de memória;

* documentos e fontes de conhecimento;

* versão do índice vetorial;

* regras de pós-processamento;

* critérios de avaliação associados à publicação.

A documentação de prompting da OpenAI recomenda tratar prompts como parte do código da aplicação, mantendo-os versionados e submetidos a processos de revisão, teste e publicação.

Essa lógica precisa se estender ao restante do Agente. Salvar apenas o prompt não ajuda quando a regressão foi provocada pela troca do modelo, por uma alteração no esquema de uma ferramenta ou por uma atualização na base de conhecimento.

Uma versão útil deve ser imutável. Depois de publicada, ela não deve ser editada. Qualquer mudança cria uma nova versão.

Em vez de alterar silenciosamente a versão 17, a equipe cria a versão 18, testa seu comportamento e decide se ela deve substituir a anterior.

Draft, versão publicada e versão ativa não são a mesma coisa

Uma estrutura segura costuma separar três conceitos.

Draft

É a configuração que ainda está sendo editada. Pode receber novas instruções, documentos, ferramentas, modelos e regras.

O draft deve ser usado para configuração e testes. Ele não deve atender usuários reais.

Versão publicada

É um snapshot imutável do Agente. Ela registra exatamente quais configurações foram aprovadas naquele momento.

Uma versão publicada pode existir sem estar ativa. Isso permite manter um histórico de releases e selecionar qualquer uma delas para comparação, auditoria ou restauração.

Versão ativa

É a versão para a qual a produção está apontando.

O ideal é que a operação não dependa de sobrescrever configurações. Em vez disso, existe um ponteiro semelhante a:

```text

produção → versão 18

```

Quando ocorre um rollback, a equipe altera o ponteiro:

```text

produção → versão 17

```

O gerenciamento de prompts do LangSmith utiliza uma lógica semelhante. Commits preservam configurações anteriores, enquanto identificadores usados pelos ambientes podem ser reposicionados para outra versão.

Esse modelo torna a reversão mais rápida porque a equipe não precisa reconstruir manualmente a configuração anterior. Ela continua armazenada e pronta para ser utilizada.

Um rollback só funciona quando a versão anterior continua reproduzível

Imagine que a versão 17 utilizava um determinado prompt, um modelo específico e uma ferramenta chamada `consultar_pedido`.

Na versão 18, a ferramenta foi substituída por `buscar_status_pedido`, com outros parâmetros e outro formato de resposta.

Se o código antigo tiver sido apagado, simplesmente reativar o prompt da versão 17 não restaurará o comportamento anterior.

O mesmo problema acontece quando:

* documentos antigos são removidos definitivamente;

* o índice de conhecimento é sobrescrito;

* um esquema de ferramenta é alterado sem compatibilidade;

* o nome do modelo aponta para uma versão variável;

* regras de banco de dados deixam de aceitar chamadas antigas;

* variáveis de configuração são substituídas sem histórico.

Para permitir um rollback real, cada versão deve apontar para dependências que ainda possam ser executadas.

Isso também vale para o modelo. Quando o provedor disponibiliza identificadores fixos ou snapshots, eles ajudam a reduzir mudanças inesperadas de comportamento.

A documentação de versões de modelos da Anthropic, por exemplo, diferencia identificadores fixados de aliases que podem passar a apontar para snapshots mais recentes.

Utilizar apenas um identificador genérico como “modelo mais recente” pode introduzir mudanças em produção sem que o prompt ou o código da aplicação tenham sido alterados.

Não teste apenas a resposta final

Em um chatbot simples, pode ser suficiente verificar se a resposta gerada está correta.

Em um Agente, isso é insuficiente.

Considere uma solicitação de cancelamento. O Agente pode produzir a seguinte resposta:

Seu pedido foi cancelado com sucesso.

O texto parece perfeito. A avaliação correta, porém, precisa confirmar se o cancelamento realmente ocorreu no sistema.

A Anthropic diferencia o trace, que contém o registro da execução, do outcome, que representa o resultado final no ambiente. Um Agente pode afirmar que concluiu uma tarefa mesmo quando nenhuma alteração foi realizada no sistema externo.

Por isso, um teste completo precisa analisar pelo menos três camadas.

1. O resultado apresentado ao usuário

A resposta foi correta, clara, relevante e compatível com as políticas da empresa?

2. A trajetória da execução

O Agente selecionou a ferramenta adequada? Utilizou os parâmetros corretos? Executou as etapas necessárias? Fez um handoff quando deveria?

A OpenAI destaca que avaliações de Agentes precisam considerar tanto a escolha da ferramenta quanto a precisão dos argumentos enviados.

3. A alteração de estado

O que deveria acontecer no ambiente realmente aconteceu?

Isso pode significar confirmar que:

* o agendamento foi criado;

* o pagamento foi registrado;

* o pedido correto foi cancelado;

* o lead foi atualizado no CRM;

* o atendimento foi encaminhado para a fila adequada;

* nenhuma ação duplicada foi executada.

Uma avaliação baseada somente no texto pode aprovar um Agente que fala corretamente, mas executa incorretamente.

Esse cuidado complementa os testes realizados antes de colocar um Agente IA no atendimento real. No go-live e nas atualizações seguintes, é necessário testar respostas, ferramentas, limites, handoffs e efeitos produzidos nos sistemas.

Use traces para localizar onde a regressão começou

Quando uma avaliação considera apenas a entrada e a resposta final, ela funciona como uma caixa-preta. A equipe sabe que a versão 18 teve um resultado pior, mas não sabe exatamente por quê.

O trace permite visualizar a execução completa:

```text

mensagem recebida

→ classificação da intenção

→ recuperação de contexto

→ seleção da ferramenta

→ argumentos enviados

→ resultado da ferramenta

→ decisão seguinte

→ resposta final

```

A avaliação de traces aplica critérios estruturados sobre esse caminho. Ela pode identificar, por exemplo, que o Agente chegou à resposta errada porque consultou a ferramenta correta com um identificador incorreto.

A OpenAI descreve o trace grading como uma forma de avaliar o registro completo de decisões, chamadas de ferramentas e etapas de execução.

O objetivo é localizar falhas, comparar mudanças e identificar regressões em escala, em vez de observar apenas o resultado final.

Essa análise depende de uma boa observabilidade de Agentes IA. Sem logs, traces e identificação das versões utilizadas, a equipe encontra a resposta errada, mas não consegue reconstruir o caminho que levou até ela.

Também é possível avaliar trajetórias de maneiras diferentes.

Em processos muito definidos, o teste pode exigir uma sequência específica:

```text

consultar política

→ validar identidade

→ executar cancelamento

```

Em outros casos, a ordem pode ser flexível, desde que as ferramentas necessárias sejam chamadas e nenhuma ação indevida seja executada.

As avaliações de trajetória do LangSmith permitem comparar sequências estritas, chamadas em qualquer ordem, conjuntos mínimos de ferramentas ou o comportamento geral avaliado por outro modelo.

Construa uma suíte de regressão antes de publicar

Uma suíte de regressão é um conjunto de casos que toda nova versão precisa enfrentar antes de chegar à produção.

Ela não deve ser formada apenas por exemplos em que o Agente já funciona bem. Seu maior valor está nos casos que historicamente provocaram falhas.

A base pode incluir:

* jornadas comerciais mais frequentes;

* conversas reais anonimizadas;

* objeções comuns;

* solicitações incompletas;

* mudanças de assunto no meio da conversa;

* mensagens contraditórias;

* erros de digitação;

* usuários que não respondem às perguntas esperadas;

* tentativas de induzir o Agente a ignorar instruções;

* falhas anteriores transformadas em casos permanentes;

* situações críticas envolvendo pagamentos, cancelamentos ou dados pessoais.

Quando uma regressão aparece em produção, ela não deve gerar apenas uma correção. Deve gerar também um novo teste.

Assim, o problema pode acontecer uma vez, mas não deve voltar silenciosamente em versões futuras.

A OpenAI recomenda avaliações contínuas a cada mudança relevante e a ampliação dos conjuntos de teste conforme novos casos e comportamentos inesperados são encontrados.

Essa é a base de uma rotina de avaliação contínua de Agentes IA: falhas reais deixam de ser apenas incidentes e passam a aumentar a cobertura dos testes futuros.

Compare a nova versão com a versão atual

Avaliar apenas a candidata isoladamente não responde à pergunta mais importante:

Ela está realmente melhor do que a versão que já está funcionando?

O processo deve executar a mesma suíte de testes em duas configurações:

```text

baseline: versão atualmente ativa

candidate: nova versão proposta

```

Depois, os resultados devem ser comparados por dimensão.

Uma nova versão pode melhorar a taxa de conclusão de tarefas, mas aumentar o número de chamadas de ferramentas. Pode oferecer respostas melhores, mas elevar a latência. Pode reduzir encaminhamentos humanos, mas começar a tomar decisões fora do escopo permitido.

Por isso, a avaliação não deve produzir apenas uma nota genérica. Ela pode observar métricas como:

* taxa de sucesso da tarefa;

* correção da resposta;

* escolha correta de ferramentas;

* precisão dos argumentos;

* alterações de estado corretas;

* chamadas não autorizadas;

* taxa de encaminhamento humano;

* número de etapas por execução;

* custo por atendimento;

* tempo de resposta;

* violações de política;

* experiência percebida pelo usuário.

Alguns critérios devem funcionar como bloqueios absolutos. Uma única chamada indevida de pagamento, cancelamento ou envio de dados pode impedir a publicação, mesmo que a média geral da candidata seja superior.

As métricas escolhidas também precisam estar ligadas ao resultado da operação. O conteúdo sobre como medir se um Agente IA está funcionando mostra por que tempo de resposta, isoladamente, não revela se a automação está conduzindo tarefas, registrando dados e ajudando o atendimento a avançar.

Execute os mesmos casos mais de uma vez

Aplicações baseadas em modelos generativos possuem variação entre execuções. Uma versão pode acertar um caso em uma tentativa e falhar em outra.

Por isso, cenários críticos devem ser executados repetidamente.

Em vez de registrar apenas “passou” ou “falhou”, acompanhe a taxa de sucesso:

```text

Versão 17: 48 acertos em 50 execuções

Versão 18: 41 acertos em 50 execuções

```

Uma única demonstração manual da resposta desejada não comprova que a mudança é segura.

Esse é um dos motivos pelos quais avaliações automatizadas ganham importância conforme o Agente cresce. Elas podem ser executadas em escala e antes de a mudança atingir usuários reais.

A Anthropic recomenda combinar avaliações automatizadas, monitoramento de produção, testes controlados e revisão humana. Nenhuma dessas camadas consegue detectar todos os problemas isoladamente.

Publique gradualmente, não de uma vez

Passar nos testes offline não garante que a nova versão funcionará com toda a variedade encontrada em produção.

Uma publicação controlada pode seguir cinco etapas.

1. Staging

A versão é publicada em um ambiente separado, com as mesmas integrações e configurações fundamentais da produção, mas sem afetar clientes reais.

O objetivo é identificar incompatibilidades de configuração, permissões, ferramentas e dependências antes da exposição ao tráfego real.

2. Shadow mode

A nova versão recebe cópias de solicitações reais, mas suas respostas e ações não chegam ao usuário.

Ela pode classificar intenções, selecionar ferramentas simuladas e gerar respostas para comparação. Ferramentas com efeitos externos devem permanecer bloqueadas ou ser substituídas por mocks.

O shadow mode permite observar como a candidata se comportaria diante de tráfego real sem correr o risco de enviar mensagens, cancelar pedidos ou criar agendamentos.

3. Canary release

A nova versão atende apenas uma pequena porcentagem do tráfego, como 5%.

Se os indicadores permanecerem estáveis, a exposição pode aumentar progressivamente:

```text

5% → 20% → 50% → 100%

```

4. Segmentação

Em vez de distribuir a versão aleatoriamente, a equipe pode começar por um segmento de menor risco, um canal interno, uma unidade específica ou um tipo limitado de atendimento.

5. Promoção completa

A versão só se torna padrão depois de passar pelos critérios definidos e permanecer estável durante a janela de observação.

Esse processo reduz o impacto de regressões que não apareceram nos testes anteriores.

Defina os critérios de rollback antes da publicação

O momento de decidir quando reverter uma versão não é durante o incidente.

Cada publicação deve possuir critérios objetivos de rollback, como:

```text

Reverter se:

• a taxa de conclusão cair mais de 5%;
• chamadas incorretas de ferramentas ultrapassarem 1%;
• ocorrer qualquer ação financeira não autorizada;
• o custo médio crescer mais de 20%;
• a latência p95 ultrapassar o limite operacional;
• o encaminhamento humano aumentar acima do esperado;
• surgir uma violação crítica de política.

```

Os números dependem do processo, do risco envolvido e da quantidade de tráfego. O importante é impedir que a equipe permaneça discutindo se a deterioração parece grave o suficiente enquanto usuários continuam sendo afetados.

Também deve existir uma pessoa responsável por executar ou autorizar a reversão.

Como executar o rollback sem parar a operação

Quando um critério de rollback é atingido, o procedimento pode seguir esta ordem:

1. interromper a expansão da nova versão;

2. registrar o motivo e os indicadores do incidente;

3. apontar novas execuções para a versão estável anterior;

4. impedir novas ações externas da versão problemática;

5. decidir como tratar execuções que já estavam em andamento;

6. confirmar a recuperação das métricas;

7. preservar os traces da versão revertida para investigação;

8. transformar a falha encontrada em um novo caso de regressão.

O rollback não deve depender de editar novamente o prompt até ele ficar parecido com o anterior. Ele deve restaurar um artefato conhecido e testado.

A equipe também precisa considerar falhas externas durante o processo. O Agente pode ser revertido enquanto uma agenda, um CRM ou um sistema de pagamento continua indisponível. Por isso, vale definir antecipadamente como o Agente deve agir quando uma integração sai do ar.

Não misture versões durante uma mesma execução

Cada execução deve registrar qual versão do Agente a iniciou.

Em processos curtos, uma mensagem pode gerar uma única execução. Em conversas longas, a equipe precisa definir se a versão ficará fixada durante toda a sessão ou se poderá mudar entre mensagens.

O que deve ser evitado é trocar componentes no meio da mesma execução:

```text

decisão inicial: versão 18

chamada da ferramenta: versão 18

interpretação do resultado: versão 17

resposta final: versão 17

```

Esse tipo de mistura dificulta a reprodução do problema e pode criar comportamentos que nunca foram avaliados como um conjunto.

Durante um rollback, novas execuções podem ser encaminhadas imediatamente à versão anterior. As que já começaram podem ser concluídas com a versão original, canceladas com segurança ou reiniciadas, dependendo do risco e dos efeitos já produzidos.

Rollback de configuração não desfaz ações já executadas

Reverter o Agente impede que novas execuções utilizem a versão problemática. Isso não desfaz automaticamente o que já aconteceu.

Se a versão incorreta:

* enviou uma mensagem inadequada;

* criou um agendamento;

* aplicou um desconto;

* cancelou um pedido;

* alterou um registro;

* disparou uma cobrança;

a operação pode precisar de uma ação compensatória.

Por isso, ferramentas com efeitos externos devem registrar:

* versão do Agente;

* ID da execução;

* usuário afetado;

* parâmetros enviados;

* resposta do sistema externo;

* horário da ação;

* chave de idempotência;

* possibilidade de compensação.

A chave de idempotência evita que uma repetição ou tentativa de recuperação execute a mesma ação duas vezes.

A ação compensatória permite corrigir um efeito anterior, como restaurar um pedido cancelado ou remover um agendamento criado indevidamente.

Um exemplo de publicação controlada

Considere um Agente comercial que utiliza a versão 23 em produção.

A equipe percebe que ele está oferecendo o agendamento cedo demais e cria a versão 24, com três mudanças:

* novo prompt de qualificação;

* nova descrição da ferramenta de agendamento;

* modelo diferente.

A publicação poderia seguir este processo.

Primeiro, a versão 24 é executada contra a suíte de regressão. Ela precisa demonstrar que continua identificando intenção, qualificando corretamente, consultando disponibilidade e realizando agendamentos sem duplicidade.

Depois, os traces das versões 23 e 24 são comparados. A equipe verifica não apenas as respostas, mas quando a ferramenta foi chamada, quais parâmetros foram utilizados e quantas etapas foram necessárias.

Em seguida, a candidata entra em shadow mode com conversas reais. A versão 23 continua respondendo, enquanto a 24 é observada silenciosamente.

Depois, 5% dos novos atendimentos passam a utilizar a versão 24. As métricas de conversão, encaminhamento, chamadas de ferramentas, latência e custo são monitoradas.

Por fim, a exposição cresce gradualmente.

Se a nova versão começar a agendar reuniões com dados incompletos, o ponteiro de produção volta para a versão 23. Os traces problemáticos são preservados, o caso é adicionado à suíte de regressão e a equipe começa a trabalhar na versão 25.

A versão 24 não é corrigida silenciosamente. Ela permanece no histórico como o registro exato da configuração que falhou.

Erros comuns na gestão de mudanças em Agentes IA

Editar diretamente a versão de produção

Isso elimina a possibilidade de reproduzir o comportamento anterior e torna difícil descobrir qual alteração provocou a regressão.

Versionar apenas o prompt

O problema pode estar no modelo, na ferramenta, na memória, no roteamento, nos guardrails ou na base de conhecimento.

Testar somente conversas ideais

Os maiores riscos aparecem em entradas incompletas, mudanças de assunto, solicitações ambíguas e situações fora do fluxo esperado.

Avaliar somente a resposta final

O texto pode estar correto mesmo quando a ferramenta errada foi chamada ou quando nenhuma alteração real aconteceu.

Apagar dependências antigas

Uma versão anterior não pode ser restaurada se o código, os documentos ou os esquemas utilizados por ela deixaram de existir.

Publicar para 100% dos usuários imediatamente

Mesmo uma boa suíte de testes não reproduz toda a distribuição de entradas encontrada em produção.

Não praticar o rollback

Um plano de reversão que nunca foi testado pode falhar justamente durante um incidente.

Corrigir a falha sem criar um teste

Sem transformar o problema em um caso permanente, a mesma regressão pode voltar meses depois.

O objetivo não é impedir mudanças

Versionamento e rollback não existem para tornar a evolução do Agente mais lenta.

Eles existem para permitir que a equipe mude com mais frequência e menos medo.

Quando cada release é identificável, testável e reversível, a operação deixa de depender de alterações improvisadas. Uma melhoria pode ser comparada com a versão atual, publicada para uma pequena parcela do tráfego, monitorada e revertida rapidamente caso apresente um resultado inferior.

Com o tempo, os próprios erros tornam o sistema mais confiável. Cada falha real vira um caso de teste. Cada regressão aumenta a cobertura da suíte. Cada publicação produz dados que ajudam a entender melhor o comportamento do Agente.

Sem esse processo, a equipe entra em um ciclo reativo: corrige um problema, cria outro, tenta lembrar o que foi alterado e edita novamente a produção.

Um Agente sem versões, testes e rollback transforma cada melhoria em uma aposta feita diretamente na produção.

A arquitetura mais segura não é aquela em que o Agente nunca falha. É aquela em que a equipe consegue detectar a falha, localizar sua origem e restaurar rapidamente uma versão conhecida, sem interromper toda a operação.

Fontes utilizadas

* Anthropic: Demystifying evals for AI agents

* OpenAI: Evaluation best practices

* OpenAI: Trace grading

* OpenAI: Prompting

* LangSmith: Trajectory evaluations

* LangSmith: Manage prompts

* Anthropic: Model IDs and versions