Los agentes tienen sus propios ordenadores con Sandboxes (disponibilidad general)

Cuando anunciamos Cloudflare Sandboxes el pasado mes de junio, la idea era sencilla: los agentes de IA necesitan desarrollar y ejecutar código, y deben hacerlo en un entorno seguro.

Si un agente desempeña funciones propias de un desarrollador, esto implica clonar repositorios, compilar código en diversos lenguajes, gestionar servidores de desarrollo, etc. Para hacer todo esto de forma eficaz, a menudo necesitarán un ordenador de verdad (¡y si no, siempre pueden recurrir a algo más ligero!).

Muchos desarrolladores están combinando soluciones utilizando máquinas virtuales o soluciones de contenedores existentes, pero hay muchos problemas difíciles de resolver:

• Picos de actividad: como cada sesión necesita su propio entorno aislado, a menudo tienes que poner en marcha muchos entornos rápidamente, pero no quieres pagar por recursos informáticos inactivos en espera.

• Rápida restauración del estado: cada sesión debería iniciarse y reiniciarse rápidamente, retomando el estado anterior.

• Seguridad: los agentes necesitan acceder a los servicios de forma segura, pero no se les pueden confiar las credenciales.

• Control: debe ser sencillo controlar mediante programación el ciclo de vida del entorno aislado, ejecutar comandos, gestionar archivos y mucho más.

• Ergonomía: debes proporcionar una interfaz sencilla para que tanto los usuarios como los agentes realicen operaciones comunes.

Hemos dedicado tiempo a resolver estos problemas para que tú no tengas que hacerlo. Desde nuestro lanzamiento inicial, hemos mejorado Sandboxes para ejecutar agentes a escala. Hemos colaborado con nuestros socios iniciales, como Figma, que ejecutan agentes en contenedores con Figma Make:

“Figma Make está diseñado para ayudar a creadores y desarrolladores de todo tipo a pasar de la idea a la producción más rápido. Para alcanzar ese objetivo, necesitábamos una solución de infraestructura que nos ofreciera entornos aislados fiables y altamente escalables en los que pudiéramos ejecutar código no verificado creado por agentes y usuarios. Cloudflare Containers es esa solución".

- Alex Mullans, responsable de IA y plataformas para desarrolladores en Figma

Queremos ofrecer Sandboxes a aún más organizaciones importantes, así que hoy estamos encantados de anunciar que tanto Sandboxes como Cloudflare Containers ya están disponibles para todos.

Echemos un vistazo a algunos de los cambios recientes en Sandboxes:

• La inyección segura de credenciales te permite realizar llamadas autenticadas sin que el agente tenga acceso a credenciales  

• La compatibilidad con PTY te ofrece a ti y a tu agente un terminal real

• Los intérpretes de código persistente proporcionan a tu agente un lugar para ejecutar Python, JavaScript y TypeScript con estado de forma inmediata

• Los procesos en segundo plano y las URL de vista previa en directo proporcionan una forma sencilla de interactuar con los servidores de desarrollo y verificar los cambios en curso

• La observación del sistema de archivos mejora la velocidad de iteración a medida que los agentes realizan cambios

• Instantáneas te permiten recuperar rápidamente la sesión de codificación de un agente

• Los límites más altos y el precio de la CPU activa te permiten implementar una flota de agentes a escala sin pagar por los ciclos de CPU no utilizados

Antes de entrar en algunos de los cambios recientes, repasemos rápidamente los conceptos básicos.

Un Cloudflare Sandbox es un entorno persistente y aislado que funciona con Cloudflare Containers. Pides un entorno aislado por su nombre. Si se está ejecutando, lo obtienes. Si no es así, se inicia. Cuando está inactivo, entra en suspensión automáticamente y se activa cuando recibe una solicitud. Es fácil interactuar mediante programación con el entorno aislado utilizando métodos como exec, gitClone, writeFile y más.

import { getSandbox } from "@cloudflare/sandbox";
export { Sandbox } from "@cloudflare/sandbox";

export default {
  async fetch(request: Request, env: Env) {
    // Ask for a sandbox by name. It starts on demand.
    const sandbox = getSandbox(env.Sandbox, "agent-session-47");

    // Clone a repository into it.
    await sandbox.gitCheckout("https://github.com/org/repo", {
      targetDir: "/workspace",
      depth: 1,
    });

    // Run the test suite. Stream output back in real time.
    return sandbox.exec("npm", ["test"], { stream: true });
  },
};

Siempre que proporciones el mismo identificador, las solicitudes posteriores pueden llegar a este mismo entorno aislado desde cualquier parte del mundo.

Uno de los problemas más difíciles en las cargas de trabajo de los agentes es la autenticación. A menudo se necesitan agentes para acceder a servicios privados, pero no se puede confiar plenamente en ellos con credenciales sin cifrar. 

Los entornos aislados resuelven este problema inyectando credenciales en la capa de red mediante un proxy de salida programable. Esto significa que los agentes de entorno aislado nunca tienen acceso a las credenciales y puedes personalizar completamente la lógica de autenticación como mejor te parezca:

class OpenCodeInABox extends Sandbox {
  static outboundByHost = {
    "my-internal-vcs.dev": (request, env, ctx) => {
      const headersWithAuth = new Headers(request.headers);
      headersWithAuth.set("x-auth-token", env.SECRET);
      return fetch(request, { headers: headersWithAuth });
    }
  }
}

Para más información sobre cómo funciona, incluida la inyección de credenciales con reconocimiento de identidad, la modificación dinámica de las reglas y la integración con los enlaces de Workers, lee nuestra reciente publicación del blog sobre la autenticación de Sandbox.

Los primeros sistemas de agentes solían representar el acceso al shell como un bucle de solicitud-respuesta: ejecutar un comando, esperar a que apareciera el resultado, volver a mostrar el historial en la línea de comandos y repetir. Funciona, pero no es así como los desarrolladores utilizan realmente un terminal. 

Los humanos ejecutan algo, observan la transmisión de salida, lo interrumpen, se vuelven a conectar más tarde y continúan. Los agentes se benefician de ese mismo bucle de retroalimentación.

En febrero, anunciamos la compatibilidad con PTY. Una sesión de pseudoterminal en un entorno aislado, redireccionada mediante proxy a través de WebSocket, compatible con xterm.js.

Simplemente llama a sandbox.terminal para servir el backend:

// Worker: upgrade a WebSocket connection into a live terminal session
export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);
    if (url.pathname === "/terminal") {
      const sandbox = getSandbox(env.Sandbox, "my-session");
      return sandbox.terminal(request, { cols: 80, rows: 24 });
    }
    return new Response("Not found", { status: 404 });
  },
};

Y usa el complemento xterm para llamarlo desde el cliente:

// Browser: connect xterm.js to the sandbox shell
import { Terminal } from "xterm";
import { SandboxAddon } from "@cloudflare/sandbox/xterm";

const term = new Terminal();
const addon = new SandboxAddon({
  getWebSocketUrl: ({ origin }) => `${origin}/terminal`,
});

term.loadAddon(addon);
term.open(document.getElementById("terminal-container")!);
addon.connect({ sandboxId: "my-session" });

Esto permite a los agentes y desarrolladores utilizar un PTY completo para depurar esas sesiones en directo.

Cada sesión de terminal tiene su propio shell aislado, su propio directorio de trabajo, su propio entorno. Abre tantos como necesites, como lo harías en tu propio equipo. La salida se almacena en el búfer del servidor, así que al volver a conectarte se reproduce lo que te perdiste.

Para los flujos de trabajo de análisis de datos, scripting y exploración, también ofrecemos una abstracción de mayor nivel: que es un contexto de ejecución de código persistente.

La palabra clave es "persistente". Muchas implementaciones de intérpretes de código ejecutan cada fragmento de código de forma aislada, por lo que el estado se pierde entre llamadas. No puedes establecer una variable en un paso y leerla en el siguiente.

Los espacios seguros te permiten crear "contextos" que persisten. Las variables y las importaciones persisten en las llamadas de la misma manera que lo harían en un cuaderno Jupyter Notebook:

// Create a Python context. State persists for its lifetime.
const ctx = await sandbox.createCodeContext({ language: "python" });

// First execution: load data
await sandbox.runCode(`
  import pandas as pd
  df = pd.read_csv('/workspace/sales.csv')
  df['margin'] = (df['revenue'] - df['cost']) / df['revenue']
`, { context: ctx });

// Second execution: df is still there
const result = await sandbox.runCode(`
  df.groupby('region')['margin'].mean().sort_values(ascending=False)
`, { context: ctx, onStdout: (line) => console.log(line.text) });

// result contains matplotlib charts, structured json output, and Pandas tables in HTML

Los agentes son más útiles cuando pueden crear algo y mostrárselo al usuario de inmediato. Los entornos aislados admiten procesos en segundo plano, comprobaciones de disponibilidad y URL de vista previa. Esto permite a un agente iniciar un servidor de desarrollo y compartir un enlace en directo sin abandonar la conversación.

// Start a dev server as a background process
const server = await sandbox.startProcess("npm run dev", {
  cwd: "/workspace",
});

// Wait until the server is actually ready — don't just sleep and hope
await server.waitForLog(/Local:.*localhost:(\d+)/);

// Expose the running service with a public URL
const { url } = await sandbox.exposePort(3000);

// url is a live public URL the agent can share with the user
console.log(`Preview: ${url}`);

Con waitForPort() y waitForLog(), los agentes pueden secuenciar el trabajo basándose en señales reales del programa en ejecución en lugar de conjeturas. Esto es mucho mejor que la alternativa habitual, que suele ser algo así como dormir (2000) seguido de "esperanza".

Los bucles de desarrollo modernos se basan en eventos. Guarda un archivo, vuelve a ejecutar la compilación. Edita una configuración, reinicia el servidor. Cambia una prueba, vuelve a ejecutar la suite.

Lanzamos sandbox.watch() en marzo. Devuelve un flujo SSE basado en inotify nativo, el mecanismo del núcleo que utiliza Linux para los eventos del sistema de archivos.

import { parseSSEStream, type FileWatchSSEEvent } from '@cloudflare/sandbox';

const stream = await sandbox.watch('/workspace/src', {
  recursive: true,
  include: ['*.ts', '*.tsx']
});

for await (const event of parseSSEStream<FileWatchSSEEvent>(stream)) {
  if (event.type === 'modify' && event.path.endsWith('.ts')) {
    await sandbox.exec('npx tsc --noEmit', { cwd: '/workspace' });
  }
}

Esta es una de esas primitivas que cambia silenciosamente lo que los agentes pueden hacer. Un agente que puede observar el sistema de archivos en tiempo real puede participar en los mismos bucles de retroalimentación que un desarrollador humano.

Imagina a un desarrollador (humano) trabajando en su portátil. Hace un git clone de un repositorio, ejecuta npm install, escribe código, envía un PR, luego cierra su portátil mientras espera la revisión del código. Cuando llega el momento de reanudar el trabajo, simplemente vuelve a abrir el portátil y continúa donde lo dejó.

Si un agente quiere replicar este flujo de trabajo en una plataforma de contenedores básica, se encuentra con un inconveniente. ¿Cómo retomas rápidamente lo que habías dejado? Se podría mantener un entorno aislado en funcionamiento, pero luego se pagaría por los procesos inactivos. Podrías empezar desde cero con la imagen del contenedor, pero entonces tendrías que esperar a que se completaran el git clone y el npm install, lo cual lleva bastante tiempo.

Nuestra respuesta son las instantáneas, que se implementarán en las próximas semanas.

Una instantánea conserva el estado completo del disco de un contenedor, la configuración del sistema operativo, las dependencias instaladas, los archivos modificados, los archivos de datos y mucho más. Luego, te permite restaurarlo rápidamente más tarde.

Puedes configurar un Sandbox para que tome instantáneas automáticamente cuando entre en modo de suspensión.

class AgentDevEnvironment extends Sandbox {
  sleepAfter = "5m";
  persistAcrossSessions = {type: "disk"}; // you can also specify individual directories
}

También puedes crear una instantánea mediante programación y restaurarla manualmente. Esto es útil para el trabajo de puntos de control o para bifurcar sesiones. Por ejemplo, si quisieras ejecutar cuatro instancias de un agente en paralelo, podrías arrancar fácilmente cuatro espacios seguros desde el mismo estado.

class AgentDevEnvironment extends Sandbox {}

async forkDevEnvironment(baseId, numberOfForks) {
  const baseInstance = await getSandbox(baseId);
  const snapshotId = await baseInstance.snapshot();

  const forks = Array.from({ length: numberOfForks }, async (_, i) => {
    const newInstance = await getSandbox(`${baseId}-fork-${i}`);
    return newInstance.start({ snapshot: snapshotId });
  });

  await Promise.all(forks);
}

Las instantáneas se almacenan en R2 dentro de tu cuenta, lo que te proporciona durabilidad e independencia de la ubicación. El sistema de alojamiento en caché por niveles de R2 permite restauraciones rápidas en toda la region: planeta Tierra.

En futuras versiones, también se capturará el estado de la memoria en vivo, lo que permitirá que los procesos en ejecución se reanuden exactamente donde se dejaron. Un terminal y un editor se volverán a abrir en el estado exacto en el que se encontraban cuando se cerraron por última vez.

Si te interesa restaurar el estado de la sesión antes de que se activen las instantáneas, puedes utilizar los métodos de copia de seguridad y restauración hoy mismo. Estos también persisten y restauran directorios utilizando R2, pero no son tan eficaces como las verdaderas instantáneas a nivel de máquina virtual. Aunque aún pueden mejorar considerablemente la velocidad con respecto a la recreación ingenua del estado de la sesión.

^{Iniciar un entorno aislado, clonar "axios" e instalarlo con npm lleva 30 segundos. La restauración desde una copia de seguridad tarda dos segundos.}

No te pierdas la publicación de la instantánea oficial.

Desde nuestro lanzamiento inicial, hemos ido aumentando constantemente la capacidad. Los usuarios de nuestro plan de precios estándar ahora pueden ejecutar 15 000 instancias simultáneas del tipo de instancia ligera, 6 000 instancias del tipo básico y más de 1 000 instancias simultáneas más grandes. Ponte en contacto si deseas ejecutar más instancias.

También hemos cambiado nuestro modelo de precios para que el funcionamiento a escala sea más rentable. Los entornos aislados ahora solo cobran por los ciclos de CPU utilizados activamente. Esto significa que no estás pagando por la CPU inactiva mientras tu agente espera que un LLM responda.

Hace nueve meses, lanzamos un entorno aislado que podía ejecutar comandos y acceder a un sistema de archivos. Eso fue suficiente para probar el concepto.

Lo que tenemos ahora es algo totalmente distinto. Hoy en día, un entorno aislado es un entorno de desarrollo completo: un terminal al que se puede conectar un navegador, un intérprete de código con estado persistente, procesos en segundo plano con URL de vista previa en directo, un sistema de archivos que emite eventos de cambio en tiempo real, proxies de salida para la inyección segura de credenciales, y un mecanismo de instantáneas que hace que los arranques en caliente sean casi instantáneos. 

Si sigues por este camino, surge un patrón muy satisfactorio: agentes que realizan un verdadero trabajo de ingeniería. Clona un repositorio, instálalo, ejecuta las pruebas, lee los fallos, edita el código, vuelve a ejecutar las pruebas. Ese tipo de retroalimentación constante que hace que un ingeniero humano sea eficaz — ahora el agente también lo tiene.

Estamos en la versión 0.8.9 del SDK. ¡Empieza hoy mismo!

npm i @cloudflare/sandbox@latest