Chamadas idempotentes em agentes de IA: repetir sem duplicar trabalho
Veja como fazer uma nova tentativa nunca gerar outra cobrança, reserva ou mensagem. Cobre chaves, checagem de estado e resultados incertos.

Uma chamada de ferramenta idempotente produz o mesmo efeito não importa quantas vezes seja executada com a mesma intenção. Em agentes de IA, isso significa que uma nova tentativa após um timeout, um fluxo reiniciado ou uma instrução repetida deve devolver o resultado original, em vez de emitir um segundo reembolso, uma segunda reserva ou um segundo e-mail. Para obter esse efeito, cada ação que altera algo precisa de uma identidade estável, o resultado precisa ser registrado antes de o agente informar sucesso, e o estado precisa ser verificado antes de qualquer escrita que não possa ser desfeita.
Principais pontos
- Dê a cada ação pretendida um identificador estável, montado a partir de fatos do negócio, criado antes da primeira tentativa e reutilizado em todas as novas tentativas.
- Registre o resultado de cada escrita em um lugar que a camada de ferramentas consiga ler antes de o agente informar sucesso.
- Trate um timeout como resultado desconhecido, e não como falha. Consulte o resultado pela chave antes de tentar de novo.
- Imponha a proteção contra duplicidade na ferramenta e no banco de dados, e não no prompt do sistema.
- Mantenha limites de aprovação em ações irreversíveis, como pagamentos, reservas e mensagens enviadas, mesmo quando a ferramenta for idempotente.
Por que novas tentativas geram trabalho duplicado
Um agente raramente falha do jeito que um script simples falha. Uma chamada de ferramenta pode ser concluída do outro lado da conexão enquanto o agente nunca recebe a confirmação. A requisição expira, o orquestrador reinicia a etapa, ou um operador clica em executar de novo no console. Do ponto de vista do agente, nada aconteceu ainda. Do ponto de vista do sistema de reservas, agora existe um segundo agendamento.
Há uma segunda fonte de duplicidade que as equipes costumam não ver. O modelo pode planejar a mesma ação outra vez depois de um contexto longo, de um resumo ou de uma instrução alterada, e gerar argumentos um pouco diferentes da primeira tentativa: um novo carimbo de data e hora, uma observação reescrita, outra grafia do nome do cliente. A proteção no nível de transporte não pega isso, porque o sistema enxerga o que parece ser uma nova requisição. A mesma ação pretendida precisa mapear para a mesma identidade, mesmo quando o texto muda.
Dê a cada ação pretendida uma identidade estável
Comece pelo objeto de negócio, e não pela tentativa. Um reembolso é um reembolso de uma cobrança específica por um motivo declarado. Uma reserva é um cliente, um serviço e um horário específicos. Um lembrete é uma consulta específica, um modelo e uma janela de envio. A chave é derivada desses fatos e armazenada junto com a requisição. Um identificador aleatório gerado a cada tentativa anula o objetivo, porque para o sistema receptor cada nova tentativa parece inédita.
Alguns provedores já oferecem esse padrão. A documentação da Stripe descreve chaves de idempotência: o cliente envia uma chave com a requisição, e requisições repetidas com a mesma chave devolvem o resultado da primeira, por um período que o próprio provedor define. A maioria dos sistemas internos não tem esse comportamento, então a camada de ferramentas precisa fornecê-lo.
- Derive a chave dos fatos que definem a ação, e não do horário da requisição.
- Inclua o tipo da ação, para que um reembolso e uma nota de crédito referentes à mesma cobrança não colidam por acidente.
- Guarde junto da chave uma impressão digital dos argumentos normalizados, para que uma chave reutilizada com argumentos diferentes seja recusada, e não respondida em silêncio.
- Mantenha a chave idêntica entre novas tentativas, reinícios e replanejamentos do modelo.
Para um passo a passo mais detalhado desse padrão em casos de reembolso, veja ações idempotentes e reembolsos duplicados.
Imponha a regra na ferramenta, não no prompt
Escrever no prompt do sistema que o lembrete nunca deve ser enviado duas vezes é um pedido, não um controle. Modelos seguem instruções na maior parte do tempo, e na maior parte do tempo não é um padrão aceitável para um pagamento. A garantia deve estar no banco de dados e na ferramenta: uma restrição de unicidade sobre a chave, uma escrita condicional que só funcione uma vez, ou uma consulta que rode antes da chamada externa.
As orientações da Anthropic sobre como escrever ferramentas para agentes destacam que as descrições e os valores de retorno moldam o comportamento do agente. Torne o caso de duplicidade explícito no retorno. Quando a ferramenta encontrar uma ação já concluída sob a mesma chave, deve devolver esse resultado com um status claro, como já processado, e não um erro que leve o agente a procurar outro caminho. Assim o agente não tem nada para consertar e nenhum motivo para improvisar.
Trate o resultado desconhecido
O caso mais difícil é o timeout. O agente enviou a escrita, a confirmação não chegou, e ninguém sabe se a ação aconteceu. Trate esse estado como desconhecido. Resolva consultando a chave no seu próprio registro e no sistema externo antes que qualquer outra coisa seja executada.
- Se a escrita retornou sucesso claro, guarde o resultado sob a chave e siga em frente.
- Se a escrita retornou uma recusa definitiva, como conta encerrada ou serviço inválido, registre o motivo, não tente de novo e escale.
- Se a escrita expirou, consulte a chave. Se a ação existir, guarde o identificador externo e siga. Se não existir, tente uma única vez de novo com a mesma chave.
- Se a própria consulta falhar, pare a etapa, mantenha a requisição em uma fila e avise o operador. Não escreva de novo com base em um palpite.
- Se a ação for irreversível e o resultado continuar incerto após a consulta, entregue a uma pessoa a chave, os argumentos e os registros relevantes.
As regras mais amplas sobre quantas tentativas um agente pode fazer e quanto tempo espera entre elas pertencem a uma política separada. O guia sobre política de repetição para agentes de IA cobre essa camada.
Proteja mensagens, reservas e webhooks
Mensagens precisam de um padrão próprio, porque um e-mail enviado não pode ser retirado. Grave a intenção, com sua chave, em uma tabela de saída antes de chamar o serviço de envio. Um remetente separado lê as linhas pendentes, despacha as mensagens e registra o identificador de mensagem do provedor. Se o remetente falhar depois do despacho, mas antes do registro, a linha continua pendente, e a etapa de consulta deve verificar os registros do provedor pela chave antes de enviar de novo. Quando o provedor não permite consulta pela sua chave, a janela não pode ser fechada por completo. Nesse caso, reduza a janela e exija revisão humana para mensagens de alto impacto.
Eventos de entrada exigem a mesma disciplina. A documentação de webhooks da Stripe descreve entregas que podem chegar mais de uma vez, então o lado receptor deve validar a assinatura e processar cada identificador de evento apenas uma vez. O agente deve registrar que um evento foi tratado, em vez de tratar cada entrega como uma nova instrução para agir.
Uma entrega repetida deve produzir uma resposta registrada, não uma segunda ação.
Cenário ilustrativo: uma pequena empresa de serviços usa um agente para confirmar agendamentos. A chamada de confirmação expira depois que a reserva foi criada. Uma nova tentativa ingênua reserva um segundo horário para a mesma visita. Com uma chave montada a partir de cliente, serviço e horário, a nova tentativa encontra a primeira reserva, devolve o identificador dela, e o agente envia uma única confirmação. O negócio vê uma visita na agenda e uma mensagem no histórico do cliente.
Checklist e como a Be Human trata isso
Antes de qualquer ferramenta de escrita entrar em produção, confirme os itens abaixo para cada uma delas:
- A ferramenta tem uma chave documentada e os campos que a alimentam.
- A chave é imposta por restrição de unicidade, escrita condicional ou mecanismo do provedor.
- Uma chave repetida devolve o resultado anterior com status claro.
- Timeouts disparam consulta, e não uma nova tentativa às cegas.
- Cada resultado é guardado com a chave, o horário e o identificador externo.
- Ações irreversíveis têm um limite de aprovação ou um período supervisionado antes.
- Os testes simulam uma resposta perdida e uma entrega duplicada. A abordagem de testar chamadas de ferramentas sem sistemas reais permite testar o caminho de escrita sem tocar em sistemas ao vivo.
- Os registros tornam visíveis as tentativas duplicadas, para que possam ser contadas e revisadas.
A Be Human trata isso como parte do desenho operacional, e não como um conserto pontual. Em um primeiro projeto, a equipe define o papel único do agente, as ferramentas de que ele precisa, as chaves de cada escrita, os limites de aprovação e o critério de sucesso, incluindo como uma tentativa duplicada aparece nos registros. Na operação gerenciada, o trabalho continua: revisões de permissões, acompanhamento de chaves repetidas e de argumentos recusados, e resposta a incidentes quando uma duplicidade escapa. Cada mudança em uma ferramenta de escrita é registrada, para que o negócio consiga ler o que mudou e por quê.
Se você não tem certeza de qual ação do seu agente merece esse tratamento primeiro, o diagnóstico gratuito de IA da Be Human é uma forma prática de encontrar a primeira tarefa que vale entregar a um agente.
Perguntas frequentes
Chave de idempotência é a mesma coisa que política de repetição? Não. A política de repetição decide quando e com que frequência uma etapa roda de novo, enquanto a chave de idempotência decide se uma execução repetida altera algo. Você precisa das duas, porque novas tentativas sem chaves multiplicam escritas duplicadas, e chaves sem política de repetição deixam o trabalho que falhou parado.
Ferramentas somente de leitura precisam de idempotência? Leituras não alteram estado, então o risco de duplicidade está ligado a custo e consistência, e não a dinheiro ou mensagens. Entradas estáveis ainda ajudam, porque permitem que o agente raciocine sobre os mesmos dados em todas as tentativas. Concentre o maior esforço nas ferramentas que movimentam dinheiro, criam registros ou entram em contato com pessoas.
O meu provedor de modelo ou a plataforma de orquestração pode evitar duplicidades por mim? Essas plataformas podem repetir requisições, mas não sabem o que conta como duplicidade no seu negócio. Duas solicitações de reserva para o mesmo cliente podem ser ambas legítimas, e só a definição da sua chave captura essa diferença. A proteção precisa estar na sua camada de ferramentas, perto dos sistemas que registram a ação.
Por onde começar se meus sistemas não suportam chaves? Comece pela escrita mais cara. Mantenha um registro local de cada ação, indexado pelos fatos de negócio, adicione uma consulta antes da chamada externa e rode a ferramenta em modo supervisionado até que as checagens de duplicidade se sustentem em testes. Você também pode começar esta semana anotando uma única ação, os fatos que a definem e a chave que você usaria.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


