Configuração como código para agentes de IA

O mesmo agente pode virar três sistemas diferentes

O time testa um agente em homologação. O fluxo usa um modelo específico, consulta duas fontes e mantém escrita externa bloqueada. O resultado é aprovado.

Na produção, alguém altera a temperatura pelo painel do fornecedor. Outra pessoa habilita uma ferramenta para resolver um caso urgente. Uma variável aponta para um índice antigo. O timeout continua diferente entre workers. Nenhuma mudança aparece no repositório usado pela equipe.

O nome do agente e o código permanecem iguais, mas a composição executada já mudou.

Configuração como código para agentes de IA coloca parâmetros, referências, políticas e ligações operacionais em arquivos versionados, revisáveis e validados. A produção deixa de depender de cliques, memória e ajustes sem histórico. Cada ambiente passa a ser comparável com uma configuração declarada.

Esse método não transforma segredo em arquivo público e não elimina painéis administrativos. Ele define qual estado deveria existir, quem pode alterá-lo, como a mudança chega a cada ambiente e como a equipe detecta divergências.

Por que agentes possuem uma superfície de configuração ampla

Em uma aplicação comum, configuração costuma cobrir endpoint, banco, timeout e flags. Um agente adiciona outras camadas que mudam comportamento e consequência.

Modelo e parâmetros

Fornecedor, modelo, perfil de roteamento, limite de tokens, temperatura, formato de resposta e fallback afetam qualidade, custo e latência.

Instruções e skills

Prompts, procedimentos, exemplos, ferramentas permitidas e critérios de escalonamento orientam o trabalho.

Fontes e memória

Índices, coleções, validade, filtros, regras de recuperação e escopo por cliente definem o contexto disponível.

Ferramentas e integrações

Endpoints, operações habilitadas, schemas, timeouts, tentativas e chaves de idempotência determinam como o agente age.

Identidade e permissões

Contas técnicas, escopos, alçadas e políticas de autorização controlam o alcance da consequência.

Operação

Concorrência, filas, limites de custo, aprovação humana, alertas, modos degradados e kill switch também fazem parte da versão real.

O guia sobre controle de mudanças em agentes de IA governa a hipótese, o risco, a aprovação, a liberação e a reversão de uma alteração. Configuração como código fornece uma forma reproduzível de declarar parte importante dessa composição e comparar o estado executado com o aprovado.

O que deve entrar no código

A regra prática é versionar a estrutura e os valores não secretos que definem comportamento. Segredos ficam em um cofre e entram apenas por referência autorizada.

Um manifesto de configuração pode declarar:

identificador e versão do agente;
ambiente;
modelo ou perfil de modelo;
parâmetros permitidos;
versões de instruções e skills;
ferramentas habilitadas;
endpoints por serviço;
schemas de entrada e saída;
timeouts e política de tentativa;
limites de concorrência e custo;
fontes e índices autorizados;
política de memória;
classes que exigem aprovação;
flags de autonomia;
telemetria e retenção;
referências para credenciais;
regras de fallback e interrupção.

O arquivo pode usar YAML, JSON, TOML ou outro formato compatível com a plataforma. A sintaxe é secundária. A configuração precisa ser legível por máquina, validável e associada a uma versão.

O que deve ficar fora

Não coloque no repositório:

tokens;
senhas;
chaves privadas;
payloads reais de clientes;
documentos sensíveis;
dados pessoais usados como exemplo;
respostas completas capturadas em produção;
credenciais codificadas em base64;
URLs temporárias que carregam assinatura.

O manifesto registra uma referência como secret://producao/crm/agente-comercial. O runtime resolve o valor pelo mecanismo de segredos autorizado. A referência pode ser revisada; o conteúdo permanece protegido.

A página sobre identidade e credenciais para agentes de IA detalha criação, escopo, rotação e revogação. Configuração como código não substitui esse ciclo.

Crie uma hierarquia simples

Copiar o arquivo inteiro para desenvolvimento, homologação e produção costuma gerar divergência. Prefira uma base comum com sobreposições explícitas.

Uma estrutura possível:

config/
  schema.json
  base.yaml
  environments/
    development.yaml
    staging.yaml
    production.yaml
  agents/
    comercial.yaml
    financeiro.yaml
  policies/
    autonomy.yaml
    retention.yaml
    tools.yaml

A base contém padrões compartilhados. O arquivo do agente declara sua responsabilidade. O ambiente aplica diferenças autorizadas, como endpoints, cotas e modos de consequência.

Evite uma cascata de herança difícil de reconstruir. A equipe precisa conseguir renderizar a configuração final em um único artefato e explicar de onde cada valor veio.

Separe diferenças legítimas de acidentes

Ambientes não precisam ser idênticos. Eles precisam divergir por motivos conhecidos.

Diferenças legítimas incluem:

endpoint de sandbox;
credencial com escopo menor;
dados sintéticos;
limite de volume reduzido;
envio externo bloqueado;
retenção curta;
telemetria mais detalhada em teste;
grupo limitado de usuários.

Diferenças perigosas incluem:

modelo distinto sem avaliação;
instrução antiga em produção;
ferramenta habilitada somente por clique;
timeout maior para esconder falha;
permissão de escrita ausente na homologação e ativa em produção;
schema incompatível;
índice com versão não registrada;
fallback que nunca foi testado.

O objetivo da paridade não é apagar a fronteira de segurança. É garantir que a evidência produzida em um ambiente represente a composição que será promovida, com exceções conhecidas.

Use schemas para bloquear configurações inválidas

Arquivos versionados ainda podem conter erro. Um schema deve validar estrutura, tipos, valores permitidos e combinações proibidas.

Verifique pelo menos:

campos obrigatórios;
modelo pertencente ao catálogo aprovado;
temperatura dentro da faixa permitida;
timeout positivo e abaixo do teto;
ferramenta existente no catálogo;
versão de schema compatível;
ambiente reconhecido;
política de retenção presente;
referência de segredo no formato correto;
limite de custo definido;
aprovação exigida para ações sensíveis;
telemetria ativa quando existe escrita externa.

Também crie regras entre campos. Se external_write estiver ativo, exija confirmação do destino, idempotência, tracing, mecanismo de pausa e política de aprovação compatível. Validar cada campo separadamente não detecta uma composição insegura.

A policy as code para agentes de IA ajuda a tornar permissões e decisões de política executáveis. O schema valida a configuração. A política avalia se uma ação pode ocorrer naquele contexto.

Valide semântica, não apenas sintaxe

Um YAML pode estar bem formado e apontar para algo que não existe.

A validação semântica verifica:

endpoint acessível no ambiente esperado;
referência de segredo existente, sem revelar o valor;
modelo disponível na região ou conta;
ferramenta compatível com o schema declarado;
índice de conhecimento publicado;
fila e tópico existentes;
regra de roteamento sem destino vazio;
fallback sem ciclo;
limites compatíveis com a cota do fornecedor;
versão da instrução localizada;
alerta associado a um canal e responsável válidos.

Essas verificações devem usar identidade de leitura e evitar consequências. Um teste de configuração não deveria enviar mensagem ou criar registro real para provar que um endpoint existe.

Gere um artefato imutável por versão

A configuração final usada pelo runtime precisa ter identidade própria.

Depois de combinar base, agente e ambiente:

valide o schema;
execute regras semânticas;
produza o arquivo final;
normalize a serialização;
gere hash ou identificador;
associe commit, build e aprovadores;
armazene o artefato em local controlado;
promova exatamente esse artefato.

Não reconstrua produção a partir da branch corrente no momento do deploy. A branch pode ter mudado depois dos testes. Promover o artefato avaliado preserva a relação entre evidência e versão.

O tracing de agentes de IA deve registrar o identificador da configuração em cada execução. Quando um desvio aparece, a equipe consegue localizar a composição real.

Promova entre ambientes

Uma sequência segura evita editar produção diretamente.

Desenvolvimento

A equipe ajusta arquivos, valida estrutura e executa testes rápidos com ferramentas isoladas.

Homologação

O pipeline aplica a candidata em ambiente semelhante, roda regressão, cenários de falha e integrações autorizadas. Usuários do processo podem avaliar casos representativos.

Produção limitada

O mesmo artefato recebe escopo pequeno, como uma carteira, classe de tarefa ou percentual do volume. Métricas e traces acompanham a janela.

Produção ampliada

A equipe aumenta o alcance depois de cumprir critérios. A configuração não muda durante a ampliação; apenas o parâmetro de escopo previamente governado avança.

Cada promoção registra origem, destino, versão, evidência, aprovador, horário e condição de rollback.

Trate mudança manual como exceção controlada

Pode haver uma urgência real que exija alterar um painel ou variável antes do pipeline normal. Fingir que isso nunca acontecerá só torna a mudança invisível.

Crie um procedimento de emergência:

incidente ou justificativa vinculada;
pessoa autorizada;
valor anterior e novo;
alcance e prazo;
revisão por outra pessoa quando o impacto justificar;
log de auditoria;
alerta automático;
expiração ou reversão programada;
reconciliação obrigatória com o repositório;
validação posterior.

A alteração emergencial deve gerar drift intencional por pouco tempo. Se a equipe não incorpora ou reverte o valor, a exceção vira configuração permanente sem fonte confiável.

Detecte configuration drift

Drift ocorre quando o estado executado diverge do estado declarado. Pode nascer de clique manual, deploy parcial, variável antiga, segredo apontando para outra versão ou componente que não recarregou a configuração.

Compare periodicamente:

hash da configuração ativa;
versão de instrução e skill;
modelo e parâmetros;
ferramentas habilitadas;
flags de autonomia;
endpoints e schemas;
limites de concorrência, custo e tentativa;
referências de segredo;
fontes e índices;
políticas de retenção e telemetria;
versão por worker ou instância.

A verificação deve alcançar todas as réplicas. Um worker antigo pode continuar processando parte do tráfego enquanto os demais usam a versão nova.

Classifique a divergência:

esperada e temporária;
emergencial autorizada;
deploy incompleto;
alteração não registrada;
componente desatualizado;
configuração inválida;
possível incidente de segurança.

A resposta pode reconciliar automaticamente valores reversíveis e conhecidos. Diferenças de permissão, identidade, dados ou consequência externa pedem bloqueio conservador e revisão.

Evite que o runtime escolha sua própria política

O agente pode selecionar ferramenta ou rota dentro de opções autorizadas. Ele não deveria alterar os próprios limites para concluir uma tarefa.

Mantenha fora do alcance do modelo:

permissões;
teto de custo;
número máximo de tentativas;
classes que exigem aprovação;
destino dos logs;
política de retenção;
lista de fontes autorizadas;
isolamento entre clientes;
kill switch;
regra de confirmação externa.

Esses controles pertencem à camada determinística. A configuração declarada informa o que vale. A aplicação e a infraestrutura fazem cumprir.

Planeje rollback de configuração e de estado

Restaurar um arquivo anterior corrige somente a composição futura. O agente pode ter iniciado tarefas ou criado efeitos com a versão defeituosa.

O plano de rollback deve cobrir:

interrupção de novas entradas;
identificação da versão afetada;
restauração do artefato anterior;
confirmação em todas as instâncias;
tratamento de execuções em andamento;
localização de efeitos externos;
reconciliação de filas e estados;
rotação de segredo, se necessário;
validação da versão restaurada;
retomada gradual.

Feature flags podem desligar uma capacidade sem reimplantar todo o agente. Ainda assim, a flag precisa ser versionada, auditada e vinculada a uma política de uso. A página sobre feature flags para agentes de IA detalha escopo, expiração e segurança dessas chaves.

Observe configuração como parte da saúde

Um painel operacional deve mostrar qual composição está ativa e se ela corresponde ao estado aprovado.

Acompanhe:

versão por ambiente e instância;
último deploy e responsável;
hash esperado e observado;
divergências abertas;
configuração emergencial perto de expirar;
falhas de validação;
segredo indisponível ou próximo da rotação;
uso de modelo fora do catálogo;
ferramenta habilitada fora da política;
diferença de schema;
rollback executado;
execuções por versão.

O monitoramento de agentes em produção liga essa saúde técnica a qualidade, risco e impacto do processo. Versão correta não garante resultado bom, mas versão desconhecida torna qualquer investigação frágil.

Um exemplo para agente comercial

Considere um agente que lê oportunidades, prepara a próxima ação e cria tarefas no CRM.

A configuração pode declarar:

modelo aprovado para classificação;
versão da instrução comercial;
campos do CRM permitidos para leitura;
operação de escrita limitada à criação de tarefa;
segmentos excluídos;
horário de execução;
teto de oportunidades por lote;
prazo da fila;
classes que exigem revisão;
confirmação obrigatória do ID da tarefa;
chave de idempotência;
limite de custo;
tracing ativo;
flag de envio externo desabilitada.

Se alguém habilitar envio de mensagem pelo painel, a comparação detecta uma ferramenta e uma autonomia que não pertencem ao manifesto aprovado. O sistema pode bloquear a capacidade e alertar o dono antes de processar novos casos.

Métricas do processo de configuração

A disciplina deve reduzir erro sem criar uma burocracia cega.

Meça:

percentual de ambientes com estado declarado;
divergências por período;
tempo para detectar drift;
tempo para reconciliar;
mudanças emergenciais não incorporadas;
falhas de deploy por validação;
incidentes ligados a configuração;
tempo de rollback;
instâncias em versão antiga;
alterações aprovadas que exigiram correção;
tempo entre mudança e promoção;
cobertura de regras semânticas.

Quantidade de arquivos ou commits não indica controle. A métrica útil mostra se a versão aprovada chegou inteira, permaneceu observável e pôde ser revertida.

Erros comuns

Colocar segredos no repositório

Criptografar ou codificar sem uma política adequada continua expondo material sensível. Use referências e um cofre.

Versionar apenas o prompt

Modelo, ferramentas, fontes, permissões, filas e limites também alteram o comportamento.

Copiar arquivos por ambiente

Duplicação amplia divergência silenciosa. Use base, sobreposições curtas e renderização final.

Validar somente YAML ou JSON

Sintaxe correta pode apontar para modelo proibido, segredo inexistente ou fallback circular.

Permitir ajustes sem reconciliação

Mudanças emergenciais sem prazo e sem retorno ao repositório criam uma segunda fonte da verdade.

Promover reconstruindo a candidata

Se o pipeline refaz o artefato com arquivos mais novos, a produção recebe uma versão diferente da testada.

Comparar somente no deploy

Drift também nasce horas ou dias depois. A verificação precisa ser contínua e alcançar todas as instâncias.

Checklist de configuração como código

A configuração cobre modelo, instruções, ferramentas, fontes, permissões e operação?
Segredos aparecem somente por referência?
Existe schema com combinações proibidas?
Validações semânticas conferem recursos reais?
Diferenças entre ambientes estão explícitas?
A configuração final pode ser renderizada e explicada?
O artefato promovido é o mesmo que foi testado?
Cada execução registra a versão ativa?
Mudanças manuais possuem autorização, prazo e reconciliação?
Drift é verificado em todas as instâncias?
Divergências sensíveis bloqueiam capacidade?
O runtime não pode ampliar os próprios limites?
Rollback cobre configuração, filas e efeitos externos?
Métricas mostram detecção e correção de divergência?

Configuração visível preserva a evidência

Agentes mudam por muitas superfícies. Quando parte dessas mudanças vive apenas em painéis, variáveis soltas e memória da equipe, a empresa perde a ligação entre teste, aprovação e execução.

Configuração como código torna o estado desejado legível e comparável. A equipe valida estrutura e relações, promove um artefato conhecido, detecta drift e restaura versões com mais segurança.

O ganho prático aparece na operação. Quando qualidade, custo ou comportamento mudam, a investigação começa por uma composição identificável. A empresa consegue corrigir o componente certo sem reconstruir a história a partir de cliques e suposições.