El Agents SDK: cada agente es un Durable Object

Cuando estudiaste los Durable Objects seguramente los archivaste como la pieza rara del catálogo: la que se usa para salas de chat, contadores y cerrojos. Ahora vuelven convertidos en la infraestructura central de la IA con estado, y no por moda. Un agente necesita un nombre estable al que dirigirse, un hilo único que ordene los turnos, memoria que sobreviva al reinicio y un canal abierto para contar lo que va haciendo. Esa lista no describe un producto de IA: describe exactamente un Durable Object. El Agents SDK es, en el fondo, el reconocimiento de esa coincidencia —una capa fina que envuelve la primitiva que ya tenías y le pone encima el vocabulario del agente.

Tres capas bajo un nombre

La clase que vas a extender es la punta de un apilamiento muy deliberado. Abajo está el DurableObject del runtime, con sus propiedades duras: una instancia por identificador en todo el planeta, ejecución de un solo hilo y almacenamiento transaccional en SQLite dentro del propio objeto. En medio está Server, heredado de partyserver, que no añade persistencia: sustituye las primitivas de bajo nivel por callbacks cómodos y aporta el direccionamiento por nombre. Arriba, la clase Agent añade lo específico del oficio: estado sincronizado, tareas programadas, clientes MCP y los ganchos del ciclo de vida.

Esta arqueología importa porque explica qué puedes esperar y qué no. Nada de lo que ofrece el SDK es magia inaccesible: cuando necesites bajar, ahí abajo sigue estando this.ctx.storage con su transaccionalidad, y las mismas garantías de consistencia que estudiaste. Y explica también la restricción operativa: un agente exige el binding y la migración de un Durable Object, porque literalmente lo es.

import { Agent, routeAgentRequest } from "agents";

type Estado = { turnos: number; euros: number };

export class AgenteSoporte extends Agent<Env, Estado> {
  initialState: Estado = { turnos: 0, euros: 0 };

  async onStart() {
    this.sql`CREATE TABLE IF NOT EXISTS notas (id TEXT PRIMARY KEY, texto TEXT)`;
  }

  async onMessage(conexion: Connection, mensaje: string) {
    const respuesta = await this.pensar(mensaje);
    this.setState({ ...this.state, turnos: this.state.turnos + 1 });
    conexion.send(respuesta);
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    return (
      (await routeAgentRequest(request, env)) ??
      new Response("No encontrado", { status: 404 })
    );
  },
};

El Worker de entrada ha quedado reducido a un despachador. routeAgentRequest lee de la URL el nombre de la clase y el nombre de la instancia, resuelve el objeto correspondiente y le entrega la petición; si la ruta no le corresponde, devuelve un valor nulo y sigues tú. Todo el trabajo interesante ocurre ya dentro del objeto, donde this.state, this.sql y las conexiones abiertas están simplemente ahí, sin cliente que instanciar ni credencial que pasar.

El estado que viaja solo

El estado del agente tiene dos formas y conviene no confundirlas. Por un lado está this.state, un objeto serializable, pequeño, pensado para lo que el cliente debe ver: el turno actual, el gasto acumulado, si hay una herramienta esperando aprobación. Por otro está this.sql, la base SQLite embebida, para lo que crece: el historial completo, los documentos, las trazas de cada paso.

Lo notable es el comportamiento de la primera. Cuando llamas a setState, no solo persistes: el SDK difunde el estado nuevo a todos los clientes conectados por WebSocket. Y funciona en los dos sentidos, porque el cliente también puede empujar. Ese doble camino convierte el par agente y navegador en algo parecido a un estado compartido replicado, sin que escribas una sola línea de sincronización.

import { useAgent } from "agents/react";

function Panel({ conversacionId }: { conversacionId: string }) {
  const agente = useAgent<AgenteSoporte, Estado>({
    agent: "agente-soporte",
    name: `conv-${conversacionId}`,
    onStateUpdate: (estado, origen) => console.log(origen, estado.turnos),
  });

  return <p>Turnos: {agente.state?.turnos ?? 0}</p>;
}

El hook abre el WebSocket, lo reconecta si se cae y expone state como una propiedad reactiva. Fíjate en el argumento name: es el que decide a qué instancia te conectas. Dos pestañas con el mismo nombre aterrizan en el mismo agente y ven el mismo estado en el mismo instante; dos nombres distintos son dos agentes que no comparten absolutamente nada.

flowchart LR
C1[pestana A] --> W[worker con routeAgentRequest]
C2[pestana B] --> W
C3[otro usuario] --> W
W -->|conv-42| A1[agente conv-42]
W -->|conv-99| A2[agente conv-99]
A1 --> S1[estado y sqlite propios]
A2 --> S2[estado y sqlite propios]
style A1 fill:#89b4fa,color:#11111b
style A2 fill:#89b4fa,color:#11111b

Tareas que despiertan solas

Hay una capacidad que distingue a un agente de un chat y que se olvida con facilidad: puede actuar cuando nadie le está hablando. El SDK lo expone con this.schedule, que acepta un retardo en segundos, una fecha concreta o una expresión de cron, y el nombre del método que debe ejecutarse cuando llegue el momento.

export class AgenteSoporte extends Agent<Env, Estado> {
  async onMessage(conexion: Connection, mensaje: string) {
    await this.schedule(60 * 60 * 24 * 3, "revisarPedido", { pedido: "A-1001" });
  }

  async revisarPedido(datos: { pedido: string }) {
    const estado = await this.env.PEDIDOS.consultar(datos.pedido);
    if (estado === "retenido") {
      this.broadcast(JSON.stringify({ aviso: "tu pedido sigue retenido", ...datos }));
    }
  }
}

Por debajo son las alarmas de los Durable Objects, con toda su durabilidad: el agente hiberna, deja de consumir recursos y el runtime lo despierta tres días después con el contexto intacto. Nada de esto exige un cron externo, ni una cola de tareas, ni un proceso vigilando una tabla, y por eso encaja tan bien con el seguimiento —comprobar dentro de una semana si el caso quedó resuelto— o con la memoria que se destila por la noche.

Lo interesante es que la planificación también puede ser una herramienta que expones al modelo. Si le das la capacidad de programarse a sí mismo, el agente puede responder a un recuérdamelo el viernes creando su propia cita futura. Es un patrón potente y, como todo lo potente en este nivel, conviene acotarlo: sin un tope de tareas pendientes por agente, tienes un despertador que se multiplica.

El nombre es la arquitectura

Todo lo anterior descansa en una elección que se toma en una línea y condiciona el sistema entero: qué cadena usas como nombre de la instancia. Ese nombre define la unidad de aislamiento, la unidad de concurrencia y la unidad de memoria, las tres a la vez.

Como los turnos de una misma instancia se ejecutan en un solo hilo, el nombre es también el ámbito de la exclusión mutua: dentro de un agente jamás hay dos turnos pisándose. Ese regalo tiene precio, y es el que ya conoces del nivel de los Durable Objects: un agente muy compartido es una cola con un único servidor, y una operación lenta bloquea a los demás. Elegir el nombre es, por tanto, elegir dónde pones la frontera entre aislamiento y memoria compartida.