🧰 Como usar este módulo
É um build real. Cada caixa de código abaixo é um prompt para copiar e rodar no seu assistente (com o n8n conectado via MCP) — sempre com 🎯 objetivo, o bloco para copiar e ✅ como verificar. As partes entre <chaves> você troca pelos seus valores. Pré-requisitos: um assistente de código com o MCP do n8n ligado, uma conta de e-mail e uma chave de IA com embeddings (ex.: OpenAI). Vá em camadas: rode um prompt, verifique, só então avance.
A planta do projeto tem duas máquinas que dividem o trabalho: uma aprende as políticas uma única vez (o indexador), a outra responde a cada e-mail (o agente). Elas se comunicam por um lugar comum — o vector store, onde o conhecimento fica buscável.
Diagrama ilustrativo — o indexador alimenta o vector store; o agente lê dele a cada execução. Separar "aprender" de "responder" mantém cada parte simples de testar.
🎯 O escopo do projeto
O que é
O projeto é um agente de suporte por e-mail. Ele parte de dois documentos: um de políticas (envio, devoluções, garantia, cobrança, preços, promoções, privacidade, vale-presente) e um de FAQ. A partir deles, para cada e-mail que chega, ele decide se é uma dúvida de suporte, busca a resposta nos documentos e rascunha uma réplica — que um humano ainda aprova antes de enviar.
O que é?RAG (Retrieval-Augmented Generation) — em vez de a IA "chutar" de memória, ela primeiro busca (retrieval) o trecho certo nos seus documentos e só então gera a resposta com base nele. Rascunho (draft) — a resposta fica salva como rascunho na caixa de e-mail, não é enviada sozinha.
O escopo é deliberadamente estreito e seguro: o agente rascunha, não envia (humano no loop), e a regra de ouro é não inventar — se o assunto não está nas políticas, ele não improvisa uma resposta. Esse recorte é o que torna o projeto confiável o suficiente para um cenário real de negócio.
Por que aprender
Este é o "olá mundo" dos agentes que valem dinheiro: junta três habilidades num único caso útil — RAG (ancorar em documentos), classificação (filtrar o que é suporte) e geração de texto (escrever a resposta no tom certo).
- •Ancorado: respostas vêm das políticas, não da imaginação da IA.
- •Seguro: rascunho + humano aprova; fora de escopo = não responde.
- •Reutilizável: troque os PDFs e o mesmo agente serve outra empresa.
Conceitos-chave
Buscar antes de gerar.
É suporte ou não?
Humano aprova o envio.
Fora de escopo = não responde.
🏗️ A arquitetura: indexador + agente
O que é
São dois workflows separados. O indexador roda por gatilho manual: lê os documentos, fatia o texto em pedaços (text splitter), gera embeddings e grava no vector store. O agente roda por gatilho de e-mail: a cada 15 minutos lê os não-lidos, classifica, consulta o vector store como ferramenta e cria o rascunho.
O que é?Embeddings — uma forma de transformar texto em números que capturam significado, para que a busca encontre trechos por sentido, não só por palavra exata. Vector store — o banco que guarda esses números e devolve os pedaços mais parecidos com a pergunta. Text splitter — divide o documento em pedaços (chunks) do tamanho certo para a busca.
Por que aprender
Separar quem aprende de quem responde é uma decisão de engenharia: você indexa só quando as políticas mudam (raro), mas o agente roda o tempo todo (barato, porque só consulta). Misturar os dois encareceria cada e-mail e dificultaria o teste.
✓ Indexador (aprende)
- ✓Gatilho manual — você roda quando os PDFs mudam.
- ✓Documento → splitter → embeddings → vector store.
- ✓Roda uma vez e o conhecimento fica salvo.
✓ Agente (responde)
- ✓Gatilho Gmail — a cada 15 min, e-mails não lidos.
- ✓Classifier → agente com a ferramenta de vector store.
- ✓Gera o rascunho; ramo "não relevante" encerra.
🎯 Decisão de arquitetura: system prompt vs vector store
Para poucos documentos pequenos, dá pra colar o texto inteiro no system prompt (mais simples e barato). Mas escolhemos vector store porque escala: ele busca só a seção relevante, em vez de mandar o documento todo a cada e-mail — melhor quando a base cresce. Deixe a IA propor isso e confirme a escolha.
Conceitos-chave
Aprender vs responder.
Ponte entre os dois.
Busca só o relevante.
Indexa raro, consulta sempre.
📝 O prompt de abertura abrangente
O que é
É um único pedido, em Plan Mode, que descreve o resultado completo: os documentos de origem, a lógica do fluxo e o comportamento esperado — deixando a IA escolher como armazenar e buscar. Coloque os PDFs na pasta do projeto e referencie-os por tag. Em vez de pedir um vector store de cara, descreva o resultado e deixe a IA propor a arquitetura.
O que é?Plan Mode — um modo em que a IA pesquisa, faz perguntas e propõe um plano antes de construir, sem alterar nada. Você revisa e aprova; só então ela executa.
🎯 Objetivo: descrever o agente inteiro num só prompt e deixar a IA propor o plano (em Plan Mode).
Entre em plan mode. Quero um agente de suporte por e-mail no n8n. Anexei dois documentos na pasta do projeto: - @(envio, devoluções, garantia, cobrança, preços, promoções, privacidade) - @ Resultado desejado: 1. Use esses documentos como base de conhecimento da empresa. 2. A cada e-mail novo, classifique se é uma dúvida de suporte técnico. 3. Se for, rascunhe uma resposta APOIADA nos documentos (não invente nada). 4. Se NÃO for suporte, ignore (não responda). 5. A resposta deve ficar como RASCUNHO no Gmail, nunca enviada automaticamente. Você decide como armazenar e buscar os documentos. Antes de construir, me faça as perguntas que precisar e me mostre o plano dos workflows.
✅ Como verificar: a IA deve fazer perguntas (provedor de IA, como armazenar, o que conta como suporte, tom) e devolver um plano com dois workflows antes de criar qualquer nó. Se ela já começar a construir, peça "fique em plan mode e me mostre o plano primeiro".
Por que aprender
Um bom prompt de abertura economiza horas: a IA antecipa as decisões (provedor, armazenamento, tom, o que é "fora de escopo") e pergunta o que falta, em vez de adivinhar e construir errado. Você responde, aprova o plano e só então deixa construir — o ciclo Plan → Build em ação.
✓ No prompt, inclua
- ✓Os documentos de origem (por tag/anexo).
- ✓O resultado completo (classificar, ancorar, rascunhar).
- ✓As regras de segurança (não inventar, não enviar).
✗ Evite
- ✗Ditar "use um nó de vector store em memória com…".
- ✗Deixar a IA construir sem mostrar o plano antes.
- ✗Pular as perguntas de esclarecimento dela.
Conceitos-chave
Plano antes de construir.
O "o quê", não o "como".
PDFs na pasta + tag.
Responda as perguntas.
🔧 Build dos dois workflows
O que é
Com o plano aprovado, a IA constrói os nós. O Workflow 1 (indexador) fica: gatilho manual → nó de código com o texto dos documentos → inserção no vector store (com data loader e text splitter por caractere). O Workflow 2 (agente) fica: gatilho Gmail (a cada 15 min, só não lidos) → classifier (suporte vs não relevante) → agente de IA com a ferramenta de vector store → nó de rascunho no Gmail; o ramo "não relevante" termina sem responder.
🎯 Objetivo: popular a base e ativar o agente na ordem certa.
1. Construa os dois workflows conforme o plano. 2. Rode o Workflow 1 (indexador) manualmente UMA vez, para popular o vector store com as políticas. 3. Só depois, ATIVE o Workflow 2 (agente do e-mail). 4. Se algum nó der erro, me copie a mensagem e diga em qual nó — eu te devolvo a correção.
✅ Como verificar: o indexador deve concluir sem erro e o vector store ficar populado. Ative o agente só depois — senão ele consulta uma base vazia.
🐛 Debug em camadas (erros reais que aparecem)
No build, dois erros típicos do classifier: (1) a propriedade do modelo precisava do formato estruturado {mode, id/value} em vez de texto puro; (2) uma falha de parsing some ao desativar a opção de resposta-JSON padrão do nó do modelo do classifier. A correção é sempre a mesma receita: copie a mensagem do nó e devolva pra IA com a localização.
Para ler um nó: à esquerda ficam as entradas (nós anteriores), no meio o nó, à direita a saída em JSON.
Por que aprender
Assistir ao build e devolver erros é o ciclo central do vibe coding: você não conserta nós na mão, você descreve o sintoma. Ver o I/O de cada nó também ensina a anatomia de um pipeline RAG — e a confirmar que o rascunho bate com a fonte (ex.: os termos de garantia no rascunho conferem com o PDF de políticas).
Conceitos-chave
Indexar antes de ativar.
Mensagem + nó.
Esquerda entra, direita sai.
Rascunho bate com o PDF.
🔑 Credenciais (o que a IA NÃO faz)
O que é
Há uma fronteira clara: a IA constrói os fluxos, mas você conecta as credenciais com as mãos. São duas: a conta de e-mail via Gmail OAuth (autoriza o n8n a ler e rascunhar) e a chave de API da IA (OpenAI, usada tanto pelos modelos de chat quanto pelos embeddings). Segredo nunca vai pro chat.
O que é?OAuth — um jeito de autorizar um app a agir em seu nome sem entregar sua senha; você clica "permitir" e o app recebe um acesso revogável. Chave de API — uma senha de máquina que identifica e cobra o uso da IA; fica guardada na credencial da ferramenta, não no código nem no chat.
Diagrama ilustrativo — a IA não tem (nem deve ter) suas credenciais. Conectar OAuth e colar a chave é trabalho seu, na ferramenta.
Por que aprender
Saber o que não delegar é metade da disciplina de segurança. Mapeamento de credenciais e autorização ficam com você; isso protege seus dados e mantém o segredo fora do contexto da IA — uma regra de ouro que volta em toda a trilha de produção.
Conceitos-chave
Autoriza sem senha.
Chat + embeddings.
A IA não tem o segredo.
Segredo fica na ferramenta.
🧪 Testes: devolução, garantia, fora de escopo
O que é
Teste com casos reais cobrindo os três comportamentos: um e-mail de devolução (deve responder com a política certa), um de garantia (a resposta deve bater termo a termo com o PDF) e um fora de escopo — um "vamos jantar amanhã?" — que deve ser classificado como não relevante e não receber resposta. Verde ≠ correto: só esses testes revelam se o RAG está mesmo ancorando.
🎯 Objetivo: disparar os três cenários e conferir o comportamento.
Envie 3 e-mails de teste para a caixa conectada: A) "Qual é o prazo para devolver um produto?" → deve rascunhar a política de devolução B) "Meu aparelho parou; ainda está na garantia?" → resposta deve bater com o PDF de garantia C) "Bora jantar amanhã às 20h?" → classificar como "não relevante", NÃO responder Rode o agente e me diga: ele ancorou nas políticas? Algum número (ex.: "30 dias") confere com o documento? Ele recusou o caso C sem inventar?
✅ Como verificar: A e B geram rascunho fiel ao PDF (confira os números — "30 dias" ≠ "um ano"); C não gera resposta. Se C foi respondido, ajuste o classifier.
✓ Sinais de que está certo
- ✓Os termos de garantia batem com o PDF, palavra por palavra.
- ✓O e-mail social é marcado "não relevante" e encerra.
- ✓Números (prazos, valores) conferem com a fonte.
✗ Sinais de alerta
- ✗Resposta "bonita" mas com prazo inventado.
- ✗O agente responde ao convite de jantar.
- ✗Confiar no "verde" sem ler o conteúdo do rascunho.
Por que aprender
O caso fora de escopo é o mais importante: ele prova que o agente recusa inventar. Um agente que responde tudo é perigoso; um que sabe dizer "isso não está na minha base" é confiável. Casos de borda revelam isso melhor que qualquer execução "verde".
Conceitos-chave
Devolução, garantia, social.
Números vs PDF.
Fora de escopo = silêncio.
Leia o conteúdo.
✨ Os 6 enhancements aplicados
O que é
Seis melhorias incrementais, pedidas em linguagem natural e testadas uma de cada vez — iterar em camadas na prática. As três primeiras tratam de lógica/erro (fallback, filtro de tempo, ignorar automáticos); as três últimas, de qualidade de saída (tom, nome do cliente, indicador de confiança).
Diagrama ilustrativo — uma camada por vez, testando a cada uma. Se quebrar, você sabe exatamente qual mudança foi a culpada.
🎯 Enhancement 1 — Fallback de não-encontrado: se a base não tem a resposta, não invente.
Quando a base de conhecimento NÃO tiver a resposta, o agente não deve inventar.
Faça o agente emitir um marcador ("política encontrada" / "política não encontrada");
um nó de código lê esse marcador, um nó IF ramifica, e no caso "não encontrada"
crie um rascunho educado de "vamos pesquisar e retornamos em breve".
Antes de mudar, me pergunte o limiar de match e o texto do fallback.
✅ Como verificar: mande uma pergunta fora da base (ex.: "vocês enviam para o exterior?"). Deve cair no rascunho de pesquisa — não numa resposta inventada.
🎯 Enhancements 2 e 3 — Filtros: só e-mails recentes; ignorar automáticos.
[2] Processe apenas e-mails recebidos há menos de <10> minutos.
(a IA descobre a sintaxe de busca do Gmail e adiciona um filtro
"newer than" no próprio gatilho, sem nó extra.)
[3] Ignore e-mails automáticos: fora-do-escritório, notificações de entrega,
newsletters e remetentes no-reply / postmaster / bounce / marketing.
Adicione um nó de código que marque isAutomated + motivo e ramifique
para PULAR esses casos.
✅ Como verificar: ficam três portões em sequência — automático? → é suporte? → tem política? Atenção a um bug clássico: o filtro pode deixar passar um no-reply@ se o código ler o campo errado do remetente.
🎯 Enhancements 4, 5 e 6 — Qualidade: tom, nome e confiança.
[4] Ajuste o tom para <amigável, prestativo, descontraído> — "experto, mas
nunca condescendente". Atualize TANTO o system prompt do agente QUANTO o
rascunho de "vamos pesquisar". Varie as despedidas.
[5] Personalize com o nome do cliente: um nó de código extrai o nome da
assinatura ("Abraço, João" / "Obrigada, Sara") e usa na saudação,
com fallback "Olá" quando não houver assinatura.
[6] Adicione um indicador de confiança (uso interno): o agente marca
alto/médio/baixo conforme o match (alto > 0.8, médio 0.6–0.8, baixo < 0.6);
um nó de código monta um selo HTML (verde/amarelo/vermelho) anexado ao
rascunho, só para revisão interna.
✅ Como verificar: o tom muda nos dois rascunhos (resposta e fallback); um e-mail assinado "Abraço, João" é respondido com "Olá João"; o selo de confiança aparece no rascunho. Teste cada um antes de pedir o próximo.
Por que aprender
Os enhancements mostram o stair-step real: cada melhoria é um pedido em português, testado isoladamente. Note como a IA às vezes faz mais do que você pediu (reorganiza nós, reescreve o ramo falso) — por isso você revisa a cada passo. Ancore cada pedido no comportamento desejado, não na implementação.
Conceitos-chave
Uma melhoria por vez.
Auto? suporte? política?
Selo alto/médio/baixo.
A IA faz extra; confira.
✅ Verificação final & checklist
O que é
Antes de declarar "pronto", passe a checklist objetiva. Definir o que é "pronto" evita o loop infinito de "só mais uma melhoria" — e te dá um critério claro para fechar o projeto com segurança.
🎯 Objetivo: confirmar que o projeto está pronto e guardar um backup.
[ ] O indexador popula o vector store sem erro. [ ] E-mails de suporte são classificados como suporte. [ ] As respostas ancoram nas políticas (números conferem com o PDF). [ ] Fora de escopo NÃO é respondido (recusa inventar). [ ] Automáticos e antigos são ignorados (3 portões funcionando). [ ] Tom, nome e selo de confiança aparecem no rascunho. [ ] Tudo fica como RASCUNHO; humano aprova o envio. Backup: "Exporte os dois workflows como JSON para eu guardar."
✅ Como verificar: todos os itens marcados + o JSON exportado salvo. Se um item falhar, volte ao tópico correspondente e itere só aquela camada.
Por que aprender
"Pronto" é uma decisão, não um sentimento. A checklist transforma a verificação em algo repetível, e o export JSON é o seu backup — se uma futura mudança quebrar algo, você restaura a versão que funcionava. É o mesmo hábito de "backup antes de mudar" que vale para todo projeto desta trilha.
Um cliente pergunta algo que não está nas políticas. Qual é o comportamento correto do agente?
📌 Resumo do Módulo
Próximo Módulo:
5.2 — Agentes Hospedados (Agendado + Webhook): tire o agente da sua máquina e coloque na nuvem.