🧰 Requisitos previos y cómo usarlo
Cada cuadro de abajo es un prompt o comando para copiar y ejecutar, con 🎯 objetivo e ✅ cómo verificar. Cambia lo que está entre <chaves>. Requisitos previos: repositorio conectado en GitHub, cuenta de Trigger.dev conectada, el MCP de Trigger.dev e o MCP de Firecrawl instalados en el asistente (reinicia después de instalar), proyecto inicializado y las env vars en el panel. Construye por capas: deploy → prueba manual → corregir → repetir.
La diferencia entre este módulo y el anterior es quién lo activa el agente. Antes eras tú. Ahora hay dos activadores diferentes: uno reloj (cron, según el calendario) y una timbre (webhook, por evento). Ambos se ejecutan en la nube, sin que tú estés presente.
Diagrama ilustrativo — misma plataforma en la nube (el «coordinador» en cian), dos disparadores: el reloj activa el primero; una solicitud externa activa el segundo.
🔁 Agente de investigación programado
Qué es
El primer agente es una tarea programada que se ejecuta sola cada mañana: mediante un disparador cron, toma un tema fijo y busca contenido en la web con Firecrawl, sintetiza con la IA y registra una línea estructurada en el Google Sheets — sin que tú estés presente. Toda la tarea queda en un solo archivo, morning-research.ts, con el tema al principio (fácil de cambiar y versionar).
¿Qué es?Cron — un programador con 5 campos (minuto, hora, día del mes, mes, día de la semana). Ej.: 0 8 * * * = "todos los días a las 8 h". Firecrawl — una herramienta que busca y extrae contenido de páginas web en un formato limpio. Tarea (task) — una unidad de trabajo alojada que ejecuta la plataforma.
🎯 Objetivo: confirmar que el MCP de Firecrawl esté disponible antes de planificar.
¿Tienes acceso al MCP server de Firecrawl? Si no, configúralo: la clave está en mi archivo .env.
✅ Cómo verificar: la IA confirma que está configurado (o lo instala leyendo la clave de .env). Reinicia el asistente después de instalar cualquier MCP.
🎯 Objetivo: planificar la tarea de investigación programada.
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.
✅ Cómo verificar: la hoja de cálculo debe tener una pestaña Sheet1 con encabezado (fecha, tema, resumen, fuentes, estado). La tarea nace en un único archivo con el tema en la parte superior.
Por qué aprender
Este es el primer agente que «vive solo» — cierra el agentic gap entre ejecutar en local y estar en producción. Ten en cuenta que incorporas manejo de errores y log desde el primer prompt: un agente alojado no te tiene cerca para que lo arregles en el momento, así que la robustez se construye desde el inicio.
Conceptos clave
Agenda con 5 campos.
Búsqueda en la web.
Tema en la parte superior, versionable.
Error + log en el primer prompt.
🔐 OAuth refresh token (y la alternativa mediante terminal)
Qué es
En la nube no hay una ventana de inicio de sesión donde el agente pueda hacer clic. En su lugar, usa un refresh token: una credencial de larga duración que renueva automáticamente el acceso (access token). Para Google, necesitas cuatro valores en el .env y en el panel: client ID, client secret, refresh token e o sheet ID.
¿Qué es?Access token — clave de acceso breve, que caduca en minutos. Refresh token — clave larga que intercambias por un nuevo access token sin iniciar sesión de nuevo. Sheet ID — el identificador de la hoja de cálculo, que aparece en la URL entre las barras después de /d/.
🎯 Objetivo: obtener el refresh token cuando falla el método mediante la interfaz.
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.
✅ Cómo verificar: el terminal imprime una URL → autorizas en el navegador → imprime el refresh token. Pégalo en el .env e en las variables de entorno de la plataforma (dev y prod).
🗺️ Dónde encontrar cada credencial
Client ID y secret: Google Cloud Console → APIs & Services → Credentials (crea un OAuth2 client ID y un nuevo client secret). Sheet ID: en la URL de la hoja de cálculo, entre las barras después de /d/. Clave de Firecrawl: en el panel de firecrawl.dev → API Keys. Usa OAuth, no service account — dile esto a la IA para que ajuste los campos del .env.
Por qué aprender
El refresh token es la fricción clásica al alojar agentes, y el camino «oficial» (OAuth Playground) a veces simplemente falla. Conoce el fallback vía terminal desbloquea el deploy justo cuando más lo necesitas, en vez de dejarte atascado en una pantalla de error.
Conceptos clave
Renueva sin iniciar sesión.
ID, secret, token, sheet.
Script de terminal.
Avísale a la IA.
🐛 Error que solo aparece en producción
Qué es
Después del deploy, tú activa una prueba manual en el panel (no se puede esperar a la hora programada) y lee los traces en tiempo real. Los errores de producción tienen su propia realidad: en este proyecto, Firecrawl devolvió success: false pero con resultados — solo que bajo la propiedad web en lugar de data. El formato real de la respuesta difería de lo que el código suponía.
Diagrama ilustrativo — el loop humano de depuración: trace → error → IA → fix → redeploy → vuelve a ejecutar. La pieza clave es copiar el error completo con contexto.
🎯 Objetivo: devolver el error de producción con contexto para que la IA lo corrija.
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.
✅ Cómo verificar: después del redeploy, la plataforma vuelve a ejecutar y el run queda en verde (p. ej.: 8 resultados, estado success). Cuidado con las pistas falsas: aquí la sospecha inicial era la clave de prod, pero estaba bien: el error estaba en el formato.
✅ El manejo de errores demostró su valor
Incluso cuando Firecrawl falló, la tarea no se rompió: también guardó una fila parcial en Sheets (fecha, tema, resumen, sin fuentes, estado=parcial), exactamente lo que pidió el prompt. Es la prueba de que "trata los errores sin romper nada" compensa desde el primer prompt.
Por qué aprender
La producción es donde la teoría se encuentra con la realidad: los formatos de respuesta cambian, ocurren timeouts y desaparecen las env vars. La habilidad central no es «nunca equivocarse», es el ciclo humano de depuración — leer el trace, copiar el error completo (no un resumen tuyo), devolverlo con contexto y hacer el redeploy.
Conceptos clave
No esperes al cron.
Copia todo, con contexto.
Confirma antes de culpar.
Una línea parcial está bien.
📄 Informe por webhook (payload → .docx → Drive)
Qué es
El segundo agente se activa mediante evento, no según el reloj. Recibe un payload JSON vía webhook (con los campos: nombre de la empresa, sector, objetivo, desafío), genera un informe en .docx y lo guarda en el Google Drive. La IA arma las secciones del informe (resumen ejecutivo, contexto del sector, desafíos) a partir de solo estos cuatro campos.
¿Qué es?Payload — los datos que llegan junto con la solicitud al webhook (p. ej., { "company": "Acme", "industry": "Construção" }). .docx — formato de documento de Word. Folder ID — el identificador de una carpeta de Drive, para organizar la salida (sin él, el archivo queda en la raíz).
🎯 Objetivo: planificar la tarea activada por webhook que genera el informe.
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.
✅ Cómo verificar: la tarea crea tipos para el payload y normaliza las etiquetas del form. Opcional: proporciona un ID de la carpeta de Drive para organizar la salida.
🎯 Objetivo: probar localmente ANTES de conectar cualquier 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>" }
✅ Cómo verificar: aparece el run, se genera el .docx y el archivo está en Drive; todo esto antes de conectar el formulario. Probar primero en local ahorra un ciclo de depuración.
Por qué aprender
Este agente enseña cómo activar por evento: responde a una solicitud externa, no a un reloj. Es el patrón que conecta cualquier fuente (formulario, otro sistema, un botón) con un agente que produce un artefacto — y la prueba local primero es la disciplina que evita depurar dos problemas (tu formulario y tu tarea) al mismo tiempo.
Conceptos clave
Datos del pedido.
.docx en Drive.
Organiza la salida.
Antes del formulario.
🔔 Webhook como «timbre digital» + auth Bearer
Qué es
Un webhook es una «campanilla digital»: una URL que queda a la escucha de datos; cuando alguien la «toca» (hace una solicitud), activa la tarea y envía el payload. Como la URL se puede compartir (cabe en un sitio web, en un correo electrónico), la proteges con un encabezado Authorization: Bearer + tu clave secreta.
¿Qué es?Header (encabezado) — información adicional que viaja con la solicitud. Bearer token — un esquema de autenticación donde la clave va en el header Authorization: Bearer <chave>; a quien no envía la clave correcta se le rechaza.
🎯 Objetivo: configurar el nodo HTTP Request de n8n para que active el timbre con 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 }
✅ Cómo verificar: ten cuidado con el espacio después de "Bearer" (error común). Sin el token correcto, la tarea rechaza la solicitud. Con él, el run aparece en el panel con el payload visible.
Por qué aprender
La URL del webhook es pública por naturaleza: cualquiera que la descubra puede «tocar el timbre» y consumir tus recursos. El Bearer es el candado básico: sin la clave correcta, se rechaza la solicitud. Es la primera línea de seguridad de cualquier agente que acepta activaciones externas.
Conceptos clave
El timbre digital.
Datos en el cuerpo.
Clave en el header.
"Bearer " + clave.
📋 Formulario no-code → webhook
Qué es
Para darle un aspecto humano al agente, creas un formulario no-code que, al enviarse, hace la solicitud al webhook con el payload. En n8n son solo dos nodos: un Form Submission (los cuatro campos + enviar) y el Solicitud HTTP del tema anterior. La herramienta de form se puede cambiar: sirve cualquiera que acepte webhook/API.
¿Qué es?No-code — crear algo arrastrando bloques, sin escribir código. Form Submission trigger — un nodo que crea un formulario y activa el flujo cuando alguien lo envía.
🎯 Objetivo: conectar el formulario al webhook y hacer una prueba de extremo a extremo.
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.
✅ Cómo verificar: el run aparece en la plataforma con el payload del form y el informe llega a Drive. Atención: algunas herramientas de form fallan en la parte de API; si la tuya falla, cámbiala por n8n.
Por qué aprender
El form conecta a una persona real con el agente sin que tengas que escribir un frontend todavía; eso llega en el módulo 5.3. Es la forma más rápida de darle una interfaz a una automatización y comprobar el flujo de punta a punta con un envío real.
Conceptos clave
Form + HTTP Request.
Form → payload.
URL de producción.
Cualquier form con API.
🐙 Pipeline de GitHub → deploy automático
Qué es
En lugar de hacer deploy manual con cada cambio, conectas el repositorio GitHub a la plataforma de alojamiento: cada push activa el deploy automáticamente. Así, el código del repositorio es la fuente de la verdad e iterar con la IA ya publica la versión más reciente. La parte manual es un secret de repositorio que le da permiso a GitHub para hacer el deploy.
¿Qué es?commit / push — guardar una instantánea del código y enviarla a la nube. .gitignore — lista de archivos que Git debe ignorar (el .env NUNCA sube). Repository secret — un secreto guardado en GitHub, que usan las automatizaciones de deploy.
🎯 Objetivo: hacer que cada push a GitHub publique automáticamente.
[prompt] Configura el flujo para que, cuando itere contigo, el código se envíe a GitHub y GitHub haga el deploy automático en la plataforma. Confirma que .env está en .gitignore y crea un .env.example seguro. [paso manual en GitHub] Settings → Security → Secrets and Variables → Actions → Repository Secrets → New Repository Secret Name: TRIGGER_ACCESS_TOKEN Value:
✅ Cómo verificar: haz un pequeño cambio, haz push y comprueba que el deploy se ejecute automáticamente. El .env no puede aparecer en el repositorio (confirma que está en el .gitignore).
Por qué aprender
El deploy manual es un paso fácil de olvidar y de hacer mal. Automatizarlo significa que «lo que está en el repositorio es lo que está en línea» y que iterar consiste solo en conversar con la IA y hacer push. Es el hábito que diferencia un prototipo de un sistema mantenido. (La ruta 6 profundiza en GitHub y Trigger.dev.)
Conceptos clave
Push = publica.
El repo manda.
Permite hacer el deploy.
.env nunca se sube.
📊 Verificar las ejecuciones, los rastros y el schedule
Qué es
Como el agente funciona sin ti, el panel es cómo sabes que está funcionando correctamente. Aprende a leer: la lista de runs (ejecuciones), el trace de cada una (cada línea es un paso), las schedules (el cron activo + el próximo horario) y la separación dev vs prod. Revisa también la fila real que apareció en Sheets.
¿Qué es?Run — una ejecución de la tarea. Trace — el paso a paso de esa ejecución (entradas, salidas, errores). Schedule — la regla cron que activa la tarea. dev vs prod — entorno de pruebas frente al entorno real; una tarea puede quedar por error solo en dev.
🎯 Objetivo: confirmar que los dos agentes están en buen estado y 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.
✅ Cómo verificar: el schedule muestra el próximo run; un run de prueba queda en verde; la alerta se activa en un run forzado a fallar. Recuerda: los retries resuelven fallos transitorias, no bugs de lógica.
Por qué aprender
La observabilidad es lo que hace confiable a un agente alojado: cuando no estás presente, runs, traces, schedules y alertas son tus ojos. Un error común es dejar la tarea solo en dev y creer que está en línea; siempre confirma el entorno. Y las alertas cierran el ciclo: solo actúas cuando algo realmente falla.
Una llamada externa falla de vez en cuando por timeout, pero la lógica es correcta. ¿Cuál es la solución adecuada?
📌 Resumen del módulo
Authorization: Bearer (cuidado con el espacio)..env nunca se sube.Siguiente módulo:
5.3 — App Full-Stack (Lead Qualifier) + Frontend para n8n: del agente al producto con interfaz, auth y pago.