Todo build conversado segue o mesmo ciclo de quatro fases. Você descreve o resultado, a IA planeja e constrói (build); quando algo quebra você devolve o erro para ela depurar (troubleshoot) e, por fim, pede melhorias para otimizar. O diagrama abaixo mostra o loop — e que ele volta sempre ao plano.
Diagrama ilustrativo — recriação conceitual do ciclo, não uma captura de tela real.
🔐 Modos de permissão & Plan Mode
O que é: antes de a IA fazer qualquer coisa, você escolhe o modo de permissão — quanta autonomia ela tem para editar arquivos e rodar comandos. Os modos vão de "perguntar antes de tudo" até "pular toda aprovação". O Plan Mode é o modo em que ela só planeja: pesquisa, faz perguntas e propõe, sem mexer em nada até você aprovar.
🧭 Por que aprender
O modo certo equilibra velocidade e segurança. Começar em Plan Mode garante que você sempre veja o plano antes do build; o Bypass acelera, mas você deixa de enxergar o que a IA faz — use com cuidado, e nunca em comandos potencialmente perigosos sem entender o risco.
✓ Quando usar cada modo
- ✓Plan Mode: sempre que for começar algo novo — só planeja.
- ✓Perguntar antes: aprende observando cada passo.
- ✓Editar automático / Auto: quando já confia no fluxo.
✗ Cuidado com o Bypass
- ✗Bypass pula a aprovação de comandos potencialmente perigosos.
- ✗Você deixa de ver o que a IA está fazendo.
- ✗Ative só quando já entende o build e quer velocidade.
🎯 Dica prática
Para habilitar o Bypass, busque "bypass" nas configurações (permitir pular permissões com cuidado) e reinicie. Mas a regra de ouro continua: comece sempre em Plan Mode e só mude de modo quando já vir o plano aprovado.
Conceitos-chave
Só planeja, não mexe.
Aprova cada edição.
Mais autonomia.
Pula aprovação — cuidado.
📋 Fase 1 — Plan
O que é: na fase de plano, a IA pesquisa os nós e padrões relevantes, faz perguntas de esclarecimento (que colunas registrar, ações extras como rótulos ou notificações) e então propõe um plano para você aprovar. Nada é construído antes da sua aprovação.
🧭 Por que aprender
O plano é o seu ponto de controle: é onde você corrige o rumo antes de qualquer linha existir. Responder bem às perguntas de esclarecimento define a qualidade de tudo que vem depois — vale mais investir aqui do que consertar no fim.
Preciso de um workflow que monitore o Gmail
em busca de e-mails com "urgente" no assunto
e registre cada um numa planilha do Google Sheets.
# a IA responde com:
- perguntas: quais colunas? rótulo? notificação?
- um plano com gatilho Gmail → append row
- a lista de credenciais necessárias
🎯 Dica prática
Não-determinismo é normal: o mesmo prompt pode gerar nomes de nós, estrutura e layout diferentes a cada vez. Variação não é erro — não compare tela a tela com a de outra pessoa.
Conceitos-chave
Acha nós e padrões.
Esclarece antes de agir.
Você assina o plano.
Saída não-determinística.
🏗️ Fase 2 — Build
O que é: aprovado o plano, a IA cria e valida os nós no n8n, corrigindo automaticamente problemas de validação. No exemplo, ela monta um gatilho do Gmail ligado a um nó "append row" do Google Sheets. Mas há coisas que ela não faz por você.
✓ O que a IA faz
- ✓Cria os nós e conecta a estrutura do workflow.
- ✓Valida a configuração e auto-corrige erros de validação.
- ✓Relata que as credenciais precisam ser configuradas à mão.
✗ O que a IA NÃO faz
- ✗Configurar as credenciais OAuth (Gmail, Sheets).
- ✗Criar a planilha de destino na sua conta Google.
- ✗Mapear os valores dos campos (from, subject, snippet, ID, data).
🧭 Por que aprender
Saber a fronteira entre "o que a IA monta" e "o que é trabalho manual" evita frustração: você não fica esperando a IA fazer um login OAuth que só você pode fazer. O build entrega a estrutura; você liga as contas e cria o destino.
Conceitos-chave
Monta o workflow.
Auto-corrige config.
Gatilho + append row.
Credenciais são manuais.
🔑 Credenciais OAuth & chaves
O que é: conectar com segurança as contas que o workflow usa. Gmail e Google Sheets entram por OAuth2 (você faz login com a conta Google); a OpenAI entra por chave de API (uma chave secreta que você gera no painel). É o passo manual mais importante do build.
Passo a passo das credenciais
OAuth2 no Gmail e no Sheets
No nó, escolha "Create new credential" → OAuth2 → faça login com o Google. Use a mesma conta em que vai criar a planilha de destino.
Chave de API da OpenAI
No painel da OpenAI, em "API keys", crie uma chave secreta, dê um nome descritivo e copie na hora — ela aparece só uma vez. Cole no nó como nova credencial.
Guarde como dados sensíveis
Trate a chave como se fosse um cartão de crédito: quem tiver acesso pode gastar seus tokens. Guarde uma cópia segura (digital + física).
⚠️ Por que aprender — e a armadilha
- ✗A chave da OpenAI é mostrada uma única vez — se não copiar, gere outra.
- ✗Nunca cole credenciais no chat — uma chave vazada pode ser abusada.
- ✗Autorizar com a conta "errada" cria a planilha onde a IA não enxerga.
Conceitos-chave
Login no Gmail/Sheets.
Chave secreta OpenAI.
Copie na criação.
Planilha onde a IA vê.
🔧 Fase 3 — Troubleshoot
O que é: a fase de depuração é simples e poderosa — você devolve a mensagem de erro para a IA, junto da localização do nó, e ela diagnostica e corrige. Você não precisa decifrar o erro sozinho; a IA lê, entende a causa e aplica o conserto.
# erro no nó: "intervalo inválido: 14 horas" # você cola o erro de volta no chat ↓ "Deu este erro no gatilho do Gmail: ..." # a IA diagnostica e corrige: - troca o intervalo por uma expressão cron */5 - explica por que o formato anterior falhou
🧭 Por que aprender
Depurar conversando muda a relação com o erro: ele deixa de ser um bloqueio e vira um insumo. Sempre informe o erro e a localização do nó — quanto mais contexto, mais precisa a correção. Depois de cada conserto, recarregue o n8n antes de re-testar.
🎯 Dica prática
Alguns ajustes de nó só aceitam formatos específicos. O gatilho do Gmail, por exemplo, só aceita "a cada minuto" ou uma expressão cron — por isso um pedido de "5 minutos" é resolvido como cron (*/5).
Conceitos-chave
Mensagem + nó.
A IA acha a causa.
Formato específico.
Antes de re-testar.
⚡ Fase 4 — Optimize
O que é: com o workflow funcionando, você pede melhorias em linguagem natural — por exemplo, "mude o polling para a cada 5 minutos". A IA aplica a mudança; se ela esbarrar num formato inválido, isso vira mais uma rodada de troubleshoot. Otimizar é simplesmente continuar a conversa.
✓ Peça em linguagem natural
- ✓"Verifique o Gmail a cada 5 minutos em vez de 10."
- ✓"Adicione um rótulo aos e-mails já processados."
- ✓"Inclua a data de recebimento na planilha."
✗ Não microgerencie
- ✗Editar a expressão cron na mão dentro do nó.
- ✗Reconstruir o workflow do zero por uma mudança pequena.
- ✗Fazer várias mudanças de uma vez sem testar.
🧭 Por que aprender
A fase de otimização fecha o ciclo, mas o ciclo nunca "acaba": cada melhoria pode revelar um novo erro a depurar ou um novo ajuste a planejar. Pensar em loop — e não em linha reta — é o que separa um build de brinquedo de um workflow que evolui.
Conceitos-chave
Pede a melhoria.
Testa entre mudanças.
Pode reabrir troubleshoot.
O ciclo não termina.
📨 Projeto-guia: agente de suporte (RAG)
O que é: o projeto-guia deste módulo é um agente de suporte por e-mail com RAG — ele lê documentos de política em PDF, identifica perguntas de suporte e rascunha respostas fundamentadas para revisão humana. A arquitetura tem dois workflows: um que indexa o conhecimento e outro que responde os e-mails.
🧱 Os dois workflows
- •Indexador da base: gatilho manual → nó de código (texto dos documentos) → vector store em memória com embeddings da OpenAI.
- •Agente de suporte: gatilho Gmail (a cada 15 min, só não lidos) → classificador de texto → modelo OpenAI → agente de IA com a ferramenta de vector store → rascunho no Gmail.
🧭 Por que aprender — system prompt vs. vector store
Uma decisão de arquitetura aparece logo no plano: embutir os documentos no system prompt (mais simples e barato para textos pequenos) ou usar um vector store / RAG (escalável, busca só os trechos relevantes, melhor para crescer). Aqui escolhemos o vector store pela escalabilidade.
Embute o texto direto. Simples, barato, ótimo para docs pequenos.
Busca só trechos relevantes. Escala e reduz custo de contexto.
🎯 Dica prática
Ordem de execução importa: rode o workflow indexador uma vez manualmente para popular o vector store; só depois ative o agente de suporte. Coloque os PDFs na pasta do projeto e referencie-os por tag no prompt para a IA lê-los.
Conceitos-chave
Responde a partir de docs.
Suporte vs. não-relevante.
Busca semântica.
Revisão humana antes.
🧪 Verificação & testes
O que é: antes de confiar no agente, você roda um checklist visual e testa cenários reais. A regra de ouro: green ≠ correto — uma execução sem erro não prova que a resposta está certa. O melhor agente é aquele que se recusa a inventar o que não sabe.
Cenários de teste reais
Pergunta de devolução
"Comprei um notebook há 3 semanas, já abri."
O rascunho deve citar corretamente a janela de 30 dias e a taxa de reposição. Confira os números (30 dias, não "um ano").
Pergunta de garantia
"A TV falhou depois de 8 meses."
O rascunho deve citar a garantia de um ano do fabricante — exatamente como no PDF de política.
Fora de escopo (horário da loja)
"Que horas a loja abre?"
O agente deve dizer honestamente que não tem essa informação, em vez de inventar — prova de que usa só os PDFs fornecidos.
✓ Checklist por teste
- ✓E-mail recebido → classificado como suporte.
- ✓Política correta encontrada no vector store.
- ✓Rascunho preciso gerado e visível na pasta Rascunhos.
✗ Sinais de alerta
- ✗Workflow "verde" mas com número errado na resposta.
- ✗O agente inventa um horário de loja que não existe nos PDFs.
- ✗E-mail não-suporte gerando rascunho (deveria parar).
🧭 Por que aprender
Testar com cenários reais é o que transforma "parece funcionar" em "funciona". A recusa em alucinar é um resultado desejado, não um bug — e perguntas de área cinza (como horário da loja) revelam onde você precisa decidir o próprio escopo do agente.
Auto-recuperação (opcional): o workflow rodou sem nenhum erro (tudo "verde"). Isso garante que a resposta está correta?
📌 Resumo do Módulo
Próximo Módulo:
1.3 — De "Funciona" a "Funciona Bem": Enhancement