Diagnosticar e corrigir falhas de um Agente de IA
Isole o sintoma, proteja o atendimento, confira agente, provedor, conhecimento, rotas e ferramentas e valide a correção antes de restaurar a operação.
Neste artigo
Antes de começar
- Acesso à configuração do Agente de IA e aos tickets de teste
- Fila humana de emergência ativa e com cobertura
- Permissão para consultar consumo e log de auditoria quando necessário
- Contato, canal e registros controlados para repetir o problema
- Credenciais protegidas e responsável por integrações externas identificado
Escolher a verificação pelo sintoma
- Não responde: comece por Perfil, vínculo com canal ou fluxo e Provedor.
- Responde com informação errada: confira a fonte em Conhecimento e as instruções do Perfil.
- Diz que vai transferir, mas continua respondendo: confira destinos e condições no Roteamento.
- Não registra ou consulta algo: confira a condição em Ações ou Ferramentas e o resultado no sistema de destino.
- Demora ou consome mais: confira atraso, modelo, contexto e chamadas no mesmo período.
Se clientes estão sendo afetados, contenha o impacto primeiro. Depois use a seção correspondente ao sintoma; não é necessário alterar todas as abas para investigar um caso.
Conter o impacto antes de investigar
- 1
Confirme se a falha ainda está afetando clientes ou alterando dados.
- 2
Quando houver risco, interrompa novas entradas e ações indevidas pelo procedimento aprovado. Desativar o agente não comprova que os tickets existentes foram transferidos.
- 3
Confira os tickets afetados, direcione-os à fila humana e confirme quem assumiu cada caso.
- 4
Preserve ticket, horário, mensagens e registros necessários para investigar sem compartilhar dados pessoais desnecessários.
- 5
Avise a operação sobre o alcance conhecido e registre quem está conduzindo a resposta.
Reunir evidências e classificar o sintoma
- 1
Anote número do ticket, horário, canal, agente esperado e resultado observado.
- 2
Identifique a primeira etapa com desvio e compare o horário com a última alteração na configuração.
- 3
Consulte notas do ticket, consumo e log de auditoria conforme as permissões disponíveis.
- 4
Escolha uma hipótese pelo sintoma e repita o mesmo roteiro em um cenário isolado, alterando um item por vez.
Corrigir quando o agente não responde


- 1
Em Perfil, confira Só base de conhecimento. Se estiver habilitado, a ausência de atendimento direto é esperada: mantenha o cadastro inativo e valide o uso do conteúdo pelo agente principal.
- 2
Para atendimento direto, confirme Só base de conhecimento desligado, Ativo ligado e vínculo do canal ou Chat Flow com o agente correto. Reabra a configuração salva para conferir; faça alterações somente no cenário de teste.
- 3
Em Provedor, confira se está selecionada Chave própria ou IA da plataforma, se há um modelo escolhido e se a configuração foi salva.
- 4
Em Chave própria, valide chave, endereço, modelo e permissão diretamente com o responsável pelo serviço, sem copiar o segredo para o ticket. Créditos de IA da plataforma não substituem saldo ou autorização dessa conta externa.
- 5
Em IA da plataforma, use Ver saldo e confira Créditos de IA > Consumo e a nota gerada na transferência à fila de emergência. Não é necessário preencher uma chave externa nessa modalidade.
- 6
Se a lista de modelos não aparecer em IA da plataforma, use o ícone de atualização ao lado de Modelo. Se continuar vazia, confirme disponibilidade e permissões com o administrador antes de mudar a modalidade ou gerar uma recarga.
- 7
Confirme se a fila de emergência existe, está selecionada e possui usuários disponíveis.
- 8
Em canal ou fluxo isolado, inicie uma conversa controlada e compare o novo ticket com o caso afetado.
Corrigir resposta incorreta ou conhecimento ignorado
- Confirme se Usar base de conhecimento está ligado e se a fonte necessária está ativa.
- Compare a resposta com o artigo, arquivo, link ou dado estruturado que deveria sustentá-la.
- Procure fontes duplicadas, regras vencidas e conteúdo contraditório.
- Verifique se um link já passou pela releitura periódica depois da atualização.
- Teste a pergunta pelo título, por um sinônimo e por uma frase incompleta para avaliar a busca.
- Se o conteúdo vem de outra base, confira o vínculo em Conhecimento > Usar também a base de outros agentes. Quando a conexão de IA é diferente, essa base usa busca por palavras; não presuma que Busca inteligente está sendo aplicada a ela.
- Separe erro factual de erro de comportamento: fatos pertencem à base; tom e limites pertencem às instruções.
- Corrija a menor fonte possível no cenário de teste e repita as perguntas que funcionavam antes. Uma base compartilhada pode afetar outros agentes: isole também a fonte antes de editá-la.
Corrigir transferência errada ou resposta junto com uma pessoa


- 1
Compare a frase do cliente com a descrição de todos os destinos disponíveis.
- 2
Torne Quando transferir específico e remova sobreposição entre fila, fluxo, pessoa e agente especialista.
- 3
Confirme horário, cobertura, permissão e disponibilidade do destino esperado.
- 4
Confira a Palavra de saída em Perfil e a fila de emergência em Roteamento; teste a palavra exata configurada.
- 5
Se agente e pessoa responderem juntos, suspenda o piloto e revise posse do ticket, bloqueio da automação e estado depois da transferência.
- 6
Teste uma frase inequívoca, uma ambígua e outra fora de todos os destinos.
- 7
Confirme que somente o novo responsável continua a conversa e que o contexto foi preservado.


Corrigir ação, webhook ou servidor MCP


- 1
Confirme se a condição da ação ou ferramenta corresponde ao texto usado no teste.
- 2
Valide campos obrigatórios, formato dos parâmetros, destino e permissão para executar o efeito.
- 3
Para webhook ou MCP, teste endereço, autenticação, disponibilidade e tempo de resposta.
- 4
No MCP, confira se a ferramenta foi publicada pelo servidor e aprovada na administração. Depois confira se o servidor correto foi adicionado em Ferramentas > Servidores MCP do agente.
- 5
Depois de salvar ou alterar o servidor MCP, aguarde até um minuto para a propagação antes de repetir o teste.
- 6
Confirme o resultado no contato, ticket, funil, agenda ou sistema externo; a mensagem de sucesso isolada não comprova a alteração.
- 7
Teste ausência de um parâmetro e pedidos fora do escopo somente no ambiente preparado para o piloto; a simulação de indisponibilidade deve ser feita pelo responsável técnico sem afetar serviços compartilhados.
Investigar lentidão ou aumento de consumo

- Confira Atraso na resposta em Perfil: Mínimo e Máximo usam segundos, com limite de 120 segundos. Campos vazios significam que não há espera adicional configurada; o processamento ainda leva tempo. Considere o intervalo configurado ao medir o tempo observado.
- Compare o período afetado com o volume de conversas e o consumo por chamada, quando disponível.
- Verifique mudança de modelo, quantidade de mensagens lembradas, tamanho das instruções, anexos e conteúdo enviado como conhecimento.
- Conte consultas a especialistas e chamadas de ferramentas necessárias à mesma resposta.
- Para integrações lentas, confirme o tempo na origem antes de apenas aumentar o limite de espera.
- Repita o mesmo roteiro com uma alteração por vez e compare qualidade, tempo e custo.
- Não remova contexto essencial somente para reduzir consumo; valide respostas, transferências e ações depois do ajuste.

Validar a correção e restaurar a operação
- 1
Documente a causa confirmada e a única alteração aplicada.
- 2
Repita o cenário que falhava e registre o resultado no destino adequado.
- 3
Execute perguntas e rotas que funcionavam antes para verificar regressões.
- 4
Teste conteúdo fora da base, palavra de saída, fila de emergência e retomada humana.
- 5
Peça revisão de outra pessoa quando a falha tiver afetado dados, clientes ou integrações.
- 6
Restaure o vínculo para um alcance pequeno e acompanhe os primeiros tickets.
- 7
Se o problema reaparecer, volte à configuração segura registrada e mantenha a operação na fila humana.
Preparar um encaminhamento técnico útil
- Informe ticket, data, horário, canal, agente, sintoma e resultado esperado.
- Descreva a última alteração conhecida e os testes já executados.
- Inclua mensagem de erro e captura apenas depois de ocultar contatos, credenciais e dados pessoais.
- Indique se o problema é reproduzível e se afeta um caso, um canal ou toda a operação.
- Liste o procedimento temporário usado para manter os clientes atendidos.
- Nunca envie senha, chave ou token; quando necessário, informe apenas tipo, ambiente e momento da validação.
Se ainda houver dúvida, continue pelos artigos relacionados abaixo.
