🧰 Pré-requisitos e como usar
Cada caixa abaixo é um prompt ou comando para copiar e rodar, com 🎯 objetivo e ✅ como verificar. Troque o que está entre <chaves>. Pré-requisitos: repositório no GitHub conectado, conta Trigger.dev conectada, o MCP do Trigger.dev e o MCP do Firecrawl instalados no assistente (reinicie depois de instalar), projeto inicializado e as env vars no painel. Construa em camadas: deploy → teste manual → corrigir → repetir.
A diferença entre este módulo e o anterior é quem dispara o agente. Antes era você. Agora são dois gatilhos diferentes: um relógio (cron, por agenda) e uma campainha (webhook, por evento). Os dois rodam na nuvem — sem você presente.
Diagrama ilustrativo — mesma plataforma na nuvem (o "coordenador" em ciano), dois gatilhos: o relógio acorda o primeiro; um pedido externo acorda o segundo.
🔁 Agente de pesquisa agendado
O que é
O primeiro agente é uma tarefa agendada que roda sozinha toda manhã: por um gatilho cron, ela pega um tópico fixo, busca conteúdo na web com Firecrawl, sintetiza com a IA e grava uma linha estruturada no Google Sheets — sem você presente. Toda a tarefa fica num único arquivo, morning-research.ts, com o tópico no topo (fácil de mudar e versionar).
O que é?Cron — um agendador em 5 campos (minuto, hora, dia-do-mês, mês, dia-da-semana). Ex.: 0 8 * * * = "às 8h, todo dia". Firecrawl — uma ferramenta que busca e extrai conteúdo de páginas da web em formato limpo. Tarefa (task) — uma unidade de trabalho hospedada que a plataforma executa.
🎯 Objetivo: confirmar que o MCP do Firecrawl está disponível antes de planejar.
Você tem acesso ao MCP server do Firecrawl? Se não, configure — a chave está no meu arquivo .env.
✅ Como verificar: a IA confirma que está configurado (ou instala lendo a chave do .env). Reinicie o assistente após instalar qualquer MCP.
🎯 Objetivo: planejar a tarefa agendada de pesquisa.
Quero construir uma tarefa agendada que rode totalmente sozinha toda manhã. Ela pega um tópico fixo (<tópico>), busca na web com Firecrawl, sintetiza os achados e grava uma linha no Google Sheets. Sem perguntas no meio da execução, trate erros sem quebrar e registre log em cada passo. Me ajude a planejar isso.
✅ Como verificar: a planilha deve ter uma aba Sheet1 com cabeçalho (data, tópico, resumo, fontes, status). A tarefa nasce num arquivo único com o tópico no topo.
Por que aprender
Este é o primeiro agente que "vive sozinho" — fecha o agentic gap entre rodar local e estar em produção. Note que você embute tratamento de erro e log desde o primeiro prompt: agente hospedado não tem você por perto para consertar na hora, então a robustez nasce com ele.
Conceitos-chave
Agenda em 5 campos.
Busca na web.
Tópico no topo, versionável.
Erro + log no 1º prompt.
🔐 OAuth refresh token (e o fallback via terminal)
O que é
Na nuvem não existe uma janela de login para o agente clicar. Em vez disso, ele usa um refresh token: uma credencial de longa duração que renova o acesso (access token) automaticamente. Para o Google, você precisa de quatro valores no .env e no painel: client ID, client secret, refresh token e o sheet ID.
O que é?Access token — chave de acesso curta, que expira em minutos. Refresh token — chave longa que troca por um novo access token sem novo login. Sheet ID — o identificador da planilha, que fica na URL entre as barras depois de /d/.
🎯 Objetivo: obter o refresh token quando o método pela interface falha.
O método pelo OAuth Playground deu "Access blocked: this app's request is invalid". Gere um script de terminal que use meu client ID e secret do .env para imprimir uma URL de autorização. Vou abrir no navegador, autorizar, e o terminal vai imprimir o refresh token. Aí eu colo no .env e nas env vars do painel.
✅ Como verificar: o terminal imprime uma URL → você autoriza no navegador → ele imprime o refresh token. Cole-o no .env e nas env vars da plataforma (dev e prod).
🗺️ Onde achar cada credencial
Client ID e secret: Google Cloud Console → APIs & Services → Credentials (crie um OAuth2 client ID e um novo client secret). Sheet ID: na URL da planilha, entre as barras depois de /d/. Chave do Firecrawl: no painel do firecrawl.dev → API Keys. Use OAuth, não service account — diga isso à IA para ela ajustar os campos do .env.
Por que aprender
O refresh token é o atrito clássico de hospedar agentes — e o caminho "oficial" (OAuth Playground) às vezes simplesmente falha. Conhecer o fallback via terminal destrava o deploy quando você mais precisa, em vez de te deixar travado numa tela de erro.
Conceitos-chave
Renova sem login.
ID, secret, token, sheet.
Script de terminal.
Avise a IA.
🐛 Debug que só aparece em produção
O que é
Depois do deploy, você dispara um teste manual no painel (não dá pra esperar a hora agendada) e lê os traces em tempo real. Erros de produção têm realidade própria: neste projeto, o Firecrawl voltou com success: false mas com resultados — só que sob a propriedade web em vez de data. O formato real da resposta divergia do que o código assumia.
Diagrama ilustrativo — o loop humano de debug: trace → erro → IA → fix → redeploy → re-executa. A peça-chave é copiar o erro completo com contexto.
🎯 Objetivo: devolver o erro de produção com contexto para a IA corrigir.
O run falhou em produção. Aqui está o erro completo do trace: <cole o erro do passo que ficou vermelho> O Firecrawl retornou resultados, mas numa propriedade "web" em vez de "data", e success veio false. O formato da resposta do SDK difere do que assumimos. Corrija o parsing e me diga o comando de redeploy.
✅ Como verificar: após o redeploy, a plataforma reexecuta e o run fica verde (ex.: 8 resultados, status success). Cuidado com pistas falsas: aqui a suspeita inicial era a chave de prod, mas ela estava certa — o erro estava no formato.
✅ O tratamento de erro provou seu valor
Mesmo quando o Firecrawl falhou, a tarefa não quebrou: ela ainda gravou uma linha parcial no Sheets (data, tópico, resumo, sem fontes, status=parcial) — exatamente o que o prompt pediu. É a prova de que "trate erros sem quebrar" desde o primeiro prompt compensa.
Por que aprender
Produção é onde a teoria encontra a realidade: formatos de resposta mudam, timeouts acontecem, env vars somem. A habilidade central não é "nunca errar", é o loop humano de debug — ler o trace, copiar o erro completo (não um resumo seu), devolver com contexto e fazer o redeploy.
Conceitos-chave
Não espere o cron.
Copie tudo, com contexto.
Confirme antes de culpar.
Linha parcial é ok.
📄 Relatório por webhook (payload → .docx → Drive)
O que é
O segundo agente é disparado por evento, não por relógio. Ele recebe um payload JSON via webhook (com os campos: nome da empresa, setor, objetivo, desafio), gera um relatório em .docx e o salva no Google Drive. A IA monta as seções do relatório (sumário executivo, contexto do setor, desafios) a partir de só esses quatro campos.
O que é?Payload — os dados que chegam junto com o pedido ao webhook (ex.: { "company": "Acme", "industry": "Construção" }). .docx — formato de documento do Word. Folder ID — o identificador de uma pasta do Drive, para organizar a saída (sem ele, o arquivo cai na raiz).
🎯 Objetivo: planejar a tarefa disparada por webhook que gera o relatório.
Quero uma tarefa disparada por webhook (via um form / HTTP request). Ela recebe um payload JSON com os campos: <nome da empresa, setor, objetivo, desafio> Gera um relatório .docx e salva no Google Drive. Sem perguntas no meio, trate erros sem quebrar, registre log em cada passo. Me ajude a planejar.
✅ Como verificar: a tarefa cria tipos para o payload e normaliza os rótulos do form. Opcional: forneça um folder ID do Drive para organizar a saída.
🎯 Objetivo: testar localmente ANTES de conectar qualquer form.
Suba o dev server e teste a tarefa de relatório com este payload:
{ "company": "<Acme>", "industry": "<Construção>",
"goal": "<dobrar leads>", "challenge": "<ciclo de venda longo>" }
✅ Como verificar: o run aparece, o .docx é gerado e o arquivo está no Drive — tudo isso antes de ligar o form. Testar local primeiro economiza um ciclo de debug.
Por que aprender
Este agente ensina o disparo por evento: ele reage a um pedido externo, não a um relógio. É o padrão que conecta qualquer fonte (form, outro sistema, um botão) a um agente que produz um artefato — e o teste local primeiro é a disciplina que evita debugar dois problemas (o seu form e a sua tarefa) ao mesmo tempo.
Conceitos-chave
Dados do pedido.
.docx no Drive.
Organiza a saída.
Antes do form.
🔔 Webhook como "campainha digital" + auth Bearer
O que é
Um webhook é uma "campainha digital": uma URL que fica escutando dados; quando alguém a "toca" (faz uma requisição), ela acorda a tarefa e passa o payload adiante. Como a URL é compartilhável (cabe num site, num e-mail), você a protege com um cabeçalho Authorization: Bearer + a sua chave secreta.
O que é?Header (cabeçalho) — informações extras que viajam com a requisição. Bearer token — um esquema de auth onde a chave vai no header Authorization: Bearer <chave>; quem não manda a chave certa é rejeitado.
🎯 Objetivo: configurar o nó HTTP Request do n8n para tocar a campainha com auth.
Method: POST
URL: <url-do-webhook-da-tarefa> (inclui o ID/nome da tarefa, ex.: webhook-report)
Authentication: None (a auth vai pelo header)
Send Headers: ON
Name: Authorization
Value: Bearer <sua-chave-secreta> ← "Bearer" + ESPAÇO + chave (do painel → API Keys → secret)
Send Body: ON → JSON
campo: payload → { company, industry, goal, challenge }
✅ Como verificar: cuidado com o espaço depois de "Bearer" (erro comum). Sem o token correto, a tarefa rejeita o pedido. Com ele, o run aparece no painel com o payload visível.
Por que aprender
A URL do webhook é pública por natureza — qualquer um que a descobrir pode "tocar a campainha" e gastar seus recursos. O Bearer é o cadeado básico: sem a chave certa, o pedido é recusado. É a primeira linha de segurança de qualquer agente que aceita disparos externos.
Conceitos-chave
A campainha digital.
Dados no corpo.
Chave no header.
"Bearer " + chave.
📋 Form no-code → webhook
O que é
Para dar uma cara humana ao agente, você monta um formulário no-code que, ao ser enviado, faz a requisição ao webhook com o payload. No n8n são só dois nós: um Form Submission (os quatro campos + enviar) e o HTTP Request do tópico anterior. A ferramenta de form é trocável — qualquer uma que aceite webhook/API serve.
O que é?No-code — montar algo arrastando blocos, sem escrever código. Form Submission trigger — um nó que cria um formulário e dispara o fluxo quando alguém envia.
🎯 Objetivo: ligar o form ao webhook e fazer um teste de ponta a ponta.
1. Form Submission trigger: 4 campos de texto (empresa, setor, objetivo, desafio) + enviar. 2. HTTP Request: configurado como no tópico 5 (POST + Bearer + body payload). 3. Mapeie cada campo do form para o payload. 4. Execute o nó do form com dados de teste e confira o run no painel. 5. Para o teste final: PUBLIQUE o form em produção e use a URL de produção.
✅ Como verificar: o run aparece na plataforma com o payload do form e o relatório cai no Drive. Atenção: algumas ferramentas de form falham na parte de API — se a sua falhar, troque pelo n8n.
Por que aprender
O form conecta uma pessoa real ao agente sem você precisar escrever um frontend ainda — isso vem no módulo 5.3. É o jeito mais rápido de dar uma interface a uma automação e provar o fluxo de ponta a ponta com um envio de verdade.
Conceitos-chave
Form + HTTP Request.
Form → payload.
URL de produção.
Qualquer form com API.
🐙 Pipeline GitHub → deploy automático
O que é
Em vez de fazer deploy manual a cada mudança, você liga o repositório GitHub à plataforma de hospedagem: cada push dispara o deploy sozinho. Assim o código no repositório é a fonte da verdade, e iterar com a IA já publica a versão mais nova. A peça manual é um secret de repositório que dá à GitHub permissão para fazer o deploy.
O que é?commit / push — salvar um instantâneo do código e enviá-lo para a nuvem. .gitignore — lista de arquivos que o Git deve ignorar (o .env NUNCA sobe). Repository secret — um segredo guardado no GitHub, usado pelas automações de deploy.
🎯 Objetivo: fazer cada push no GitHub publicar automaticamente.
[prompt] Configure o fluxo para que, quando eu iterar com você, o código seja enviado ao GitHub e o GitHub faça o deploy automático para a plataforma. Confirme que o .env está no .gitignore e crie um .env.example seguro. [passo manual no GitHub] Settings → Security → Secrets and Variables → Actions → Repository Secrets → New Repository Secret Name: TRIGGER_ACCESS_TOKEN Value:
✅ Como verificar: faça uma pequena mudança, dê push, e veja o deploy rodar sozinho. O .env não pode aparecer no repositório (confira que está no .gitignore).
Por que aprender
O deploy manual é um passo fácil de esquecer e de errar. Automatizá-lo significa que "o que está no repositório é o que está no ar" — e que iterar é só conversar com a IA e dar push. É o hábito que separa um protótipo de um sistema mantido. (A trilha 6 aprofunda GitHub e Trigger.dev.)
Conceitos-chave
Push = publica.
O repo manda.
Permite o deploy.
.env nunca sobe.
📊 Verificar runs, traces e o schedule
O que é
Como o agente roda sem você, o painel é como você sabe que ele está saudável. Aprenda a ler: a lista de runs (execuções), o trace de cada uma (cada linha é um passo), as schedules (o cron ativo + o próximo horário) e a separação dev vs prod. Confira também a linha real que apareceu no Sheets.
O que é?Run — uma execução da tarefa. Trace — o passo a passo daquela execução (entradas, saídas, erros). Schedule — a regra cron que dispara a tarefa. dev vs prod — ambiente de testes vs ambiente real; uma tarefa pode estar só em dev por engano.
🎯 Objetivo: confirmar que os dois agentes estão saudáveis e configurar alertas.
[ ] Em Schedules, a tarefa morning-research aparece com o cron (ex.: 0 8 * * *)
e o próximo horário (amanhã, 8h).
[ ] O último run está verde; o trace mostra cada passo.
[ ] A linha apareceu no Google Sheets / o .docx no Drive.
[ ] A tarefa está em PROD, não só em dev.
[prompt] Adicione retries com backoff exponencial (até 3, começando em 30s)
para falhas transitórias, e configure um alerta por <e-mail/Slack> quando
um run ou deploy falhar.
✅ Como verificar: o schedule mostra o próximo run; um run de teste fica verde; o alerta dispara num run forçado a falhar. Lembre: retries resolvem falhas transitórias, não bugs de lógica.
Por que aprender
Observabilidade é o que torna um agente hospedado confiável: sem você presente, runs, traces, schedules e alertas são os seus olhos. Um erro comum é deixar a tarefa só em dev e achar que está no ar — sempre confirme o ambiente. E alertas fecham o loop: você só age quando algo realmente falha.
Uma chamada externa falha de vez em quando por timeout, mas a lógica está certa. Qual é o remédio adequado?
📌 Resumo do Módulo
Authorization: Bearer (cuidado com o espaço)..env nunca sobe.Próximo Módulo:
5.3 — App Full-Stack (Lead Qualifier) + Frontend pra n8n: do agente ao produto com interface, auth e pagamento.