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

Testes e confiabilidade

Tratamento de timeout em agentes de IA: registre como desconhecido, não falho

Quando a chamada expira, o resultado é desconhecido, não falho. Saiba o status a registrar, o que verificar antes de repetir e como evitar duplicidades.

Capa tipográfica do Be Human com o título: Tratamento de timeout em agentes de IA: registre como desconhecido, não falho
Ilustração conceitual criada com IA · Be Human

Quando um agente de IA chama uma ferramenta e nenhuma resposta chega antes do prazo, o status correto é desconhecido, não falho. A ação pode ter sido concluída, pode ainda estar na fila ou pode ter sido finalizada enquanto a resposta se perdia no caminho de volta. O próximo passo é uma leitura de verificação no sistema de registro, e uma nova tentativa só acontece depois que essa leitura mostrar que a ação não ocorreu e que é seguro repeti-la.

Principais pontos

  • Registre uma chamada expirada como desconhecida até que uma leitura de verificação confirme o que aconteceu.
  • Dê a toda ferramenta que altera dados um identificador de requisição, para que o agente consulte o resultado em vez de adivinhar.
  • Verifique antes de qualquer nova tentativa, e repita apenas ações seguras para executar duas vezes.
  • Defina um limite de tentativas de verificação e, ao atingi-lo, entregue o caso a uma pessoa nomeada com as evidências anexadas.
  • Informe ao dono do negócio o que foi feito, o que continua desconhecido e o que está aguardando.

Por que um timeout não é uma falha

Uma falha é uma afirmação sobre o mundo. A ferramenta devolveu um erro, o registro não foi criado e nada mudou. Um timeout é uma afirmação sobre a conexão. O agente parou de esperar, e isso é tudo o que ele sabe. Tratar a segunda como a primeira está entre as causas mais comuns de faturas duplicadas, reservas em duplicidade e mensagens repetidas a clientes.

O erro é fácil de cometer porque a maioria dos frameworks de agentes mostra o timeout no mesmo lugar em que mostra um erro. Uma linha de log que diz que a ferramenta falhou parece igual a uma que diz que a ferramenta não respondeu a tempo. Adiante, o agente lê o rótulo e decide o que fazer. Se o rótulo diz falha, ele tenta de novo. Se a requisição original, na prática, foi processada, a segunda agora roda sobre um resultado que já existe.

Para leituras, a distinção importa menos, porque repetir uma consulta é inofensivo. Para escritas, envios, pagamentos e mudanças de status, ela importa muito. O mesmo timeout pode significar nenhuma mudança, uma mudança ou uma mudança que alguém já desfez. Só pelo timeout, o agente não consegue saber qual delas aconteceu.

Os três estados em que uma chamada expirada pode estar

Quando uma ferramenta capaz de escrever expira, o sistema por trás dela está em um de três estados. A requisição nunca chegou ao serviço, e portanto nada aconteceu. A requisição chegou, foi concluída, mas a confirmação não voltou. Ou a requisição foi aceita e ainda está em processamento. Um desenho sólido de agente considera qualquer um dos três e não escolhe um por padrão.

Por isso o status deve ser um valor próprio, separado de sucesso e falha. Um registro prático para cada ação tentada inclui o tipo de ação, o registro alvo, o identificador da requisição, o horário do envio, o horário do timeout, o status atual e o resultado da verificação. Manter esses campos faz do próximo passo uma questão de leitura, não de adivinhação.

  • Ação: o que o agente tentou fazer, em termos simples, como criar um rascunho de fatura para um cliente identificado.
  • Alvo: o registro ou a conta afetada, identificado pela chave do sistema.
  • Identificador da requisição: a chave enviada junto à chamada, para que o provedor ou o serviço interno consiga reconhecer duplicatas.
  • Status: desconhecido, sucesso confirmado, não aplicado confirmado ou aguardando revisão.
  • Verificação: a leitura realizada, seu horário e o que ela retornou.

O identificador da requisição faz a maior parte do trabalho. Provedores de pagamento e algumas APIs internas aceitam uma chave gerada pelo cliente e devolvem o resultado original quando a mesma chave é enviada de novo. A abordagem está descrita na documentação de provedores de pagamento, como a Stripe, e o mesmo princípio vale para qualquer serviço interno capaz de associar uma requisição repetida a uma anterior. Onde não existe essa chave, o agente precisa depender de uma consulta por um campo de negócio único, como uma referência externa que ele gerou e guardou antes da chamada.

O que verificar antes de qualquer nova tentativa

A etapa de verificação é onde a maioria dos desenhos de agente é fraca. Equipes costumam acrescentar uma nova tentativa com intervalo crescente e param aí, o que resolve problemas transitórios de rede, mas não uma ação que deu certo em silêncio. O próximo passo deveria ser uma leitura que responda a uma pergunta estreita: esta ação específica surtiu efeito?

A leitura deve consultar o sistema de registro diretamente, não um cache, um índice de busca ou a memória do próprio agente. A memória é útil para contexto, mas não é prova de que um sistema externo mudou. Se o sistema de registro não puder ser lido dentro do mesmo prazo, o status continua desconhecido e o caso vai para revisão.

Um plano que funciona para a maioria das ferramentas de negócio segue uma sequência curta.

  • Marque a ação como desconhecida no registro da execução e interrompa as etapas dependentes do seu resultado.
  • Faça uma leitura de verificação usando o identificador da requisição ou a referência externa guardada.
  • Se a leitura mostrar que a ação foi aplicada, registre-a como confirmada e siga apenas para a próxima etapa.
  • Se a leitura não mostrar nenhum vestígio e a ação for idempotente, tente uma única vez de novo com o mesmo identificador de requisição.
  • Se a leitura não mostrar nenhum vestígio e a ação não for idempotente, não tente de novo. Encaminhe o caso a uma pessoa com a ação proposta e as evidências.
  • Se a própria leitura expirar, mantenha o status como desconhecido, aguarde o intervalo configurado e tente a leitura novamente dentro do limite de tentativas.
  • Ao atingir o limite de tentativas, pare e escale. Não troque de ferramenta para obter o mesmo resultado sem revisão.

As duas últimas etapas importam. Um agente que continua repetindo uma leitura, ou que passa discretamente a mesma escrita por uma segunda ferramenta, pode produzir justamente a duplicidade que tentava evitar. Uma condição de parada clara protege tanto os dados quanto o orçamento. Para o padrão geral de tentativas limitadas, o guia de política de repetição para agentes de IA explica como escolher o número de tentativas e os intervalos.

Cenário ilustrativo: um orçamento enviado duas vezes

O cenário a seguir é ilustrativo e não descreve um cliente real. Um agente de operações prepara um orçamento e o envia pelo serviço de documentos da empresa. A chamada expira depois que o serviço já colocou o e-mail na fila. Em um desenho ingênuo, o agente marca o envio como falho e tenta de novo, de modo que o cliente recebe dois orçamentos idênticos com dois números de referência diferentes.

No desenho descrito aqui, o agente registra o envio como desconhecido e anexa a referência externa que gerou antes da chamada. Em seguida, procura essa referência na caixa de saída. A caixa mostra uma única mensagem na fila, então o agente marca o envio como confirmado e não tenta de novo. Ele escreve uma nota curta no registro do caso. Se a caixa de saída não mostrasse nada, e o envio não fosse idempotente, o agente teria colocado o orçamento em uma fila de revisão, com o rascunho anexado, em vez de enviá-lo de novo.

A diferença não está na ferramenta. Está no status que o agente tinha permissão para registrar e na checagem que era obrigado a fazer antes de agir novamente.

Como decidir quando uma pessoa deve assumir

Nem todo desconhecido precisa de um humano, e nem todo desconhecido pode ficar com o agente. A decisão depende do que a ação altera, de ela poder ser desfeita e de quanto tempo o negócio tem antes que a incerteza cause dano. O roteiro abaixo é um ponto de partida para combinar com o responsável pela operação, não uma regra universal.

  • Leituras e consultas: tentar de novo dentro do limite e, depois, marcar como indisponível. Em geral não é necessária revisão humana.
  • Escritas idempotentes com chave confiável: verificar e, se a leitura não mostrar vestígio, tentar uma vez.
  • Escritas não idempotentes, como pagamentos, envios ou exclusões: verificar e escalar quando a leitura for inconclusiva.
  • Ações que afetam clientes ou dinheiro quando o estado atual não pode ser lido: pausar o fluxo e avisar o responsável.
  • Desconhecidos repetidos na mesma ferramenta em um curto intervalo: tratar a ferramenta como degradada, parar novas chamadas a ela e abrir um incidente.

Quando uma pessoa assume, a passagem de bastão deve conter a decisão a ser tomada, não a transcrição completa. A pessoa precisa da ação pretendida, do identificador da requisição, dos resultados da verificação e das opções com suas consequências. O guia de escalonamento humano para falhas de agentes descreve como manter essas passagens curtas e objetivas.

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

A Be Human desenha o modelo de status, os identificadores de requisição e as etapas de verificação como parte do contexto operacional do agente, antes de dar a ele autoridade para escrever. Em operações gerenciadas, a equipe acompanha com que frequência as chamadas terminam como desconhecidas, revisa as leituras de verificação que confirmaram ou descartaram essas ações e ajusta limites de tentativa e critérios de escalonamento por meio de um processo de mudança registrado. Quando uma ferramenta degrada, a resposta segue um procedimento de incidente escrito, e o dono do negócio recebe um resumo simples do que foi aplicado, do que está pendente e do que precisa de uma decisão.

Para equipes que querem ver onde os timeouts já causam problemas, um primeiro passo útil é listar todas as ferramentas que o agente chama, marcar quais alteram dados e verificar se cada uma aceita um identificador de requisição. O diagnóstico gratuito da Be Human pode ajudar a identificar a primeira tarefa que vale entregar a um agente e o desenho de ferramenta adequado para ela.

Perguntas frequentes

Um agente de IA deve algum dia registrar uma chamada expirada como falha? Não, a menos que a ferramenta tenha retornado um erro explícito que confirme que nada foi aplicado. Um timeout só informa ao agente que ele parou de esperar, então o status honesto é desconhecido até que uma leitura de verificação mostre o resultado. Registrar como falha convida a uma nova tentativa que pode duplicar a ação.

Como um agente verifica uma ação depois de um timeout? Ele deve consultar o sistema de registro diretamente, usando um identificador de requisição ou uma referência externa que guardou antes da chamada. A leitura deve responder a uma pergunta estreita: aquela ação específica surtiu efeito? Se a própria leitura também expirar, o status continua desconhecido e a tentativa conta para o limite.

Toda chamada de ferramenta que falhou pode ser repetida com segurança? Não. Repetir é seguro apenas quando a ação é idempotente, ou seja, executá-la duas vezes tem o mesmo efeito que executá-la uma vez, ou quando o provedor devolve o resultado original para uma chave repetida. Para ações não idempotentes, como pagamentos, envios ou exclusões, o agente deve verificar e depois escalar, em vez de repetir por conta própria.

O que o dono do negócio deve pedir antes de dar a um agente permissão de escrita em uma ferramenta? Pergunte como cada escrita que expirou é registrada, qual identificador é enviado com ela, como o agente verifica o resultado e quando ele para e pede a intervenção de uma pessoa. Peça para ver um exemplo de registro de execução de um timeout em ambiente de teste. As respostas mostram se o agente consegue distinguir o que foi feito do que não foi, que é a decisão que mais importa.

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 →