Como atualizar agente de IA em produção sem quebrar nada

Para atualizar um agente de IA em produção com segurança, trate cada mudança como uma pequena versão a ser liberada. Registre como o agente se comporta hoje, altere uma coisa de cada vez (instruções, uma ferramenta ou o modelo), teste com casos reais do passado, libere para uma fatia limitada do trabalho e mantenha um caminho de volta já testado. Um agente não é só um prompt. Ele reúne instruções, ferramentas, memória, permissões e um modelo trabalhando juntos, então uma edição em um ponto pode mudar o comportamento em outro.

Principais pontos

• Um agente é um sistema. Teste o comportamento inteiro, não só a parte que você editou.
• Mude uma camada por vez (instruções, ferramentas ou modelo) e anote o que deve mudar e o que não pode mudar.
• Mantenha um conjunto pequeno de casos reais do passado como conjunto de regressão e rode-o antes e depois de cada mudança.
• Libere primeiro para uma fatia limitada do trabalho, com um responsável nomeado acompanhando e uma reversão que você já tenha experimentado.
• Registre cada mudança com motivo, versão e resultado, para que o histórico do agente seja legível por alguém que não estava lá.

Por que uma edição pequena quebra um agente que funcionava?

Uma mudança em software tradicional costuma quebrar num lugar visível. Uma mudança em agente costuma quebrar onde você não estava olhando. Você acrescenta uma frase sobre tom nas instruções e o agente, sem avisar, deixa de pedir aprovação antes de um certo tipo de ação. Você renomeia um campo de uma ferramenta, o agente continua chamando com o nome antigo e depois justifica o erro numa mensagem confiante. Você troca para um modelo mais novo e o agente passa a responder com textos muito mais longos, o que empurra uma etapa seguinte para além do limite de tempo.

Três características tornam isso provável. Primeiro, o agente lê linguagem, então toda frase também é um comportamento, inclusive as frases nas descrições das ferramentas. Segundo, o modelo preenche lacunas com julgamento, e uma nova edição muda quais lacunas ele percebe. Terceiro, a maioria das falhas é parcial. O agente ainda funciona na maior parte dos pedidos, e ninguém dá alarme até que um cliente ou um colega note um padrão.

A resposta não é congelar o agente. Um agente congelado fica desatualizado conforme produtos, políticas e pessoas mudam. A resposta é uma rotina que torne a mudança comum, pequena e reversível. Se quiser a visão mais ampla de onde cada mudança se encaixa, vale ler o que é harness de IA e lembrar das camadas: instruções, ferramentas, memória, permissões, modelo e o ambiente de execução que liga tudo. Cada uma pode ser editada, e cada uma pede seu próprio tipo de verificação.

O que registrar antes de mudar qualquer coisa?

Não dá para saber se uma mudança ajudou sem ter registrado o ponto de partida. Antes da primeira edição, escreva uma linha de base. Ela não precisa ser elaborada. Precisa ser fácil de achar e honesta.

• As instruções atuais, exatamente como estão no ar, com um rótulo de versão.
• As definições das ferramentas que o agente enxerga, incluindo nomes, descrições e as permissões com que cada ferramenta roda.
• O identificador do modelo e as configurações que afetam a saída, como limites de tamanho.
• As fontes de memória ou de conhecimento que o agente lê, e quando foram revisadas pela última vez.
• Um conjunto de referência com casos reais: pedidos que o agente resolveu bem, pedidos que resolveu mal e pedidos em que ele parou corretamente para perguntar a uma pessoa.
• A medida de sucesso pela qual a função é avaliada, escrita como algo observável, por exemplo a parcela de pedidos resolvidos sem retrabalho, conforme contada pelo responsável.

O conjunto de referência é o que mais importa. Tire-o do trabalho real, remova dados pessoais que você não precise e inclua os casos incômodos: o pedido ambíguo, o anexo que faltou, o cliente que escreve em outro idioma, o pedido que deveria ser recusado. Os guias de avaliação da [OpenAI](https://platform.openai.com/docs/guides/evals) e da [Anthropic](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) fazem o mesmo ponto de fundo: é preciso um conjunto repetível de tarefas com critérios claros de correção, ou você estará comparando impressões.

Anote também o que não pode mudar. Para a maioria dos agentes de negócio, essa lista é curta e séria: nunca envia mensagens externas sem aprovação, nunca escreve no sistema de registro fora do seu escopo, sempre escala uma classe definida de pedidos. Essas regras viram as primeiras verificações depois de cada liberação.

Como editar instruções sem efeitos colaterais?

As instruções são a coisa mais tentadora de editar, porque levam um minuto e não exigem nenhuma implantação. É por isso também que causam mais danos acidentais. Alguns hábitos mantêm isso sob controle.

Faça uma edição com um único propósito. Se você quer corrigir como o agente resume uma conversa e também ajustar o texto de escalonamento, são duas mudanças. Libere-as separadamente, para que uma regressão tenha só um suspeito.

Escreva a intenção ao lado da mudança. Uma linha no registro de mudanças como "os resumos devem citar primeiro a decisão em aberto" permite que quem revisa julgue a redação em relação ao objetivo. Sem isso, a próxima pessoa não sabe dizer se uma regra ainda é necessária.

Evite remendar para incidentes isolados. Quando um caso estranho dá errado, a correção rápida é uma regra nova que cita aquele caso. Depois de muitas, as instruções viram uma pilha de exceções que se contradizem. Pergunte se o incidente revela um princípio ausente, um contexto ausente ou um problema de ferramenta. Muitas vezes o reparo mais limpo é apagar ou reescrever uma linha existente. O artigo sobre como manter instruções de agentes de IA organizadas trata de uma estrutura que facilita isso.

Separe limites de estilo. Regras sobre aprovações, permissões e recusas merecem escrutínio extra, um segundo revisor e testes próprios. Regras de tom e formato podem mudar com revisão mais leve. Coloque-as em seções diferentes, para que uma edição de estilo nunca toque num limite por acidente.

Cenário ilustrativo: uma pequena empresa de serviços usa um agente que redige respostas a pedidos de orçamento e passa para uma pessoa tudo que envolva condições especiais. O dono acrescenta uma linha pedindo respostas mais calorosas e curtas. Nada na edição menciona escalonamento. Mas, ao rodar os casos de referência, dois pedidos com condições especiais passam a receber um rascunho curto e simpático que responde diretamente, em vez de encaminhar a uma pessoa. O estilo mais curto havia atropelado o comportamento de repasse. Como a edição era pequena e foi testada antes da liberação, a correção é uma linha esclarecendo que a regra de repasse vale mais que a regra de estilo. Sem o teste, o primeiro sinal seria um cliente recebendo condições que ninguém aprovou.

Como mudar uma ferramenta ou integração com segurança?

As ferramentas são o ponto em que o agente toca sistemas reais, então erros aqui custam mais que uma frase mal escrita. O padrão mais seguro é acrescentar em vez de substituir. Introduza a nova versão da ferramenta ao lado da antiga, aponte o agente para a nova só nos testes e aposente a antiga depois que a nova provar seu valor.

Trate a descrição da ferramenta como parte das instruções. O agente decide quando e como chamar uma ferramenta em grande parte a partir do nome, da descrição e dos campos de entrada. A orientação da Anthropic sobre [como escrever ferramentas para agentes](https://www.anthropic.com/engineering/writing-tools-for-agents) enfatiza nomes claros, parâmetros sem ambiguidade e mensagens de erro úteis. Se você muda o que a ferramenta devolve, como nomes de campos, ordem ou quantidade de texto, o comportamento do agente pode mudar mesmo com instruções idênticas. Para um aprofundamento sobre desenho, veja como escrever um contrato de tarefa de IA testável.

Mantenha as permissões fixas, a menos que ampliá-las seja o objetivo da mudança. Um erro comum é conceder acesso mais amplo para fazer uma nova integração funcionar durante o teste e depois esquecer de reduzi-lo. Anote o nível de permissão (ler, redigir ou enviar) no registro da mudança e revise-o na liberação. Se uma ação pode causar efeitos duplicados, confirme que repetir a chamada é seguro antes de permitir que o agente tente de novo.

Teste primeiro em uma cópia segura. Use contas de teste, caixas de e-mail de teste ou modos somente rascunho, para que uma chamada defeituosa gere um artefato inofensivo, e não uma mensagem enviada ou um registro alterado. Um ambiente de homologação bem definido, como o descrito no checklist para aceitar uma integração de agente de IA, torna isso rotina em vez de improviso. Depois verifique os caminhos infelizes: uma conexão expirada, um resultado vazio, um tempo esgotado, uma resposta em formato inesperado. O agente deve parar e avisar, não inventar um resultado.

Como trocar ou atualizar o modelo?

Trocar o modelo mexe em tudo ao mesmo tempo, o que faz dele a edição mais arriscada e a mais tratada com descuido. Os provedores lançam versões novas e aposentam as antigas, e a pressão para migrar é real. Trate a troca como um projeto com evidências próprias.

Rode o conjunto de referência no modelo candidato, com as instruções e ferramentas atuais, sem alterá-las. Compare os resultados caso a caso com a linha de base. Olhe além da correção, para os comportamentos dos quais as etapas seguintes dependem:

• Formato: ele ainda produz a estrutura que suas ferramentas e modelos de documento esperam?
• Tamanho: as respostas ficam mais longas ou mais curtas de um jeito que afete o tempo de leitura ou os limites?
• Uso de ferramentas: ele chama as ferramentas na mesma ordem, com os mesmos argumentos, ou pula etapas?
• Comportamento de parada: ele ainda pergunta quando deveria e recusa quando deveria?
• Velocidade e custo por tarefa concluída: continuam dentro da faixa que o fluxo tolera?

Instruções ajustadas para um modelo às vezes carregam gambiarras que um modelo mais novo já não precisa, ou até interpreta mal. Planeje uma passada curta para removê-las, como uma mudança separada, depois que a troca estiver estável. Não combine as duas.

Quando o risco permitir, rode o novo modelo em modo de observação: ele processa pedidos reais, suas saídas são registradas e as pessoas as comparam com o que o agente em operação fez, mas nada do que ele produz chega a um cliente. O artigo sobre como testar um agente de IA em modo de observação descreve como fazer. Se você ainda está decidindo se deve migrar, como escolher modelo de IA para empresa lista os critérios que valem a pena pesar. Seja qual for a decisão, mantenha a capacidade de voltar ao modelo anterior enquanto a mudança for recente.

Como é uma rotina de liberação controlada?

Aqui está um plano que você pode adotar como está e depois ajustar ao seu tamanho. Ele serve para uma edição de instruções, uma mudança de ferramenta ou uma troca de modelo.

• Nomeie a mudança e o responsável. Uma frase sobre o que muda e por quê, e uma pessoa responsável pelo resultado.
• Escreva a expectativa. O que deve ser diferente depois e o que deve continuar exatamente igual, incluindo os limites de aprovação.
• Tire um retrato do estado atual. Salve as instruções no ar, as definições das ferramentas, o identificador do modelo e as configurações sob um rótulo de versão.
• Faça a mudança em uma cópia de teste. Edite uma camada só. Não mexa em mais nada enquanto estiver lá.
• Rode os casos de referência. Compare com a linha de base. Leia as saídas de verdade, não só a contagem de aprovados e reprovados, e procure novos tipos de erro.
• Verifique os limites primeiro. Confirme que aprovações, recusas, escalonamentos e permissões se comportam como antes.
• Libere para uma fatia pequena. Escolha um conjunto de pedidos de baixo risco, um único canal ou uma única equipe, com uma pessoa acompanhando os resultados todos os dias.
• Acompanhe os sinais. Use os registros e rastros que você já coleta (o [guia introdutório de observabilidade do OpenTelemetry](https://opentelemetry.io/docs/concepts/observability-primer/) explica o vocabulário) para comparar erros, repasses, novas tentativas e conclusões com a linha de base.
• Decida entre expandir, manter ou reverter. Escreva a decisão e o motivo. Reverter deve significar restaurar o retrato salvo, e você deve ter testado essa restauração ao menos uma vez antes de precisar dela.
• Feche o registro. Anote o que mudou, o que você aprendeu e se o conjunto de referência precisa de um caso novo por causa do que você viu.

Dois hábitos mantêm isso leve. Agende as mudanças para um horário em que alguém possa acompanhá-las, não para o fim de um dia corrido. E não agrupe nada que você não aceitaria reverter junto.

Como a Be Human conduz melhorias controladas?

A Be Human trata a melhoria como parte da operação de um agente, não como uma reescrita ocasional. Instruções, definições de ferramentas e escolhas de modelo são versionadas, cada mudança é testada contra um conjunto de referência montado a partir do trabalho do próprio cliente, e as liberações vão para um escopo limitado antes de valer para todos. Limites de aprovação e permissões são revisados a cada liberação, e a versão anterior continua disponível, de modo que uma reversão é uma restauração, não uma reconstrução. O responsável pelo agente no lado do cliente vê o que mudou e por quê. Isso convive com monitoramento, avaliações recorrentes e manutenção de integrações na operação gerenciada, e o cliente mantém o controle sobre o que o agente pode fazer.

Perguntas frequentes

Com que frequência devemos atualizar um agente de IA em produção? Atualize quando houver um motivo que você consiga declarar: uma política mudou, apareceu um erro recorrente, uma ferramenta mudou ou um modelo está sendo aposentado. Mudanças pequenas, frequentes e testadas são mais seguras que mudanças grandes e raras, porque cada uma tem menos suspeitos se algo der errado. Um horário regular de revisão ajuda a decidir o que vale mudar e o que deixar como está.

Precisamos de um ambiente de teste separado para atualizar um agente em produção? Você precisa de um lugar seguro para rodar a mudança antes que clientes reais a vejam, e, para agentes que executam ações, isso costuma significar no mínimo contas de teste e modos somente rascunho. Uma cópia completa de homologação é melhor quando o agente escreve em sistemas importantes. Mesmo uma empresa pequena pode começar com uma caixa de e-mail de teste, um espaço de trabalho de teste e um conjunto salvo de casos de referência.

Como saber se uma mudança deixou o agente melhor e não apenas diferente? Compare com a linha de base usando os mesmos casos de referência e a mesma medida de sucesso, e leia você mesmo as saídas. Uma mudança é melhor quando a medida melhora, os limites se mantêm e nenhum novo tipo de erro aparece. Se você não consegue dizer o que esperava melhorar antes de fazer a mudança, ainda não está pronto para julgá-la.

O que fazer quando uma mudança liberada causa um problema? Reverta primeiro, investigue depois. Restaure a versão salva, avise as pessoas que dependem do agente sobre o ocorrido e revise os casos afetados durante o período. Em seguida, acrescente a falha ao conjunto de referência, para que o mesmo erro seja pego antes da próxima liberação.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.