Este módulo consiste en dos builds completos que se ejecutan en producción. Uno es programado: el cron se activa, Firecrawl busca, la IA sintetiza y se agrega una fila a Google Sheets. El otro es por evento: un webhook recibe un payload JSON, genera un .docx y guarda en Google Drive. El diagrama compara los dos caminos.

Diagrama ilustrativo — recreación conceptual de los dos builds en producción, no es una captura de pantalla real.

Qué es

El primer build es un agente de investigación programado: una tarea de Trigger.dev que se ejecuta sola cada mañana a una hora programada con cron. Investiga un tema fijo con el Firecrawl, sintetiza los hallazgos con la IA y escribe una línea estructurada en el Google Sheets. Todo en un único archivo (p. ej., morning-research.ts), con el tema hard-coded en la parte superior: fácil de cambiar y versionar.

Por qué aprender

El flujo de build

Conceptos clave

Qué es

Para que la tarea escriba en Google Sheets de forma autónoma, necesita un refresh token OAuth: una credencial de configuración única que renueva el acceso sin iniciar sesión manualmente. En lugar de una service account, el build usa OAuth con client ID, client secret y el refresh token, todos en el .env y en las env vars de la nube.

Por qué aprender

Conceptos clave

El fallback es elegante: un script en la terminal (que usa client ID + secret de .env) imprime una URL de autorización; la abres, autorizas y el script devuelve el refresh token para pegarlo en el .env y en las env vars. La configuración se hace una sola vez; después, la tarea renueva el acceso por su cuenta en cada ejecución.

Qué es

Algunos errores solo aparecen con datos reales en producción. En la compilación programada, Firecrawl devolvió success: false y puso los resultados en una propiedad web en vez de data — o shape de la respuesta fue diferente de lo que el código suponía. La corrección: ajustar el parsing, volver a hacer el deploy y activarlo de nuevo.

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

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

Por qué aprender

Es normal que el modelo cometa errores: puede asumir un formato incorrecto para una respuesta de API. Lo importante es cómo reaccionas: abre el paso que falló, copia el mensaje de error completo, pégalo en la IA para diagnosticar el problema, aplica la corrección del parsing, vuelve a desplegar y ejecútalo otra vez. Y aquí el manejo de errores demostró su valor: aunque Firecrawl falló, la tarea no se bloqueó y aun así escribió una fila parcial en Sheets.

Qué es

El segundo build está orientado a eventos: una tarea activada por webhook. Un formulario web envía un payload JSON (campos como nombre de la empresa, sector, meta, desafío) a la URL del webhook; la tarea genera un informe .docx a partir de estos campos y lo guarda automáticamente en el Google Drive. La IA completa las secciones del informe (resumen ejecutivo, contexto del sector, desafíos) a partir de pocos campos de entrada.

Por qué aprender

Conceptos clave

La tarea normaliza las etiquetas del formulario para ajustarlas a la estructura de payload esperada, y la ejecución puede ser totalmente exitosa o parcial. El orden de las pruebas siempre es: local primero (servidor de desarrollo + payload de ejemplo), luego con el formulario y solo entonces en producción. Cualquier formulario/sistema que admita webhooks + API sirve; no depende de una herramienta específica.

Qué es

Un webhook es un "timbre digital": una URL que escucha los datos que llegan y, al recibirlos, activa la tarea y pasa el payload más adelante. Mientras que el cron se activa por tiempo, el webhook se activa por evento. La URL incluye el ID de la task (p. ej., webhook-report) y se puede compartir e insertar: puede venir de un sitio web, un correo electrónico u otro sistema.

Por qué aprender

Conceptos clave

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

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

Qué es

O pipeline GitHub → Trigger.dev cierra el ciclo de iteración: cuando cambias algo en el editor y haces push a GitHub, GitHub hace el deploy automático en Trigger.dev. Los archivos más recientes siempre están disponibles, sin deploy manual. Es el «commit → push → deploy» funcionando solo.

Por qué aprender

Conectar GitHub con Trigger.dev

Conceptos clave

Qué es

Sin un agente que se autocure en producción, el manejo robusto de errores es lo que cierra la brecha agentic. El enfoque se organiza en capas: registro significativo en cada paso (visibilidad), try/catch alrededor de cada llamada externa, reintentos configurables con backoff y alertas de error. Trigger.dev ofrece visibilidad y reintentos, pero solo puede volver a intentar lo que reconoce como error.

Por qué aprender

Conceptos clave

Qué es

En producción, la IA todavía depura, pero ya no automáticamente. El bucle humano de depuración es el ciclo en el que tú haces de puente: abrir el trace rojo en el dashboard, copiar el error, pegarlo en la IA ("aquí está el trace que falló, ¿qué está mal y cómo lo arreglo?"), dejar que lo diagnostique, aplicar la corrección y volver a hacer el deploy. El trace + la IA permiten un diagnóstico rápido; un humano solo tiene que llevarle el error.

Por qué aprender

Conceptos clave

El cambio de mentalidad consiste en dejar de ser el disparador y configurar disparadores que se ejecuten mientras te alejas. El prompting y la lectura de traces se vuelven más fáciles con la práctica: el segundo build siempre es más rápido que el primero. Y asegúrate de que toda tarea desplegada tenga alertas de fallos, para que te enteres del problema antes que el usuario.