Idempotência em agentes de IA: como evitar duplicidade

Uma falha pode produzir dois sucessos

Um agente prepara uma cobrança, envia a solicitação ao sistema financeiro e espera a resposta. A conexão expira. O agente não sabe se a cobrança foi criada. Ao tentar novamente, cria outra.

A mesma situação aparece em mensagens, pedidos, tarefas de CRM, documentos, etiquetas de envio, chamados e atualizações cadastrais. A primeira chamada pode ter funcionado, enquanto apenas a confirmação se perdeu.

Idempotência é a propriedade que permite repetir uma operação sem produzir um novo efeito quando aquele efeito já foi concluído. Em agentes de IA, ela protege a passagem entre uma decisão probabilística e uma ação concreta no sistema da empresa.

O controle precisa existir no fluxo, na integração e no sistema de destino. Uma frase no prompt pedindo para o agente "não repetir" não resolve concorrência, entrega duplicada de eventos nem falha de rede.

Onde a duplicidade entra no processo

Duplicidade raramente nasce de uma pessoa clicando duas vezes de propósito. Ela costuma surgir em mecanismos criados para dar continuidade ao trabalho.

Webhook entregue novamente

Plataformas podem reenviar um evento quando não recebem confirmação dentro do prazo. O mesmo pagamento, formulário ou pedido chega duas vezes com poucos segundos de diferença.

Retentativa depois de timeout

A aplicação enviou uma ação, mas perdeu a resposta. O estado externo ficou incerto. Repetir sem consultar o destino pode duplicar o efeito.

Dois consumidores pegam o mesmo trabalho

Uma fila libera a mesma unidade para mais de um worker após atraso, reinício ou perda do bloqueio. As duas execuções avançam em paralelo.

Pessoa e agente atuam no mesmo caso

Enquanto o agente está pausado, alguém resolve o caso manualmente. Quando a automação volta, usa o estado antigo e repete a ação.

Tarefa longa retorna a um checkpoint

O processo reinicia depois de uma interrupção. Se o checkpoint não registra a confirmação externa, o agente volta para a etapa de escrita.

Evento muda de formato durante o caminho

Integrações diferentes representam o mesmo fato com identificadores distintos. O sistema trata cada versão como um novo trabalho.

O guia sobre agentes de IA para tarefas longas cobre estado, checkpoints e retomada do fluxo completo. Aqui, a decisão é mais estreita: como garantir que cada ação de negócio produza um único efeito verificável, mesmo quando a execução se repete.

Defina a unidade que não pode ser repetida

Antes de criar uma chave, descreva o efeito protegido. "Não duplicar o lead" é vago. O mesmo lead pode receber várias tarefas legítimas ao longo da relação.

Exemplos de unidades melhores:

criar a tarefa de follow-up referente à reunião R-184;
enviar o lembrete de vencimento da parcela P-09;
emitir a cobrança da competência 2026-07 para o contrato C-412;
abrir uma solicitação de troca para o item I-73 do pedido O-882;
publicar a versão 7 do relatório do cliente ACME;
registrar a confirmação do pagamento PAY-551 no ERP.

A unidade deve combinar o objeto de negócio, o tipo de ação e a versão relevante. Se faltar um desses elementos, duas ações diferentes podem colidir. Se a chave incluir horário aleatório ou identificador gerado a cada tentativa, duas execuções do mesmo efeito parecerão diferentes.

Construa uma chave de idempotência estável

Uma chave comum pode seguir esta composição:

processo + objeto + ação + versão

Para uma tarefa comercial:

followup + oportunidade_2481 + criar_tarefa_pos_reuniao + reuniao_184

Para uma cobrança:

cobranca + contrato_412 + emitir_parcela + 2026_07

A composição exata depende do processo. Ela precisa atender quatro condições:

permanecer igual em todas as tentativas do mesmo efeito;
mudar quando a ação de negócio realmente muda;
ser derivada de identificadores confiáveis;
poder ser encontrada por sistemas e pessoas durante a investigação.

Não use o texto gerado pelo modelo como chave. Duas redações diferentes podem representar a mesma ação, e duas redações iguais podem pertencer a clientes distintos.

Mantenha um registro de processamento

A chave precisa apontar para um estado persistente. Esse registro funciona como um livro de execução das ações externas.

Campos úteis incluem:

chave de idempotência;
unidade de trabalho;
ação solicitada;
versão do fluxo;
status;
data de início;
executor;
tentativas;
identificador devolvido pelo destino;
confirmação recebida;
resposta técnica resumida;
último erro;
próxima ação;
prazo de retenção.

Os estados podem começar simples:

reservado;
em_execucao;
confirmado;
resultado_incerto;
falhou_sem_efeito;
cancelado;
exige_reconciliacao.

Falhou sozinho esconde a pergunta mais importante. A falha ocorreu antes ou depois do efeito externo? Quando a resposta for desconhecida, o fluxo precisa consultar o destino ou encaminhar reconciliação. Não deve repetir por reflexo.

Reserve antes de executar

Uma verificação seguida de escrita pode falhar sob concorrência:

execução A consulta a chave e não encontra;
execução B consulta a mesma chave e não encontra;
as duas criam o efeito;
as duas registram sucesso.

A reserva precisa ser atômica. O sistema tenta criar a chave com restrição de unicidade. Apenas uma execução obtém o direito de prosseguir. A outra lê o estado existente e decide se aguarda, reutiliza o resultado ou encaminha análise.

Esse controle pode usar uma restrição única no banco, uma operação de comparação e troca, um lock com prazo ou o mecanismo nativo da fila. A escolha técnica varia. A regra operacional permanece: consultar e reservar fazem parte da mesma decisão.

Locks também falham. Uma execução pode morrer depois de reservar. Por isso, registre prazo, heartbeat quando necessário e regra de recuperação. Liberar a reserva por tempo sem verificar o sistema externo pode reabrir a duplicidade.

Use o suporte do sistema de destino

Algumas APIs aceitam uma chave de idempotência. Quando disponível, envie a mesma chave em todas as tentativas. O destino consegue devolver o primeiro resultado em vez de criar outro objeto.

Quando a API não oferece esse recurso, procure alternativas:

identificador externo único no registro;
campo de referência pesquisável;
operação de upsert;
restrição de unicidade;
consulta por objeto e ação antes da escrita;
endpoint para consultar o status de uma solicitação;
protocolo ou recibo retornado depois da execução.

A proteção local continua necessária. Ela organiza concorrência, evidência e retomada do agente. A proteção no destino cobre o intervalo em que a ação já saiu da aplicação.

Separe decisão, comando e confirmação

Um agente pode decidir que uma mensagem deve ser enviada. Essa decisão ainda não prova o envio.

Trate cada etapa como um evento distinto:

decisão preparada;
comando autorizado;
ação enviada;
destino confirmou o efeito;
sistema oficial registrou o resultado;
unidade avançou para o próximo estado.

Essa separação impede que uma resposta técnica genérica seja registrada como conclusão. Também facilita retomar o processo no ponto correto.

O artigo sobre fonte da verdade para agentes de IA ajuda a definir qual sistema confirma cada objeto e como tratar divergências entre memória, automação e registro oficial.

Trate respostas incertas sem improviso

Há três cenários básicos depois de uma tentativa.

Sucesso confirmado

O destino devolveu um identificador válido e a consulta posterior encontra o efeito esperado. Registre a confirmação e reutilize esse resultado em novas entregas do mesmo evento.

Falha confirmada antes do efeito

A validação rejeitou a entrada, a permissão foi negada ou a conexão falhou antes do envio. Uma nova tentativa pode ser permitida depois da correção, respeitando o teto definido.

Resultado incerto

A conexão caiu durante ou depois da chamada. Consulte o destino por referência, espere a janela de consistência ou envie o caso para reconciliação. Nova tentativa automática fica bloqueada até o estado ser esclarecido.

A pior resposta é transformar toda incerteza em repetição. Isso converte uma falha transitória em problema para cliente, financeiro ou operação.

Combine idempotência com controle de concorrência

Idempotência impede repetir o mesmo efeito. Controle de concorrência impede gravar uma ação válida sobre um estado que mudou.

Considere uma oportunidade no CRM. O agente leu o estágio proposta_enviada e preparou uma tarefa de cobrança de retorno. Enquanto isso, o vendedor marcou a oportunidade como fechado_perdido. A chave inédita não resolve o conflito. Antes de escrever, o fluxo precisa comparar a versão ou o estado atual.

Use mecanismos como:

versão do registro;
timestamp da última alteração;
etag;
transação;
pré-condição de atualização;
releitura antes do compromisso;
bloqueio por caso em etapas sensíveis.

Se o estado mudou, interrompa a ação e reavalie. Uma ação executada uma única vez ainda pode estar errada.

Defina retenção e reaproveitamento da chave

Guardar chaves para sempre aumenta custo e pode bloquear ações futuras legítimas. Apagar cedo demais permite que um evento atrasado repita o efeito.

A retenção deve considerar:

prazo máximo de reentrega do evento;
janela de retentativas da integração;
tempo de processamento e aprovação;
possibilidade de contingência manual;
obrigação de auditoria;
ciclo de vida do objeto de negócio;
prazo para reversão ou disputa.

Uma chave de lembrete diário pode ter vida curta. Uma chave ligada a pagamento, pedido ou contrato pode exigir retenção muito maior. Registre a política por tipo de ação.

Reconcilição fecha a lacuna entre sistemas

Mesmo com bons controles, haverá casos incertos. Reconciliação compara o registro local com o sistema que possui autoridade sobre o efeito.

Uma rotina de reconciliação deve:

selecionar ações em estado incerto ou antigas demais;
consultar o destino por referência estável;
comparar objeto, valor, versão e status;
confirmar o efeito já realizado;
marcar falha sem efeito quando houver evidência;
bloquear conflitos;
encaminhar exceções com contexto suficiente;
atualizar a unidade de trabalho.

Na volta de uma contingência, inclua também ações manuais. O plano de contingência para agentes de IA detalha como retomar filas sem repetir o que a equipe resolveu enquanto o agente estava suspenso.

O prompt participa, mas não governa a garantia

O modelo deve receber contexto claro sobre o estado da ação. Ele pode ajudar a classificar uma exceção ou preparar a próxima decisão. A garantia de unicidade precisa ficar em componentes determinísticos.

O agente não deveria:

inventar uma nova chave quando a anterior existe;
decidir sozinho que um resultado incerto equivale a falha;
ignorar confirmação do destino;
remover uma reserva para prosseguir;
escolher outro canal para contornar bloqueio;
considerar texto persuasivo como prova de entrega.

A instrução descreve o comportamento esperado. Banco, fila, integração e sistema oficial aplicam a regra.

Teste os caminhos que costumam duplicar efeitos

Inclua casos de falha e concorrência no ambiente de teste:

o mesmo webhook chega duas vezes;
duas execuções começam ao mesmo tempo;
a resposta se perde depois do sucesso;
o destino demora a tornar o registro consultável;
o worker reinicia depois da chamada;
o lock expira durante o processamento;
a pessoa conclui o caso manualmente;
o evento chega fora de ordem;
uma versão nova recebe uma chave antiga;
o sistema de destino devolve sucesso sem identificador;
a reconciliação encontra dois efeitos;
a reversão falha.

O guia sobre ambiente de teste para agentes de IA mostra como simular integrações, falhas e destinos controlados antes da produção.

Para cada cenário, verifique o estado local, a quantidade de efeitos no destino, a evidência preservada e a ação entregue ao responsável.

Métricas que revelam o problema

Acompanhe:

eventos repetidos recebidos;
execuções bloqueadas por chave existente;
ações confirmadas e reutilizadas;
resultados incertos;
tempo até reconciliação;
duplicidades que chegaram ao sistema oficial;
conflitos de concorrência;
intervenções manuais durante a execução;
chaves expiradas com reentrega posterior;
custo e retrabalho por duplicidade;
incidentes por tipo de integração.

Bloquear muitas repetições pode indicar que a proteção funciona. Também pode revelar uma origem enviando eventos demais. A métrica precisa levar a uma correção no componente certo.

Checklist de implementação

Antes de liberar uma ação externa, confirme:

O efeito de negócio protegido está definido?
A chave combina objeto, ação e versão?
A mesma tentativa sempre reutiliza a mesma chave?
A reserva é atômica?
Existe estado para resultado incerto?
O destino aceita chave, referência externa ou consulta posterior?
A confirmação externa fica registrada?
Retentativas distinguem falha sem efeito de efeito desconhecido?
Concorrência verifica se o objeto mudou?
Chaves possuem retenção compatível com o processo?
A reconciliação considera ações manuais?
Testes cobrem reentrega, timeout e reinício?
O dono operacional recebe exceções com evidência?
Métricas mostram duplicidade evitada e duplicidade real?

Repetir trabalho deve ser seguro

Retentativas, filas e retomadas dão resiliência a um agente. Sem idempotência, os mesmos mecanismos ampliam o impacto de falhas pequenas.

Uma implementação segura define a unidade do efeito, deriva uma chave estável, reserva a execução, usa a proteção do destino, registra confirmação e reconcilia estados incertos. O agente pode então repetir processamento quando necessário sem repetir a consequência para a empresa ou para o cliente.