Cómo crear agentes IA con Claude Code + Cloudflare por $5 al mes

Un agente que solo funciona mientras tienes el portátil abierto no es un agente: es un script. Para que trabaje de verdad necesita vivir en algún sitio, responder a peticiones y despertarse solo cuando toca.

Cloudflare Workers es de las formas más baratas de conseguirlo, y con Claude Code el desarrollo se acorta mucho. Esta guía monta uno completo y explica dónde está el gasto real, que no es donde la gente cree.

Qué cuesta esto realmente

Empecemos por lo importante, porque el titular «$5 al mes» esconde una trampa habitual.

Cloudflare Workers tiene un plan gratuito generoso (100.000 peticiones al día) y uno de pago que ronda los 5 dólares mensuales y añade almacenamiento persistente y más tiempo de CPU. Esa parte sí es barata y predecible.

La API de Claude se paga aparte y es el gasto de verdad. Un agente que procesa unos cientos de peticiones al día con contexto moderado puede costar bastante más que la infraestructura. Cualquiera que te venda «un agente por 5 dólares al mes» está contando solo el hosting.

Presupuesta así: infraestructura fija y pequeña; modelo variable y proporcional al uso. Y pon un límite de gasto en la consola de Anthropic desde el primer día.

Qué es un Worker y por qué encaja

Un Worker es una función que Cloudflare ejecuta en sus servidores cuando llega una petición. No mantienes servidor, no parcheas nada y arranca casi al instante.

Tres piezas del ecosistema te bastan para un agente:

• Workers: el código que se ejecuta.
• KV o D1: donde guardas estado (KV para clave-valor simple, D1 si necesitas SQL).
• Cron Triggers: para que el agente se despierte solo cada X tiempo.

Con eso cubres los dos modos de un agente: reaccionar a algo y actuar por su cuenta.

Montarlo

Instalación y esqueleto:

«bash npm create cloudflare@latest mi-agente cd mi-agente npm install @anthropic-ai/sdk «

La clave de API nunca va en el código. Se guarda como secreto:

«bash npx wrangler secret put ANTHROPIC_API_KEY «

Eso la cifra en Cloudflare y la expone al Worker como variable de entorno. Si la escribes en wrangler.toml acabará en git, y una clave en un repositorio es una factura ajena esperando a ocurrir.

El agente mínimo:

«`js import Anthropic from "@anthropic-ai/sdk";

export default { async fetch(request, env) { if (request.method !== "POST") { return new Response("Method not allowed", { status: 405 }); }

const { mensaje, sesion } = await request.json(); const anthropic = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });

// recuperar contexto previo const previo = await env.MEMORIA.get(sesion, { type: "json" }) ?? [];

const r = await anthropic.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, system: "Eres un asistente de soporte. Sé breve y concreto.", messages: […previo, { role: "user", content: mensaje }], });

const texto = r.content[0].text;

// guardar, recortando el historial const nuevo = [ …previo, { role: "user", content: mensaje }, { role: "assistant", content: texto }, ].slice(-20); await env.MEMORIA.put(sesion, JSON.stringify(nuevo), { expirationTtl: 60 * 60 * 24 * 7, });

return Response.json({ respuesta: texto }); }, }; «`

Dos detalles que son los que abaratan la factura:

.slice(-20) recorta el historial. Sin esto, una conversación larga crece indefinidamente y cada turno cuesta más que el anterior. Es la fuga de dinero número uno en agentes conversacionales.

expirationTtl hace que las sesiones caduquen solas. Ni acumulas basura ni conservas datos personales más de lo necesario.

La configuración en wrangler.toml:

«`toml name = "mi-agente" main = "src/index.js" compatibility_date = "2026-01-01"

[[kv_namespaces]] binding = "MEMORIA" id = "<tu-id-de-kv>"

[triggers] crons = ["0 8 * * 1-5"] # de lunes a viernes, 8:00 UTC «`

Que trabaje solo

El fetch responde cuando le llaman. Para que actúe por su cuenta se añade un scheduled:

«`js export default { async fetch(request, env) { /* … */ },

async scheduled(event, env, ctx) { const anthropic = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });

const pendientes = await obtenerTareasPendientes(env); if (pendientes.length === 0) return;

const r = await anthropic.messages.create({ model: "claude-sonnet-5", max_tokens: 800, messages: [{ role: "user", content: Resume estas incidencias y di cuál es más urgente:n${JSON.stringify(pendientes)}, }], });

await enviarResumen(env, r.content[0].text); }, }; «`

Ese patrón —despertarse, mirar el estado, decidir y avisar— cubre la mayoría de agentes útiles de verdad: informes diarios, vigilancia de cambios, avisos de cosas atascadas.

Dónde se rompe en producción

Cuatro problemas que aparecen sí o sí:

Timeouts. Los Workers tienen límite de tiempo de CPU. Si tu agente encadena varias llamadas al modelo, puedes agotarlo. Solución: partir el trabajo en pasos y encadenarlos con colas, o usar Durable Objects si necesitas procesos largos.

Peticiones duplicadas. Si quien te llama reintenta, ejecutarás dos veces. Para cualquier acción con efectos —enviar, cobrar, publicar— guarda un identificador de la operación y compruébalo antes de actuar.

Errores del modelo. La API falla a veces. Envuelve la llamada en un reintento con espera creciente y ten decidido qué hacer si aun así falla; devolver un error 500 sin más deja al usuario colgado.

Gasto desbocado. Un bucle o un abuso te puede costar mucho en horas. Además del límite en Anthropic, lleva un contador por sesión en KV y corta si se pasa.

Cómo ayuda Claude Code aquí

Este tipo de proyecto es donde Claude Code rinde: hay mucho andamiaje repetitivo (configuración de wrangler, manejo de errores, tipos) y poca lógica de negocio.

Lo que conviene dejarle claro en el CLAUDE.md del proyecto:

«`markdown

• Runtime: Cloudflare Workers. NO uses APIs de Node

(fs, path, process): no existen aquí.

• Secretos: siempre desde env, nunca escritos en el código.
• Despliegue: npx wrangler deploy
• Pruebas en local: npx wrangler dev
• Recorta siempre el historial antes de llamar al modelo.

«`

Esa primera línea evita el error más repetido: los Workers no son Node, y sin avisar es habitual que aparezca un require("fs") que revienta al desplegar.

Antes de dar por bueno el despliegue

• Prueba en local con wrangler dev y con datos reales.
• Comprueba que los secretos están puestos: npx wrangler secret list.
• Fuerza un error a propósito y mira qué devuelve al usuario.
• Revisa los logs con npx wrangler tail durante los primeros días.
• Confirma que el cron se dispara cuando esperas (ojo: los crons van en UTC, no en hora peninsular).

Ese último punto pilla a todo el mundo en algún momento: 0 8 * * * no son las ocho de la mañana en España.