Antes de los siete temas, mira qué cambia. En una sesión interactiva, la IA lee el error y lo corrige de inmediato: un ciclo que se repara solo. Pero la tarea alojada se ejecuta sin que nadie la supervise: ejecuta, pero no se adapta. Recreas este ciclo con recursos de plataforma (logs, reintentos, alertas) y mejores prompts; después, cierras el ciclo del dinero con Stripe.

Diagrama ilustrativo — la confiabilidad recrea, con la plataforma y los prompts, el ciclo de corrección que tenías gratis en la sesión interactiva; la monetización cierra el ciclo al convertir el workflow en un producto.

Qué es

Durante el desarrollo, tú y el Claude Code trabajan en un loop que se cura solo: la tarea se ejecuta, da error, la IA lee el error en el momento y lo corrige. Pero cuando la tarea es desplegada y empieza a ejecutarse solo — según una agenda (cron) o por un evento (webhook) en la nube — ese loop desaparece. El agentic gap es exactamente esa brecha: la tarea alojada ejecuta, pero no se adapta y nadie está revisando los errores.

En concreto: cierras el terminal, te vas a dormir y a las 7h el cron activa la tarea. Si la API de una fuente está fuera de servicio, la tarea puede bloquearse y morir — y como Claude Code ya no está supervisando, el fallo pasa desapercibido hasta que alguien se queja. La solución no es «cruzar los dedos»: cierras la brecha con recursos de la plataforma (reintentos, traces, alertas) y con mejores prompts (manejo de errores y logging solicitados desde el primer prompt).

Por qué aprender

Sin cerrar la brecha, «funcionó en la demo» no significa «funciona en producción». Una automatización que falla en silencio es peor que no tener ninguna: crees que estás atendiendo algo que se detuvo hace días. Entender la brecha cambia cómo construyes: empiezas a pedir robustez antes del deploy, no después del incidente.

Conceptos clave

Qué es

O Trigger.dev te da visibilidad (traces) y reintentos automáticos, pero solo puede volver a intentar lo que reconoce cómo falla — y solo puedes diagnosticar lo que cuenta el log. Para un logging significativo, pídele a la IA un log claro en cada paso importante, con contexto específico: no «task failed», sino «Firecrawl devolvió 429 en la fuente 3». Un registro vago no sirve; uno específico permite actuar.

Diagrama ilustrativo — el mismo fallo, dos registros. El específico incluye suficiente contexto para que tú (o la IA) puedas actuar sin adivinar.

Por qué aprender

Cuando algo falla a las 3 a. m., el log es todo lo que tendrás. Un trace lleno de "ok" y "error" genéricos te obliga a reproducir el problema desde cero; un trace con mensajes detallados te dice, en segundos, qué fuente falló, con qué código y en qué paso. Pedir buenos logs desde el primer prompt es más barato que agregarlos después del incidente.

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.

Conceptos clave

Qué es

Toda llamada a una API externa puede fallar: la red se cae, el servicio devuelve un error, la respuesta llega en un formato inesperado. El try/catch es el patrón que envuelve esa llamada para que, si falla, la tarea capture el error, en lugar de desaparecer: registras el error con contexto, continúas donde sea posible y solo lanza (se detiene por completo) ante fallos realmente críticos. Eso es lo que permite que la tarea guarde una fila parcial en lugar de colapsar cuando una fuente deja de funcionar.

Por qué aprender

Hay un caso real que demuestra el punto: el Firecrawl devolvió success:false con los resultados bajo la clave web en lugar de data. Sin manejo de errores, esto habría interrumpido la lectura y detenido la task. Con el try/catch en su lugar, la tarea detectó el formato inesperado, registró el problema y no se bloqueó — guardó lo que pudo. El manejo de errores no es un lujo: es lo que mantiene la automatización en pie cuando el mundo externo se comporta mal.

// 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");

Conceptos clave

Qué es

Tú configuras reintentos en la propia definición de la task (ej.: hasta 3 intentos, con backoff exponencial empezando en 30s). Si la tarea falla por un motivo pasajero, Trigger.dev espera y vuelve a intentarlo, duplicando el intervalo cada vez. La regla de oro: los reintentos resuelven fallas transitorias (tiempo de espera agotado, límite de solicitudes, inestabilidad de red), pero no resuelven errores de lógica en tu código.

Diagrama ilustrativo — si los 3 intentos fallan igual, el problema no es el momento: es la lógica. Volver a intentar un bug para siempre solo consume recursos.

Por qué aprender

Saber la diferencia evita los dos errores opuestos: no tener reintentos (una inestabilidad menor hace fallar la ejecución que habría funcionado 30s después) y confiar demasiado en ellos (un bug de lógica se vuelve a intentar infinitamente, ocultando el problema real y consumiendo ejecuciones). Si los tres intentos fallan con el mismo error, deja de reintentarlo y depura; ese es el tema 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 ...
  },
});

Conceptos clave

Qué es

Los logs y las trazas te cuentan qué pasó — si vayas a mirar. Alertas invierten eso: te buscan. En Trigger.dev, en Project Settings > Alerts, configuras notificaciones por correo electrónico, Slack o webhook activadas ante fallas de deploy o de run, con el entorno y el tipo de falla configurables. Se configura en menos de dos minutos.

Por qué aprender

Esta es la regla que cierra el agentic gap en la práctica: toda task desplegada debe tener una alerta de fallo. Sin esto, apuestas a que revisarás el dashboard justo cuando surja un problema —algo que nunca pasa—. Con alertas, el sistema te avisa; cambias la "esperanza" por el "aviso". Como se configura por entorno, deja siempre activadas las alertas de producción.

Conceptos clave

Qué es

Claude todavía depura; solo que no automáticamente más. En producción, el ciclo de corrección existe, pero contigo en medio: la tarea falla, llega la alerta y tú (el humano) haces de puente. Abre el trace rojo en el dashboard, copia el error, pégalo en Claude ("aquí está el trace que falló: <erro>, ¿qué está mal y cómo lo arreglo?"), deja que Claude identifique la solución y haz el redeploy y prueba. El trace + Claude permiten diagnosticar rápido; el humano solo tiene que pasar el error.

Línea de tiempo ilustrativa: el loop es el mismo de la sesión interactiva (error → diagnóstico → fix → redeploy → prueba), pero ahora tú es quien lleva el error hasta Claude.

Por qué aprender

Es aquí donde todo se conecta: el log significativo (el tema 2) hace que el trace sea legible; los alertas (el tema 5) te avisan que abras ese trace, y los reintentos (el tema 4) ya te indican si vale la pena depurar (el mismo error 3 veces = bug). El ciclo es rápido porque el trace + Claude hacen el diagnóstico pesado; tu parte es solo el puente. Dominar este ciclo es lo que mantiene viva una automatización alojada durante semanas.

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.

Conceptos clave

Qué es

El paso que convierte la automatización en un SaaS: agregar pagos con Stripe en un modelo freemium — un tier gratuito limitado (p. ej., 2 calificaciones de lead al día) y un tier pro de pago (p. ej., US$ 29/mes, ilimitado), todo mediante Stripe Checkout. La motivación no es solo ganar dinero: es limitar el uso para que no pagues la cuenta de IA de los usuarios que la consumen sin límite. Es lo que completa la transición de «solo un workflow» a «una app que genera ingresos».

La buena noticia: no escribes la integración a mano. Describes el resultado y el Claude Code implementa — pero tú tienes que crear las cuentas, copiar las cuatro claves y ejecutar la migración. La secuencia de abajo es la parte manual; el código lo hace Claude.

Línea de tiempo ilustrativa: cuatro claves (publishable, secret, price ID, webhook secret), una tabla nueva y un endpoint de webhook: es el esqueleto de cualquier cobro por suscripción.

Por qué aprender

Sin un límite de uso, cada usuario gratuito puede generar un consumo ilimitado de IA, y la factura te llega a ti. El modelo freemium resuelve ambos lados: el nivel gratis (2/día) sirve como vitrina y protección de costos; el nivel pro (US$ 29/mes ilimitado) genera los ingresos. Así, lo que era un workflow técnico se convierte en un producto que se sostiene por sí misma — el salto final de la ruta.

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.

Conceptos clave