Tu primer workflow en vivo: un newsletter automático con Claude Code

Módulo: 3, el framework WAT | Tiempo: unos 20 min de teoría + 60 min de práctica

Lo esencial

Se acabó la teoría: empieza la construcción. Esta lección te lleva paso a paso por la creación de un newsletter automático real: de una carpeta vacía a un sistema que funciona, que busca noticias, arma el correo y lo envía. Lo hacemos en vivo, no en diapositivas.

Conceptos clave

• Plan Mode para arrancar desde una petición vaga
• Elegir las herramientas conversando con el agente (el agente es el ejecutor de IA que trabaja por su cuenta)
• Los materiales de marca como contexto para el agente (el contexto es el texto que la IA "ve" en ese momento)
• Las cinco herramientas del newsletter automático
• Configurar el .env con las claves de API (API: interfaz de programación de aplicaciones)
• Human review point: cuándo debe detenerse el agente
• El arranque y el primer envío real

Teoría

Por qué un newsletter automático es el primer proyecto ideal

🎨 Imagínalo así: un newsletter automático es como el primer platillo de un estudiante de cocina: ni demasiado simple (un huevo frito) ni demasiado complicado (una salsa francesa). Tiene suficientes componentes para entender la arquitectura y es lo bastante simple para no ahogarte en detalles. Y el resultado se ve de inmediato: un correo en tu bandeja de entrada.

El newsletter automático es un gran primer proyecto porque:

1. Su valor para el negocio es claro: cualquier negocio entiende para qué sirve
2. Tiene todas las piezas de WAT: hay un workflow (un proceso de trabajo), hay herramientas y el agente coordina
3. Human review point: queda claro dónde hace falta que una persona revise antes de enviar
4. Resultado real: al final de la lección verás un correo real en tu bandeja de entrada
5. Escalable: este workflow se puede empaquetar como producto o servicio listo, aunque el resultado depende del nicho y de tu trabajo

Las herramientas que vamos a elegir (y por qué)

En el trabajo real, le explicas la tarea al agente y él te propone las herramientas. Vamos a recorrer ese proceso. Pero esto es lo que saldrá al final:

¿Por qué Perplexity y no simplemente Google?

Perplexity devuelve datos estructurados con enlaces reales y fuentes recientes. Hacer búsqueda por scraping es inestable: Google bloquea, y la API sale cara. La Perplexity API te da un JSON limpio (JSON es un formato de datos) con las fuentes.

¿Por qué Gmail y no SendGrid?

Para un primer proyecto, Gmail es más sencillo: no tienes que verificar un dominio y puedes empezar en 10 minutos. Los servicios especializados de envío masivo (por ejemplo, SendGrid) son mejores para envíos a miles de personas.

Paso 1: Plan Mode, empezamos con una petición vaga

Abre Claude Code en una carpeta nueva y vacía llamada newsletter-automation.

Escribe esta primera petición:

Quiero armar un newsletter semanal automático con noticias sobre [tu tema] para mis clientes.
Antes de empezar, hazme preguntas para aclarar, arma un plan
y luego muéstrame la estructura WAT que piensas crear.

El agente te hará preguntas como:

• "¿De qué fuentes saco las noticias: sitios concretos o una búsqueda general?"
• "¿Cómo se guarda la lista de destinatarios?"
• "¿El correo lleva infografía?"
• "¿En qué idioma va el correo?"
• "¿Necesitas aprobar cada envío antes de que salga?"

Responde con honestidad. Al final el agente armará un plan. Tú lo apruebas y empieza la construcción.

Paso 2: Cargar los materiales de marca

🎨 Imagínalo así: los materiales de marca para el agente son como el uniforme y la capacitación de un mesero nuevo. Sin uniforme es solo una persona más en el salón. Con uniforme y capacitación ("somos un restaurante italiano, nada de sushi, al cliente se le habla de usted, ofrecemos vino") se vuelve parte de tu marca.

Antes de que el agente empiece a generar contenido, dale el contexto de tu marca.

Crea la carpeta /brand_assets/ y pon ahí:

• logo.png: tu logotipo (o descarga cualquier imagen de relleno)
• brand_guidelines.md: la descripción de tu marca

Ejemplo de brand_guidelines.md:

# Brand Guidelines

## Tone of Voice
- Profesional pero cercano
- Sin solemnidad de más
- Lo concreto importa más que las palabras bonitas
- Oraciones cortas

## Colores
- Principal: #1A56DB (azul)
- Secundario: #F3F4F6 (gris claro)
- Acento: #10B981 (verde para noticias positivas)

## Tipografía
- Títulos: negritas, grandes
- Texto: 16px, interlineado 1.6

## Qué NO escribir
- Nada de "revolucionario" ni "único"
- No empezar con "En la era de..."
- No usar la palabra "innovador"

Después de cargar los materiales, dile al agente:

Agregué a /brand_assets/ el logotipo y las brand guidelines.
Usa estos materiales al generar el contenido y al maquetar el correo.
Menciona los archivos con @brand_assets/logo.png y @brand_assets/brand_guidelines.md.

Paso 3: El agente crea cinco herramientas

El agente escribirá todas las herramientas a partir del plan. Esto es lo que saldrá:

Herramienta 1: tools/research_news.py

Llama a la Perplexity API con la consulta indicada y devuelve una lista de 5-7 noticias con el formato [{title, description, url, date, source}].

Herramienta 2: tools/generate_infographic.py

Recibe la lista de noticias, arma un prompt (la petición para la IA) para la API de generación de imágenes y devuelve una URL o la imagen en base64. Nano Banana (a través de la Gemini API) recibe una petición de texto y devuelve una imagen.

Herramienta 3: tools/assemble_html.py

Toma las noticias + la infografía + las brand guidelines, llama a la Claude API y genera la plantilla HTML lista del correo. Inserta el logotipo y aplica los colores de las brand guidelines.

Herramienta 4: tools/send_via_gmail.py

Recibe el HTML, la lista de destinatarios y el asunto del correo. Usa la Gmail API con OAuth 2.0. Envía el correo a cada destinatario.

Herramienta 5: tools/archive_to_sheets.py

Escribe una fila en Google Sheets: fecha de envío, número de destinatarios, asunto del correo, estado. Crea un registro para analizar.

Paso 4: Archivos de configuración

El agente creará dos archivos de configuración:

config/newsletter_style.json

{
  "font_family": "system-ui, -apple-system, sans-serif",
  "font_size_body": "16px",
  "line_height": "1.6",
  "colors": {
    "primary": "#1A56DB",
    "background": "#F3F4F6",
    "accent": "#10B981",
    "text": "#111827"
  },
  "max_width": "600px",
  "news_count": 5
}

config/recipients.json

{
  "test": ["your-email@gmail.com"],
  "production": [
    "client1@email.com",
    "client2@email.com"
  ]
}

Empieza con test: envíatelo a ti. Cuando todo esté configurado, agrega a los destinatarios reales en production.

Paso 5: Configurar el .env con las claves de API

El agente creará una plantilla .env.example:

# Anthropic API (platform.claude.com → API Keys)
ANTHROPIC_API_KEY=your_key_here

# Perplexity API (perplexity.ai → API)
PERPLEXITY_API_KEY=your_key_here

# Gmail API (Google Cloud Console → Credentials)
GMAIL_CLIENT_ID=your_client_id
GMAIL_CLIENT_SECRET=your_client_secret
GMAIL_REFRESH_TOKEN=your_refresh_token

# Google Sheets (el mismo proyecto de Google Cloud)
GOOGLE_SHEETS_ID=your_spreadsheet_id

# Gemini API para generar imágenes con Nano Banana (opcional)
GEMINI_API_KEY=your_key_here

Cómo conseguir las claves:

1. Anthropic API: entra a la Console (platform.claude.com) → API Keys → Create Key
2. Perplexity API: entra a perplexity.ai → Settings → API → Generate
3. Gmail API: la más complicada. Google Cloud Console → New Project → Enable Gmail API → Credentials → OAuth 2.0 Client ID → descarga el JSON → usa google-auth-oauthlib para obtener el refresh token
4. Google Sheets API: el mismo proyecto de Google Cloud → Enable Sheets API → puedes usar el mismo OAuth

Copia .env.example a .env y llénalo con las claves reales. Asegúrate de que .env esté en el .gitignore.

Paso 6: Human Review Point, el agente se detiene

🎨 Imagínalo así: el Human Review Point es como el puesto de control de calidad en una fábrica. La línea de producción va rápido, pero antes de enviarle el pedido al cliente hay una revisión obligatoria. Si dejas pasar un defecto una vez, pierdes al cliente. Dos minutos de revisión te ahorran una semana de daño a tu reputación.

Esta es una parte crítica del workflow. Antes de enviar los correos, el agente debe detenerse y mostrarte una vista previa.

En el workflow se ve como una instrucción explícita:

### Paso 3: ⚠️ REVISIÓN OBLIGATORIA POR UNA PERSONA

DETENTE. No sigas de forma automática.

Muéstrame:
1. La vista previa HTML del correo
2. La lista de destinatarios (de qué modo: test o production)
3. El asunto del correo
4. El número de noticias y sus títulos

Espera una confirmación explícita: "Envía" o "OK send" o "go"
Si recibes "alto" o "espera", no envíes y espera instrucciones.

Por qué importa: el agente pudo haber generado una noticia con un error de hecho. O elegido un tema que no va. O pudo colarse alguien de más en la lista de destinatarios. Revisas una vez y luego el sistema trabaja por su cuenta con revisiones periódicas.

Un ejemplo real de prompt para un newsletter automático

Este es el prompt completo que puedes usar como plantilla para tu nicho:

Crea la automatización de un newsletter semanal para una agencia inmobiliaria.

Qué debe hacer el sistema:
1. Cada lunes a las 10:00, buscar 5-7 noticias recientes con la consulta
   "mercado inmobiliario Ecuador 2026" en la Perplexity API
2. Con base en las noticias encontradas, generar un correo HTML con el estilo
   de las brand guidelines de /brand_assets/
3. Agregar una sección "Propiedad de la semana" con un espacio para llenarlo a mano
4. DETENERSE y mostrarme la vista previa antes del envío
5. Después de mi "ok", enviarlo con la Gmail API a la lista de config/recipients.json
6. Registrar el envío en Google Sheets

Importante:
- Tono del correo: profesional, sin solemnidad, cifras concretas
- Idioma: español
- Máximo 800 palabras en todo el newsletter
- Siempre con enlaces a las fuentes de las noticias

Paso 7: El arranque, "escríbeme un newsletter sobre IA agéntica"

🎨 Imagínalo así: el primer arranque del workflow es como encender por primera vez un coche recién salido de la línea de ensamble. Si el motor arranca, ya es un triunfo. Luego viene el rodaje y luego el ajuste fino. No esperes que el primer arranque sea perfecto: espera que funcione.

Con todo configurado, escríbele al agente:

Corre el workflow del newsletter.
Tema de esta semana: IA agéntica para pequeños negocios.
Usa la lista de destinatarios de prueba.

El agente:

1. Llamará a research_news con tu tema
2. Te mostrará las noticias encontradas (puedes quitar alguna)
3. Llamará a generate_infographic
4. Llamará a assemble_html
5. Se detendrá y te mostrará la vista previa
6. Después de tu "Envía", llamará a send_via_gmail
7. Llamará a archive_to_sheets

En unos 3-5 minutos tendrás un correo real en tu bandeja de entrada.

Práctica

Tarea: construir un newsletter automático desde cero hasta el primer envío.

Paso 1, preparación (15 min):

1. Crea la carpeta newsletter-automation
2. Ábrela en VS Code con Claude Code
3. Crea brand_assets/brand_guidelines.md para tu tema
4. Crea un .gitignore con .env y logs/

Paso 2, Plan Mode (10 min):

1. Escribe la petición en Plan Mode (el texto del Paso 1 de la teoría)
2. Responde las preguntas del agente
3. Aprueba el plan

Paso 3, construcción (25 min):

1. Dale luz verde al agente: "Empieza a construir según el plan"
2. Observa cómo crea la estructura, el workflow y las herramientas
3. Responde las preguntas de aclaración si el agente se detiene

Paso 4, claves de API (15 min):

1. Llena el .env (como mínimo: ANTHROPIC_API_KEY y un servicio de correo)
2. Si no tienes Perplexity, usa la Anthropic API con WebSearch o simplemente datos de prueba

Paso 5, primer arranque (10 min):

1. Corre el workflow de prueba hacia tu propio correo
2. Revisa el correo en tu bandeja de entrada
3. Toma una captura de pantalla: es tu primer producto con agentes

Herramientas y recursos

• Claude Code en VS Code: la herramienta principal
• Anthropic Console: crear y administrar claves de API
• Perplexity API: la clave se obtiene en perplexity.ai/settings
• Google Cloud Console: Gmail API y Sheets API (nivel gratuito)
• Resend: alternativa a la Gmail API para enviar correos (configuración más sencilla; el servicio tiene un nivel gratuito)
• SendGrid: envíos masivos; revisa en su sitio las condiciones del acceso gratuito
• Mailgun: otra alternativa de API de correo
• trigger.dev: deploy (publicar en un servidor) del workflow a producción con horario
• Nano Banana (Gemini): generar la infografía con la Gemini API
• Claude Code: comandos: referencia de los comandos integrados

Errores comunes

Error 1: arrancar sin .gitignore

Creaste el proyecto, configuraste el .env con las claves, hiciste git add . y las claves se filtraron al repositorio. Crea siempre el .gitignore ANTES del primer commit.

Error 2: saltarte el Human Review Point

Escribiste "envía automáticamente" en el workflow y el agente mandó a todos tus clientes un correo sin revisar y con un error de hecho. En los primeros 10-20 arranques, revisa siempre a mano antes de enviar.

Error 3: un prompt inicial demasiado general

"Hazme un newsletter", sin detalles de tema, público, idioma ni estilo. Entre más concreto sea el prompt inicial, menos vueltas tendrás que dar después. Usa Plan Mode para que el agente haga las preguntas correctas.

Lecciones relacionadas

• El framework WAT: la arquitectura Workflow-Agent-Tools sobre la que está construido este workflow
• Depuración y autocorrección: qué hacer cuando el primer arranque falle (y va a fallar)
• Claves de API y .env: a detalle, cómo configurar el .env de forma segura y guardar secretos
• Deploy en Cloudflare: cómo llevar este workflow a producción en Cloudflare Workers

Ideas clave

Plan Mode te deja empezar con una idea vaga: el agente hace las preguntas correctas y arma el plan.

Los materiales de marca + las brand guidelines le dan al agente el contexto para crear contenido con el estilo que buscas.

El Human Review Point es una parada obligatoria antes de cualquier acción irreversible (enviar, publicar, pagar).

Al final no tienes solo archivos: tienes un sistema que funciona y que puedes empaquetar como servicio o producto.

Siguiente lección

→ Depuración y autocorrección: qué hacer cuando el primer arranque falle