n8n-nodes-context-provider-tools

Um nó customizado para n8n que atua como um Gestor de Fluxo e Contexto para Agentes de IA.

Este nó não é apenas um processador de dados; ele é uma Ferramenta Cognitiva (AI Tool) projetada para ser conectada a nós como "AI Agent" (LangChain). Ele fornece ao LLM a "memória de procedimento" necessária para seguir roteiros de atendimento complexos sem alucinar.

🚀 Funcionalidades Principais

• 🛡️ Blindagem contra Alucinações: Fornece instruções exatas, persona e objetivos para cada etapa da conversa.
• 🧠 Busca Fuzzy (Auto-Correção): Se o Agente errar o ID da etapa (ex: pedir "abertur" em vez de "abertura"), o nó corrige automaticamente usando Fuse.js.
• ⚡ Otimização de Tokens: Remove automaticamente campos vazios (null, undefined, "") do JSON de resposta, economizando custos e espaço na janela de contexto do LLM.
• 🔄 Auto-Início (Fail-Safe): Se o Agente enviar um input vazio ou confuso, o nó assume automaticamente que é o início da conversa (inicio), evitando loops de erro.
• valid_ids: Validação na interface para impedir criação de etapas duplicadas.

📦 Instalação

Via Comunidade n8n (Recomendado)

1. No seu n8n, vá em Settings > Community Nodes.
2. Clique em Install.
3. Procure por n8n-nodes-context-provider-tools.

Instalação Manual (Docker/Self-hosted)

Na pasta raiz do seu n8n (onde fica o package.json):

npm install n8n-nodes-context-provider-tools

⚙️ Como Configurar o Nó

1. Adicione o nó Chatbot Flow" ao seu canvas.
2. NÃO o conecte no fluxo principal. Conecte-o na entrada "Tools" do seu nó AI Agent.
3. Configure as seções:
   • Identidade: Nome do Bot (ex: Manu), Tom de Voz e Personalidade.
   • Etapas: Crie as fases da sua conversa (ex: abertura, qualificacao, oferta).

Importante: Cada etapa precisa de um ID único (ex: abertura). É através desse ID que a IA navegará.

🤖 Guia de Engenharia de Prompt (System Prompt)

Para extrair a máxima eficiência desta ferramenta, você deve instruir seu Agente de IA a se comportar como um "Navegador de Estados".

O segredo é forçar o Agente a nunca responder sem consultar a ferramenta.

Exemplo Prático: Chatbot de Academia ("Titanium Fitness")

Imagine um bot para uma academia. Temos 3 etapas configuradas no nó:

1. abertura: Boas vindas e pergunta nome.
2. planos: Explica preços (Mensal R$90/Ano R$800).
3. agendamento: Tenta marcar aula experimental.

📋 System Prompt Recomendado

Copie e cole isso na instrução do seu AI Agent:

VOCÊ É O ATENDENTE VIRTUAL DA 'TITANIUM FITNESS'.
Sua missão é converter visitantes em alunos matriculados.

⚠️ PROTOCOLO DE NAVEGAÇÃO OBRIGATÓRIO (LEIA COM ATENÇÃO):

1. **SUA CÉREBRO É A TOOL `chatbot_flow_manager`**:
   - Você NÃO sabe o que falar por conta própria.
   - Antes de responder qualquer coisa ao usuário, você DEVE chamar a ferramenta `chatbot_flow_manager`.

2. **COMO USAR A TOOL**:
   - Se o usuário disse "Oi", "Olá" ou é a primeira mensagem -> Chame com input: "inicio".
   - Se você já está em uma conversa, analise a intenção do usuário e chame o ID da etapa correspondente.
     - Ex: Usuário perguntou preço -> Chame input: "planos".
     - Ex: Usuário quer visitar -> Chame input: "agendamento".
   - Se o usuário respondeu uma pergunta sua, chame o ID da PRÓXIMA etapa sugerida no contexto anterior.

3. **COMO PROCESSAR O RETORNO DA TOOL**:
   - A tool vai te devolver um JSON contendo:
     - `instrucoes_de_atendimento`: O que você deve dizer.
     - `persona_bot`: Como você deve falar.
     - `requisitos_obrigatorios`: Dados que você precisa coletar (ex: nome, telefone).
   - Siga ESTRITAMENTE essas instruções. Não invente promoções que não estejam no JSON.

4. **REGRA DE OURO**:
   - Se a tool retornar erro ou "Etapa não encontrada", leia as "opcoes_validas" que ela sugeriu e tente novamente com o ID correto.

🧠 Exemplos de Interação (Simulation)

Cenário 1: Início da Conversa

• Usuário: "Oi, tudo bem?"
• Agente (Pensamento): "Usuário disse Oi. Preciso chamar a tool com 'inicio'."
• Tool (chatbot_flow_manager): Retorna o contexto da etapa abertura (Persona: Coach Energético).
• Agente (Resposta): "E aí, campeão! 💪 Bem-vindo à Titanium Fitness! Sou o Rex. Bora meter o shape? Qual seu nome?"

Cenário 2: Pergunta de Preço (Fuzzy Search em ação)

• Usuário: "Quais os valores?"
• Agente (Pensamento): "Intenção é saber preços. Vou tentar chamar a etapa precos."
• Tool (chatbot_flow_manager): (Não existe precos, mas existe planos. O Fuzzy Search atua).
  • Retorno: "AVISO: Assumi que você quis dizer 'planos'. Aqui estão as instruções..."
• Agente (Resposta): "Temos o plano Mensal por R$90 e o Anual por R$800. O Anual sai muito mais em conta! Qual prefere?"

🛠️ Detalhes Técnicos (Para Desenvolvedores)

• Inputs da Tool:
  • query (string): Aceita IDs de etapas, palavras-chave ("inicio") ou intenções.
• Tratamento de Erros:
  • Se o input for vazio {}, faz fallback para inicio.
  • Se o ID não existir, retorna lista de IDs disponíveis para o Agente se auto-corrigir na próxima iteração (Self-correction loop).
• Sanitização:
  • Inputs são truncados em 256 caracteres.
  • Caracteres especiais de controle são removidos.
  • Strings são normalizadas (sem acentos, lowercase).

📄 Licença

MIT. Sinta-se livre para usar e modificar.