Principal Boas práticas na construção de Fluxos Controlados Como identificar e evitar falhas nos fluxos e requisições do Fluxo Controlado

Como identificar e evitar falhas nos fluxos e requisições do Fluxo Controlado

Última atualização em Jun 24, 2026

Quando usar

  • Você está construindo um Fluxo Controlado e quer conhecer os modos de falha mais comuns
  • Você teve um timeout ou cancelamento de requisição e quer entender por que
  • Você quer mitigar falhas com fallback adequado e tratamento de erros

Pré-requisitos

  • Acesso ao Hub do projeto ClaudIA para investigação de logs
  • Conhecimento básico de construção de fluxos no Fluxo Controlado

Sobre este artigo

Para garantir um atendimento eficiente e fluido, é essencial entender os principais modos de falha que podem ocorrer nos Fluxos Controlados e na comunicação entre o Fluxo Controlado e a ClaudIA. Identificar e mitigar essas falhas permite aprimorar a experiência do cliente e evitar interrupções indesejadas.

Detalhes

Timeout e cancelamento de requisição

A comunicação entre ClaudIA e o Fluxo Controlado precisa ser rápida e eficiente para garantir um atendimento fluido. Existe uma limitação de tempo para a execução de cada requisição. Se esse tempo for ultrapassado, a requisição é cancelada automaticamente, interrompendo o fluxo.

Como funciona o timeout

  • Quando a ClaudIA chama um Fluxo Controlado, a execução das ações dentro do fluxo deve ocorrer em até 45 segundos

  • Esse limite existe para garantir que a conversa aconteça em tempo real, sem atrasos perceptíveis

  • Se uma requisição demorar mais, o Fluxo Controlado não consegue completar a ação — a operação é cancelada e a ClaudIA fica sem resposta

Limite duro: 45 segundos por requisição. Acima disso, cancelamento automático.

Principais causas de timeout e cancelamento

1. APIs com tempo de resposta alto

Quando o fluxo faz uma chamada a uma API externa, o tempo de resposta pode ultrapassar o limite. Algumas APIs não são otimizadas para consultas rápidas.

Como evitar:

  • Use APIs com tempo de resposta rápido (idealmente menos de 2-3 segundos)

  • Priorize APIs assíncronas ou com respostas em cache

  • Para APIs lentas, divida a requisição em partes menores ou use soluções intermediárias (como armazenar dados temporários)

2. Falha no retrieval

Pode acontecer por erro de configuração, alterações recentes no fluxo ou falha na indexação de dados.

Como mitigar: revise e teste regularmente os conteúdos anexados ao fluxo.

3. Erro de execução interna no Fluxo Controlado

O Fluxo Controlado pode apresentar falhas internas que impedem a execução correta. Causas comuns:

  • Configurações incorretas

  • Blocos mal estruturados

  • Uso inadequado de condições lógicas (IF/ELSE)

Como mitigar:

  • Teste cada fluxo antes da publicação

  • Revise os logs de erro no Hub quando ocorrer

4. Erro na execução de integrações

Integrações externas (chamadas de API, Google Sheets) podem retornar mensagens de erro ou falhar completamente. Quando isso acontece, o Fluxo Controlado pode seguir um caminho incorreto ou não responder ao cliente.

Como mitigar: configure tratamentos de erro adequados:

  • Retornar uma mensagem explicativa para o cliente

  • Escalar o atendimento para um agente humano (N2)

5. Fluxo incorreto de execução

Em fluxos que usam LLMs (GPT) para definir a rota, pode haver falhas na escolha do próximo passo. Isso ocorre quando a interpretação do modelo leva a um caminho inesperado ou quando as condições não estão bem definidas.

Como evitar:

  • Defina prompts claros e bem estruturados

  • Configure respostas condicionais para diferentes cenários

  • Teste variações do fluxo para garantir previsibilidade

Falha total do Fluxo Controlado

Em casos extremos, o Fluxo Controlado pode falhar completamente, impedindo a continuidade do fluxo. Para evitar que o cliente fique preso, existe uma feature de segurança que escala automaticamente a conversa para N2.

Mesmo em cenário de falha geral, o atendimento ao cliente não é interrompido — a feature de fallback garante a continuidade via N2.

Observações