Feature flags para agentes de IA: controle por capacidade

Código disponível não deveria significar capacidade liberada

Uma equipe publica uma nova versão do agente de atendimento. O pacote inclui leitura de contratos, criação de tarefas, atualização de prioridade e envio de mensagens. A empresa queria testar apenas a leitura de contratos com um grupo interno.

Como todas as capacidades chegaram ligadas ao mesmo deploy, o teste técnico virou liberação operacional. Uma configuração incorreta permitiu que a candidata atualizasse chamados fora da fila prevista.

Feature flags evitam esse acoplamento. Elas permitem publicar código e manter cada capacidade desativada até que público, risco, evidência e responsável estejam prontos.

Para agentes de IA, a flag pode governar uma ferramenta, uma ação, uma fonte, uma rota de modelo, uma classe de tarefa ou um nível de autonomia. O controle deixa de ser “agente ligado” e passa a refletir as fronteiras reais da operação.

O que são feature flags em agentes de IA

Feature flag é uma condição externa ao código principal que decide se determinada capacidade fica disponível durante uma execução. A mesma versão pode se comportar de formas diferentes conforme ambiente, usuário, cliente, processo, risco ou estado operacional.

Exemplos:

permitir consulta ao CRM, mas bloquear escrita;
liberar uma nova fonte somente para a equipe financeira;
ativar modelo novo para documentos de baixo risco;
exigir aprovação para mensagens externas;
permitir criação de tarefa e bloquear alteração de estágio;
reduzir o agente ao modo de preparação durante uma degradação;
desligar uma ferramenta específica sem suspender todo o fluxo;
liberar uma skill nova para uma coorte de teste.

A flag precisa ser aplicada na camada que controla a consequência. Escrever no prompt “não use a ferramenta” não substitui um bloqueio no dispatcher, na política ou na própria integração.

Flag, configuração e permissão não são sinônimos

Misturar essas camadas cria controles frágeis.

Configuração ajusta comportamento

Temperatura, limite de contexto, modelo, timeout e formato de saída alteram como o sistema trabalha. Uma configuração pode ser versionada e liberada gradualmente.

Feature flag decide disponibilidade

A flag responde se uma capacidade, rota ou comportamento pode entrar naquela execução. Ela costuma ser temporária, segmentável e reversível.

Permissão define autoridade

Credenciais, escopos e políticas determinam o que a identidade consegue fazer no sistema de destino. A permissão deve continuar protegendo a fronteira mesmo quando a flag falha.

Uma flag pode ocultar a ferramenta de pagamento para a maioria dos casos. A credencial do agente ainda deve possuir a menor alçada possível. Defesa em camadas evita que um erro de avaliação transforme uma capacidade desativada em ação disponível.

O guia sobre identidade e credenciais para agentes de IA mostra como atribuir acesso, rotação e revogação ao ciclo de vida do agente.

Por que agentes exigem flags mais granulares

Em software tradicional, uma flag costuma liberar uma tela ou função. Agentes combinam interpretação, contexto e ferramentas durante o caminho. Uma única execução pode atravessar capacidades com consequências muito diferentes.

Considere um agente comercial. Ele pode:

ler oportunidade;
recuperar e-mails;
resumir histórico;
classificar intenção;
criar próxima ação;
alterar estágio;
preparar mensagem;
enviar comunicação;
agendar novo contato.

Tratar tudo como uma funcionalidade impede progressão segura. Leitura e resumo podem estar maduros. Alteração de estágio pode exigir confirmação. Envio pode permanecer restrito a uma carteira e horário.

As flags devem acompanhar verbos operacionais. “CRM habilitado” é amplo. crm_read, task_create, stage_update e message_send representam fronteiras mais legíveis.

Tipos úteis de feature flags

Flag de capacidade

Ativa uma ferramenta ou ação específica. Exemplos: consultar contrato, criar tarefa, enviar mensagem ou gravar no ERP.

Flag de autonomia

Define se a saída fica em modo observação, sugestão, aprovação ou execução. A capacidade técnica existe, porém a autoridade varia por classe.

Flag de fonte

Controla uma base, índice, documento ou sistema consultado. Ajuda a introduzir uma fonte nova sem alterar todo o contexto disponível.

Flag de modelo ou rota

Direciona tarefas para uma configuração homologada. Pode comparar modelos, provedores ou perfis de custo por unidade.

Flag de público

Limita por área, usuário, cliente, carteira, região ou grupo de teste. O critério precisa respeitar isolamento e contratos.

Flag de ambiente

Separa desenvolvimento, homologação e produção. O valor deve vir do ambiente e da política, sem depender de convenção informal no nome da tarefa.

Flag operacional

Ativa modo degradado, fila manual, revisão ampliada ou bloqueio temporário durante falha, manutenção ou consumo acelerado do orçamento de erro.

Kill switch

Interrompe uma capacidade com prioridade de segurança. O kill switch para agentes de IA precisa bloquear entradas, execuções, ferramentas ou credenciais e confirmar a parada. Uma flag comum pode participar desse mecanismo, mas só funciona como kill switch quando alcance, latência e evidência foram testados.

Modele a decisão da flag como política

Um booleano global atende poucos casos. Em produção, a decisão pode considerar vários atributos.

Uma política de avaliação pode usar:

ambiente;
agente e versão;
processo;
cliente ou unidade;
usuário solicitante;
classe de tarefa;
ação pretendida;
nível de risco;
valor ou alçada;
sensibilidade do dado;
horário e cobertura humana;
estado do incidente;
coorte de implantação;
orçamento de custo disponível;
saúde da dependência.

A saída da avaliação deve ser estruturada. Em vez de apenas verdadeiro ou falso, ela pode devolver:

permitir;
permitir com limite;
exigir aprovação;
usar rota alternativa aprovada;
bloquear e registrar;
encaminhar para pessoa;
operar somente em leitura.

Essa decisão se aproxima de um guardrail para agentes de IA. A diferença está no objeto. Guardrails governam barreiras ao longo do caminho. Feature flags controlam a disponibilidade de capacidades e variações específicas.

Avalie a flag antes de expor a ferramenta

Se o agente descobre uma ferramenta e só depois recebe instrução para não usá-la, a superfície já foi ampliada. Prefira avaliar a política antes de montar o catálogo disponível para aquela execução.

Uma sequência segura pode ser:

identificar agente, usuário e unidade de trabalho;
recuperar atributos autorizados;
avaliar flags e política;
montar ferramentas e fontes permitidas;
executar o planejamento dentro do catálogo;
reavaliar antes de ação sensível;
validar parâmetros na integração;
registrar decisão e efeito confirmado.

A reavaliação importa em tarefas longas. Uma flag pode mudar durante a execução porque surgiu incidente, a aprovação venceu ou a condição do cliente mudou. O agente não deveria conservar por horas uma decisão de acesso que já perdeu validade.

Use padrões seguros quando a avaliação falha

O serviço de flags pode ficar indisponível, devolver configuração inválida ou perder conectividade. Cada capacidade precisa de um comportamento padrão.

Falha fechada

A ação fica bloqueada. É adequada para escrita, envio, dinheiro, exclusão, dados sensíveis e outras consequências relevantes.

Falha para modo limitado

O agente preserva leitura ou preparação e encaminha a execução. Serve quando manter contexto ajuda a operação sem produzir efeito externo.

Último valor conhecido

Pode ser aceitável em capacidade de baixo risco e curta validade. Registre idade, origem e limite de uso. Não preserve indefinidamente uma decisão antiga.

Contingência manual

Casos com prazo seguem para a fila responsável. O pacote precisa incluir contexto, motivo do bloqueio e próxima ação.

A escolha deve ser feita por capacidade. Um padrão global permissivo pode manter uma função conveniente e liberar outra perigosa durante a mesma falha.

Separe deploy de liberação

O fluxo operacional ganha duas decisões.

Deploy

A composição é instalada e fica tecnicamente disponível. Testes de integridade, compatibilidade, segurança e regressão precisam passar.

Liberação

Uma capacidade recebe autorização para determinado público e condição. A decisão usa evidência do caso, prontidão da equipe, risco e janela de acompanhamento.

Essa separação permite publicar uma versão durante horário controlado, manter novas ações desligadas e ativar cada faixa sem outro deploy. Também permite reverter uma capacidade rapidamente enquanto a equipe investiga, sem apagar correções saudáveis do mesmo pacote.

O controle de mudanças em agentes de IA continua governando a composição. Flags acrescentam uma camada de ativação que precisa de dono, teste e histórico.

Combine flags com implantação canário

A implantação canário para agentes de IA define quem recebe uma versão candidata e como o resultado será comparado. Feature flags decidem quais capacidades essa versão oferece para cada coorte.

Um lançamento pode seguir:

deploy da candidata com todas as novas ações desligadas;
ativação de leitura para usuários internos;
liberação de preparação em uma classe simples;
criação de tarefas com aprovação;
escrita reversível para uma carteira;
envio limitado dentro de política;
ampliação por evidência.

A coorte controla exposição. A flag controla capacidade. Usar as duas permite avançar em mais de uma dimensão sem liberar tudo para todos.

Registre cada avaliação relevante

A trilha deve responder por que uma capacidade estava disponível quando a execução ocorreu.

Registre:

identificador da flag;
versão da configuração;
agente e composição;
unidade de trabalho;
atributos usados, com proteção de dados;
decisão resultante;
regra correspondente;
horário;
aprovação associada;
ferramenta exposta;
ação solicitada;
resultado confirmado;
mudança posterior da flag, quando relevante.

Evite colocar dados pessoais ou conteúdo sensível diretamente no nome da flag. Use identificadores e atributos governados. A observabilidade precisa permitir investigação sem virar outra cópia indiscriminada do contexto.

O tracing de agentes de IA pode ligar a avaliação da flag às etapas, ferramentas e resultado final.

Controle quem pode alterar flags

Uma interface simples de ativação pode produzir impacto maior que um deploy. A governança precisa considerar:

identidade do operador;
escopo da mudança;
ambientes afetados;
capacidade controlada;
público atingido;
prazo da alteração;
dupla aprovação para ações críticas;
justificativa;
revisão por outra pessoa;
histórico imutável;
alerta para mudanças amplas;
reversão rápida.

Evite flags críticas compartilhadas entre equipes sem dono. Uma alteração feita para teste interno pode atingir produção se ambiente e escopo estiverem mal definidos.

Mudanças emergenciais também precisam de registro. Velocidade e rastreabilidade podem coexistir quando o sistema já possui papéis, modelos de alteração e revisão posterior.

Dê validade e dono para cada flag

Flags temporárias envelhecem. Meses depois, ninguém lembra por que existem, qual valor está correto ou se a rota antiga ainda pode ser removida.

Mantenha um catálogo com:

nome e descrição;
responsável;
capacidade governada;
ambiente;
padrão seguro;
público atual;
data de criação;
motivo;
prazo de revisão;
condição de remoção;
dependências;
painéis e alertas;
último teste de desligamento.

Classifique flags como:

lançamento temporário;
experimento;
controle operacional;
permissão transitória;
contingência;
configuração duradoura.

Flags de lançamento devem desaparecer depois da decisão. Flags operacionais permanentes exigem manutenção equivalente à de qualquer controle de produção.

Evite combinações impossíveis de testar

Dez flags booleanas podem gerar centenas de combinações. Um agente com modelo A, fonte B, ferramenta C e autonomia D pode entrar em um estado que nunca passou por avaliação.

Reduza o espaço:

agrupe configurações aprovadas em perfis;
declare combinações incompatíveis;
use hierarquia entre flag global e específica;
limite dependências entre flags;
teste pares críticos;
gere snapshots da composição efetiva;
bloqueie estados desconhecidos;
remova flags concluídas.

Prefira perfis legíveis como leitura, preparação, escrita-reversível e execução-supervisionada em vez de dezenas de opções independentes sem contrato.

O catálogo de ferramentas para agentes de IA ajuda a declarar operações, parâmetros, efeitos e permissões. As flags escolhem qual subconjunto desse catálogo chega à execução.

Teste o controle, não somente a funcionalidade

Inclua cenários como:

flag desligada antes da execução;
mudança durante tarefa longa;
serviço de flags indisponível;
configuração vencida;
usuário fora da coorte;
cliente associado à unidade errada;
conflito entre regra global e específica;
tentativa direta de chamar ferramenta bloqueada;
cache antigo;
alteração sem permissão;
rollback de configuração;
desligamento sob carga;
fila com unidades iniciadas antes da mudança;
reprocessamento depois da reativação.

Verifique se a ferramenta desaparece do catálogo, se a integração recusa a ação, se o agente produz estado conhecido e se o alerta informa o responsável.

O ambiente de teste para agentes de IA deve reproduzir políticas, identidades e respostas da camada de flags.

Exemplo: agente comercial por níveis de autonomia

Uma empresa quer evoluir um agente que acompanha oportunidades.

Perfil de leitura

Pode consultar CRM, agenda e notas autorizadas. Não cria nem altera registros.

Perfil de preparação

Produz resumo, risco e próxima ação sugerida. Entrega o pacote ao vendedor.

Perfil de escrita reversível

Cria tarefa pendente e atualiza a data de acompanhamento. Não altera valor, estágio ou condição comercial.

Perfil de execução supervisionada

Envia modelos aprovados para classes simples dentro de horário, carteira e política de contato. Exceções pedem aprovação.

Flags selecionam o perfil por carteira e classe. Uma flag separada controla a fonte de e-mail nova. Durante uma falha no CRM, a escrita fecha e a preparação continua. Se o serviço de política perde confiabilidade, todas as ações externas voltam ao modo bloqueado.

Esse desenho permite evoluir o agente sem tratar autonomia como um único botão.

Métricas para operar feature flags

Acompanhe:

avaliações por flag e resultado;
capacidades permitidas, limitadas e bloqueadas;
falhas de avaliação;
uso de valor antigo;
tempo para propagar alteração;
ações tentadas contra flag desligada;
incidentes por configuração;
distribuição por coorte;
qualidade por perfil;
custo por rota;
intervenções humanas;
flags sem dono ou vencidas;
tempo entre decisão e remoção;
sucesso dos testes de desligamento.

Uma flag que permanece ligada e nunca aparece na decisão pode ter perdido função. Uma flag que bloqueia frequentemente pode revelar processo mal segmentado, política confusa ou tentativa de usar a capacidade fora do caso adequado.

Checklist de feature flags para agentes

[ ] Cada flag governa uma capacidade legível?
[ ] Configuração, flag e permissão estão separadas?
[ ] O bloqueio existe na camada de execução?
[ ] A avaliação usa atributos autorizados?
[ ] O padrão de falha foi definido por capacidade?
[ ] Tarefas longas reavaliam ações sensíveis?
[ ] Deploy e liberação possuem decisões distintas?
[ ] Coortes e capacidades podem evoluir separadamente?
[ ] Cada avaliação relevante deixa trilha?
[ ] Alterações exigem identidade, escopo e justificativa?
[ ] Flags críticas possuem aprovação compatível?
[ ] Toda flag tem dono, validade e condição de remoção?
[ ] Combinações inválidas são bloqueadas?
[ ] Cache, indisponibilidade e rollback foram testados?
[ ] O desligamento funciona sob carga?
[ ] Filas e unidades em andamento possuem tratamento conhecido?

Controle granular reduz o custo de avançar e de recuar

Feature flags permitem que a arquitetura publique capacidade sem conceder uso imediato. A empresa escolhe quem recebe cada ferramenta, em qual processo, com qual autonomia e sob que condição.

O valor aparece quando a flag controla a camada executável, possui padrão seguro, deixa evidência e expira depois de cumprir sua função. Uma coleção de booleanos sem dono apenas transfere complexidade do código para a configuração.

Agentes ganham autonomia por verbos, públicos e riscos. Quando essas fronteiras podem ser ativadas e removidas separadamente, a operação consegue testar mudanças menores, conter falhas com precisão e preservar capacidades saudáveis durante uma investigação.