Versionamento de agentes de IA: prompt, ferramentas e modelo juntos
Versione prompt, schemas de ferramentas e identificadores de modelo como uma release única, para que cada execução aponte para a configuração exata e revisável.

Versionamento de agentes de IA significa dar ao prompt, aos esquemas das ferramentas e ao identificador do modelo um único identificador de release compartilhado, para que cada execução do agente possa ser rastreada até a configuração exata que a produziu. Versionar essas três partes em lugares separados deixa brechas por onde um agente muda de comportamento sem que ninguém tenha aprovado a mudança. A solução prática é um manifesto de release que liste as três partes, um identificador único para a release e o registro desse identificador em cada execução.
Principais pontos
- Trate o prompt, os esquemas das ferramentas, o identificador do modelo e as configurações relacionadas como uma única release, com um único identificador.
- Mantenha um manifesto de release que aponte para versões exatas, e não para nomes flutuantes ou para o arquivo mais recente.
- Registre o identificador da release em cada execução, em cada rastro e em cada chamada de ferramenta, para que um incidente possa ser associado à sua configuração.
- Promova as releases por um ambiente de teste e mantenha a release anterior pronta para ser restaurada em um único passo.
- Aprove cada release com evidências de avaliação e um responsável nomeado, e não com uma leitura rápida do prompt.
Por que versionar prompts, ferramentas e modelos separadamente quebra
A maioria das equipes começa de forma familiar. O prompt de sistema fica em um documento ou em um arquivo do repositório, as ferramentas ficam no código da aplicação e o nome do modelo fica em uma configuração. Cada peça tem seu próprio histórico, e cada uma pode ser revisada por uma pessoa diferente, quando é revisada. O problema é que um agente nunca roda uma dessas peças sozinha. Ele roda uma combinação, e o comportamento vem de como as peças se encaixam.
Considere três mudanças que parecem pequenas. Uma frase do prompt é reescrita para deixar as respostas mais curtas. A descrição de uma ferramenta é editada para esclarecer quando ela deve ser usada. A configuração do modelo passa para uma versão mais nova da mesma família. Cada mudança pode passar em uma verificação rápida isolada, mas juntas podem alterar qual ferramenta o agente chama, quais argumentos ele envia e como formula o resultado. Se as mudanças foram registradas em três lugares sem um identificador comum, ninguém consegue dizer depois qual combinação produziu uma resposta ruim.
Os identificadores de modelo exigem cuidado especial. Alguns provedores oferecem aliases que apontam para a versão atual e mudam com o tempo. O alias é prático, mas a mesma string de configuração pode passar a produzir outro comportamento quando o provedor troca o modelo por trás dela. Um identificador fixado no manifesto mantém o registro honesto, e uma atualização vira uma release deliberada, e não um efeito colateral invisível.
O que pertence a uma release de agente
Uma release deve conter tudo o que pode mudar o comportamento do agente. Se uma configuração pode alterar uma resposta, uma chamada de ferramenta ou uma decisão de permissão, ela pertence ao manifesto. Uma release prática inclui:
- O prompt de sistema e as instruções de papel, guardados como arquivo com um hash do conteúdo.
- O registro de ferramentas: o nome de cada ferramenta, sua descrição, seus esquemas de entrada e saída e a versão do código que a implementa.
- O identificador do modelo, fixado em uma versão explícita quando o provedor oferece essa opção, junto com o nome do provedor.
- Os parâmetros do modelo, como limites de tamanho da resposta, configurações de amostragem e qualquer ajuste de esforço de raciocínio.
- As regras de aprovação e os escopos de permissão ligados a cada ferramenta, para que mudanças de permissão apareçam no histórico da release.
- As configurações de recuperação e memória, incluindo quais coleções de documentos o agente pode ler e a versão desse índice.
- A versão da suíte de avaliação e o resultado da execução que a release passou.
Não coloque segredos no manifesto. Guarde as credenciais em um gerenciador de segredos e referencie-as pelo nome. O manifesto precisa ser legível por um revisor que não participou da mudança original. O guia da Anthropic sobre como escrever ferramentas para agentes é uma referência útil quando você revisa descrições e esquemas, já que essas descrições determinam quando e como o modelo chama cada ferramenta.
Como montar o manifesto de release passo a passo
O manifesto pode ser um único arquivo estruturado guardado no mesmo repositório da definição do agente. O formato exato importa menos do que três propriedades: ele é completo, é legível por máquina e é imutável depois de liberado. Os passos abaixo servem a uma equipe pequena com um agente e continuam funcionando quando o número de agentes cresce.
- Passo 1: defina um formato para o identificador da release, por exemplo o nome do agente seguido de uma sequência, e nunca reutilize um identificador depois que a release for aposentada.
- Passo 2: mova toda configuração que muda o comportamento para o manifesto, de modo que nada importante fique apenas em uma variável de ambiente ou em um painel.
- Passo 3: calcule o hash do prompt e de cada esquema de ferramenta e registre os hashes. O hash confirma que o texto usado na execução é o texto que o revisor aprovou.
- Passo 4: fixe o identificador do modelo em uma string de versão específica sempre que possível, e anote qualquer comportamento do provedor que importe para a sua tarefa.
- Passo 5: vincule o manifesto aos resultados de avaliação que ele passou, incluindo os casos de teste cobertos e os critérios de aprovação usados.
- Passo 6: registre o responsável pela release, a pessoa que pode ordenar uma reversão e a aprovação que colocou a release em uso real.
Depois que o manifesto existir, recuse qualquer mudança em produção que não gere um novo manifesto. Essa única regra impede a deriva silenciosa. O NIST AI Risk Management Framework trata documentação e controle de mudanças como parte da governança de sistemas de IA, e um manifesto é uma forma prática de atender a essa expectativa em um agente pequeno.
Como ligar cada execução a uma configuração
Uma release só ajuda uma investigação se cada execução registrar qual release usou. Cada execução deve gravar um pequeno registro no início, e esse registro deve ser anexado a cada chamada de modelo, a cada chamada de ferramenta e à saída final. Os campos mais importantes são:
- O identificador da release e a versão do manifesto.
- O identificador do modelo como o provedor o informa, quando ele informa.
- O hash do prompt e os hashes dos esquemas de ferramentas em vigor na execução.
- A versão do índice de recuperação ou da coleção de memória de onde a execução leu.
- O resultado de cada chamada de ferramenta, incluindo códigos de erro e o tamanho das entradas e saídas.
- O motivo da parada, para que uma execução encerrada cedo possa ser explicada.
As convenções semânticas do OpenTelemetry para IA generativa definem nomes de atributos para detalhes de modelo e de operação. Usar esses nomes facilita ler registros de ferramentas diferentes em conjunto. Sempre que possível, mantenha dados pessoais fora desses registros e defina um prazo de retenção de acordo com a sua própria política, em vez de guardar tudo por tempo indeterminado.
Um cenário ilustrativo: reverter um agente de triagem de reembolsos
Este cenário é ilustrativo e não descreve uma empresa real. Uma pequena loja online usa um agente que lê pedidos de reembolso, chama uma ferramenta de consulta de pedidos e redige uma decisão para um colaborador aprovar. A release 14 muda duas coisas ao mesmo tempo: o identificador do modelo passa para uma versão mais nova, e a ferramenta de consulta renomeia um campo do esquema de saída, de valor da compra para valor pago. Pouco depois da release, alguns rascunhos descrevem pedidos com valores errados.
Como cada execução registra o identificador da release, a equipe filtra os rascunhos ruins e constata que todos vieram da release 14. As execuções da release 13 mostram os valores esperados. O manifesto da release 14 lista as duas mudanças, então a equipe não precisa adivinhar qual delas causou o problema. Ela restaura o manifesto da release 13, que devolve o agente ao identificador de modelo anterior e ao esquema de ferramenta anterior, e mantém a release 14 suspensa até que o mapeamento do campo seja corrigido e os mesmos casos de teste passem. Sem um registro compartilhado, a equipe teria de comparar o histórico do prompt, o histórico do código e um aviso do provedor antes de chegar à mesma conclusão.
Como promover e reverter uma release com segurança
A promoção deve levar uma release pelas mesmas etapas todas as vezes: um ambiente de teste montado a partir do mesmo manifesto, uma avaliação com casos que reflitam o trabalho real, um lançamento limitado e, por fim, o uso completo. Materiais publicados sobre avaliações, como o guia de evals da OpenAI, tratam as avaliações como testes repetíveis executados a cada mudança, e esse é o hábito a construir. Para o lado dos ambientes, veja por que você precisa de ambientes de teste e de produção.
A reversão é a imagem espelhada. Ela deve restaurar um manifesto anterior por inteiro, nunca um arquivo por vez, porque uma configuração mista é justamente a situação que o versionamento existe para evitar. Use este roteiro para escolher o caminho de cada mudança:
- Se a mudança for uma redação em um único arquivo de prompt, rode a suíte de avaliação e um lançamento limitado antes do uso completo.
- Se a mudança tocar um esquema de ferramenta ou uma permissão, exija a revisão do responsável pela ferramenta e um teste que chame a ferramenta com entradas realistas.
- Se a mudança trocar o identificador do modelo, trate-a como uma nova release mesmo que o prompt não tenha mudado, e compare os resultados nos mesmos casos.
- Se a qualidade cair ou as reclamações aumentarem depois de uma release, restaure primeiro o manifesto anterior e investigue depois.
Para revisar mudanças inesperadas entre releases, veja como identificar mudanças de harness não revisadas.
Como a Be Human trata o controle de releases, e por onde começar
A Be Human projeta e opera agentes com esse tipo de registro de release desde o início. Na operação gerenciada, a equipe mantém um manifesto para cada agente, revisa mudanças de permissão e de ferramentas, executa avaliações recorrentes depois de atualizações de modelo ou de integrações e usa o identificador da release durante a resposta a incidentes, para que a investigação comece pela configuração que de fato rodou. Melhorias controladas são propostas como novas releases, testadas antes e aprovadas pelo dono do negócio antes de chegarem ao trabalho real. O primeiro projeto define um papel útil, sua memória e suas ferramentas, seus limites de aprovação e um critério de sucesso observável, e essa definição se torna a primeira entrada do histórico de releases. Se ainda não está claro qual tarefa de agente merece esse nível de controle, o diagnóstico gratuito de IA da Be Human ajuda a encontrar a primeira tarefa que vale entregar a um agente.
Perguntas frequentes
O que é versionamento de agentes de IA? Versionamento de agentes de IA é a prática de registrar o prompt, os esquemas das ferramentas, o identificador do modelo e as configurações relacionadas como uma única release numerada, de modo que cada execução do agente possa ser associada à configuração que a produziu. Ele vai além de versionar um arquivo de prompt, porque uma mudança de comportamento pode vir de um esquema de ferramenta ou de um identificador de modelo sem nenhuma edição no prompt. O identificador da release é o que conecta essas peças durante a revisão e a resposta a incidentes.
Ainda preciso registrar o identificador do modelo se meu provedor cuida das atualizações? Sim, porque um alias flutuante pode mudar o modelo em que o agente roda sem nenhuma alteração nos seus arquivos. Fixe um identificador explícito quando o provedor permitir e registre o identificador que o provedor informa em cada execução. Assim, uma atualização vira uma release que você pode testar e, se necessário, desfazer.
Quantas releases antigas uma equipe pequena deve guardar? Guarde histórico suficiente para restaurar rapidamente a última release que funcionava, e guarde todas as releases que chegaram ao trabalho real, já que um incidente pode envolver qualquer uma delas. Aposente manifestos antigos de acordo com uma política escrita e nunca reutilize um identificador. Armazenamento raramente é o limite, mas a falta de um responsável claro pelas releases antigas costuma ser.
Onde o identificador da release deve aparecer? Coloque-o no registro da execução, em cada trecho de rastro da execução, nos registros de chamadas de ferramenta e em qualquer metadado de saída que um revisor veja. Se o identificador aparecer em um único lugar, toda investigação depende de esse único registro estar completo. Trate o identificador como campo obrigatório no harness, de modo que uma execução não possa começar sem ele.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


