This module consists of two complete builds running in production. One is scheduled: the cron job fires, Firecrawl searches, the AI synthesizes, and a row is added to Google Sheets. The other is by event: a webhook receives a JSON payload, generates a .docx and save it to Google Drive. The diagram compares the two paths.

Illustrative diagram — conceptual recreation of the two production builds, not a real screenshot.

What it is

The first build is a scheduled research agent: a Trigger.dev task that runs on its own every morning on a cron schedule. It researches a fixed topic using the Firecrawl, synthesizes the findings with AI, and writes a structured line to the Google Sheets. All in a single file (e.g., morning-research.ts), with the topic hard-coded at the top — easy to change and version.

Why learn

The build flow

Key concepts

What it is

For the task to write to Google Sheets autonomously, it needs a refresh token OAuth—a one-time configuration credential that renews access without a manual login. Instead of a service account, the build uses OAuth with a client ID, client secret, and refresh token, all in the .env and in the cloud env vars.

Why learn

Key concepts

The fallback is elegant: a script in the terminal (using the client ID + secret from .env) prints an authorization URL; you open it, authorize, and the script returns the refresh token for you to paste into .env and in the env vars. Set it up once—then the task renews access on its own with each run.

What it is

Some errors only show up with real data in production. In the scheduled build, Firecrawl returned success: false and put the results in a property web instead of data — o shape from the response differed from what the code expected. The fix: adjust the parsing, redeploy, and trigger it again.

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

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

Why learn

Expecting model errors is part of the process — it may assume the wrong format for an API response. What matters is the response: open the failed step, copy the complete error message, paste it into the AI to diagnose, apply the parsing fix, redeploy, and trigger it again. And this is where error handling proved its value: even with Firecrawl failing, the task didn’t crash and still wrote a partial row to Sheets.

What it is

The second build is event-driven: a task triggered by webhook. A web form sends a JSON payload (fields such as company name, industry, goal, challenge) to the webhook URL; the task generates a report .docx from these fields and saves it automatically to Google Drive. The AI fills in the report sections (executive summary, industry context, challenges) from a few input fields.

Why learn

Key concepts

The task normalizes the form labels to match the expected payload shape, and the run can be fully or partially successful. The testing order is always: local first (dev server + sample payload), then with the form, and only then in production. Any form/system that supports webhooks + API works — you're not tied to a specific tool.

What it is

A webhook is a "digital doorbell": a URL that listens for incoming data and, when it receives it, wakes up the task, passing the payload ahead. While cron fires on a schedule, the webhook fires in response to an event. The URL includes the task ID (e.g., webhook-report), and it's shareable and embeddable — it can come from a website, an email, or another system.

Why learn

Key concepts

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

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

What it is

O GitHub → Trigger.dev pipeline closes the iteration loop: when you change something in the editor and push to GitHub, GitHub runs the automatic deploy on Trigger.dev. The latest files are always live, with no manual deployment. It’s “commit → push → deploy” running on its own.

Why learn

Connecting GitHub to Trigger.dev

Key concepts

What it is

Without a self-healing agent in production, the robust error handling is what closes the agentic gap. The approach has layers: meaningful log at each step (visibility), try/catch around each external call, retries configurable with backoff and alerts of failure. Trigger.dev provides visibility and retries, but it can only retry what it recognizes as a failure.

Why learn

Key concepts

What it is

In production, AI still debugs — but no longer automatically. The human debugging loop is the cycle where you act as the bridge: open the red trace in the dashboard, copy the error, paste it into the AI ("here's the trace that failed; what's wrong, and how do I fix it?"), let it diagnose the issue, apply the fix, and redeploy. The trace + AI provide a quick diagnosis; a human just needs to bring the error to it.

Why learn

Key concepts

The mindset shift is to stop being the trigger and start configuring triggers that run while you step away. Prompting and reading traces get easier with repetition—the second build is always faster than the first. And make sure every deployed task has failure alerts, so you know something broke before the user does.