Mensagens de erro de agentes de IA: etapa, registro e próximo responsável
Escreva mensagens de erro de agentes de IA que informem a etapa com falha, o registro afetado e o responsável pela próxima ação. Inclui checklist e exemplo.

Uma mensagem de erro de agente de IA é útil quando diz à pessoa responsável três coisas: qual etapa falhou, em qual registro o agente estava trabalhando e quem deve agir em seguida. Uma mensagem que diz apenas «falha na chamada da ferramenta» manda alguém para os logs para reconstruir a execução, e é nessa demora que começam reembolsos duplicados, e-mails repetidos e pedidos parados. Escrever essas mensagens é uma tarefa de desenho, que se termina antes de o agente tocar em trabalho real, e não uma limpeza feita depois do primeiro incidente.
Principais pontos
- Nomeie a etapa com falha em linguagem de negócio, não com o nome interno da função que o desenvolvedor usou.
- Anexe o registro afetado por um identificador estável que uma pessoa consiga buscar, e informe em que condição ele está agora.
- Indique um único papel responsável pela próxima ação e a decisão única que esse papel precisa tomar.
- Separe resultados com falha, bloqueados e desconhecidos, porque uma escrita desconhecida é a que mais chance tem de ser repetida por engano.
- Teste cada mensagem com quem vai lê-la sob pressão, e não apenas com a equipe que construiu a ferramenta.
Por que a maioria dos erros de agentes é difícil de agir
Um agente costuma funcionar como uma cadeia. Ele lê um pedido, consulta um cliente, verifica uma política, prepara uma ação e grava em um sistema. Quando um elo quebra, a saída padrão costuma ser um código de status ou um rastro técnico escrito para quem construiu a ferramenta. O gestor de operações que recebe o alerta então precisa responder perguntas que a mensagem deveria ter respondido: algo foi enviado, o registro mudou, e é seguro tentar de novo?
Erros pouco claros geram três custos que pesam no negócio. O trabalho para mais tempo do que precisaria, pessoas repetem ações que o agente talvez já tenha concluído, e a equipe deixa de confiar no agente e passa a fazer o trabalho à mão, em silêncio. Cada um desses problemas pode ser evitado com redação mais clara e roteamento melhor. Nenhum deles exige outro modelo de IA.
As três partes que toda mensagem de erro precisa ter
Cada mensagem deve trazer as mesmas partes, em linguagem simples. A etapa nomeia a ação de negócio, então «consultando o pedido no sistema de faturamento» é mais útil do que «get_invoice retornou 504». O registro identifica o objeto por uma referência estável, como número do pedido, número do chamado ou referência do contrato. O responsável nomeia o papel que decide o próximo passo, como o aprovador de faturamento ou o líder de atendimento.
Use este checklist ao escrever ou revisar uma mensagem:
- Etapa: a ação de negócio, descrita com as palavras que sua equipe usa.
- Registro: o identificador estável que alguém consegue buscar no sistema de origem.
- Estado: concluído, falhou sem efeitos ou desconhecido, sem deixar nada no palpite.
- Responsável: um único papel que decide a próxima ação, e não uma caixa compartilhada.
- Decisão: a pergunta única que esse responsável precisa responder.
- Próximo passo seguro: o que fazer agora, incluindo o que não fazer, como tentar de novo.
Cenário ilustrativo: um agente prepara um reembolso parcial do pedido 4471. Ele lê o pedido, calcula o valor e envia a solicitação ao provedor de pagamento, que não responde dentro do tempo permitido. Uma mensagem fraca diz «erro no reembolso, tempo esgotado». Uma mensagem útil diz: o reembolso do pedido 4471 parou na etapa de pagamento, o provedor não confirmou, então o reembolso pode ou não existir; não tente de novo até que o aprovador de faturamento verifique o registro no provedor. A segunda versão permite que o aprovador aja em poucos minutos, e não em uma hora.
Separe resultados com falha, bloqueados e desconhecidos
Três resultados parecem iguais em um log, mas exigem respostas diferentes. Uma etapa com falha recebeu uma recusa clara, então o agente pode registrar o motivo e parar. Uma etapa bloqueada nunca rodou porque faltava uma condição, como uma aprovação, um campo obrigatório do cliente ou um período fechado. Uma etapa desconhecida começou, mas não devolveu uma resposta confiável, geralmente depois de um tempo limite, e o sistema externo pode ter concluído o trabalho.
Trate o desconhecido como categoria própria. Não o marque como falha, porque uma nova tentativa pode duplicar a ação. Quando o sistema externo oferece suporte, o agente deve enviar uma chave de requisição estável, para que uma chamada repetida seja reconhecida e não executada duas vezes. Para o padrão de tempo limite com mais detalhes, leia Ações idempotentes em agentes de IA: evite reservas e faturas duplicadas.
Encaminhe cada erro para quem pode agir
Uma mensagem precisa, enviada à pessoa errada, ainda assim desperdiça tempo. Defina o roteamento antes da primeira falha e registre-o junto com os modelos de mensagem. Um guia prático de decisão fica assim:
- Se o agente não tem permissão ou credencial, encaminhe ao administrador do sistema que gerencia esse acesso, e nomeie a permissão que falta.
- Se os dados do registro se contradizem, encaminhe ao dono do processo daquele registro, e mostre os campos conflitantes lado a lado.
- Se um serviço externo está indisponível, segure a etapa afetada, deixe o agente seguir com trabalhos não relacionados e avise a operação com a lista de registros em espera.
- Se uma escrita terminou em estado desconhecido, encaminhe a quem pode consultar o sistema externo, e bloqueie novas tentativas até essa pessoa confirmar o resultado.
- Se o agente repete a mesma falha, pause aquela tarefa e escale ao líder de operações com o histórico da execução anexado.
Envie a decisão, não o log bruto. O responsável deve ver a pergunta, duas ou três opções e o registro, com o rastro completo a um clique de distância. O comportamento de contingência para cada rota deve ser desenhado antes, e o Plano de continuidade de negócios para agentes de IA: como agir em quedas mostra como definir o que o agente faz enquanto uma pessoa decide. O formato da passagem de bastão está detalhado em Escalonamento humano em IA: entregue a decisão necessária.
Como reescrever as mensagens atuais e testá-las
Você não precisa de um sistema novo para melhorar as mensagens. Precisa de uma revisão curta e disciplinada sobre as falhas que já existem.
- Reúna uma amostra de execuções recentes com falha nos seus logs, incluindo as que alguém teve de corrigir à mão.
- Agrupe as mensagens pelo problema de fundo, para reescrever o padrão uma vez, e não cada ocorrência.
- Reescreva cada mensagem com os seis campos do checklist, usando os nomes que sua equipe já usa para clientes, pedidos e áreas.
- Peça a uma pessoa da equipe responsável que leia cada mensagem e diga, sem ajuda, o que faria em seguida. Se ela hesitar ou perguntar a um colega, a mensagem não está pronta.
- Confirme que nenhuma mensagem sugere nova tentativa para um resultado desconhecido, e que toda mensagem ligada a escrita nomeia o sistema externo a ser consultado.
- Rode as mensagens revisadas em modo sombra antes de o agente ter permissão de escrita, para ver falhas reais sem consequências reais. O método está descrito em Modo sombra para agentes de IA: teste propostas antes de dar escrita.
Mantenha os modelos revisados no mesmo documento do guia de roteamento, para que o próximo engenheiro que alterar uma ferramenta atualize a mensagem também.
Como a Be Human trata isso em operações gerenciadas
Em um projeto gerenciado, a Be Human define com a sua equipe as categorias de falha e as regras de roteamento quando o primeiro papel é escopado, e escreve modelos de mensagem para cada ferramenta que o agente usa. Os limites de aprovação determinam qual responsável recebe cada classe de erro, e os logs mantêm o nome da etapa e o identificador do registro para que cada mensagem possa ser rastreada depois. Revisões mensais de permissões e incidentes verificam se o roteamento ainda corresponde a quem de fato detém cada decisão, e qualquer mudança em um modelo fica registrada nas notas operacionais. O objetivo é que a primeira pessoa que leia um alerta consiga agir sem reconstruir a execução.
Como escolher por onde começar
Comece pelo fluxo em que uma mensagem de erro pouco clara hoje custa mais tempo ou gera mais trabalho duplicado, porque é ali que um roteamento melhor se paga primeiro. Escreva os seis campos para as três falhas mais comuns desse fluxo, teste-os com as pessoas que são donas do trabalho e só então amplie o escopo. Se você ainda não sabe qual tarefa entregar primeiro a um agente, o diagnóstico gratuito de IA da Be Human foi pensado para ajudar você a encontrar a primeira tarefa que vale a pena delegar.
Perguntas frequentes
Um agente deve mostrar a saída técnica de erro para usuários de negócio? Não. A saída técnica pertence ao rastro que os engenheiros usam, enquanto a mensagem para o negócio deve traduzi-la em etapa, registro, estado e responsável. Mantenha o detalhe completo a um clique de distância, para que nada fique escondido durante uma investigação.
Quem deve receber os alertas de erro do agente? Envie cada alerta ao papel que pode tomar a próxima ação, e não a uma caixa compartilhada que todos supõem que outra pessoa acompanha. Alguns erros cabem a um administrador de sistema, outros a um dono de processo ou a um aprovador. Defina esse roteamento na fase de escopo e revise-o sempre que permissões ou responsabilidades da equipe mudarem.
É seguro deixar o agente tentar de novo depois de um erro? Depende do estado do resultado. Uma falha limpa, sem efeitos colaterais, normalmente pode ser repetida dentro de um limite definido. Um resultado desconhecido depois de uma escrita não deve ser repetido até que uma pessoa confirme o estado no sistema externo, a menos que a ação tenha sido desenhada para ser segura de repetir.
Como saber se uma mensagem de erro é boa o bastante? Peça a uma pessoa que é dona do processo para lê-la sem nenhum contexto extra e dizer o que faria em seguida. Se ela precisar abrir outra ferramenta, perguntar a um colega ou adivinhar se a ação aconteceu, a mensagem precisa de mais informação sobre etapa, registro, estado ou responsável. Repita essa checagem sempre que adicionar uma nova ferramenta.
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.


