# Agentes de IA alterando feature flags: controle cada alteração Agentes de IA que alteram feature flags precisam ser tratados como alterações em produção, porque é isso que fazem. Uma flag pode ficar fora do pipeline de implantação, mas ainda assim ativar código para clientes, bloquear um fluxo de pagamento, ampliar um experimento ou desativar uma verificação de segurança em poucos segundos. O erro que vejo com frequência é dar a um agente acesso ao provedor de flags porque a tarefa parece inofensiva: «ative o novo fluxo para usuários internos» ou «reduza o rollout para zero». A alteração pode até estar correta. A parte perigosa é o registro que ficou faltando. Depois de uma indisponibilidade, as pessoas precisam saber o que o agente solicitou, quem aceitou a solicitação, o que o provedor fez e se o estado final correspondeu ao pedido. Uma transcrição de chat não consegue sustentar esse peso. ## Uma alteração de flag é uma alteração em produção Uma atualização de feature flag tem a mesma natureza operacional de mudar uma configuração de banco de dados em produção ou editar uma regra de roteamento ativa. A chamada à API pode ser pequena, mas o efeito pode ser amplo e imediato. Tratar flags como uma configuração inofensiva produz uma falha conhecida. Um agente investiga uma taxa elevada de erros, encontra uma flag associada ao recurso recente e a define como `false`. Isso pode proteger os usuários. Também pode desativar um caminho de código não relacionado porque a flag usa uma regra de direcionamento em vez de um simples booleano, ou porque o agente selecionou o ambiente errado. Se ninguém consegue identificar a alteração exata solicitada e a pessoa que a aprovou, a equipe passa o incidente discutindo o histórico em vez de restaurar o serviço. O artigo de Martin Fowler sobre Feature Toggles faz uma distinção que muitas equipes acabam apagando. Flags de lançamento, de experimento, operacionais e de controle de permissões têm durações e níveis de dinamismo diferentes. Essa distinção deve mudar o controle aplicado a uma ação do agente. Uma flag operacional que desativa uma integração com falha pode exigir uma aprovação humana rápida. Uma flag de permissões que muda quem pode acessar dados regulados merece um processo muito mais rigoroso. Chamar ambas de «uma flag» diz pouco sobre o risco. As alterações de flags também passam ao largo de controles que engenheiros associam a implantações de código. Uma pull request pode mostrar revisão por pares, um build pode mostrar resultados de testes e uma versão pode mostrar a versão do artefato. Uma chamada ao provedor de flags pode mostrar apenas um nome de token e um horário. Se um processo autônomo controla o token, até esse nome pode ser compartilhado por várias execuções. Faça a mesma pergunta que faria antes de qualquer alteração em produção: que estado exato esta solicitação vai mudar, sob qual autoridade e como vamos provar o estado resultante? Uma leitura é diferente. Um agente pode inspecionar uma flag, seu ambiente e suas regras atuais para preparar uma recomendação. Uma escrita altera um sistema externo. Não agrupe essas permissões só porque uma integração torna isso conveniente. ## Separe intenção, autorização, execução e estado observado Um único evento não descreve bem uma ação sobre uma feature flag. Um registro confiável contém quatro fatos diferentes, e misturá-los esconde a falha que você precisará diagnosticar mais tarde. A **intenção** é o que o agente pediu para acontecer. Ela deve identificar uma flag estável, o ambiente, o valor solicitado ou a alteração de regra, o motivo e o escopo. Precisa ser registrada antes da chamada ao provedor. A **autorização** informa quem permitiu essa intenção. A aprovação humana precisa estar vinculada à alteração exata proposta, não a um pedido vago como «deixe o agente gerenciar flags». A pessoa aprovadora precisa de contexto suficiente para decidir: ambiente de destino, estado atual, estado proposto, segmento afetado, prazo de expiração, se houver, e a tarefa ou o incidente que levou à solicitação. A **execução** registra a solicitação enviada e a resposta do provedor. Isso é uma evidência de que o gateway tentou realizar a ação aprovada. Não prova que o estado desejado existe. O **estado observado** vem da leitura da flag depois da alteração. Ela detecta payloads malformados, atualizações parciais, comportamentos de valor padrão e chamadas enviadas ao projeto ou ambiente errado. Uma nova leitura ainda tem limites. Clientes SDK em cache podem não ter buscado a configuração alterada, e a leitura não prova que o código controlado pela flag funciona corretamente. Essas são observações separadas, que pertencem à telemetria da implantação e ao monitoramento da aplicação. Essa distinção importa durante uma reversão. Suponha que um agente solicite `checkout_v2=false`, uma pessoa aprove, e o provedor retorne sucesso. Se uma segunda pessoa alterar a flag antes que o agente faça a leitura, um log ingênuo contará uma história limpa, mas falsa. Um registro adequado dirá que a solicitação aprovada teve sucesso no limite da API e depois informará o estado observado, incluindo uma versão ou revisão, se o provedor disponibilizar uma. Não deixe que um motivo escrito livremente substitua esses campos. «Reduzir erros no checkout» é um contexto útil. Não é um alvo, um valor anterior, um novo valor aprovado nem um resultado final. ## Capture um envelope de alteração antes da chamada ao provedor O agente deve enviar uma solicitação de alteração estruturada, não montar uma solicitação HTTP arbitrária para o provedor de flags. Um envelope fixo cria algo que uma pessoa revisora consegue ler e que um gateway consegue validar. Este exemplo usa uma flag booleana, mas o mesmo formato se aplica a configurações JSON, rollouts percentuais e regras de direcionamento. Mantenha alterações de regras separadas de alterações de valores escalares. Uma regra de direcionamento pode ampliar a exposição muito mais do que um único valor verdadeiro ou falso sugere. ```json { "request_id": "ffchg_01J8KQ4W6D7P", "correlation_id": "incident_INC-1842", "operation": "set_boolean_flag", "flag": { "project": "storefront", "environment": "production", "name": "checkout_v2" }, "expected": { "value": true, "revision": "481" }, "requested": { "value": false }, "reason": "Reduce checkout failures while payment timeout is investigated", "rollback": { "value": true, "expires_at": "2025-03-08T18:00:00Z" } } ``` O bloco `expected` impede uma sobrescrita silenciosa. Ele diz: faça esta alteração somente se o valor e a revisão atuais ainda corresponderem ao que a pessoa solicitante verificou. Se outra pessoa ou automação tiver alterado a flag depois da leitura do agente, rejeite a solicitação e mostre o novo estado. Tentar novamente às cegas é a resposta errada. O agente precisa perguntar de novo, porque perdeu a base para agir. O `request_id` precisa ser idempotente. Falhas de rede podem ocorrer depois que um provedor recebe uma solicitação, mas antes que o chamador receba a resposta. Sem idempotência, uma nova tentativa do agente pode criar eventos de auditoria duplicados ou aplicar duas vezes uma regra percentual quando o provedor modela atualizações como patches. Armazene o ID da solicitação e devolva o resultado original para uma submissão repetida. Um gateway pode devolver um resultado neste formato: ```json { "request_id": "ffchg_01J8KQ4W6D7P", "status": "applied", "provider_request_id": "p_9d3ab", "authorization": { "approver": "ops@example.com", "approved_at": "2025-03-08T17:18:32Z" }, "observed": { "value": false, "revision": "482", "read_at": "2025-03-08T17:18:35Z" } } ``` Não inclua tokens do provedor em nenhum desses registros. Um log de solicitações que contém credenciais acaba se tornando um segundo cofre de segredos, geralmente com controles de acesso piores e mais cópias. ## Uma aprovação precisa descrever o raio de impacto Uma pessoa não pode aprovar uma alteração segura apenas com o nome da flag. Os nomes mudam, as flags sobrevivem à intenção original e um booleano pode esconder uma grande regra de direcionamento atrás de um rótulo agradável. O cartão de aprovação ou a tela de revisão deve mostrar a representação atual ao lado da representação solicitada. Em um rollout percentual, mostre as porcentagens antiga e nova, o público ou segmento, qualquer flag de pré-requisito e o ambiente. Em uma edição de regra, mostre a regra completa antes e depois em um formato canônico e legível. Uma diferença que omite uma cláusula porque ela parece repetitiva é o caminho para transformar acidentalmente «funcionários da região A» em «todos os usuários». A pessoa aprovadora também precisa do motivo e do prazo de expiração. Alterações operacionais temporárias costumam se tornar permanentes porque o incidente termina e todos seguem para a próxima tarefa. Uma expiração não é uma reversão automática. Ela oferece um momento programado para que alguém reavalie a flag e cria um compromisso visível no registro da ação. O escopo da aprovação deve corresponder à alteração, não ao agente. «Aprove este processo pelo restante da sessão» pode fazer sentido para inspeções repetidas ou para um conjunto predefinido de ações fora de produção. É um escopo ruim para um rollout em produção em que cada ação altera uma população diferente de clientes. Eu usaria uma aprovação separada para cada alteração em produção quando qualquer uma destas condições se aplicar: - A alteração afeta um controle operacional, pagamentos, autenticação, autorização ou retenção de dados. - A solicitação altera uma regra de direcionamento, segmento, pré-requisito ou porcentagem, em vez de um único valor booleano. - A ação tem como alvo a produção ou um ambiente conectado ao tráfego real de clientes. - O agente propõe um valor diferente do plano de reversão aprovado. Isso não é teatro de aprovação. O trabalho da pessoa não é redigitar a solicitação. Ela decide se o escopo declarado e a condição operacional atual justificam a alteração. Se o cartão esconder o escopo, a pessoa só poderá aprovar sem analisar. Evite uma aprovação permanente que diga que um agente pode «gerenciar feature flags». Ela é popular porque elimina interrupções. Também transforma cada alteração posterior em uma escrita em produção sem revisão, inclusive a alteração incomum que acontece enquanto o agente está confuso por causa de um contexto antigo ou de um resultado enganoso da ferramenta. ## A concorrência torna a reversão automática insegura por padrão Um agente só pode reverter uma flag quando prova que está desfazendo a própria alteração. O conselho comum de «sempre mandar o agente reverter em caso de falha» ignora operadores concorrentes e é inseguro. Considere esta sequência. Às 10:00, o valor atual é `true`, revisão 481. O agente recebe aprovação para defini-lo como `false`, e o provedor registra a revisão 482. Às 10:06, uma pessoa de plantão percebe outro sintoma e define deliberadamente a flag como `true`, revisão 483. Às 10:08, a condição de monitoramento do agente é acionada e ele executa a reversão planejada para `true`. Nesse caso específico, o valor duplicado parece inofensivo, mas o mesmo padrão com uma regra de direcionamento causa danos. A pessoa de plantão pode ter alterado a regra para limitar um caminho a um único tenant. O agente restaura a regra ampla antiga porque guardou um snapshot anterior à alteração. Agora ele sobrescreveu uma intervenção deliberada sem perceber. Uma solicitação de reversão deve incluir a revisão criada pela ação original como estado esperado. O gateway deve aplicar a reversão somente se o provedor ainda informar essa revisão ou a configuração canônica exata escrita pelo agente. Se a condição falhar, devolva `needs_review` com a configuração atual. O agente pode explicar o conflito a uma pessoa, mas não deve resolvê-lo sozinho. Use um payload de reversão que carregue a ação original: ```json { "request_id": "ffrb_01J8KR0Y8J2M", "operation": "rollback_boolean_flag", "parent_request_id": "ffchg_01J8KQ4W6D7P", "flag": { "project": "storefront", "environment": "production", "name": "checkout_v2" }, "expected": { "value": false, "revision": "482" }, "requested": { "value": true } } ``` Alguns provedores não disponibilizam revisões nem APIs de atualização condicional. Nesse caso, você não consegue tornar uma reversão automática segura o suficiente para uma flag de produção contestada. Leia o estado, apresente a diferença e exija aprovação humana para a alteração de restauração. Aceitar essa limitação é melhor do que fingir que um horário oferece controle de concorrência. Também diferencie a reversão de uma feature flag da recuperação do estado dos usuários. Desativar uma flag pode interromper novas exposições, mas não desfaz migrações de dados, trabalhos enfileirados nem registros criados enquanto o recurso estava ativo. Quando uma flag controla gravações, o contexto da aprovação deve dizer isso claramente. ## Restrinja verbos, alvos e credenciais Um agente deve ter permissão para solicitar um vocabulário restrito de ações sobre flags, não acesso de administrador ao provedor. O token ou a credencial de API do provedor precisa permanecer fora do contexto do agente. Comece listando os verbos permitidos. `get_flag` e `list_flag_metadata` são leituras. `set_boolean_flag` é uma escrita limitada. `set_rollout_percentage`, `replace_targeting_rule`, `create_flag`, `archive_flag` e `edit_segment` têm consequências muito maiores e devem ser operações distintas. Não exponha uma ação genérica como `PATCH /flags/{id}` esperando que as instruções mantenham o agente cuidadoso. Endpoints de patch genéricos convidam campos que nenhuma pessoa revisora esperava. Depois, restrinja os alvos. Vincule uma credencial a um projeto e ambiente quando o provedor oferecer esse escopo. No gateway de ações, mantenha uma lista permitida de identificadores de flags e operações para o trabalho específico. Um agente de lançamento que controla `checkout_v2` não precisa acessar todas as flags da organização. Uma solicitação de ação deve falhar antes de chegar ao provedor se tentar usar um verbo não aprovado, um ambiente desconhecido, uma revisão esperada ausente ou um alvo não permitido. Essa validação precisa ser determinística. Uma política em linguagem natural como «faça apenas alterações seguras» dá ao agente uma frase para interpretar, não um limite para impor. O Sallyport mantém as credenciais HTTP em seu cofre criptografado e executa a chamada à API sem passar o segredo ao agente. Isso é útil para este padrão porque o agente pode solicitar uma ação enquanto a credencial permanece no Mac que o controla. Mantenha a credencial do provedor separada da identidade do próprio agente. O registro de auditoria do provedor pode enxergar apenas uma conta de serviço, mas seu registro de ações pode identificar a sessão do agente, a tarefa de origem e a pessoa que aprovou a alteração exata. Essa separação também torna a revogação prática: você pode interromper uma execução específica do agente sem trocar uma credencial usada por um fluxo legítimo de uma pessoa. Não coloque um token de API em um arquivo de configuração do agente «só para o incidente». Agentes copiam contexto para transcrições, histórico do shell, patches gerados e argumentos de ferramentas com mais facilidade do que as equipes imaginam. Trocar o token depois não apaga essas cópias. ## Teste o caminho de controle com falhas, não apenas com caminhos felizes Uma integração de feature flags só está pronta depois que você testa como ela se comporta quando suas premissas falham. O caminho feliz, ler o valor, aprovar e atualizar o valor, prova muito pouco. Execute um teste controlado em um ambiente que não seja de produção e provoque deliberadamente estes resultados: 1. Altere a flag depois que o agente a ler e envie a solicitação original. O gateway deve rejeitar a revisão esperada desatualizada. 2. Envie o mesmo ID de solicitação duas vezes depois de simular uma resposta perdida. A segunda chamada deve devolver o primeiro resultado registrado, sem criar uma nova alteração. 3. Rejeite a aprovação. O provedor não deve receber nenhuma escrita, e o registro de auditoria deve mostrar a rejeição, não um timeout ambíguo. 4. Deixe uma pessoa editar a flag depois da ação do agente e tente uma reversão automática. A reversão deve parar para revisão. 5. Bloqueie ou revogue a sessão do agente durante uma solicitação pendente. A ação deve falhar antes do uso da credencial. Esses testes revelam um problema sutil de design: muitas equipes registram apenas alterações bem-sucedidas. Solicitações falhas e negadas importam tanto quanto. Uma solicitação negada mostra que um agente tentou acessar um escopo que não possuía. Uma rejeição por escrita desatualizada mostra que o sistema impediu uma sobrescrita. Os dois registros explicam por que o estado do provedor não mudou quando alguém esperava que mudasse. Teste também a canonização. Duas regras de direcionamento em JSON podem significar a mesma coisa mesmo com os campos em ordem diferente. Se seu código de comparação e definição comparar JSON bruto, produzirá conflitos falsos. Se normalizar de forma agressiva demais, poderá não perceber uma diferença semântica. Escolha uma representação canônica para o modelo do provedor, registre-a e teste-a com campos reordenados, valores padrão omitidos e referências equivalentes a segmentos. Por fim, teste o caminho em que o provedor retorna sucesso, mas a leitura posterior falha. Registre `execution=accepted` e `observed=unknown`; não classifique a solicitação inteira como bem-sucedida. Alguém precisa verificar o estado do provedor antes que o agente faça uma alteração dependente. ## Um rastro de auditoria precisa sobreviver a um incidente contestado Um registro útil de feature flag precisa responder a uma pergunta cética: «Como sabemos que essa versão da alteração não foi editada depois do fato?» Logs comuns de aplicação muitas vezes bastam para depuração, mas raramente respondem a essa pergunta quando muitas pessoas têm acesso ao sistema de logs. Escreva eventos de ação somente para inclusão, com número de sequência, horário, envelope da solicitação, resultado da autorização, resultado da execução e estado observado. Relacione eventos ligados por IDs de solicitação e IDs de solicitações pai. O encadeamento por hash torna alterações posteriores visíveis: cada evento inclui um resumo do próprio conteúdo e o resumo do evento anterior. A verificação percorre a cadeia na ordem. O encadeamento por hash não torna um log verdadeiro. Ele não prova que a pessoa que aprovou uma solicitação a entendeu, nem recupera registros que nunca foram escritos. Ele torna detectáveis a exclusão ou alteração posterior quando você preserva a cadeia e a verifica de forma independente. Essa é a afirmação correta e já é mais útil do que chamar um log de «imutável» sem explicar o mecanismo. Mantenha o histórico nativo do provedor de flags como evidência complementar, não como o único registro. Associe os IDs de solicitação do provedor quando ele os disponibilizar. Associe o `correlation_id` da ação a um registro de incidente ou a uma alteração de implantação. Quando alguém perguntar por que uma flag mudou, você deve conseguir rastrear a decisão sem reconstruí-la a partir de mensagens de chat e da memória das pessoas. O Sallyport projeta registros de sessão e de chamadas individuais a partir de um log de auditoria criptografado e encadeado por hash, e `sp audit verify` verifica a cadeia offline sem uma chave do cofre. Isso dá à equipe uma forma de verificar se o registro das ações de controle continua internamente consistente mesmo quando o cofre permanece bloqueado. Revise ações negadas e conflitos de escrita desatualizada como parte do trabalho operacional normal. Eles não são ruído. Um número crescente de conflitos pode mostrar que várias automações controlam as mesmas flags. Repetidas solicitações negadas para determinados alvos podem indicar que o escopo da tarefa do agente é amplo demais ou foi mal especificado. ## Faça o agente produzir primeiro uma proposta de alteração O padrão operacional mais seguro é simples: deixe o agente inspecionar, diagnosticar e redigir a alteração. Depois, exija que um caminho de escrita controlado a execute. A proposta deve ser detalhada o suficiente para que outra pessoa engenheira possa aprová-la sem ler toda a transcrição do agente. Para cada solicitação em produção, exija que o agente informe o estado atual observado, o estado exato desejado, a revisão esperada, por que a alteração ajuda, o que pode ser afetado e a condição de reversão. Se não conseguir fornecer esses fatos, ainda não conquistou permissão para escrever. Não exija um texto longo. Exija uma solicitação completa. A diferença importa. Textos extensos muitas vezes escondem que o agente nunca verificou o ambiente de destino ou nunca buscou a regra atual. Um envelope estruturado mostra a omissão imediatamente. As equipes que adotam essa disciplina descobrem que muitas alterações propostas não precisam ser executadas. O agente pode descobrir que a flag já tem o valor desejado, que o grupo com falha não corresponde à regra ou que uma reversão da implantação é a solução real. Ler primeiro e registrar o estado esperado impede que o agente faça uma alteração meramente formal para cumprir uma tarefa. Uma feature flag é um controle rápido sobre o comportamento ativo. Dê a um agente de IA a capacidade de usar esse controle somente quando o sistema registrar sua solicitação, vincular uma decisão humana à alteração exata, impedir sobrescritas desatualizadas e verificar o que o provedor armazenou. Qualquer coisa menos que isso deixa seu interruptor de produção mais conveniente ligado a uma conta que ninguém consegue explicar por completo.