Tratamento de erros em agentes de IA: uma falha, um próximo passo
Mapeie cada falha de ferramenta de agente de IA a um próximo passo: repetir, acionar uma pessoa ou parar. Substitua improvisos por regras escritas e revisáveis.

Um erro de ferramenta é qualquer resposta com falha, vazia ou pouco clara de um sistema que o agente chama, como um CRM, uma API de cobrança, uma agenda ou um repositório de documentos. A forma confiável de tratar esse erro é classificar a falha e atribuir a cada classe um próximo passo predefinido: repetir dentro de limites, passar a decisão para uma pessoa nomeada ou parar a execução e preservar o estado. Agentes que improvisam a recuperação tendem a chutar, repetir ações com efeito colateral ou esconder o problema atrás de uma resposta confiante.
Principais pontos
- Classifique as falhas de ferramenta pelo que significam para o negócio, e não apenas pelo código de erro.
- Dê a cada classe de falha um passo padrão: repetir, perguntar a uma pessoa ou parar.
- Repita apenas quando a ação for segura de repetir, e limite as tentativas para cada ferramenta.
- Trate um tempo limite em uma escrita como resultado desconhecido, porque a ação pode já ter acontecido.
- Registre a falha, a regra aplicada e a pessoa que pode mudar a decisão.
Por que improvisar a recuperação é o padrão errado
Quando um agente encontra um erro que nenhuma regra cobre, ele escolhe um caminho a partir do prompt e das últimas mensagens no contexto. Esse caminho pode ser sensato numa execução e prejudicial na seguinte. Uma ferramenta de busca devolve vazio, e o agente escreve uma resposta plausível mesmo assim. Uma chamada de pagamento expira, e o agente a refaz, criando uma segunda cobrança. O modelo não é descuidado nesses casos. Ele não tem um limite declarado para aquela situação, então o limite passa a ser o que ele infere naquele momento.
Líderes de negócio não precisam de um agente mais esperto com erros. Precisam que o caminho de erro esteja decidido antes, revisado pelas pessoas donas do processo e visível depois. O AI Risk Management Framework do NIST trata o risco como algo a mapear, medir e gerenciar ao longo do ciclo de vida do sistema, e uma falha de ferramenta é um ponto concreto onde esse mapeamento gera retorno.
Classifique cada falha de ferramenta antes de desenhar a resposta
Comece pelas ferramentas que o agente realmente usa. Para cada uma, liste as formas como pode falhar e o que o agente precisa saber em cada caso. A maioria das falhas cai em um conjunto pequeno de classes, e esse conjunto é um bom ponto de partida para o seu mapa:
- Erro transitório: a ferramenta sinaliza que está ocupada ou indisponível, e a requisição não foi processada.
- Requisição recusada: a ferramenta rejeita a entrada porque falta um campo, uma permissão não existe ou uma regra de negócio foi quebrada.
- Resultado vazio ou ambíguo: a ferramenta respondeu, mas a resposta não serve à tarefa, como nenhum cliente encontrado ou dois possíveis.
- Resultado desconhecido: a requisição expirou ou a conexão caiu depois que a ação pode ter sido executada.
- Dados conflitantes: o resultado contradiz outra fonte que o agente tem.
- Pedido fora do limite: concluir a tarefa exigiria uma ação fora da alçada de aprovação do agente.
A classe de resultado desconhecido merece mais atenção. Em uma leitura, o agente pode simplesmente perguntar de novo. Em uma escrita, ele não consegue saber se deve repetir a ação ou relatá-la como concluída, e chutar é como surgem reservas duplicadas e reembolsos em dobro. A classe de pedido fora do limite não é uma falha da ferramenta, mas deve seguir o mesmo mapa, para que o agente nunca contorne uma permissão que não recebeu.
Associe cada classe a repetir, perguntar a uma pessoa ou parar
Cada classe recebe um passo padrão. Mantenha o mapa curto o bastante para que um gestor o leia em poucos minutos:
- Erro transitório: repita com um limite fixo de tentativas e pausas crescentes. Se o limite for atingido, passe o caso a uma pessoa.
- Requisição recusada: não reenvie a mesma entrada. Pergunte a uma pessoa somente se a informação faltante existir fora do agente; caso contrário, pare e registre o motivo.
- Resultado vazio ou ambíguo: não escolha em silêncio. Apresente os candidatos e a dúvida em aberto a uma pessoa.
- Resultado desconhecido em leitura: repita, porque repetir uma leitura é seguro.
- Resultado desconhecido em escrita: pare novas escritas, consulte o sistema de registro com uma leitura somente se ela existir e peça a uma pessoa antes de qualquer repetição.
- Dados conflitantes: pare a etapa afetada e pergunte a uma pessoa qual fonte está atualizada.
- Pedido fora do limite: pare, registre o pedido e encaminhe ao aprovador definido no modelo de permissões.
O padrão é consistente. Repetições ficam onde repetir o mesmo pedido é inofensivo e provavelmente bem-sucedido. A passagem para uma pessoa fica onde a decisão certa depende de um contexto que o agente não tem. A parada fica onde continuar criaria efeitos colaterais que ninguém aprovou.
Repita o que é seguro repetir, pergunte sobre o que depende de contexto e pare o que mudaria o negócio sem aprovação.
Escreva o plano de cada ferramenta como passos que alguém possa auditar
Uma política geral como trate erros com cuidado não pode ser testada. Um plano por ferramenta pode. Escreva um plano curto para cada ferramenta que o agente usa, com estes elementos:
- O nome da ferramenta, o dono do sistema por trás dela e as ações que o agente pode executar.
- As classes de falha que se aplicam àquela ferramenta e o passo padrão de cada uma.
- Os limites: número máximo de tentativas, tempo máximo decorrido e o ponto em que a execução para.
- A pessoa ou fila que recebe os encaminhamentos e o prazo de resposta esperado dela.
- O que o agente informa: o pedido, a classe do erro, as tentativas feitas e o último estado conhecido.
- Como uma pessoa retoma ou encerra a execução e se o agente pode continuar a partir de um ponto de controle salvo.
- Quando o plano é revisado, inclusive depois de cada incidente e de cada mudança na ferramenta.
Guarde esses planos junto às notas operacionais do agente, para que a pessoa de plantão possa agir sem precisar perguntar ao construtor o que o agente foi projetado para fazer.
Cenário ilustrativo: um agente que prepara decisões de reembolso para uma equipe de suporte chama o serviço de pagamentos para verificar uma cobrança, e a primeira chamada expira. Pelo plano, o agente classifica o resultado como desconhecido em um caminho de escrita. Ele faz uma consulta somente leitura à cobrança, não encontra reembolso registrado e não emite nenhum. Coloca o caso na fila humana com o identificador da cobrança, o horário do tempo limite e o resultado da consulta. O responsável pelo suporte decide se emite o reembolso, e a execução para aí. Nada disso depende de o agente adivinhar.
Limite as repetições para que nunca dupliquem um efeito colateral
A lógica de repetição costuma falhar de um jeito específico: trata toda falha como o mesmo tipo de problema. Repetir uma leitura é inofensivo. Repetir uma reserva, um pagamento ou uma mensagem de saída pode duplicar uma ação de negócio que o cliente ou o fornecedor vai notar. O padrão seguro é dar a cada escrita um identificador único, para que o sistema receptor reconheça uma repetição e devolva o resultado original. A Stripe documenta essa abordagem em sua API com as chaves de idempotência, nas quais uma requisição repetida devolve o resultado da primeira em vez de criar um registro novo. Se você constrói as próprias ferramentas, o princípio é o mesmo: se a ferramenta não consegue reconhecer uma repetição, o agente não deve repetir uma escrita.
Defina limites de tentativas e de tempo por ferramenta, em vez de um número global, porque uma busca interna lenta e um gateway de pagamento têm tolerâncias diferentes. Para o padrão completo de repetição, leia uma política de repetição que evita erros repetidos. Para o problema específico de um tempo limite que deixa o resultado desconhecido, leia Tempo limite para agentes de IA: pare execuções sem controle.
O que registrar para que toda falha possa ser revisada
Um caminho de erro só é útil se alguém conseguir vê-lo funcionando. Registre o suficiente para reconstruir cada decisão: a ferramenta, um resumo da entrada sem dados pessoais, a classe do erro, a regra aplicada, o número de tentativas, o estado final e o destino do encaminhamento. Rastros que acompanham um pedido por várias etapas tornam isso mais fácil de ler. A documentação do OpenTelemetry sobre conceitos de observabilidade descreve esse modelo de spans e traces, útil mesmo que suas ferramentas de log sejam outras.
Quando o agente passa um caso a uma pessoa, o encaminhamento deve trazer a decisão necessária, não a transcrição inteira. Um revisor que precisa ler quarenta mensagens para achar uma pergunta acaba parando de ler. Para o formato do encaminhamento, leia Escalonamento humano em IA: entregue a decisão necessária.
Como a Be Human conduz isso em operações gerenciadas
A Be Human desenha o mapa de erros como parte de um primeiro projeto, partindo do papel único que o agente vai executar e das ferramentas que esse papel precisa. Definimos as classes de falha para cada ferramenta, o passo padrão de cada classe e os limites de aprovação que decidem quando um agente pode escrever, quando deve perguntar e quando deve parar. Nas operações gerenciadas, o monitoramento acompanha os logs de falha em busca de classes que aparecem com mais frequência do que o esperado, as revisões de permissão removem acessos que não são mais necessários, e a resposta a incidentes atualiza o plano quando uma falha expõe uma lacuna. Mudanças em limites de repetição ou em regras de encaminhamento são feitas de forma controlada e registradas em um formato que o dono do negócio consegue ler.
Se você não tem certeza de qual falha de ferramenta na sua operação causaria mais dano, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrar a primeira tarefa que vale entregar a um agente.
Perguntas frequentes
Um agente de IA deve repetir toda chamada de ferramenta que falhou? Não. Repetições são seguras para leituras e para erros transitórios, em que uma nova tentativa tende a funcionar sem efeitos colaterais. Para escritas com resultado desconhecido, o agente deve consultar o sistema de registro e pedir a uma pessoa antes de repetir qualquer coisa. Uma regra global de repetição que ignora essa diferença é uma das causas mais comuns de ações duplicadas.
Quando o agente deve parar em vez de perguntar a uma pessoa? Ele deve parar quando continuar criaria um efeito de negócio que ninguém aprovou, como uma escrita fora das permissões do agente ou uma escrita feita depois que surgem dados conflitantes. Perguntar a uma pessoa é a escolha certa quando a decisão depende de um contexto que o agente não tem, como qual de dois cadastros de cliente está atualizado. Parar também mantém o estado da execução intacto, para que uma pessoa possa retomá-la depois.
Como tratar um tempo limite em uma ação de escrita? Trate-o como resultado desconhecido, não como falha, porque a ação pode ter sido concluída antes de a conexão cair. O agente deve verificar o resultado por uma consulta somente leitura, se o sistema oferecer uma, e não deve reenviar a escrita até que uma pessoa ou uma regra verificada permita. Quando a ferramenta aceita chaves de idempotência, a repetição é segura, porque o sistema receptor devolve o resultado original.
Quem deve ser o dono do mapa de erros de um agente? O dono do processo de negócio deve ser o responsável, com o construtor técnico mantendo a implementação. O dono decide o que significa um encaminhamento, quem o recebe e em quanto tempo precisa ser respondido. Revisar o mapa após cada incidente mantém o documento preciso à medida que ferramentas e permissões mudam.
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.


