Forux · Custom Agents
Forux · Documentação de apresentação

Custom Agents, por dentro.

Como o Forux atende cada cliente sob medida na 2ª instância do N8N. Arquitetura em módulos e o detalhe de ponta a ponta de quatro agentes: Supera, TF Pneus, Balbino e Sparta: fluxo, ferramentas, para onde cada uma chama e o que retorna.

Supera · Sol TF Pneus · Ana Balbino · Artur Sparta · Isa Atualizado 19/10/2026
Meta Pipedrive Formulário Supabase ElevenLabs Agenda
01 · Arquitetura

Como funciona, módulo a módulo

Toda mensagem segue o mesmo caminho. O que muda de um cliente para outro é apenas o Custom Agent no fim da linha. Clique em um módulo para abri-lo no N8N.

WhatsApp
Cliente envia (Meta oficial ou Evolution)
Chatwoot
Recebe e dispara o webhook do agente
ORC
Orquestrador: carrega o agentConfig e roteia
Flow Agent B2B
Motor genérico, o “cérebro” padrão
Custom Agent
Fluxo sob medida do cliente
Resposta
Volta pelo Chatwoot ao cliente

ORC · orquestrador de entrada

  • Recebe a mensagem (webhook invoke_agent).
  • Carrega o agentConfig pelo chatwoot_account_id.
  • Decide produção vs. homologação (nó “Hml?”) e chama o Flow Agent.
Abrir ORC no N8N

Flow Agent B2B · motor genérico

  • Agrupa mensagens (buffer Redis), trata áudio/imagem, créditos e limite.
  • Roda o agente padrão e, se há integração ativa, chama o Custom Agent.
  • Envia a resposta: texto pelo Chatwoot; o áudio é gerado no ElevenLabs e também entregue pelo Chatwoot.
Abrir Flow Agent (v1.2)

Custom Agent · 2ª instância

  • Fluxo e ferramentas sob medida de cada cliente.
  • Acionado por POST .../webhook/{agentId}.
  • Recebe agentConfig + webhook + sessão e devolve a resposta.
Abrir instância custom
?
Onde fica a homologação no N8N? Não existe instância separada de homologação. Ela é um ramo ou agente de teste dentro do mesmo workflow. No motor genérico, o ORC usa o nó “Hml?” (lista de números internos da Forux) para desviar à cópia HML do Flow Agent. Nos Custom Agents, um nó “session” compara a chave de sessão da conversa (telefone do contato mais o ID do agente) com a do número de teste interno (558287232915) e manda a conversa de teste ao agente HML. Lead real sempre cai no agente de produção.
#
Session key: como cada conversa fica isolada. Cada conversa tem uma chave de sessão formada pelo telefone do contato mais o ID do agente (um UUID). Por exemplo +5511989619653:5fe02d70-4028-4cc6-b137-07eb568e8da2, em que o UUID identifica o agente (o mesmo em todas as conversas daquele cliente). É ela que separa a memória, o buffer e o histórico de uma conversa das outras. Para a homologação, o nó session compara essa chave inteira com a do número de teste interno (+558287232915:<id-do-agente>): se bater, a conversa vai ao agente de teste; qualquer outra vai à produção. O Custom Agent é acionado pelo agentId e recebe essa mesma sessão.
02 · Arquitetura

Follow-up: a retomada automática

Quando o cliente some no meio da conversa, o agente volta a falar sozinho na hora certa. O follow-up tem duas partes: decidir quando retomar e executar respeitando o horário e o atendimento humano. Vale para todos os Custom Agents, porque vive no motor genérico.

Parte 1Agendar · schedule-fup

A cada resposta do agente, um classificador de IA olha a última mensagem e o contexto e decide agendar, reagendar ou cancelar o follow-up. A decisão é gravada em data contacts (quando retomar e qual é o próximo passo).

Parte 2Executar · Execute FUP (cron 1 min)

Um cron varre os follow-ups vencidos. Só envia dentro do horário comercial (08h às 20h no fuso do agente) e se nenhum humano assumiu a conversa. A mensagem pode ser fixa ou gerada por IA com o histórico; depois avança para o próximo passo ou encerra.

Agente responde o cliente
schedule-fup · decisão
Classificador: agendar, reagendar ou cancelar
Agenda
Grava em data contacts
Quando retomar e o próximo passo.
Execute FUP
Cron de 1 min varre os vencidos
Gate
Horário comercial e sem humano?
Senão, reagenda ou pausa.
Ação
Encerrar ou interagir
Conforme inactivity_actions.
Envio
Mensagem fixa ou gerada por IA
Avança o passo ou conclui
i
Regra

Os tempos do follow-up são configuráveis por agente. O primeiro FUP pode ser 30 min, 1 h, 3 h ou mais: o sistema respeita exatamente o tempo definido na configuração do cliente.

03 · Ambiente

Instâncias, ambientes e credenciais

Onde cada peça vive e como chegar rápido nela. As credenciais nunca ficam aqui: estão no Vaultwarden, na organização de cada cliente.

Duas instâncias de N8N

Principalb2b-n8n.ovuwza… · motor genérico (ORC → Flow Agent B2B).
Customizadoscustom-agents-b2b-n8n.bipy7u… · os Custom Agents.
HomologaçãoRamo/agente de teste dentro do próprio workflow (não é instância à parte).
N8N principal N8N customizados

Dados, memória e credenciais

BancoSupabase projeto b2b (PostgreSQL + pgvector). Compartilhado entre hml e produção.
Memória / RAGMemória em Postgres · base de conhecimento = RAG no Supabase (pgvector).
CredenciaisNo Vaultwarden (acesso via Bitwarden), organizadas por cliente.
Supabase (projeto b2b)
04 · Custom Agents

Um board por cliente

Cada agente tem o mesmo esqueleto, mas fluxo e ferramentas próprios. Use as abas para ir da visão geral ao fluxograma, às ferramentas (clique em cada uma para ver a configuração real) e à infra.

S

Supera · Sol

SDR de franquia: qualifica o lead, apresenta o investimento e agenda a reunião com o closer.
marketing@franquiasupera.com.br Meta oficial Abrir workflow

O que a Sol faz

Recebe o lead de franquia, qualifica (região e experiência), cria a oportunidade no CRM, apresenta o investimento e conduz até agendar a reunião com um closer. O agendamento é proativo: ela oferece horários reais e nunca inventa disponibilidade.

Cobre / não cobre

Cobre o funil de franquia ponta a ponta e também responde quem só quer saber se já existe unidade numa cidade. Fora do escopo Supera, não conversa.

Quando transfere / não trata

  • Transfere ao especialista quando o lead pede falar com humano ou closer.
  • Transfere também em erro técnico de agenda ou CRM (registra a nota e passa).
  • Não trata nada fora da franquia Supera (investimento, agenda, unidades).
  • Nunca gera senhas, códigos de verificação ou passo a passo técnico.
💬 Exemplo · confirmação ao transferir
Pronto! Em instantes alguém da equipe vai te atender aqui mesmo. 😊
9
ferramentas
87
nós no workflow
gpt-4o
modelo (prod)
Pipedrive
CRM integrado
T

TF Pneus · Ana

Venda de pneus: consulta o catálogo por medida ou por veículo e gera o orçamento.
tf.pneus@forux.io Channel::Whatsapp Abrir workflow

O que a Ana faz

Descobre o pneu certo (pela medida ou pelo modelo do veículo), consulta o catálogo e entrega a oferta já formatada. Quando o cliente quer fechar, gera o orçamento completo. Regra de ouro: preço nunca vem da memória, sempre de consulta fresca.

Cobre / não cobre

Cobre consulta de catálogo, orçamento e dúvidas de serviço. Nunca calcula preço por conta própria: é sempre via ferramenta.

Quando transfere / não trata

  • Transfere conforme as regras configuradas do agente e quando o cliente pede humano.
  • “Vou pensar”, “vou comparar” ou “estou orçando em outro lugar” não disparam transferência.
  • Nunca inventa preço (sempre pela tool) nem compartilha dados de outros contatos.
5
ferramentas
53
nós no workflow
gpt-4o
modelo (prod)
glm-4.6
modelo (hml)
B

Balbino · Artur

Venda de móveis: qualifica o lead, envia o catálogo e faz o handoff para o closer.
balbinomoveis@arvore.party Meta oficial Abrir workflow

O que o Artur faz

Classifica a intenção, dá as boas-vindas, qualifica o lead e conduz a conversa. Em pergunta de preço, envia o catálogo em PDF. Quando o lead está pronto, faz o handoff para o time humano em uma única chamada.

Cobre / não cobre

É o mais enxuto dos quatro: foco em qualificar, informar e transferir. Pós-venda e fora de expediente têm caminhos próprios.

Quando transfere / não trata

  • Transfere a sinal de intenção de compra (lead qualificado), com o briefing preenchido.
  • Pós-venda, garantia e pedido explícito de humano também vão para a fila.
  • Pergunta de preço isolada não transfere. Sem prazo e sem cidade é curiosidade: encerra cordial.
  • Expediente seg a sex, 8h às 17h; fora disso retoma no próximo dia útil.
🟢 Exemplo · nota de handoff no Chatwoot
🟢 LEAD QUALIFICADO
Tipo de uso: [comercial - segmento / residencial]
Modelo/linha: [dobrável / fixa / estofada]
Quantidade exata: [N mesas + N cadeiras]
Prazo: [pronta-entrega / até X dias]
Localização: [cidade/estado]
Pedido em nome de: [nome do cliente]
Classificação: [Quente / Morno]
Observações: [objeções, sinais relevantes]
3
ferramentas
30
nós no workflow
gpt-4o
modelo
1
agente (sem split)
Sp

Sparta Cursos · Isa

SDR de cursos: qualifica o interesse, informa cursos e valores e registra a matrícula após o pagamento.
spartacursosia@gmail.com Meta oficial Abrir workflow

O que a Isa faz

Atende quem procura os cursos, qualifica o interesse, informa curso, valor e link de pagamento (a partir de uma fonte única de verdade) e, depois que o cliente paga, coleta os dados e registra a matrícula para o financeiro avaliar.

Cobre / não cobre

Cobre a venda de cursos e a matrícula. A transferência para humano é por configuração e limite de interações (a tool de transferência está desligada).

Quando transfere / não trata

  • A transferência só dispara se houver regra configurada; sem regra, a tool fica desligada e a Isa redireciona por texto.
  • Produto, valor e link de pagamento só da fonte oficial, nunca repetidos da memória da conversa.
  • Não compartilha dados de outros contatos nem trata assuntos fora de cursos.
2
ferramentas
22
nós no workflow
glm-4.6
modelo (primário)
gpt-4o
modelo (fallback)
05 · Operação

Para dar manutenção: onde olhar

Diante de uma falha, siga o caminho da mensagem e identifique até onde ela chegou.

Roteador de diagnóstico

SintomaOnde verificar
Agente não respondeSaldo OpenRouter · atribuição no Chatwoot · créditos · execução do ORC/Flow Agent
Respondeu erradoPrompt/config do agente (impersonando) + execução do Custom Agent
Tool não agiu / agiu erradoDeveria acionar? Acionou? Recebeu os dados certos? Retornou o esperado?
Não achou na baseknowledge_chunks + filtro agent_id na tool baseDeConhecimento
Não transferiuRegra configurada + tool no prompt + limite de interações

Regras de ouro

HomologaçãoNunca altere o agente de produção direto. Teste no ramo HML e só então promova.
BancoSupabase é compartilhado hml/prod: toda mudança precisa ser aditiva.
CanalConfie em webhook.channel, não na coluna connection_type.
ExecuçõesO N8N guarda ~4 dias. Janelas maiores: Chatwoot e Supabase.
CredenciaisSempre pelo Vaultwarden, na organização do cliente.