Cloudflare Agents SDK no es otro wrapper de prompts. Es un runtime TypeScript para agentes persistentes: cada instancia vive en un Durable Object con SQL, estado sincronizado, WebSockets, tareas programadas y herramientas MCP.
Cloudflare Agents SDK es un runtime TypeScript para crear agentes de IA persistentes sobre Cloudflare Workers y Durable Objects. La diferencia importante frente a un endpoint serverless normal es que cada agente tiene identidad duradera, SQL local, estado sincronizado, conexiones WebSocket, tareas programadas y una ruta natural hacia MCP, Workflows y herramientas del ecosistema Cloudflare.
Plan de despliegue. TL;DR La keyword principal es
Cloudflare Agents SDK. La intención de búsqueda en español es práctica: entender qué es, cuándo usarlo frente a un backend propio o un framework de agentes Python, y cómo diseñar una arquitectura mínima sin convertir el agente en un servicio opaco. Mi postura: merece la pena cuando el producto necesita sesiones vivas, memoria por usuario o equipo, eventos, WebSockets, scheduling y acciones largas. Para una llamada aislada al modelo, es demasiada plataforma; usa una API directa y guarda la complejidad para cuando el agente tenga ciclo de vida real.
Qué es Cloudflare Agents SDK y qué no es
Una definición citable: Cloudflare Agents SDK es una capa de runtime para agentes stateful donde una clase Agent encapsula estado, conexiones, métodos invocables, llamadas a modelos, herramientas, errores y tareas programadas, ejecutándose sobre Durable Objects.
No es un modelo, no es un prompt mágico y no reemplaza la disciplina de producto. El SDK te da primitivas para que un agente recuerde, despierte, reciba eventos, coordine trabajo y hable con clientes en tiempo real. La calidad sigue dependiendo de tus tools, permisos, evals, límites y diseño del workflow.
La lectura práctica es esta: Cloudflare intenta convertir el problema de dónde vive mi agente en infraestructura gestionada. En lugar de reconstruir sesión, memoria, WebSocket, cola y cron en piezas separadas, puedes colgarlo de una instancia direccionable por nombre.
Briefing. El modelo mental: agente como micro-servidor duradero Cada instancia de agente se parece más a un pequeño servidor con identidad que a una función stateless. Si el agente representa a un usuario, una sala, un ticket, un repositorio o un tenant, el mismo identificador devuelve la misma instancia. Eso elimina mucho pegamento: no tienes que sincronizar manualmente memoria conversacional entre Lambda, Redis, base de datos y WebSocket gateway. El coste conceptual es que debes diseñar fronteras de instancia. Un agente por usuario facilita privacidad y preferencias. Un agente por equipo facilita colaboración. Un agente por repositorio facilita automatización de desarrollo. Mezclar todo en un agente global suele acabar en permisos borrosos y estado difícil de auditar.
La pregunta buena no es ¿puedo hacer un chatbot?. La pregunta buena es: ¿qué entidad del producto necesita recordar, recibir eventos, ejecutar tareas y mantener conexiones? Esa entidad debería mapearse a una instancia de agente.
La idea sana: el modelo razona dentro de un runtime con identidad, estado y límites; no dentro de un endpoint que olvida todo al devolver la respuesta.
Arquitectura mínima que sí desplegaría
La versión mínima seria tiene seis piezas. Primero, una clase Agent<Env, State> con un estado pequeño y serializable. Segundo, routeAgentRequest para enrutar peticiones a instancias por nombre. Tercero, una política explícita de nombres: usuario, equipo, sala, ticket o repositorio. Cuarto, SQL local solo para datos que pertenecen a esa instancia. Quinto, WebSockets o SSE solo cuando el usuario necesita ver progreso. Sexto, observabilidad y límites antes de tools mutantes.
No empezaría conectando Browser, MCP, pagos, email y Workflows el día uno. Empezaría con una tarea de lectura, una tool controlada y un estado mínimo. Cuando eso sea observable, añadiría scheduling. Cuando scheduling no baste para trabajo largo con reintentos, movería esa parte a Workflows.
La arquitectura debe dejar claro qué vive en el agente y qué vive fuera. Preferencias, progreso y memoria local encajan en el agente. Datos de negocio compartidos, billing, permisos corporativos y auditoría de largo plazo suelen pertenecer a sistemas externos que el agente consulta con credenciales limitadas.
Código mínimo: estado, routing y RPC
import { Agent, callable, routeAgentRequest } from "agents";
type State = {
lastTask: string | null;
completed: number;
};
export class RepoAgent extends Agent<Env, State> {
initialState: State = { lastTask: null, completed: 0 };
@callable()
async summarizeRepo(task: string) {
this.setState({ ...this.state, lastTask: task });
// Aqui llamarias a un modelo y a tools de lectura con permisos limitados.
const summary = `Resumen pendiente para: ${task}`;
this.setState({ ...this.state, completed: this.state.completed + 1 });
return { summary, completed: this.state.completed };
}
}
export default {
async fetch(request: Request, env: Env) {
return (await routeAgentRequest(request, env)) ??
new Response("Not found", { status: 404 });
},
} satisfies ExportedHandler<Env>;
Lo que conviene comprobar
El detalle que importa no es la sintaxis del contador. Es el contrato: estado pequeño, método invocable, actualización explícita y routing que devuelve siempre la misma instancia cuando el nombre coincide. Eso hace posible reanudar trabajo sin inventarte otro session store.
Configurar Durable Objects sin olvidar migraciones
Agents SDK depende de Durable Objects. En wrangler.jsonc, cada clase de agente necesita binding y migración SQLite. Si cambias el nombre de la clase o creas otro tipo de agente, trátalo como cambio de infraestructura, no como refactor inocente.
{
"durable_objects": {
"bindings": [
{ "name": "RepoAgent", "class_name": "RepoAgent" }
]
},
"migrations": [
{ "tag": "v1", "new_sqlite_classes": ["RepoAgent"] }
]
}
Mi regla: versiona la configuración junto al agente y revisa migraciones en PR. Un agente con memoria persistente no se comporta como una función desechable; si rompes identidad o esquema, rompes continuidad para usuarios reales.
Estado: cuándo usar setState y cuándo usar SQL
Usa setState para el estado pequeño que el cliente necesita ver sincronizado: fase actual, progreso, última acción, preferencias simples o bandera de aprobación. Es persistente, se guarda en SQLite y se sincroniza en tiempo real con clientes conectados.
Usa this.sql para historial, filas consultables, eventos, resultados intermedios o datos que no quieres enviar enteros a cada cliente. La tentación de meter todo en state es fuerte porque funciona rápido; también es la forma más fácil de crear payloads enormes y acoplar UI con almacenamiento interno.
Estado de agente no es memoria infinita para el LLM. Si usas estado como contexto del modelo, resume y selecciona. Poner transcripciones completas en cada turno dispara coste, latencia y riesgo de prompt injection acumulada.
Briefing. Scheduling: agentes que despiertan sin usuario El scheduling es una de las razones reales para usar este runtime. Puedes programar una tarea con retraso, fecha concreta, cron o intervalo, y la tarea sobrevive reinicios porque queda persistida. Por debajo, Cloudflare usa Durable Object alarms para despertar la instancia.
export class DigestAgent extends Agent<Env, { runs: number }> { initialState = { runs: 0 }; async onRequest(request: Request) { await this.schedule("0 8 * * *", "dailyDigest", { audience: "dev-team", }); return new Response("Digest scheduled"); } async dailyDigest(payload: { audience: string }) { this.setState({ runs: this.state.runs + 1 }); // Generar resumen, consultar fuentes y enviar notificacion. } }
No usaría scheduling para procesos de horas con reintentos complejos y compensaciones. Ahí entran Workflows. Scheduling es ideal para recordatorios, polling prudente, reintentos simples, digest diarios y mantenimiento de una instancia concreta.
Lectura práctica. Workflows: cuándo sacar trabajo del turno interactivo Un turno de chat debería mantenerse explicable. Si el agente necesita investigar durante minutos, coordinar pasos con reintentos o garantizar ejecución aunque se corte la conexión, separa el trabajo en Workflows. El agente puede iniciar el workflow, persistir estado visible y recibir resultado o progreso. La diferencia mental: el agente conserva identidad y conversación; Workflows ejecuta procesos duraderos. Juntos sirven para casos como análisis de repositorios, informes programados, procesamiento de tickets, migraciones asistidas o tareas que deben sobrevivir despliegues. El error frecuente es meter todo en el método
onChatMessage. Eso produce demos espectaculares y producción frágil. Si una operación tiene fases, presupuesto y retry policy, dale forma de workflow o de tarea programada, no de respuesta improvisada.
MCP: conectar herramientas sin abrir toda la cuenta
Cloudflare Agents puede consumir MCP y también servir herramientas mediante MCP. Eso encaja muy bien con agentes internos: el agente mantiene sesión y permisos locales, mientras MCP expone capacidades concretas a modelos o clientes compatibles.
Pero MCP no es una licencia para conectar toda tu infraestructura. Usa OAuth o credenciales por ámbito, separa lectura de escritura, registra tool calls y limita qué servidores puede usar cada tipo de agente. Si el agente opera sobre Cloudflare, GitHub o sistemas internos, el blast radius lo define tu política de tools, no el SDK.
Para DevAI, la pauta sería: MCP para capacidades bien acotadas, output estructurado para resultados auditables y revisión humana para acciones irreversibles. Sin esas tres cosas, solo has creado una consola de administración con lenguaje natural.
WebSockets y cliente React: progreso sin polling torpe
El cliente puede conectarse al agente con useAgent o useAgentChat. Eso permite leer estado sincronizado, invocar métodos y mostrar progreso sin montar un gateway WebSocket separado. Para UIs de chat, AIChatAgent y useAgentChat añaden persistencia de mensajes y recuperación de streams.
Lo que conviene comprobar
No pondría todo el producto dentro del hook. La UI debe tratar el agente como runtime de interacción, no como base de datos global. El patrón limpio es: estado visible en el agente, datos de negocio en APIs normales, y eventos largos como progreso o milestones.
Si el usuario cierra la pestaña o se cae la conexión, la promesa del runtime es que pueda volver a la misma instancia. Diseña la UI para esa realidad: muestra última fase, último error, siguiente acción disponible y si hay aprobación humana pendiente.
Seguridad y permisos: el agente no es el perímetro
Cloudflare te da identidad duradera del agente, pero eso no equivale a autorización de negocio. Comprueba usuario, tenant y permisos en cada acción sensible. El nombre de instancia ayuda a enrutar; no debería ser el único control de acceso.
Separa secrets por entorno, scope y tool. Un agente de soporte no necesita credenciales de despliegue. Un agente de repositorio no necesita escribir en billing. Un agente que genera resúmenes no necesita ejecutar acciones mutantes. Lo aburrido sigue siendo lo correcto: mínimo privilegio, allowlists, logs y revisión humana.
También vigilaría prompt injection persistente. Un agente que recuerda instrucciones, páginas visitadas o resultados de tools puede acumular datos hostiles. Resume, etiqueta procedencia y evita que contenido recuperado se convierta en instrucciones del sistema.
Observabilidad y coste
Mide por instancia y por tipo de trabajo: turnos, tools, modelo, tokens, duración, reintentos, errores, tareas programadas y workflows iniciados. Si usas AI Gateway, aprovecha caching, rate limits, fallback y logs para ver consumo real en vez de adivinarlo por factura.
La métrica que más me interesa no es mensajes respondidos. Es decisiones útiles completadas sin intervención peligrosa. Un agente que contesta mucho pero dispara workflows innecesarios, llama tools caras o requiere revisión manual constante no está ahorrando tiempo.
Para producción pondría presupuestos por agente, por usuario y por acción. Cuando un agente cruza umbral, debe degradar: modelo más barato, menos contexto, cola asíncrona o pedir aprobación. Sin degradación, el primer incidente será coste o permisos.
Briefing. Cuándo elegir Cloudflare Agents SDK frente a LangGraph, ADK u OpenAI Agents SDK Elige Cloudflare Agents SDK si el problema principal es runtime: identidad duradera, WebSockets, estado por instancia, scheduling, Workers, Durable Objects, Workflows y herramientas cerca de la edge. Encaja especialmente en productos web que necesitan agentes vivos por usuario, equipo, canal o recurso. Elige LangGraph si el núcleo del problema es orquestación explícita de estados y grafos complejos en Python. Elige Google ADK si tu stack está en Google Cloud y quieres sesiones, evals y despliegue dentro de ese ecosistema. Elige OpenAI Agents SDK si priorizas handoffs, guardrails y tracing alrededor de modelos OpenAI.
La comparación honesta: Cloudflare no gana por tener el mejor loop de razonamiento. Gana cuando quieres dejar de fabricar infraestructura alrededor del loop. Si tu equipo ya tiene backend robusto, colas, WebSockets y cron bien resueltos, el valor incremental baja.
Lectura práctica. Checklist de producción Define la entidad que representa cada instancia de agente: usuario, equipo, sala, ticket, repo o proceso. Mantén
statepequeño, serializable y visible; usa SQL para historial y eventos consultables. Configura Durable Object bindings y migraciones como parte revisada del despliegue. Separa tools de lectura y escritura; aplica credenciales de mínimo privilegio. Usa scheduling para tareas simples y Workflows para procesos largos con reintentos. Instrumenta turnos, tools, tokens, latencia, errores, tareas y workflows por instancia. Añade revisión humana para acciones irreversibles o con coste relevante. Protege el agente contra prompt injection persistente: procedencia, resumen y límites de contexto. Prueba reconexión, hibernación, despliegue y recuperación antes de anunciarlo como producción.
Plan de adopción en cinco días
Día 1: elige una entidad clara, por ejemplo
repo-agent/<owner>/<repo>osupport-agent/<ticket-id>, y crea un agente sin tools mutantes.Día 2: añade estado mínimo, SQL para eventos y una UI que muestre fase, último error y progreso.
Día 3: conecta un modelo y una sola tool de lectura. Mide tokens, latencia y errores por instancia.
Día 4: añade scheduling para una tarea real, como digest diario, revisión de cola o reintento con backoff.
Día 5: decide si necesitas MCP, Workflows o ambos. Si no puedes explicar permisos y recuperación, no añadas más herramientas todavía.
Conclusión
Cloudflare Agents SDK es interesante porque ataca una parte poco glamourosa de los agentes: dónde viven, cómo recuerdan, cómo se reconectan, cómo despiertan y cómo ejecutan trabajo duradero. Eso no convierte cualquier chatbot en producto, pero sí reduce mucha infraestructura accidental.
Lo que conviene comprobar
Mi recomendación es usarlo cuando el agente tenga vida propia: sesiones, estado, eventos, scheduling, progreso y tools. Si solo necesitas transformar un input en JSON, no lo compliques. Pero si estás construyendo un agente que acompaña a un usuario o equipo durante horas o días, Durable Objects como runtime empiezan a tener mucho sentido.
Preguntas frecuentes
¿Qué es Cloudflare Agents SDK?
Cloudflare Agents SDK es un SDK TypeScript para crear agentes de IA persistentes sobre Workers y Durable Objects, con estado, SQL local, WebSockets, scheduling, Workflows y soporte MCP.
¿Cloudflare Agents SDK requiere Durable Objects?
Sí. El modelo de identidad, estado persistente, SQL y conexiones del agente se apoya en Durable Objects y sus bindings de configuración.
¿Puedo usar OpenAI o Anthropic con Cloudflare Agents SDK?
Sí. El runtime puede usar Workers AI o proveedores externos como OpenAI, Anthropic y Gemini; la elección del modelo no es lo mismo que la elección del runtime.
¿Cuándo usar scheduling y cuándo Workflows?
Usa scheduling para tareas simples en una instancia: retrasos, cron, intervalos y reintentos ligeros. Usa Workflows para procesos largos, multi-paso, con reintentos y garantías más fuertes.
¿Cloudflare Agents SDK reemplaza a MCP?
No. MCP es una interfaz de herramientas y contexto. Agents SDK puede consumir o servir MCP, pero sigues necesitando permisos, allowlists y observabilidad.
¿Es mejor que LangGraph o Google ADK?
No universalmente. Cloudflare Agents SDK destaca como runtime stateful para productos web; LangGraph destaca en grafos de ejecución; Google ADK encaja en el ecosistema Google; OpenAI Agents SDK encaja en orquestación OpenAI.
Cómo llevar un agente Cloudflare Agents SDK a producción
Elegir la entidad de instancia. Decide si cada agente representa un usuario, equipo, sala, ticket, repositorio o proceso programado.
Crear la clase Agent. Define
Agent<Env, State>con estado pequeño, métodos invocables y una política clara de nombres.Configurar Durable Objects. Añade bindings y migraciones SQLite en
wrangler.jsoncy revísalos como infraestructura.Separar estado y datos. Usa
setStatepara estado visible y SQL o APIs externas para historial y datos compartidos.Añadir tools con permisos mínimos. Empieza por lectura, registra llamadas y exige aprobación humana para acciones irreversibles.
Programar trabajo duradero. Usa
schedulepara tareas simples y Workflows para procesos largos con reintentos y recuperación.Verificar recuperación. Prueba reconexión WebSocket, hibernación, despliegue, errores de modelo y reanudación antes de exponerlo a usuarios.
Cierre editorial. Regla operativa Activa la automatización donde el comentario pueda cambiar una decisión técnica, no donde solo vaya a producir ruido revisable.
Fuentes y referencias
¿Te sirve esto? Cada semana resumo herramientas de IA para devs (agentes, MCP, seguridad, workflows) en un email de 5 minutos, en español. Suscríbete gratis.
Publicado originalmente en devaisemanal.com.
Top comments (0)