Este módulo são dois builds completos rodando em produção. Um é agendado: o cron dispara, o Firecrawl pesquisa, a IA sintetiza e uma linha vai para o Google Sheets. O outro é por evento: um webhook recebe um payload JSON, gera um .docx e salva no Google Drive. O diagrama compara os dois caminhos.

Diagrama ilustrativo — recriação conceitual dos dois builds em produção, não uma captura de tela real.

O que é

O primeiro build é um agente de pesquisa agendado: uma tarefa do Trigger.dev que roda sozinha toda manhã num horário cron. Ela pesquisa um tópico fixo com o Firecrawl, sintetiza os achados com a IA e escreve uma linha estruturada no Google Sheets. Tudo num arquivo único (ex.: morning-research.ts), com o tópico hard-coded no topo — fácil de mudar e versionar.

Por que aprender

O fluxo de build

Conceitos-chave

O que é

Para a tarefa escrever no Google Sheets de forma autônoma, ela precisa de um refresh token OAuth — uma credencial de configuração única que renova o acesso sem login manual. Em vez de uma service account, o build usa OAuth com client ID, client secret e o refresh token, todos no .env e nas env vars da nuvem.

Por que aprender

Conceitos-chave

O fallback é elegante: um script no terminal (usando client ID + secret do .env) imprime uma URL de autorização; você abre, autoriza, e o script devolve o refresh token para colar no .env e nas env vars. É o setup feito uma vez — depois a tarefa renova o acesso sozinha a cada execução.

O que é

Alguns erros só surgem com dados reais em produção. No build agendado, o Firecrawl retornou success: false e colocou os resultados numa propriedade web em vez de data — o shape da resposta diferiu do que o código assumia. A correção: ajustar o parsing, redeployar e disparar de novo.

// o código esperava:
{ "success": true, "data": [ ... ] }

// mas em produção veio:
{ "success": false, "web": [ ... ] }   // ← parsing quebra aqui

Por que aprender

Esperar erros do modelo é parte do jogo — ele pode assumir o formato errado de uma resposta de API. O importante é a reação: abrir o passo que falhou, copiar a mensagem de erro completa, colar na IA para diagnosticar, aplicar a correção de parsing, redeployar e disparar de novo. E aqui o tratamento de erro provou seu valor: mesmo com o Firecrawl falhando, a tarefa não crashou e ainda escreveu uma linha parcial no Sheets.

O que é

O segundo build é orientado a evento: uma tarefa disparada por webhook. Um formulário web envia um payload JSON (campos como nome da empresa, setor, meta, desafio) para a URL do webhook; a tarefa gera um relatório .docx a partir desses campos e o salva automaticamente no Google Drive. A IA preenche as seções do relatório (sumário executivo, contexto do setor, desafios) a partir de poucos campos de entrada.

Por que aprender

Conceitos-chave

A tarefa normaliza os rótulos do formulário para o shape de payload esperado, e a execução pode ser de sucesso total ou parcial. A ordem de teste é sempre: local primeiro (dev server + payload de exemplo), depois com o formulário, e só então em produção. Qualquer formulário/sistema que suporte webhooks + API serve — não está preso a uma ferramenta específica.

O que é

Um webhook é uma "campainha digital": uma URL que escuta dados que chegam e, ao recebê-los, acorda a tarefa, passando o payload adiante. Enquanto o cron dispara por tempo, o webhook dispara por evento. A URL inclui o ID da task (ex.: webhook-report), e ela é compartilhável e embutível — pode vir de um site, um e-mail, outro sistema.

Por que aprender

Conceitos-chave

POST https://.../webhook-report
Authorization: Bearer <chave-da-API>
Content-Type: application/json

{ "payload": { "empresa": "...", "setor": "..." } }

O que é

O pipeline GitHub → Trigger.dev fecha o ciclo de iteração: quando você muda algo no editor e dá push para o GitHub, o GitHub faz o deploy automático no Trigger.dev. Os arquivos mais recentes estão sempre no ar, sem deploy manual. É o "commit → push → deploy" rodando sozinho.

Por que aprender

Ligando o GitHub ao Trigger.dev

Conceitos-chave

O que é

Sem um agente se auto-curando em produção, o tratamento de erro robusto é o que fecha o agentic gap. A abordagem é em camadas: log significativo em cada passo (visibilidade), try/catch em volta de cada chamada externa, retries configuráveis com backoff e alertas de falha. O Trigger.dev dá visibilidade e retry, mas só consegue retentar o que reconhece como falha.

Por que aprender

Conceitos-chave

O que é

Em produção, a IA ainda depura — mas não mais automaticamente. O loop humano de debug é o ciclo em que você é a ponte: abrir o trace vermelho no dashboard, copiar o erro, colar na IA ("aqui está o trace que falhou, o que está errado, como conserto?"), deixá-la diagnosticar, aplicar a correção e redeployar. O trace + a IA dão diagnóstico rápido; um humano só precisa levar o erro até ela.

Por que aprender

Conceitos-chave

A mudança de mentalidade é deixar de ser o gatilho para configurar gatilhos que rodam enquanto você se afasta. Prompting e leitura de traces ficam mais fáceis com a repetição — o segundo build é sempre mais rápido que o primeiro. E garanta que toda tarefa deployada tenha alertas de falha, para você saber da quebra antes do usuário.