Quando um Procedure Fin não resolve uma conversa como esperado, você pode usar ferramentas de inspeção integradas para investigar a lógica de decisão do Fin. Use este guia para identificar onde o fluxo saiu do caminho e como refinar suas instruções.

O que você vai aprender

Depure falhas em Procedures usando os pensamentos do Fin e eventos da conversa.
Diagnostique problemas comuns como gatilhos errados de Procedure, passos fora de sequência e falhas em ramificações.
Solucione erros de conectores de Dados, incluindo falhas de autenticação e dados ausentes.
Valide correções antes de entrar em produção usando Simulações.

Acessando o depurador de conversas

Para entender por que o Fin tomou uma ação específica, você deve primeiro ativar a visibilidade técnica dentro do fio da conversa.

Abra a conversa específica na Inbox.
Clique no ícone de três pontos no canto superior direito do cabeçalho da conversa.
Selecione Mostrar eventos da conversa.

Dica: Use o atalho de teclado ⌘ + E (Mac) ou Ctrl + Shift + E (Windows) para alternar esta visualização.

Inspecionando os "pensamentos do Fin"

Uma vez que os eventos da conversa estejam visíveis, você pode ver o raciocínio por trás de cada passo que o Fin tomou durante um Procedure. Para rastrear o processo de decisão do Fin, localize os eventos pensamentos do Fin na linha do tempo da conversa. Esses eventos resumem o raciocínio do Fin antes de enviar uma mensagem ou executar uma ação.

Para detalhes mais granulares, clique em Fin Thoughts e depois em Ver mais. Isso revela:

O passo atual: O passo específico do Procedure que o Fin estava executando.
Interpretação da intenção: Como o Fin entendeu a solicitação do cliente.
Caminho lógico: Por que o Fin decidiu pular um passo, revisitar um anterior ou seguir para um ramo específico.

Importante: Este artigo cobre solução de problemas apenas para Procedures Fin. A linha do tempo e o depurador dos "pensamentos do Fin" estão disponíveis somente quando um Procedure foi acionado. Se o Fin deu uma resposta inesperada em uma conversa padrão, essas ferramentas não estarão presentes nos eventos da conversa.

Falhas comuns em Procedures

Se o Fin não está funcionando como esperado, geralmente é devido à forma como as instruções são formuladas ou como a lógica é ramificada.

Procedure não está sendo acionado

Antes de revisar as falhas numeradas abaixo, revise primeiro estes conceitos básicos:

Verifique se o procedure está publicado: Procedures em rascunho não serão acionados para clientes. Confirme que o status está definido como Publicado no editor.
Verifique se o Simple Deploy está ativo: Se o Simple Deploy estiver desligado, o Fin não executará nenhum procedure. Vá para Fin AI Agent > Deploy > Chat e confirme que o Fin está habilitado.
Verifique o direcionamento do público: Um erro comum é direcionar para Users quando o cliente é um Lead (ou vice-versa). Na seção "Quando usar este procedure", clique no botão de público e verifique se o tipo de público e o canal corretos estão selecionados.
Verifique se há workflows de prioridade mais alta: Workflows ativos são executados antes do Fin avaliar a intenção do procedure. Revise seus workflows para garantir que nenhum esteja interceptando a conversa antes que o Fin possa acionar o procedure.
Revise o escopo dos critérios de gatilho: Critérios muito restritos impedem que o Fin corresponda a mensagens válidas do cliente. Verifique a descrição "Quando usar este procedure" e adicione exemplos positivos (mensagens que devem acioná-lo) e exemplos negativos (mensagens que não devem).

1. Fin aciona o procedure errado

Problema: O Fin inicia um procedure que não corresponde à solicitação do cliente.

Solução: Revise suas instruções "Quando usar este procedure". Use exemplos positivos e negativos para ajudar o Fin a distinguir entre intenções semelhantes. Se um novo procedure compartilhar critérios de gatilho semelhantes com um procedure publicado existente, o publicado pode ter prioridade. Para isolar o novo procedure durante o teste: exclua temporariamente seu usuário de teste do procedure existente ajustando seus critérios de público, ou restrinja o gatilho do novo procedure a uma frase única que só você enviaria. Use pensamentos do Fin > Expandir pensamentos no depurador de conversas para confirmar qual procedure foi realmente acionado.

2. Passos fora de sequência

Problema: O Fin pula um passo pré-requisito ou avança para uma resolução prematuramente.

Solução: Verifique se há ambiguidade em suas instruções em linguagem natural. Se um passo depende de um dado específico, certifique-se de que a instrução declare explicitamente: "Só prossiga se [dado] for fornecido."

3. Falhas na lógica de ramificação

Problema: O Fin segue o caminho "Else" quando deveria ter seguido o caminho "If".

Solução: Inspecione as Condições. Se estiver usando linguagem natural para ramificação, tente reformular para maior clareza. Para lógica complexa (ex.: cálculos de datas), considere usar blocos de código Python para impor regras determinísticas estritas.

4. Conteúdo do Help Center tendo prioridade

Problema: O Fin responde a partir do Help Center em vez de executar o procedure, mesmo quando a intenção do cliente corresponde claramente aos critérios de gatilho do procedure.

Solução: Se o Fin está padrão para uma resposta do Help Center em vez de executar o procedure, existem duas abordagens dependendo da sua configuração. Tente a Opção 1 primeiro — se o problema persistir, passe para a Opção 2.

Opção 1: Ativar a Troca de Procedure
Agentic Switch é uma configuração por procedure que permite ao Fin alternar automaticamente do procedure atual para outro procedure ativo quando detecta que a intenção do cliente mudou no meio da conversa — em vez de ficar preso ao procedure original ou voltar para uma resposta do Help Center. Quando ativado:
- O Fin revisa a conversa e todas as descrições de gatilho dos procedures ativos para decidir quando a troca beneficiaria mais o cliente
- Se múltiplos procedures puderem se aplicar, o Fin pode fazer uma pergunta de esclarecimento para selecionar o melhor
- Apenas o procedure de origem (do qual o Fin está alternando para fora) precisa da configuração ativada
- O comando @Switch ainda pode ser usado para alternar manualmente
Para ativar: Fin AI Agent > Train > Procedures > Settings > Agentic Switch

Opção 2: Remover ou atualizar conteúdo conflitante do Help Center
Se habilitar o Agentic Switch não resolver o problema, a solução mais confiável é remover ou atualizar o conteúdo do Help Center que o Fin está exibindo em vez de executar o procedimento. O Fin usa respostas do Help Center por padrão quando há conteúdo relevante para um tópico — então, se um artigo cobre a mesma intenção que seu procedimento, o Fin pode responder diretamente a partir dele em vez de acionar o procedimento.

Para identificar o conteúdo conflitante:
- Encontre a conversa na sua Inbox e abra os pensamentos do Fin.
- Procure referências a artigos do Help Center no caminho da resposta.
- Remova o artigo conflitante ou atualize-o para direcionar os clientes a contatar o suporte, para que o Fin encaminhe para o procedimento em vez disso.

Exemplo: Uma empresa tem um procedimento que lida com pedidos de reembolso - ele coleta o número do pedido, verifica a elegibilidade e processa o reembolso automaticamente. Eles também têm um artigo do Help Center intitulado "Como faço para obter um reembolso?" que explica a política de reembolso. Quando um cliente envia a mensagem "Gostaria de um reembolso", o Fin encontra o artigo do Help Center e responde com a explicação da política em vez de acionar o procedimento. Nesse caso, atualizar o artigo para dizer algo como "Para solicitar um reembolso, inicie um chat e nosso assistente irá guiá-lo" remove a resposta conflitante e encaminha os clientes para o procedimento em vez disso.

5. O procedimento trava ou sai antes de completar

Problema: O procedimento chega a uma determinada etapa e para, ou sai para um estado final sem completar todas as etapas esperadas.

Solução: Isso geralmente é causado por padrões de design que confundem a capacidade do Fin de rastrear onde ele está no procedimento. Verifique o seguinte:

Declarações redundantes "Proceda imediatamente": Se várias etapas incluem instruções como "prossiga imediatamente para a próxima etapa", o Fin pode reavaliar etapas já concluídas em vez de avançar. Remova essas declarações e deixe o Fin avançar naturalmente pelo procedimento com base no fluxo.
Instruções de pular etapas: Frases como "volte para a etapa 2" ou "repita a etapa de verificação" podem fazer o Fin entrar em loop entre as etapas em vez de avançar. Projete cada etapa para que haja um caminho claro para frente.
Lógica de condição sobreposta: Se duas condições podem ser verdadeiras ao mesmo tempo, o Fin pode ramificar de forma imprevisível ou travar. Certifique-se de que suas condições sejam mutuamente exclusivas — apenas um ramo deve ser verdadeiro em qualquer momento.
Saídas de subprocedimento sem continuação: Se um subprocedimento é concluído, mas o procedimento principal não tem uma instrução clara sobre o que fazer em seguida, o Fin pode tratar o fim do subprocedimento como o fim de todo o fluxo. Na etapa que chama o subprocedimento, adicione uma instrução explícita: "Uma vez que o subprocedimento esteja completo, continue para [nome da próxima etapa]."

Use os pensamentos do Fin > Ver mais no depurador de conversas para identificar exatamente em qual etapa o Fin estava quando o procedimento saiu inesperadamente.

Solução de problemas de conectores de dados

Esta seção cobre falhas específicas de conectores de dados que rodam dentro de um Procedimento. Se seu conector passa em testes independentes, mas falha durante uma execução ao vivo do Procedimento, comece aqui.

Conector funciona no teste, mas falha em um Procedimento ao vivo

Problema: O conector passa nos testes independentes, mas falha durante uma execução ao vivo.

Solução: Isso geralmente é causado por um dos seguintes:

Credenciais: Re-salve e republicar após rotacionar uma chave. Verifique se há caracteres ocultos, como espaços finais nos valores do token.
Permissões: Uma mudança recente de segurança no seu sistema externo pode ter removido o acesso.
Lista de IPs permitidos: Confirme se os IPs de saída do Intercom estão incluídos. Contate seu gerente de conta para os intervalos atuais.

Importante: Se seu conector parar de funcionar sem alterações do seu lado, verifique se seu provedor externo de API (por exemplo, Shopify, Stripe) atualizou ou descontinuou um endpoint.

Erros de autorização 401 e 403

401 Não autorizado: O token está ausente, expirado ou malformado. O Intercom tenta novamente automaticamente uma vez. Verifique a aba Logs para confirmar se uma atualização foi tentada.
403 Proibido: O token é válido, mas não tem permissão. Revise as permissões no seu sistema externo.
Usuários OAuth: Use o botão Reautenticar em vez de deletar e recriar o token.

Conector não parece estar acionando

Verifique os logs: Navegue até Configurações > Integrações > Conectores de dados > Logs. Se não houver entrada de log, a etapa provavelmente foi pulada; verifique a lógica do ramo anterior.
Verifique os eventos da conversa: Selecione Logs de qualquer evento de erro na Inbox para detalhes completos.

Conector retorna dados, mas o Fin não os usa

Use os pensamentos do Fin para ver como o Fin interpretou a resposta do conector.
Torne a instrução da etapa mais explícita: "Use @connector_name para responder a isso — não use conteúdo da knowledge base."
Verifique se a resposta está vazia ou nula; o Fin pode recorrer a outras fontes se nenhum dado utilizável for encontrado.
O Fin chama um conector por vez: Se seu procedimento precisa fazer várias chamadas de conector em sequência, cada chamada deve ser uma etapa distinta. O Fin processa uma chamada de ferramenta por turno de conversa — não pode encadear múltiplas chamadas de conector dentro de uma única instrução de etapa.

Importante: O Fin só pode processar uma chamada de conector por turno, então se seu servidor MCP enviar duas respostas separadas pelo mesmo fluxo SSE, o Fin não poderá usar de forma confiável a primeira resposta para construir sua resposta.

Conector não aparece no editor de procedimentos

Problema: Seu conector de dados está publicado e configurado, mas não aparece quando você tenta adicioná-lo a uma etapa dentro do editor de procedimentos.

Solução: Siga estas verificações na ordem:

Confirme que o conector está definido como Ao Vivo: Vá para Configurações > Integrações > Conectores de dados e verifique o status do conector. Um conector em Rascunho não aparecerá no editor de procedimentos.
Verifique se pelo menos uma ação está configurada: Um conector sem ações definidas não aparecerá como opção no editor de procedimentos, mesmo que esteja Ao Vivo.
Verifique as permissões do seu papel: Alguns papéis podem ver conectores em Configurações, mas não têm acesso a eles dentro do editor de procedimentos. Confirme se seu papel tem acesso a ambas as áreas.
Atualize a página: O editor de procedimentos às vezes precisa de uma atualização forçada para refletir conectores publicados recentemente. Use ⌘ + Shift + R (Mac) ou Ctrl + Shift + R (Windows).
Contate o Suporte Intercom: Se nada disso resolver, entre em contato com o Suporte Intercom com o nome do conector e os detalhes do seu workspace. Algumas configurações de workspace exigem uma etapa manual para tornar um conector disponível dentro do editor de procedimentos.

Conector falha no modo de execução automática

Problema: O conector de dados está configurado para rodar automaticamente — sem solicitar ao cliente — mas falha silenciosamente durante uma conversa ao vivo. O Fin escala ou dá uma resposta inesperada, e não há erro visível na conversa.

Solução: No modo de execução automática, o Fin não pode pular uma etapa de conector que falhou e continuar o procedimento. Se o conector retornar um erro, o Fin trata toda a etapa como irresolúvel e ou escala para um humano ou recorre ao seu comportamento padrão.

Existem duas formas de lidar com isso:

Modifique sua API externa para retornar um valor de fallback: Em vez de retornar um erro quando os dados não estiverem disponíveis (por exemplo, um 404 quando um pedido não for encontrado), configure sua API para retornar um resultado vazio ou padrão que o Fin possa usar. Esta é a solução mais confiável porque o Fin sempre recebe algo com que possa trabalhar.
Adicione uma etapa de Condição após a chamada do conector: Use a saída status_code do conector para ramificar para uma mensagem amigável ou um caminho de escalonamento controlado quando o conector falhar. Veja "Manipulação avançada de falhas com status_code" neste artigo para saber como configurar isso.

A saída do conector não preenche os atributos da conversa

Problema: Uma etapa do conector de dados é executada e retorna os dados esperados, mas o valor não aparece como um atributo da conversa — e etapas posteriores no procedimento não conseguem acessá-lo.

Solução: Os atributos da conversa são definidos no início de uma conversa e não podem ser atualizados em tempo real enquanto um procedimento está em execução. Um conector executando dentro de um procedimento não pode gravar um novo valor em um atributo da conversa no meio da conversa.

O que isso significa na prática:

Use a saída do conector diretamente em etapas posteriores: Os dados que seu conector retorna estão disponíveis como saída de etapa dentro do procedimento. Faça referência a eles nas instruções das etapas subsequentes usando a sintaxe de saída @connector_name. O valor é acessível dentro do procedimento — ele simplesmente não aparecerá como um atributo da conversa no Inbox.
Para persistir dados em um atributo da conversa: Use uma etapa Handoff to workflow e defina o valor do atributo dentro do workflow em vez disso. Note que o procedimento não continuará após o handoff, então planeje seu fluxo para concluir antes de fazer o handoff.

Conector de dados configurado para READ em vez de UPDATE

Problema: O procedimento é executado, mas não coleta ou armazena a entrada do cliente, mesmo que a etapa do conector de dados pareça ser executada.

Solução: Verifique o tipo de ação do conector de dados na etapa relevante. READ apenas verifica um valor armazenado existente — não solicitará entrada do cliente nem salvará novos dados. UPDATE coleta a entrada do cliente e a salva no atributo. Se seu procedimento deve coletar informações do cliente (por exemplo, um endereço de e-mail, número do pedido ou motivo do contato), altere o tipo de ação para UPDATE.

Manipulação avançada de falhas com status_code

O status_code retornado por uma chamada do conector de dados é exposto como um atributo de saída. Você pode referenciá-lo em uma etapa Condition step para ramificar com base em códigos de resposta HTTP específicos, dando controle preciso sobre como o Fin lida com diferentes cenários de falha em vez de depender de um único ramo de sucesso/falha.

Por exemplo, você pode direcionar um 404 (recurso não encontrado) para uma mensagem diferente de um 500 (erro do servidor), ou escalar para um agente humano somente quando um código de erro específico for retornado.

Dica: Veja Como escrever condições de código para Fin Procedures para exemplos de código usando status_code em uma etapa Condition.

Validando correções com Simulations

Antes de colocar seu Procedure ao vivo, use Simulations para verificar a correção:

Preview vs. Simulations — qual devo usar? Preview mostra a experiência completa para o cliente. Usar Preview enquanto seu procedimento está ao vivo pode expor mensagens de etapas para clientes reais. Simulations executam o procedimento em segundo plano sem saída para o cliente — são a maneira mais segura de validar a lógica e o disparo de correspondência antes de entrar ao vivo.

Navegue até o editor de Procedure e clique em Test.
Execute uma Simulation onde a IA atua como o cliente no cenário de falha.
Revise o resultado de aprovação/reprovação e o julgamento da IA para confirmar que a lógica é confiável.

FAQs

O depurador de conversa funciona para conversas padrão do Fin?

Não, a linha do tempo e o depurador "Fin's thoughts" estão disponíveis apenas quando um Procedure foi acionado. Se o Fin deu uma resposta inesperada em uma conversa padrão, essas ferramentas não estarão presentes — verifique os eventos da conversa no Inbox em vez disso.

Por quanto tempo os logs do conector de dados são armazenados?

Os logs de resposta do conector de dados são armazenados por até 7 dias por padrão. Se seu workspace tiver logs estendidos ativados, isso aumenta para 14 dias. Acesse-os em Settings > Integrations > Data connectors > Logs.

Posso usar Simulations para testar respostas do conector de dados?

Sim — Simulations executam o Procedure completo, incluindo quaisquer etapas do conector de dados, tornando-os a maneira mais confiável de validar o comportamento do conector antes de entrar ao vivo.

Por que meu Procedure está sendo bloqueado por um Workflow?

Workflows são executados antes do Fin avaliar a intenção do procedimento. Se um Workflow estiver ativo para o mesmo gatilho de conversa, ele pode direcionar a conversa antes que o Fin tenha a chance de corresponder a um procedimento. Para corrigir isso: revise seus workflows ativos para gatilhos sobrepostos e garanta que o bloco Let Fin Handle esteja configurado corretamente no caminho do workflow onde você deseja que os procedimentos estejam disponíveis.

Por que meu Procedure fez handoff para um humano inesperadamente?

Existem duas maneiras de um Procedure fazer handoff para um humano:

Comportamento padrão de escalonamento — Fin escala automaticamente com base em sua lógica interna: quando um cliente claramente pede para falar com um humano, quando o Fin detecta forte frustração ou raiva, ou quando o cliente está preso em um loop repetitivo. Isso sempre ocorre independentemente de como seu Procedure está configurado.
Handoff configurado — Uma etapa Handoff to team que você adicionou em um ponto específico do Procedure, ou orientação específica do Procedure que você escreveu que instrui o Fin a fazer handoff em um cenário particular.

Se o handoff foi inesperado, use Fin's thoughts no depurador de conversa para ver qual tipo foi acionado e em qual etapa.

Por que minha Escalation Guidance não está funcionando dentro de um Procedure?

A Escalation Guidance não se aplica dentro de um Procedure por padrão — você precisa habilitá-la explicitamente no painel Guidance do Procedure:

Abra seu Procedure, clique na engrenagem de configurações no canto superior direito do editor de Instructions e clique em Guidance.
Selecione as categorias de orientação em nível de workspace que deseja aplicar, incluindo Handover and escalation.
O Fin combinará a orientação selecionada do workspace com qualquer orientação personalizada específica do Procedure que você tenha escrito.

Nota: O comportamento padrão de escalonamento do Fin (cliente pede um humano, frustração detectada, loop repetitivo) sempre ocorre dentro de um Procedure independentemente das configurações de Guidance. O painel Guidance controla apenas sua Escalation Guidance e Regras de Escalonamento em nível de workspace.

Qual a diferença entre Handoff to team e Handoff to workflow?

Ambas as etapas terminam o Procedure, mas direcionam a conversa de formas diferentes:

Handoff to team — Termina o Procedure e entrega a conversa a um colega humano. A conversa então segue o caminho de escalonamento configurado no seu workflow Deploy após a etapa Let Fin handle (bloco Let Fin handle).
Handoff to workflow — Termina o Procedure e passa a conversa para um Workflow reutilizável específico que você já criou (por exemplo, uma pesquisa de satisfação ou um fluxo de roteamento especializado). O Procedure não continuará após o Workflow ser concluído.

Um handoff de Procedure é cobrado como um Fin Outcome?

Um Procedure do Fin é cobrado como um Fin Outcome apenas quando a conversa termina de duas maneiras:

Resolução — o cliente confirma que o Fin resolveu seu problema, ou não pede mais ajuda após o Fin responder.
Procedure Handoff — Fin faz handoff para uma equipe, colega ou workflow via uma etapa de Handoff configurada ou orientação específica do Procedure que você configurou.
Em ambos os casos, você é cobrado $0,99 — e apenas uma vez por conversa, independentemente de quantas etapas o Fin executou ou quantas perguntas o cliente fez.

Nota: Você não será cobrado se um Procedure não for concluído, sair sem alcançar um desses resultados, um cliente pedir para falar com um humano a qualquer momento, ou a conversa terminar pelo comportamento padrão de escalonamento do Fin ou regras de escalonamento em nível de workspace.

Para detalhes completos, veja Entendendo Fin Outcomes.

Meu Procedimento para no meio da conversa — pode ser um tempo limite?

Sim. Os Procedimentos são executados dentro de um bloco Let Fin Handle no seu Workflow, e esse bloco tem um tempo limite padrão de inatividade. Se um cliente demorar mais que isso para responder, o bloco pode fechar antes do procedimento ser concluído. Para corrigir, abra o bloco Let Fin Handle nas configurações do seu Workflow e aumente o tempo limite de inatividade para corresponder melhor à duração esperada da conversa.

Posso usar Guidance para acionar um Procedimento?

Não. Guidance controla como Fin responde e se comporta — não pode iniciar um procedimento nem direcionar uma conversa para um. Os dois sistemas são separados: Guidance molda o tom e as regras de escalonamento do Fin; Procedimentos definem os workflows passo a passo que Fin segue quando uma intenção específica é identificada.

Para mudar de um procedimento para outro no meio da conversa, use o comando @Switch dentro do procedimento de origem, ou ative Agentic Switch nas configurações do procedimento (veja "4. Help Center content taking priority" neste artigo).

Se você quer que Fin decida inteligentemente quando chamar um conector de dados ou seguir um fluxo específico baseado no que o cliente diz, construa essa lógica em um procedimento em vez de usar guidance.

Minha condição de código não está ramificando — como faço para depurá-la?

Condições de código falham silenciosamente quando há um erro de sintaxe ou quando o caminho de dados que você está tentando acessar não existe no contexto da conversa. Fin não exibirá o erro diretamente — ele apenas seguirá o ramo Else ou travará. Veja como diagnosticar:

Abra a conversa no Inbox e ative Mostrar eventos da conversa (veja "Accessing the conversation debugger" acima).
Em Fin's thoughts, verifique qual valor Fin recebeu como entrada para sua condição. Se o valor for null ou undefined, o caminho de dados no seu código está incorreto.
Verifique estes padrões comuns de acesso a dados: • Tipo de cliente: inputs["user"]["role"] — retorna "user" ou "lead" • Saída do conector: use o nome exato do campo do esquema de resposta do seu conector • Atributo da conversa: inputs["conversation"]["attribute_name"]
Teste seu bloco de código em um interpretador Python antes de adicioná-lo ao procedimento. Isso detecta erros de sintaxe imediatamente, sem precisar executar uma conversa ao vivo.
Se a condição for avaliada mas direcionar para o ramo errado, adicione uma instrução print() no seu bloco de código para registrar o valor real que Fin está recebendo. A saída aparecerá nos eventos da conversa.

Solução de Problemas em Procedures Fin e conectores de Dados