Rollback automatizado para efeitos colaterais de agentes

O rollback de um agente pode restaurar código, configuração ou dados selecionados do aplicativo. Ele não consegue fazer outra organização esquecer uma solicitação, retirar um e-mail entregue de uma caixa de entrada nem fingir que uma cobrança no cartão nunca chegou à processadora de pagamentos. Equipes que chamam todas essas operações de «rollback» criam um controle reconfortante que falha justamente quando as consequências importam.

Um projeto seguro separa quatro mecanismos: snapshots do aplicativo, reverts no Git, recuperação de banco de dados e ações compensatórias. Cada um tem um limite próprio. Toda ação que ultrapassa o limite do aplicativo precisa ter sua própria aprovação, evidência, regra de nova tentativa e caminho de recuperação antes de o agente executá-la. Se ninguém consegue descrever esse caminho em uma frase, a ação ainda não está pronta para execução sem supervisão.

Rollback tem quatro significados diferentes

O rollback só ajuda quando a equipe nomeia o estado que vai restaurar e o estado que não consegue tocar. A palavra costuma esconder quatro mecanismos com garantias muito diferentes.

Um snapshot restaura uma versão capturada de um aplicativo ou espaço de trabalho. Dependendo do produto, esse snapshot pode incluir código gerado, configuração e parte do estado gerenciado. Ele não diz nada sobre serviços externos, a menos que o contrato do snapshot os inclua explicitamente.

Um Git revert registra um novo commit cujas alterações invertem um commit anterior. Ele corrige o histórico do código-fonte sem apagar esse histórico. Não entra em contato com os serviços que o código antigo chamou enquanto estava em execução.

A recuperação de banco de dados altera registros mantidos pelo banco. O rollback de uma transação descarta gravações ainda não confirmadas dentro de uma transação. Restaurar um backup ou usar recuperação para um ponto no tempo é uma operação muito maior, que move um cluster de banco de dados para mais perto de um estado anterior. Nenhuma dessas operações reconcilia automaticamente sistemas fora desse banco de dados.

Uma ação compensatória cria um novo efeito para compensar um efeito antigo. Um reembolso compensa um pagamento capturado. Um pedido de cancelamento compensa um pedido. Um e-mail de correção pode reduzir o impacto de um e-mail errado, embora não consiga remover a primeira mensagem. A compensação preserva a verdade incômoda de que a ação original aconteceu.

Em revisões de projeto, uso uma tabela de responsabilidade pelos efeitos porque ela obriga respostas precisas:

A última coluna é a mais importante. Uma operação inversa não prova que a original desapareceu. Registros de auditoria, cópias dos destinatários, lançamentos de liquidação, webhooks e trabalho físico podem permanecer.

Um revert de código muda o programa, não o passado

Um revert de código impede ou muda o comportamento futuro. Ele não reverte o comportamento que a versão antiga já provocou. Isso continua valendo quando a equipe usa Git, um snapshot da plataforma ou rollback de deploy.

A documentação do Git descreve git revert como o registro de commits que revertem alterações introduzidas por commits anteriores. A formulação é exata: o Git aplica um patch inverso ao conteúdo do repositório. O Git não sabe nada sobre e-mails, pagamentos, recursos de nuvem, tickets de suporte ou APIs de parceiros criados quando o commit revertido foi executado.

Suponha que um agente modifique uma função de cobrança, faça o deploy e a invoque duas vezes antes de o monitoramento detectar o defeito. Reverter o commit pode impedir que a função incorreta rode novamente. As duas tentativas de pagamento permanecem na processadora. Se o banco de dados local registrou apenas uma tentativa, o revert pode até dificultar a investigação ao remover o caminho de código que entendia a segunda resposta.

O rollback de deploy tem o mesmo limite. Direcionar o tráfego de volta para uma compilação anterior restaura o comportamento executável. Solicitações já aceitas pela compilação substituída mantêm suas consequências. Trabalhos na fila também podem sobreviver ao deploy e executar suposições antigas contra a versão restaurada.

Antes de reverter, preserve as evidências operacionais produzidas pela compilação antiga:

• Identificador do deploy e commit de origem
• Identificadores da execução e da intenção do agente
• Identificadores das mensagens da fila e status do lease
• Identificadores de solicitações externas
• Respostas do provedor e horários

Depois interrompa novas execuções, reconcilie operações incompletas e restaure o código. Reverter primeiro e fazer perguntas depois costuma destruir o caminho mais fácil para entender quais efeitos escaparam.

Um snapshot pode ser mais abrangente que um commit do Git, mas a mesma regra vale. O contrato do snapshot deve informar exatamente quais recursos ele contém. Se ele contém código e configuração, chame-o de mecanismo de recuperação de código e configuração. Não o transforme em um desfazer universal com uma formulação otimista na interface.

A recuperação de banco de dados tem um papel mais limitado do que parece

A recuperação de banco de dados restaura o estado do banco, não a realidade do negócio entre todos os participantes de uma transação. Uma transação pode ser atômica dentro de um banco de dados enquanto a operação ao redor continua dividida entre vários sistemas.

Considere esta sequência:

1. O agente insere uma linha de fatura.
2. Ele chama uma API de pagamento.
3. A processadora aceita a cobrança.
4. O commit no banco de dados falha.

O rollback local remove a linha da fatura. A cobrança continua existindo. Repetir toda a operação sem reconciliação pode cobrar o cliente outra vez. Essa é a falha clássica de escrita dupla: o aplicativo tentou tornar uma ação de negócio atômica entre sistemas que não compartilham um coordenador de transações.

Inverter a ordem não resolve. Se o aplicativo confirma primeiro a fatura e depois a chamada de pagamento falha, o banco contém uma fatura não paga. Esse estado é mais fácil de inspecionar, mas o aplicativo ainda precisa de uma máquina de estados que diferencie payment_pending, payment_confirmed, payment_failed e payment_unknown.

A documentação do PostgreSQL explica a recuperação para um ponto no tempo como a restauração de um backup base e a reprodução de registros de write ahead log até um alvo de recuperação escolhido. Esse é um procedimento de operador para recuperar um cluster de banco de dados. Não é um desfazer seletivo para uma execução de agente e não consegue pedir a uma processadora de pagamentos ou serviço de e-mail que volte ao mesmo horário.

Mover o banco de dados para trás pode criar uma segunda divergência. Imagine uma restauração para as 10:00 após uma indisponibilidade. Um provedor aceitou solicitações até as 10:07, mas o banco restaurado não contém mais seus registros. Agentes que enxergam linhas «ausentes» podem recriar os sete minutos inteiros de trabalho. Por isso, a recuperação precisa de uma etapa de reconciliação externa antes de os workers voltarem a funcionar.

O padrão outbox reduz uma lacuna perigosa. O aplicativo confirma a alteração de negócio e uma intenção de efeito na mesma transação local:

BEGIN;

INSERT INTO invoices (invoice_id, customer_id, status)
VALUES ('inv_2048', 'cust_91', 'payment_pending');

INSERT INTO effect_intents
  (intent_id, operation, subject_id, status)
VALUES
  ('eff_7f31', 'capture_payment', 'inv_2048', 'pending');

COMMIT;

Depois, um worker assume eff_7f31, chama o provedor com um valor estável de idempotência e registra o resultado. A outbox não torna a chamada externa atômica. Ela dá ao sistema uma evidência durável de que o trabalho foi pretendido, o que torna possíveis novas tentativas e a reconciliação.

Ações externas precisam de compensações, e algumas não têm nenhuma

Um efeito colateral externo precisa de uma compensação específica do provedor ou de uma declaração explícita de que não existe compensação significativa. Tratar toda ação como reversível é pior do que admitir que algumas exigem aprovação.

O e-mail é o exemplo mais simples. Antes de o provedor aceitar a mensagem, o aplicativo pode cancelar um trabalho na fila. Após a aceitação, o provedor talvez permita cancelamento por um breve estágio interno, mas não existe garantia geral de recall entre destinatários e sistemas de e-mail. Depois de entregue, uma segunda mensagem pode corrigir o registro, mas não apagar a primeira. Dados sensíveis, avisos jurídicos e danos à reputação continuam expostos.

Pagamentos têm vários estados que as equipes costumam resumir como «cobrado». Uma autorização reserva capacidade de gasto. Uma captura pede a movimentação de fundos vinculados a essa autorização. Uma anulação pode liberar uma autorização que ainda não foi liquidada. Um reembolso cria um lançamento financeiro posterior que devolve dinheiro após a captura. Essas operações têm prazos, tarifas, permissões e impacto no cliente diferentes. Uma ferramenta genérica chamada undo_payment esconde informações de que o agente precisa para agir com segurança.

Outras APIs colaboram ainda menos. Uma solicitação pode pedir estoque, provisionar infraestrutura, publicar conteúdo, conceder acesso, enviar um pacote ou levar uma pessoa a começar um trabalho. Um endpoint DELETE não prova reversibilidade. Excluir um recurso pode deixar logs de auditoria, dados copiados, notificações, recursos dependentes ou consequências físicas.

Classifique a compensação pelo que ela consegue realizar com honestidade:

• Um inverso local exato devolve o estado controlado ao valor anterior.
• O cancelamento pelo provedor interrompe trabalho que ainda não foi concluído.
• A compensação financeira cria um reembolso ou crédito.
• A comunicação corretiva reconhece que a primeira mensagem continua visível.
• A correção manual lida com efeitos cujo contexto não cabe em uma regra automatizada segura.

A compensação também pode falhar. O endpoint de reembolso pode atingir timeout. A janela de cancelamento pode fechar. O endereço do destinatário pode rejeitar a correção. A conta usada pelo agente pode não ter permissão. Por isso, o sistema precisa rastrear a compensação como outra operação, com identificador de intenção, status, tentativas, evidências e política de aprovação próprios.

Não crie um recurso recursivo de «rollback do rollback». Modele o histórico como um livro-razão de ações. Se uma compensação causar um novo erro, emita outra ação explícita depois de revisar o estado atual. O histórico fica mais longo, mas continua compreensível durante um incidente.

A idempotência evita repetições, mas não reverte um sucesso

A idempotência protege as novas tentativas contra efeitos pretendidos duplicados. Ela não desfaz o primeiro efeito bem-sucedido. As equipes confundem essas ideias com frequência e descobrem a diferença depois de um timeout.

A RFC 9110 define um método de solicitação idempotente pelo efeito pretendido de várias solicitações idênticas ser o mesmo de uma só solicitação. Ela identifica PUT, DELETE e métodos seguros como idempotentes no nível da semântica do protocolo. POST não costuma ser idempotente, embora uma API possa adicionar esse comportamento por seu próprio contrato.

A ressalva importa. Um DELETE idempotente ainda pode produzir um novo registro de log, métrica ou resposta a cada chamada. A implementação de idempotência de um provedor também pode expirar registros, limitar identificadores a uma conta, rejeitar parâmetros alterados ou armazenar em cache somente resultados selecionados. Leia o contrato do provedor em vez de inferir garantias pelo verbo HTTP.

Toda intenção de efeito deve receber um valor estável de idempotência antes da primeira tentativa. As novas tentativas para essa mesma intenção reutilizam esse valor. Uma nova intenção de negócio recebe um valor novo. Nunca o derive apenas de parâmetros mutáveis, como cliente, valor e data, porque duas compras legítimas podem compartilhar esses valores.

Um timeout cria um resultado desconhecido, não uma falha. Use esta sequência:

1. Marque a tentativa como outcome_unknown. Não crie uma intenção substituta.
2. Consulte o provedor pelo valor de idempotência ou referência da operação.
3. Se o provedor confirmar o sucesso, registre esse sucesso localmente.
4. Se ele confirmar que não houve operação, tente de novo com o mesmo valor.
5. Se ele não conseguir responder, mantenha a operação para reconciliação ou revisão humana.

Este formato de resposta dá ao agente informações suficientes para distinguir aceitação de incerteza no transporte:

{
  "intent_id": "eff_7f31",
  "attempt": 2,
  "idempotency_key": "eff_7f31",
  "transport_status": "timeout",
  "provider_status": "unknown",
  "provider_reference": null,
  "next_action": "reconcile"
}

Um valor de idempotência deve aparecer em logs, mensagens da fila, cabeçalhos de API e metadados do provedor, quando houver suporte. Se os operadores não conseguem pesquisá-lo nos dois lados do limite, eles vão adivinhar durante a recuperação.

A aprovação deve ficar no limite do efeito

A aprovação deve ocorrer depois que o agente formou a ação externa exata e antes que a primeira solicitação irreversível saia do sistema. Uma aprovação no início de uma tarefa ampla dá ao agente liberdade demais para mudar depois destinatários, valores, escopos ou ferramentas.

«Cuide da conta deste cliente» não é aprovação suficiente para cobrar um cartão ou enviar e-mail a todos os usuários. Uma aprovação válida descreve a operação concreta: destinatário, valor e moeda, resumo da mensagem ou do payload, conta de destino, ferramenta, validade e número de tentativas permitidas. Se algum campo aprovado mudar, a aprovação deixa de corresponder.

Uma política útil organiza os efeitos pela consequência, não pelo agente ou modelo que os solicitou. O acesso de leitura ainda pode expor dados privados, mas não cria o mesmo problema de recuperação de uma ação de saída. Redigir um e-mail é local e reversível. Enviá-lo cruza o limite. Criar uma proposta de pagamento é local. Capturar fundos cruza o limite.

Exija aprovação explícita para ações que:

• Movam dinheiro ou criem uma obrigação financeira
• Enviem informações a uma pessoa ou organização externa
• Publiquem, excluam ou revelem dados fora do armazenamento controlado
• Alterem identidade, acesso, propriedade ou configurações de segurança
• Iniciem trabalho físico ou outro processo que não possa ser recolhido de forma confiável

Ações repetitivas de baixa consequência podem usar uma aprovação contínua limitada. O limite deve informar valor máximo, conjunto de destinatários, ferramenta permitida, prazo de validade, frequência e total de operações. «Aprovado para cobrança» não tem um limite que possa ser aplicado.

A aprovação também precisa de proteção contra repetição. Vincule-a a um resumo imutável da operação e marque-a como consumida quando a política permitir apenas uma execução. Se a execução retornar resultado desconhecido, não peça uma nova aprovação para criar uma segunda intenção. Primeiro reconcilie a intenção aprovada.

A tela de aprovação deve explicar a verdade sobre a recuperação em linguagem comum. «Esta mensagem não pode ser recolhida depois da entrega» é útil. «Esta operação é reversível» engana quando a recuperação real é um reembolso que pode levar tempo e continuar aparecendo em extratos financeiros.

Os contratos das ferramentas devem mostrar todo o ciclo de vida do efeito

O contrato de uma ferramenta de agente deve descrever intenção, execução, observação e compensação como operações separadas. Uma única função que produz um efeito e retorna success: true deixa poucas evidências para novas tentativas, aprovações ou resposta a incidentes.

Este fragmento de política é pequeno o bastante para aplicar e específico o bastante para revisar:

tools:
  send_email:
    effect: irreversible
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_message_id
    compensation: null

  capture_payment:
    effect: compensatable
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_payment_id
    compensation: refund_payment

  update_draft:
    effect: local_reversible
    approval: none
    compensation: restore_version

effect informa ao planejador qual classe de recuperação se aplica. approval bloqueia a execução até que os argumentos exatos sejam autorizados. O campo de idempotência faz as novas tentativas reutilizarem uma identidade. O campo de evidência informa aos operadores o que precisa sobreviver. O campo de compensação aponta para uma ferramenta separada, em vez de fingir que a chamada original pode ser executada ao contrário.

A execução deve aceitar um envelope imutável:

{
  "intent_id": "eff_7f31",
  "operation": "capture_payment",
  "arguments": {
    "invoice_id": "inv_2048",
    "amount_minor": 12900,
    "currency": "USD"
  },
  "approval": {
    "approval_id": "apr_662",
    "scope_hash": "sha256:8b4f...",
    "expires_at": "2026-07-27T18:00:00Z"
  }
}

O executor calcula o resumo da operação, compara-o com scope_hash, verifica a validade, reserva a intenção e só então entra em contato com o provedor. Ele armazena os metadados da solicitação antes da chamada e a resposta depois. Se falhar entre essas gravações, a intenção durável continua disponível para reconciliação.

O executor deve rejeitar quatro condições sem improvisar: argumentos alterados, aprovação expirada, reutilização de uma intenção para outra operação e tentativa de compensar um efeito cuja conclusão bem-sucedida ainda não foi confirmada. Agentes são bons em encontrar continuações plausíveis. Controles financeiros e de comunicação devem preferir uma parada visível a um palpite plausível.

Dê à observação sua própria ferramenta, como get_payment_status(intent_id). A observação não deve criar um efeito. Mantê-la separada permite que o agente resolva resultados ambíguos sem receber permissão para repetir a ação original.

Uma execução com falha pode atravessar todos os limites de recuperação

Uma única execução de agente pode deixar código, registros no banco de dados e sistemas externos em momentos diferentes. Percorrer essa falha antes do lançamento revela lacunas que um controle genérico de rollback esconde.

Imagine que um agente crie um aplicativo de associação, faça o deploy de uma alteração, importe uma lista de clientes, cobre taxas anuais e envie e-mails de boas-vindas. A tarefa parece unificada, mas atravessa pelo menos quatro limites de recuperação.

Às 14:00, o agente implanta código que calcula a taxa anual a partir da coluna errada. Às 14:02, ele grava no banco de dados 40 intenções de pagamento e rascunhos de e-mail. Às 14:03, um worker captura vários pagamentos. Às 14:04, o provedor de e-mail aceita mensagens de boas-vindas com a taxa incorreta. Às 14:05, o monitoramento interrompe o worker. Algumas chamadas de pagamento atingiram timeout depois de chegar à processadora, então o status local não revela se foram bem-sucedidas.

Restaurar o snapshot de código das 13:59 interrompe o cálculo incorreto em execuções futuras. Isso não altera a taxa copiada nas intenções já existentes. Reverter o commit do Git documenta a correção no código-fonte, mas tem o mesmo limite.

Restaurar o banco de dados para as 13:59 removeria os registros locais de intenção que contêm referências do provedor e valores de idempotência. Isso piora a divergência externa. A melhor ação no banco é uma correção lógica: preservar as intenções, marcar operações incertas para reconciliação e corrigir linhas somente depois de conferir o estado no provedor.

A equipe de resposta deve então seguir pela classe de efeito. Ela consulta cada pagamento incerto usando sua identidade estável de operação. Capturas confirmadas seguem para revisão de reembolso, tentativas com falha encerram sem nova tentativa e tentativas sem solução permanecem bloqueadas. E-mails entregues recebem uma correção cuidadosamente aprovada. Mensagens na fila que ainda não chegaram ao provedor são canceladas. Cada compensação recebe uma nova intenção vinculada à original.

Esse exemplo também mostra por que a compensação automática pode ser perigosa. Se o sistema reembolsar imediatamente cada registro local payment_unknown, poderá emitir reembolsos para cobranças que nunca existiram ou chamar um endpoint de reembolso com a referência errada. Se reenviar todos os e-mails ausentes depois da recuperação do banco, os destinatários poderão receber duplicatas. A reconciliação deve vir antes da compensação sempre que o estado local e o do provedor divergirem.

A execução só termina quando toda intenção chega a um estado final, como succeeded, confirmed_failed, compensated ou manual_exception. «O aplicativo passou por rollback» descreve apenas a primeira parte do incidente.

A recuperação só funciona quando a evidência sobrevive

Os controles de recuperação falham quando o rollback exclui os registros necessários para decidir o que aconteceu. Mantenha um livro-razão de efeitos somente para acréscimo, fora do estado do aplicativo que snapshots ou restaurações de rotina podem substituir, e retenha evidência suficiente do provedor para reconciliar cada operação.

O livro-razão deve registrar a criação da intenção, o resumo dos argumentos, a aprovação, o lease de execução, a tentativa, o resultado de transporte, a referência do provedor, o estado observado no provedor e os vínculos de compensação. Restrinja mudanças a transições de estado, em vez de permitir que agentes sobrescrevam entradas antigas. As correções devem acrescentar eventos, não editar o histórico.

Monitore estados sem solução, não apenas erros explícitos. Um outcome_unknown parado por dez minutos pode ser mais perigoso que uma rejeição clara, porque alguém pode repeti-lo manualmente. Gere alertas também quando uma aprovação expirar durante a execução, um valor de idempotência aparecer com outro resumo de argumentos ou uma compensação falhar.

Faça exercícios de recuperação com pontos de falha deliberadamente incômodos. Encerre um worker depois que o provedor aceitar uma solicitação, mas antes da gravação local de sucesso. Restaure os dados do aplicativo de um snapshot anterior preservando o livro-razão de efeitos. Deixe a aprovação expirar entre o planejamento e a execução. Indisponibilize a API de observação. O exercício passa quando o sistema para, reconcilia e mostra a decisão pendente sem duplicar o efeito.

Ao usar Koder.ai, trate seus snapshots e rollback como a camada de recuperação do aplicativo. Depois, projete controles separados para o histórico do banco de dados e para cada ação externa que o aplicativo pode disparar. A exportação do código-fonte, os controles de deploy e o rollback ajudam a restaurar o software, enquanto os contratos das ferramentas do aplicativo continuam responsáveis por aprovações e compensação.

Um botão de rollback deve informar seu limite ao lado do botão: código, configuração, dados gerenciados ou efeitos externos. Se a interface não consegue tornar essa frase precisa, ela não deve prometer rollback. O controle honesto pode parecer menos mágico, mas dá à equipe de incidentes o que ela precisa às 2 da manhã: um relato confiável do que mudou, do que escapou e da próxima ação segura.