Before the seven topics, take a look at what changes. In an interactive session, the AI reads the error and fixes it right away—a self-healing loop. But the task hosted runs without anyone watching: it executes, but doesn’t adapt. You recreate this loop with platform features (logs, retries, alerts) and better prompts; then close the revenue loop with Stripe.

Illustrative diagram — reliability recreates, with a platform and prompts, the healing loop you got for free in the interactive session; monetization closes the cycle by turning the workflow into a product.

What it is

During development, you and the Claude Code work in a self-healing loop: the task runs, errors, and the AI reads the error right away and fixes it. But when the task is deployed and starts running on its own — on a schedule (cron) or triggered by an event (webhook) in the cloud — this loop disappears. The agentic gap is exactly this gap: the hosted task runs, but it doesn't adapt, and no one is reading the errors.

In practical terms: you close the terminal, go to sleep, and at 7 a.m. cron triggers the task. If a source's API is down, the task can freeze and die — and since Claude Code is no longer monitoring, the failure goes unnoticed until someone complains. The solution isn’t to “hope for the best”: you close the gap with platform resources (retries, traces, alerts) and with better prompting (error handling and logging requested from the very first prompt).

Why learn

Without closing the gap, “it ran in the demo” doesn’t mean “it runs in production.” An automation that fails silently is worse than none: you believe it’s taking care of something that stopped working days ago. Understanding the gap changes how you build—you start asking for robustness before of deployment, not after the incident.

Key concepts

What it is

O Trigger.dev gives you visibility (traces) and automatic retries, but it can only retry what recognizes how it fails — and you can only diagnose what the log tells you. Meaningful logging means asking AI for a clear log entry at each important step, with specific context: not “task failed,” but “Firecrawl returned 429 on source 3.” A vague log is useless; a specific log is actionable.

Illustrative diagram — the same failure, two logs. The specific one carries enough context for you (or the AI) to act without guessing.

Why learn

When something fails at 3 a.m., the log is all you'll have. A trace full of generic "ok" and "error" messages forces you to reproduce the problem from scratch; a trace with rich messages tells you in seconds which source went down, with which code, at which step. Asking for good logs from the very first prompt is cheaper than adding them after the incident.

Revise os arquivos da task <nome-da-task> e adicione um log claro
em cada passo significativo. Em vez de mensagens genéricas como
"task failed", logue o contexto: serviço, código de status e qual item.

Exemplos do que eu quero ver nos logs:
  - "Firecrawl retornou 429 na fonte 3 (rate limit)"
  - "Supabase: gravada linha parcial para lead <id> (1 fonte faltando)"
  - "OpenAI ok: resumo gerado para <empresa> em 1.4s"

Use o logger do Trigger.dev (logger.info / logger.warn / logger.error)
para que apareçam no trace do dashboard.

Key concepts

What it is

Every call to an external API can fail — the network goes down, the service returns an error, or the response comes in an unexpected format. The try/catch is the pattern that wraps this call so that, if it fails, the task capture the error instead of letting it die: you log the error with context, continue where possible, and only launches (stops permanently) on truly critical failures. That's what allows the task to write a partial row instead of breaking when a source goes down.

Why learn

There's a real case that proves the point: the Firecrawl returned success:false with the results under the key web instead of data. Without error handling, this would have broken the read and crashed the task. With the try/catch in place, the task detected the unexpected format, logged the issue, and didn’t freeze — saved what it could. Error handling isn’t a luxury: it’s what keeps the automation running when the outside world misbehaves.

// TypeScript — chamada a uma API externa dentro da task
let dadosFonte = null;

try {
  const resp = await fetch(`https://api.<servico>.com/<rota>`, {
    headers: { Authorization: `Bearer ${process.env.<CHAVE>}` },
  });

  if (!resp.ok) {
    // falha não-crítica: loga COM contexto e continua
    logger.warn(`<Servico> retornou ${resp.status} na fonte ${fonteId}`);
  } else {
    dadosFonte = await resp.json();
  }
} catch (err) {
  // erro de rede/timeout: registra e segue sem essa fonte
  logger.error(`Falha ao chamar <Servico> (fonte ${fonteId}): ${err.message}`);
}

// grava a linha mesmo parcial — não descarta o que deu certo
await salvarLinha({ ...resto, fonte: dadosFonte ?? "faltando" });

// só lança se faltar algo CRÍTICO (sem isso não há resultado)
if (!dadoEssencial) throw new Error("Dado essencial ausente — abortando");

Key concepts

What it is

You configure retries in the task definition itself (e.g., up to 3 attempts, with exponential backoff starting in 30s). If the task fails for a temporary reason, Trigger.dev waits and tries again, doubling the interval each time. The golden rule: retries solve transient failures (timeout, rate limit, network instability) — but no fix logic bugs in your code.

Illustrative diagram — if all 3 attempts fail the same way, the problem isn’t the timing: it’s the logic. Retrying a bug forever just burns resources.

Why learn

Knowing the difference helps you avoid two opposite mistakes: not have retries (a minor hiccup brings down a run that would have worked 30s later) and trust them too much (a logic bug gets retried forever, masking the real problem and wasting executions). If all three attempts fail with the same error, stop retrying and start debugging — the subject of topic 6.

// trigger/<sua-task>.ts — configuração de retries
export const minhaTask = task({
  id: "<id-da-task>",
  retry: {
    maxAttempts: 3,            // até 3 tentativas
    minTimeoutInMs: 30_000,    // backoff começa em 30s
    factor: 2,                 // exponencial: 30s → 60s → 120s
  },
  run: async (payload) => {
    // ... sua lógica aqui ...
  },
});

Key concepts

What it is

Logs and traces tell you what happened — if you’re going to look. Alerts turn that around: they come to you. In Trigger.dev, at Project Settings > Alerts, you configure notifications by email, Slack or webhook triggered by deploy or run failures, with configurable environment and failure type. It takes less than two minutes to set up.

Why learn

This is the rule that closes the agentic gap in practice: every deployed task needs a failure alert. Without this, you’re betting that you’ll check the dashboard exactly when something goes wrong—which never happens. With alerts, the system contacts you; you replace "hope" with "a warning." Since it’s configurable by environment, keep production alerts on at all times.

Key concepts

What it is

Claude still debugs — it just doesn’t automatically and more. In production, the healing loop exists, but with you in the middle: the task fails, the alert arrives, and you (the human) bridge the gap. Open the red trace in the dashboard, copy the error, paste it into Claude (“here’s the trace that failed: <error>, what’s wrong and how do I fix it?”), let Claude identify the fix, make the redeploy and test it. The trace + Claude provide a quick diagnosis; the human just needs to pass along the error.

Illustrative timeline—the loop is the same as in the interactive session (error → diagnosis → fix → redeploy → test), but now you is what carries the error to Claude.

Why learn

This is where everything connects: the meaningful log (topic 2) makes the trace readable, while the alerts (topic 5) tell you to open that trace, and the retries (topic 4) already tell you whether it’s worth debugging (same error 3x = bug). The cycle is fast because the trace + Claude handle the heavy diagnostic work; your part is just the bridge. Mastering this loop is what keeps a hosted automation running for weeks.

Aqui está o trace que falhou:

<cole o erro completo copiado do dashboard do Trigger.dev>

Contexto: é a task <nome-da-task>, rodou via <cron/webhook> em produção.
O que está errado e como conserto? Aplique o fix nos arquivos da task
e me explique em uma frase a causa raiz.

Key concepts

What it is

The step that turns the automation into a SaaS: add payments with Stripe in a model freemium — a limited free tier (e.g., 2 lead qualifications per day) and a paid pro tier (e.g., US$ 29/month, unlimited), all through Stripe Checkout. The motivation isn’t just making money: it’s limit usage so you don’t end up paying for users’ uncapped AI usage. That’s what completes the transition from “just a workflow” to “an app that generates revenue.”

The good news: you don’t write the integration by hand. You describe the result, and the Claude Code implements — but you you need to create the accounts, copy the four keys, and run the migration. The sequence below is the manual part; Claude handles the code.

Illustrative timeline—four keys (publishable, secret, price ID, webhook secret), a new table, and a webhook endpoint: this is the framework for any subscription billing.

Why learn

Without a usage limit, each free user can trigger unlimited AI usage—and the bill lands in your lap. Freemium solves both sides: the free tier (2/day) is a showcase and cost safeguard; the pro tier (US$ 29/month unlimited) generates revenue. With that, what was a technical workflow becomes a product that holds up — the final leap in the learning path.

Adicione pagamentos Stripe ao app com modelo freemium:

  - Tier grátis: até 2 qualificações de lead por dia.
  - Tier pro: US$ 29/mês, ilimitado, via Stripe Checkout.

Use as env vars: STRIPE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY,
STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET.
Crie a rota /api/stripe-webhook escutando checkout.session.completed,
customer.subscription.updated e customer.subscription.deleted,
e atualize a tabela subscriptions no Supabase conforme o status.
Bloqueie o uso acima do limite no tier grátis.

Key concepts