Ir para conteúdo
be-human.ai
← Voltar ao blog

Ferramentas e integrações

Chamadas de ferramenta idempotentes em agentes de IA: evite duplicidades

Projete ferramentas de escrita para que uma ação de agente de IA repetida não crie faturas, reservas ou registros duplicados. Chaves, checagens e recuperação.

Capa tipográfica do Be Human com o título: Chamadas de ferramenta idempotentes em agentes de IA: evite duplicidades
Ilustração conceitual criada com IA · Be Human

Uma escrita idempotente em ferramenta é aquela que produz o mesmo resultado, não importa quantas vezes o mesmo pedido chegue até ela. Para agentes de IA, isso importa porque timeouts, retentativas de rede e replanejamento são situações normais, então uma chamada de criar fatura ou reservar horário pode chegar duas vezes. A solução é dar a cada escrita uma chave de operação estável, registrar o resultado antes de responder e fazer o agente consultar o sistema de destino antes de tentar de novo.

Principais pontos

  • Toda ferramenta de escrita deve exigir uma chave de operação que identifique a intenção de negócio, não a tentativa.
  • A ferramenta deve guardar o resultado de cada chave e devolver esse mesmo resultado a qualquer chamada repetida.
  • O agente deve ler o sistema de destino antes de qualquer segunda tentativa de uma escrita que ele não consegue confirmar.
  • Resultados ambíguos, como um timeout depois que o pedido saiu, precisam de um caminho de conciliação e de uma pessoa quando o valor ou o compromisso é relevante.
  • Idempotência é uma propriedade de projeto da ferramenta, então ela pertence ao contrato da ferramenta e aos testes de aceitação, não a um prompt.

Por que as retentativas geram duplicatas em fluxos com agentes

Uma escrita duplicada raramente nasce de um erro óbvio. Normalmente ela vem de uma sequência de passos razoáveis. O modelo envia o pedido, a rede perde a resposta, o orquestrador estoura o tempo limite e o agente, que nunca viu uma confirmação, planeja a ação de novo. Se a ferramenta trata cada chamada como nova, a fatura é criada duas vezes, a sala é reservada duas vezes ou o mesmo cliente aparece em dois cadastros.

As retentativas vêm de várias camadas ao mesmo tempo. O modelo de linguagem pode regerar uma chamada de ferramenta depois de uma falha parcial. O executor do fluxo pode repetir um passo que não informou sucesso. Um provedor de webhooks pode reenviar um evento que acredita não ter sido confirmado. Cada camada faz o que foi projetada para fazer. A ferramenta de escrita é o único ponto onde você consegue tornar a segunda chegada inofensiva.

Por isso a pergunta não é « o agente vai tentar de novo? », e sim « o que acontece quando ele tenta? ». Planeje a chegada repetida como o caso normal.

Como dar a cada escrita uma chave de operação estável?

Uma chave de operação é um identificador que quem chama envia junto de cada pedido de escrita. A ferramenta a usa para decidir se já executou aquele trabalho. A chave precisa permanecer a mesma em todas as retentativas da mesma intenção e precisa mudar quando a intenção mudar.

O erro mais comum é gerar um identificador aleatório novo a cada tentativa. Isso impede a ferramenta de reconhecer uma retentativa, e a proteção desaparece. Uma abordagem melhor deriva a chave dos fatos de negócio que definem a ação.

  • Nomeie o objeto de negócio e a ação, por exemplo o cliente, o pedido e o passo « criar fatura ».
  • Inclua o período ou a versão que tornam a intenção única, como a data de cobrança ou o identificador do pedido de reserva na mensagem de origem.
  • Monte a chave de forma determinística a partir desses campos, para que o agente ou o fluxo gere a mesma string em cada retentativa.
  • Recuse qualquer escrita que chegue sem chave. Chave ausente é erro de projeto, não um caso para adivinhar.
  • Mantenha as chaves em um formato que a equipe consiga ler nos registros, para que um operador veja de qual intenção veio cada registro.

Quando o sistema de destino já oferece suporte a chaves de idempotência, use esse recurso. Provedores de pagamento e de faturamento costumam aceitar um cabeçalho com a chave e devolver a resposta original para pedidos repetidos. Leia a documentação do provedor para saber por quanto tempo as chaves são guardadas e o que acontece quando a mesma chave é enviada com parâmetros diferentes. A sua própria ferramenta deve aplicar a mesma regra, porque nem todo sistema conectado vai oferecer esse recurso.

Como a ferramenta deve guardar os resultados antes de responder?

A ferramenta precisa de um livro-razão de operações. É um pequeno registro, separado do sistema de negócio, que associa cada chave de operação ao seu status e ao seu resultado. Um registro típico guarda a chave, a ação pedida, um status como pendente, concluído ou falhou, o identificador criado no sistema de destino e um carimbo de data e hora.

A ordem das operações importa. A ferramenta deve gravar um registro pendente antes de chamar o sistema de destino. Depois que o destino confirma, ela atualiza o registro para concluído e guarda o identificador devolvido. Quando chega uma chamada repetida, a ferramenta consulta a chave primeiro. Se o status for concluído, devolve o resultado guardado sem escrever de novo. Se o status for pendente, não pode iniciar uma segunda escrita. Deve esperar, conciliar com o sistema de destino ou informar que o resultado é desconhecido.

Mantenha o livro-razão legível. Operadores devem conseguir pesquisá-lo pelo objeto de negócio e ver cada tentativa, inclusive as que falharam. Esse histórico é o que faz uma investigação de duplicidade levar minutos em vez de dias.

Um registro no livro-razão é um recibo de uma intenção. Se o recibo existe, o trabalho não é refeito.

Cenário ilustrativo: uma pequena clínica permite que um agente marque retornos a partir da mensagem de um paciente. O pedido estoura o tempo limite depois que o sistema de agendamento aceitou a reserva. O agente não vê confirmação e pede para agendar de novo. Como a chave foi montada com o paciente, o horário solicitado e a mensagem de origem, a segunda chamada encontra o registro pendente, consulta o sistema de agendamento, localiza a consulta e a devolve. Nenhuma segunda consulta é criada, e o agente informa ao paciente a reserva que já existe.

O que o agente deve checar antes de uma segunda tentativa?

A ferramenta protege contra escritas repetidas, mas o agente também deve ter um hábito: antes de tentar de novo uma escrita que não consegue confirmar, ele lê o estado do destino. É a leitura antes da escrita. Essa checagem é barata e pega casos que a chave não pega, como uma pessoa criando a mesma fatura à mão enquanto o agente trabalhava.

A checagem deve comparar campos específicos, e não apenas perguntar se algo parecido existe. Para uma fatura, compare cliente, valor, data de emissão e referência. Para uma reserva, compare recurso, janela de horário e solicitante. Se existe uma correspondência exata, o agente trata a escrita como concluída. Se existe um registro próximo, mas diferente, o agente para e pergunta a uma pessoa, porque uma correspondência aproximada é uma pergunta, não uma resposta.

Dê ao agente uma lista curta para essa etapa:

  • Pesquise no sistema de destino pela chave de operação ou pela referência de negócio da qual a chave foi montada.
  • Compare os campos que definem a intenção, e não apenas o identificador.
  • Se existir uma correspondência exata, registre o identificador existente no livro-razão e informe sucesso.
  • Se nada corresponder, tente mais uma vez com a mesma chave e depois pare.
  • Se existir um registro semelhante, encaminhe para uma pessoa nomeada em vez de escrever.

O limite de tentativas importa. Um agente que entra em loop numa escrita com falha pode gerar muitos resultados parciais, mesmo com cada chamada protegida. Um número pequeno e fixo de tentativas, seguido de um alerta, mantém a falha visível.

Como o contrato da ferramenta pode dificultar pedidos duplicados?

O nome, as entradas e as saídas da ferramenta moldam o uso que o agente faz dela. Um contrato vago convida ao uso incorreto. Dê às ferramentas de escrita nomes que descrevam a ação de negócio, como criar rascunho de fatura ou solicitar reserva, e não um nome genérico como atualizar registro. Separe criar de atualizar, para que o agente não crie um segundo objeto quando queria alterar o primeiro.

Exija a chave de operação no esquema de entrada e devolva na saída o identificador guardado e o status. A saída deve dizer com clareza se a escrita foi nova, se já existia ou se ainda está pendente. Um agente que recebe o status explícito de já existente tem muito menos chance de tratar um resultado repetido como falha e tentar de novo.

Mantenha a entrada enxuta. Cada campo de texto livre é um ponto onde duas chamadas com a mesma intenção podem diferir por um espaço ou uma palavra, e então a chave deixa de coincidir. Quando um valor tem um conjunto fixo de opções, use uma enumeração. Quando um valor é data ou quantia, use um campo tipado e valide antes da escrita. Nosso guia sobre esquemas de ferramentas para agentes de IA aborda nomes e tipos com mais detalhe.

Por fim, decida quais escritas são permitidas. Uma ferramenta de escrita que pode criar um pagamento ou um reembolso não deve ser exposta ao mesmo agente que redige respostas a clientes. Separe a permissão da mecânica, para que a idempotência proteja as escritas que você escolheu permitir.

O que acontece quando o resultado é desconhecido?

Algumas falhas deixam o resultado indefinido. O pedido pode ter chegado ao sistema de destino, ou pode não ter chegado. Trate esse estado como um caso próprio, com regra própria. Não adivinhe, e não escreva de novo antes de conhecer o status.

O caminho de conciliação é direto. A ferramenta marca o registro no livro-razão como desconhecido, agenda uma checagem no sistema de destino e repete a consulta em intervalos que respeitem os limites de uso do destino. Se o registro for encontrado, o livro-razão é atualizado para concluído. Se o registro não for encontrado depois da janela de checagem, ele é marcado como falho e a operação volta para a fila ou para uma pessoa. Para orientação sobre o ritmo dessas checagens, veja limites de taxa para agentes de IA.

Valores, compromissos legais e mensagens enviadas a clientes merecem uma pessoa no processo quando o resultado é desconhecido. O agente pode preparar o resumo, incluindo a chave, o horário da tentativa e a pesquisa que executou, para que a pessoa decida com uma única olhada, sem reconstruir o histórico.

Se a própria conexão falhar, o problema é maior do que uma escrita. Pause a ferramenta de escrita, mantenha o livro-razão intacto e siga um processo de recuperação antes de retomar. O que um agente deve fazer quando uma conexão expira descreve essa sequência.

Como a Be Human trata isso em operações gerenciadas

A Be Human trata a idempotência como parte do primeiro projeto, e não como um remendo depois que surge uma duplicata. A primeira etapa define a escrita única que o agente precisa, a chave de operação que ele vai usar, o livro-razão que registra cada intenção e o limite de aprovação para ações com efeito financeiro ou jurídico. Cada um desses pontos fica documentado para que o responsável pelas operações do cliente consiga lê-lo e alterá-lo. Depois, as operações gerenciadas mantêm a proteção funcionando ao longo do tempo: monitoramento de registros pendentes e desconhecidos, testes periódicos que enviam chamadas repetidas para confirmar que devolvem o resultado original e revisão sempre que a API ou as permissões do sistema de destino mudarem. O objetivo é que uma retentativa seja um evento de rotina que o sistema absorve, e que uma pessoa veja qualquer coisa que ele não consiga resolver sozinho.

Se você quer saber qual dos seus fluxos tem maior exposição a escritas repetidas, faça o diagnóstico gratuito de IA da Be Human para identificar a primeira tarefa que vale entregar a um agente.

Perguntas frequentes

Uma chave de idempotência impede todas as duplicatas? Não. Ela impede duplicatas que vêm de chamadas repetidas com a mesma intenção. Ela não impede que duas pessoas diferentes, ou duas intenções diferentes, criem registros parecidos. Por isso o agente também deve consultar o sistema de destino antes de agir sobre uma correspondência aproximada, e por isso a chave deve ser montada a partir dos fatos de negócio que definem a ação.

Quem deve gerar a chave de operação, o agente ou a ferramenta? A ferramenta deve aceitar a chave e recusar pedidos sem ela, enquanto o fluxo ou o agente a monta a partir de campos de negócio estáveis. Se o agente inventa uma chave aleatória a cada tentativa, a proteção falha. Uma chave determinística derivada do registro de origem tem o mesmo valor em cada retentativa, e o livro-razão consegue reconhecê-la.

A idempotência basta se o agente tem permissão para escrever? Não. A idempotência protege contra escritas repetidas, mas não decide se uma escrita deve acontecer. Ações de alto valor ou irreversíveis ainda precisam de um limite de aprovação, de uma pessoa nomeada que possa aprová-las e de um registro claro de quem autorizou cada passo. Idempotência e aprovação são controles complementares.

Como testar escritas idempotentes antes de ir para produção? Envie o mesmo pedido várias vezes em um ambiente de teste, inclusive com um timeout simulado entre a confirmação do destino e a resposta da ferramenta. Confirme que o sistema de destino guarda um único registro, que as chamadas repetidas devolvem o identificador original e que o livro-razão mostra uma única entrada concluída. Repita o teste sempre que a ferramenta, a API do destino ou as permissões mudarem.

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.

Menos tarefas. Mais espaço para você.

Traga o trabalho para o qual falta tempo.

Agende uma conversa e teste 7 dias grátis um agente de IA personalizado ↗Ou faça o diagnóstico gratuito de IA →