SyncroCentral de Ajuda
No results found
Acessar Syncro

Transferir para Agente IA

Updated on April 30, 2026

Padrão recomendado de atendimento: bot qualifica + IA conversa. Cliente abre conversa, bot pergunta nome/e-mail/interesse, e quando dados estão coletados, transfere pra IA que assume com contexto. Esse artigo explica como configurar a transferência via action assign_ai_agent.

Pré-requisitos

Como adicionar action assign_ai_agent

  1. Em /chatbot/fluxos/{flow}/editar, abra o builder.
  2. Sidebar → arraste Ação pro canvas.
  3. Conecte ao nó anterior (geralmente último input/condição antes de transferir).
  4. Clique no nó Ação → painel direito abre.
  5. Tipo de ação: selecione Atribuir Agente IA.
  6. Agente IA: dropdown lista todos agentes ativos do tenant. Escolha o desejado.
  7. (Opcional) Adicione mensagem de transferência num nó Mensagem antes da Action — ex: "Te conectei com Camila, nossa especialista. Ela vai cuidar daqui pra frente. 😊".
  8. Salve fluxo.
📸 PRINT necessário: builder com nó "Ação: Atribuir Agente IA" + dropdown de agentes

O que acontece no momento da transferência

Quando o nó action assign_ai_agent executa:

  1. Valida o agente:
  • Existe no tenant?
  • Está ativo (is_active=true)?
  • Pertence ao tenant correto?
  • Se algum check falha, ação é ignorada e bot tenta seguir pro próximo nó.
  1. Incrementa flow.completions_count (analytics — bot completou seu propósito).
  2. Atualiza conversa:
  • ai_agent_id = X (ID do agente).
  • chatbot_flow_id = NULL (limpa bot).
  • chatbot_node_id = NULL.
  • chatbot_variables = NULL.
  1. Cria evento na timeline (visível no chat): "Bot atribuiu conversa ao agente Camila" (mensagem com type='event', sent_by='chatbot').
  2. Dispara IA imediatamente via ProcessAiResponse::process:
  • IA lê histórico completo da conversa (incluindo o que bot perguntou e cliente respondeu).
  • IA gera saudação contextualizada.
  • Mensagem da IA é enviada ao cliente.
  1. Loop do bot para automaticamente — o ProcessChatbotStep detecta chatbot_flow_id=null e retorna.

Mutual exclusion

Conversa não pode ter chatbot_flow_id E ai_agent_id ao mesmo tempo. Sistema garante isso via trait EnforcesExclusiveHandler — qualquer tentativa dispara DomainException.

A action assign_ai_agent respeita o invariante: limpa o bot antes de setar a IA.

Veja Chatbot vs Agente IA pra entender por quê.

Contexto preservado

Quando IA assume, o que ela vê:

✅ Histórico completo de mensagens — todas as interações do cliente com o bot ficam visíveis no WhatsappMessage. IA lê e entende.

✅ Lead vinculado — IA tem acesso aos dados do lead (nome, email, tags, custom fields, etapa do funil).

✅ Variáveis de sistema — $contact_name, $lead_stage_name, etc continuam válidas.

❌ Variáveis de sessão do bot (vars[nome], vars[interesse]) NÃO são preservadas. Sistema limpa pra evitar conflito de estado.

Como passar dados do bot pra IA

Pra preservar dados estruturados capturados pelo bot, salve no lead antes de transferir:

Estratégia 1 — Custom field

Antes do assign_ai_agent, adicione action set_custom_field:

{
 "type": "set_custom_field",
 "field_name": "interesse",
 "value": "{{interesse}}"
}

IA depois consulta o custom field via tool get_lead_data.

Veja Campos personalizados.

Estratégia 2 — Tag

Pra dado simples (categorização), use tag:

{
 "type": "add_tag",
 "value": "interessado-curso-{{interesse}}"
}

IA vê tags no contexto e usa.

Estratégia 3 — Atualizar lead direto

Pra nome e email, action set_custom_field ou update_lead (via webhook custom):

{
 "type": "save_variable",
 "variable": "lead_data_for_ai",
 "value": "{{nome}} | {{email}} | {{interesse}}"
}

Mensagem do nó End (antes da transfer) pode ser: "Repassei seus dados ({{nome}}, {{email}}, {{interesse}}) pra nossa especialista.". IA lê o histórico e captura.

Mensagem de transferência (opcional)

Recomendado: avisar o cliente antes de transferir. Cria expectativa de continuidade.

Adicione um nó Mensagem antes da action:

"Pronto, {{nome}}! Vou te conectar com a Camila, nossa especialista. Ela já está atendendo." 🤝

Aí action assign_ai_agent. IA assume e manda saudação:

"Olá, {{nome}}! Vi que você está interessado em {{interesse}}. Posso te ajudar a entender melhor as opções."

Validar que IA assumiu

Após transferência, verifique no /chats:

  1. Conversa em questão.
  2. Header da conversa mostra:
  • Avatar do agente IA.
  • Nome do agente (ex: "Camila").
  • Sem badge de chatbot.
  1. Próximas mensagens outbound têm badge "IA" (animação pulse na primeira).
📸 PRINT necessário: header da conversa com avatar Camila + badge IA na bolha

Erros comuns

"Action executou mas IA não respondeu"

Possíveis causas:

  • Agente IA está inativo (is_active=false). Sistema não dispara.
  • Cota de tokens IA esgotada (tenant.ai_tokens_exhausted=true). IA fica bloqueada — recarregue tokens.
  • Agno service down (sistema de IA fora do ar). Verificar health check.
  • API Key OpenAI inválida (config no master). Contate suporte.

"IA respondeu mas com saudação genérica"

IA não leu o histórico ou cota foi atingida e fallback genérico foi usado. Verifique:

  • agent.use_agno=true (RAG ativo).
  • Histórico tem mensagens (não foi limpo).
  • Logs do Agno (canal agno).

"Bot continuou rodando depois da action"

Bug improvável — sistema garante chatbot_flow_id=null após action. Se acontecer, contate suporte com conversation_id.

"Action falhou silenciosamente"

Causa: agente IA selecionado não existe mais ou foi desativado. Action ignora e bot tenta seguir.

Solução: ao desativar/excluir um agente, revise os fluxos que apontam pra ele.

Edge cases

Cliente responde antes da IA processar

Mensagem nova chega na conversa. IA tá com ai_agent_id setado mas ProcessAiResponse não terminou ainda.

Sistema usa debounce + lock: se IA está processando, nova mensagem agrupa no batch atual (espera response_wait_seconds).

Cliente recusa atendimento da IA

IA tá conversando. Cliente diz: "Quero falar com humano".

IA detecta intent → action assign_human (via tool dela). Atribui pro user. IA encerra. Atendente assume.

Veja Tools do agente.

Cota IA esgota DURANTE a transferência

Bot transfere → IA tenta responder → cota acaba → IA não responde → cliente fica esperando.

Modal de upsell aparece pro admin em /ia/agentes quando cota esgota. Compre tokens pra restaurar atendimento.

Chatbot reaparece depois

Não acontece automaticamente. Pra voltar pro bot, admin manual via dropdown da conversa. Variáveis bot perdidas.

Quando NÃO transferir pra IA

❌ Após cliente concluir tarefa fim

Bot agendou consulta → finaliza com nó End. Não precisa de IA — cliente já tem o que queria.

❌ Após cliente comprar/converter

Pedido feito → atendente humano cuida. Action assign_human, não assign_ai_agent.

❌ Cliente reclama do bot

Cliente irritado: "Esse bot é horrível!". Direto pra humano (assign_human), não IA. IA não é solução pra frustração — humano resolve mais rápido.

❌ Plano sem cota IA suficiente

plano Trial não tem IA inclusa. Bot deve atender sozinho ou transferir direto pra humano.

Boas práticas

1. Transfira após coletar mínimo necessário

Bot pode pegar: nome, e-mail/telefone, intenção principal. Aí transfere. IA tem contexto suficiente.

2. Mensagem de transferência clara

Cliente quer saber o que aconteceu. "Vou te conectar com X" > "Aguarde".

3. Agente IA bem treinado

Veja Base de conhecimento RAG — IA precisa ter conhecimento real pra brilhar.

4. Tag o lead antes

Ajuda a separar leads que vieram via fluxo X vs Y. Action add_tag antes do assign_ai_agent.

Próximos passos

Artigos relacionados