ADR 012: Cloudflare Agents SDK para servicios educativos impulsados por IA

Contexto

A2R Workspaces es una plataforma SaaS multi-tenant para la industria educativa. La plataforma ya utiliza Cloudflare Durable Objects para comunicacion WebSocket en tiempo real (ver ADR-002 y Comunicacion en Tiempo Real). Existe una necesidad creciente de servicios educativos impulsados por IA — tutoria, generacion de contenido, evaluacion y un asistente educativo — que sean:

• De larga duracion y persistentes: Las conversaciones abarcan multiples sesiones. Los estudiantes regresan a hilos de tutoria en curso, y los profesores revisan contenido generado por IA de forma iterativa.
• Multi-usuario: Multiples estudiantes o profesores pueden interactuar con el mismo agente simultaneamente (por ejemplo, una sesion de tutoria en aula).
• En tiempo real: Las respuestas se transmiten via WebSocket, siguiendo los patrones existentes de infraestructura en tiempo real.
• Conformes con el RGPD: Todos los datos personales — incluyendo historial de conversaciones, perfiles de estudiantes y resultados de evaluaciones — deben almacenarse y procesarse exclusivamente dentro de la Union Europea.

Construir estos servicios sobre Durable Objects sin procesar requeriria reimplementar la gestion de conversaciones, el enrutamiento WebSocket, la persistencia de estado y la invocacion de herramientas desde cero. El Cloudflare Agents SDK proporciona estas capacidades como una abstraccion de primera clase sobre Durable Objects.

Decisión

Adoptar el Cloudflare Agents SDK (paquete agents) para todos los servicios educativos impulsados por IA. Todos los Durable Objects de agentes se fijan a la jurisdiccion de la UE usando jurisdiction("eu").

Tipos de agentes

La plataforma define cuatro tipos de agentes, cada uno extendiendo AIChatAgent:

Patron de implementacion base

import { AIChatAgent } from "agents/ai-chat-agent";
import { type Connection, type WSMessage } from "agents";

export class TutoringAgent extends AIChatAgent<Env, AgentState> {
  // Agent-local SQLite stores conversation history automatically
  // Multi-user WebSocket with hibernation support inherited from base

  async onChatMessage(onFinish: StreamTextOnFinishCallback<ToolSet>) {
    const { messages, model } = this;
    const result = streamText({
      model: createOpenAI({ apiKey: this.env.OPENAI_API_KEY })("gpt-4o"),
      system: this.getSystemPrompt(),
      messages,
      tools: this.getTools(),
      onFinish,
    });
    return result;
  }
}

Integracion con el frontend

import { useAgentChat } from "agents/ai-react";

function TutoringChat({ agentId }: { agentId: string }) {
  const { messages, input, handleInputChange, handleSubmit } = useAgentChat({
    agent: "tutoring-agent",
    name: agentId,
  });

  return (
    <form onSubmit={handleSubmit}>
      {messages.map((m) => <ChatMessage key={m.id} message={m} />)}
      <input value={input} onChange={handleInputChange} />
    </form>
  );
}

Conformidad con el RGPD

Todos los Durable Objects de agentes se fijan a la jurisdiccion de la UE:

// workers/agent-service/wrangler.jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "TUTORING_AGENT",
        "class_name": "TutoringAgent",
        "script_name": "agent-service",
        "jurisdiction": "eu"
      }
    ]
  }
}

Consecuencias

Positivas

• Construido sobre infraestructura existente: El Agents SDK extiende Durable Objects, que la plataforma ya utiliza para comunicacion en tiempo real. El equipo tiene experiencia operativa con patrones de DO, hibernacion WebSocket y configuracion de wrangler.
• Estado de conversacion persistente: Cada instancia de agente almacena su historial de conversacion en SQLite local del agente. Los estudiantes pueden retomar sesiones de tutoria despues de dias o semanas sin depender de bases de datos externas.
• WebSocket multi-usuario: Multiples usuarios pueden conectarse a la misma instancia de agente simultaneamente. Esto habilita escenarios de aula donde un profesor y estudiantes interactuan con el mismo agente de tutoria en tiempo real.
• RPC tipado via @callable(): El decorador @callable() expone metodos del agente como endpoints RPC tipados sobre WebSocket, consistente con el patron existente de RPC via service bindings de la plataforma.
• Hooks de React: El hook useAgentChat proporciona una integracion lista para usar con la arquitectura MFE basada en React, reduciendo el boilerplate del frontend.
• Soporte de servidor MCP: Los agentes pueden exponer herramientas via el Model Context Protocol, habilitando la integracion con herramientas externas impulsadas por IA e IDEs.
• Fijacion de jurisdiccion a la UE: jurisdiction("eu") asegura que todo el estado del agente — historial de conversaciones, datos de estudiantes, resultados de evaluaciones — se almacene y procese exclusivamente en centros de datos de la UE, cumpliendo los requisitos de residencia de datos del RGPD.

Negativas

• Madurez del SDK: El Cloudflare Agents SDK alcanzo disponibilidad general en 2025. La superficie de la API sigue evolucionando, y son posibles cambios incompatibles en versiones menores. Mitigacion: fijar versiones exactas del SDK y monitorear el changelog de Cloudflare.
• Costes de modelos de IA: Cada interaccion de IA incurre en costes de API del modelo (precios por token). Para una plataforma que sirve a miles de estudiantes, los costes pueden escalar significativamente. Mitigacion: implementar presupuestos de tokens por tenant, cachear respuestas comunes y usar modelos mas pequenos para tareas simples.
• Moderacion de contenido: La IA educativa debe producir contenido apropiado para la edad, preciso e imparcial. La plataforma debe implementar filtrado de contenido, validacion de salidas y supervision humana — especialmente para agentes de evaluacion que influyen en las calificaciones de los estudiantes. Mitigacion: definir politicas de moderacion, implementar guardrails de salida y requerir revision del profesor para evaluaciones de alto impacto.
• Procesamiento solo en la UE: Restringir todo el procesamiento de IA a centros de datos de la UE puede limitar la eleccion de proveedores de modelos o incrementar la latencia para modelos alojados fuera de la UE. Mitigacion: preferir proveedores con endpoints en la UE (por ejemplo, Azure OpenAI regiones UE, Anthropic UE).
• Limitaciones de desarrollo local: La hibernacion de Durable Objects no esta completamente simulada en Miniflare. Las conexiones WebSocket de agentes funcionan localmente, pero el comportamiento de hibernacion debe probarse en staging. Mitigacion: documentar las limitaciones de desarrollo local y establecer procedimientos de prueba en staging.

Alternativas consideradas

Framework personalizado sobre Durable Objects sin procesar

Construir la funcionalidad de agentes de IA directamente sobre la infraestructura existente de Durable Objects sin el Agents SDK. Esto proporciona control total pero requiere reimplementar la gestion de conversaciones, el enrutamiento WebSocket, la persistencia de estado, el streaming y la invocacion de herramientas — todo lo cual el Agents SDK proporciona de forma nativa. El esfuerzo de ingenieria es sustancial sin ventaja arquitectonica sobre el uso del SDK.

Servicio de IA externo (por ejemplo, SaaS alojado)

Usar una plataforma de IA de terceros (por ejemplo, una API de tutoria alojada) en lugar de construir agentes sobre Cloudflare. Esto evita la complejidad de infraestructura pero introduce dependencias externas, preocupaciones de residencia de datos (la conformidad con el RGPD pasa a ser responsabilidad del proveedor, con auditabilidad limitada), costes mas altos por consulta y menor flexibilidad para personalizacion educativa. La plataforma tambien perderia la integracion estrecha con su infraestructura Cloudflare existente.

Vercel AI SDK (sin Agents)

Usar el Vercel AI SDK para streaming de IA e invocacion de herramientas, ejecutandose en Cloudflare Workers sin Durable Objects. Esto funciona para interacciones de chat sin estado pero no proporciona historial de conversacion persistente, sesiones multi-usuario ni almacenamiento local del agente. Cada solicitud necesitaria recargar la conversacion completa desde una base de datos externa, anadiendo latencia y complejidad. El Agents SDK resuelve estos problemas de forma nativa a traves del estado de Durable Objects.

Documentación Relacionada

• Vision General de Arquitectura — Arquitectura del sistema, stack tecnologico y propiedad de equipos
• Infraestructura Cloudflare — Workers, servicios de almacenamiento, service bindings y conformidad con el RGPD
• Comunicacion en Tiempo Real — Patrones de Durable Objects y WebSocket utilizados por los agentes
• Arquitectura de Agentes IA — Arquitectura completa de agentes, implementacion y detalles del RGPD