Gli agenti hanno i propri computer con Sandboxes disponibile al pubblico

Quando abbiamo lanciato Cloudflare Sandboxes lo scorso giugno, la premessa era semplice: gli agenti IA devono sviluppare ed eseguire codice e devono farlo in un posto sicuro.

Se un agente si comporta come uno sviluppatore, ciò significa clonare repository, compilare codice in molti linguaggi, eseguire server di sviluppo e così via. Per fare queste cose in modo efficace, spesso avranno bisogno di un computer completo (e se non ce l'hanno, possono optare per qualcosa di leggero).

Molti sviluppatori stanno mettendo insieme soluzioni utilizzando macchine virtuali o soluzioni di container esistenti, ma ci sono molti problemi complessi da risolvere.

• Burstiness: poiché ogni sessione necessita di una propria sandbox, spesso è necessario avviare rapidamente molte sandbox, ma non si vuole pagare per la potenza di calcolo inattiva in standby.

• Ripristino rapido dello stato: ogni sessione dovrebbe avviarsi rapidamente e riavviarsi rapidamente, riprendendo lo stato precedente.

• Sicurezza: gli agenti devono accedere ai servizi in modo sicuro, ma non ci si può fidare delle credenziali.

• Controllo: deve essere semplice controllare a livello di codice il ciclo di vita della sandbox, eseguire comandi, gestire file e altro ancora.

• Ergonomia: è necessario fornire un'interfaccia semplice affinché sia gli esseri umani che gli agenti possano eseguire operazioni comuni.

Abbiamo dedicato del tempo a risolvere questi problemi in modo che tu non debba farlo. Dal nostro lancio iniziale, abbiamo reso Sandboxes un ambiente ancora migliore per eseguire agenti su larga scala. Abbiamo collaborato con i nostri partner iniziali, come Figma, che eseguono agenti in container con Figma Make:

"Figma Make è stato creato per aiutare costruttori e creatori di ogni livello a passare dall'idea alla produzione, più velocemente." Per raggiungere tale obiettivo, avevamo bisogno di una soluzione infrastrutturale in grado di fornire ambienti di test affidabili e altamente scalabili, dove poter eseguire codice non attendibile scritto da agenti e utenti. Cloudflare Containers è quella soluzione."

- Alex Mullans, IA e piattaforme per sviluppatori presso Figma

Vogliamo rendere Sandbox accessibile a un numero ancora maggiore di grandi organizzazioni, quindi oggi siamo lieti di annunciare che Sandboxes e Cloudflare Container sono entrambi disponibili al pubblico.

Diamo un'occhiata ad alcune delle recenti modifiche a Sandboxes:

• L'iniezione sicura delle credenziali consente di effettuare chiamate autenticate senza che l'agente abbia mai accesso alle credenziali  

• Il supporto PTY offre a te e al tuo agente un vero terminale

• Gli interpreti di codice persistenti al tuo agente un ambiente in cui eseguire codice Python, JavaScript e TypeScript stateful, pronto all'uso.

• Processi in background e URL di anteprima live forniscono un modo semplice per interagire con i server di sviluppo e verificare le modifiche in corso

• Il monitoraggio del filesystem migliora la velocità di iterazione man mano che gli agenti apportano modifiche

• Le istantanee consentono di recuperare rapidamente la sessione di codifica di un agente

• Limiti più elevati e prezzi delle CPU attive ti consentono di distribuire un parco di agenti su larga scala senza pagare per i cicli di CPU inutilizzata

Prima di esaminare alcune delle modifiche recenti, diamo un'occhiata rapida alle nozioni di base.

Una Cloudflare Sandbox è un ambiente persistente e isolato basato su Cloudflare Containers. Hai richiesto una sandbox specificandone il nome. Se è in esecuzione, la ottieni. Se non lo è, viene avviata. Quando è inattiva, si sospende automaticamente e si riattiva quando riceve una richiesta. È facile interagire programmaticamente con la sandbox utilizzando metodi come exec, gitClone, writeFile e altri.

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 });
  },
};

Se fornisci lo stesso ID, le richieste successive possono arrivare a questa stessa sandbox da qualsiasi parte del mondo.

Una delle difficoltà maggiori per i carichi di lavoro agentici è legata all'autenticazione. Spesso è necessario l'intervento di un agente per accedere a servizi privati, ma non ci si può fidare completamente di loro fornendo solo le credenziali. 

Le sandbox risolvono questo problema iniettando le credenziali a livello di rete tramite un proxy di uscita programmabile. Ciò significa che gli agenti della sandbox non hanno mai accesso alle credenziali e puoi personalizzare completamente la logica di autenticazione come meglio credi:

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 });
    }
  }
}

Per un'analisi approfondita del funzionamento, inclusi l'iniezione di credenziali basata sull'identità, la modifica dinamica delle regole e l'integrazione con i binding Workers , leggi il nostro recente post sul blog sull'autenticazione delle sandbox.

I primi sistemi basati su agenti spesso modellavano l'accesso alla shell come un ciclo richiesta-risposta: esegui un comando, attendi l'output, inserisci la trascrizione nel prompt, ripeti. Questo approccio funziona, ma non è così che gli sviluppatori usano effettivamente un terminale. 

Gli esseri umani avviano un processo, osservano il flusso di output in ingresso, lo interrompono, lo ricollegano in seguito e continuano. Anche gli agenti beneficiano di questo stesso meccanismo di feedback.

A febbraio abbiamo rilasciato il supporto PTY, una sessione pseudo-terminale in una sandbox, con proxy su WebSocket, compatibile con xterm.js.

Basta chiamare sandbox.terminal per servire il 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 });
  },
};

E usa il componente aggiuntivo xterm per chiamarlo dal client:

// 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" });

Ciò consente ad agenti e sviluppatori di utilizzare un PTY completo per eseguire il debug di tali sessioni in tempo reale.

Ogni sessione di terminale ottiene la propria shell isolata, la propria directory di lavoro, il proprio ambiente. Aprine quanti ne servono, proprio come faresti sulla tua macchina. L'output viene memorizzato in un buffer lato server, quindi ricollegandosi viene riprodotto ciò che si è perso.

Per l'analisi dei dati, lo scripting e i flussi di lavoro esplorativi, forniamo anche un'astrazione di livello superiore: un contesto di esecuzione del codice persistente.

La parola chiave è "persistente". Molte implementazioni di interpreti di codice eseguono ogni frammento di codice in isolamento, quindi lo stato scompare tra le chiamate. Non è possibile impostare una variabile in un passaggio e leggerla in quello successivo.

Le sandbox ti consentono di creare "contesti" che conservano lo stato. Le variabili e le importazioni persistono tra le chiamate nello stesso modo in cui avverrebbe in un notebook Jupyter:

// 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

Gli agenti sono più utili quando possono creare qualcosa e mostrarlo immediatamente all'utente. Le sandbox supportano processi in background, controlli di prontezza e URL di anteprima. Ciò consente a un agente di avviare un server di sviluppo e condividere un collegamento live senza abbandonare la conversazione.

// 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() e waitForLog(), gli agenti possono mettere in sequenza il lavoro in base a segnali reali provenienti dal programma in esecuzione, invece di affidarsi a congetture. Questo è molto meglio di un'alternativa comune, che di solito è una qualche versione di sleep(2000) seguita da hope.

I moderni cicli di sviluppo sono basati sugli eventi. Salva un file, esegui nuovamente la build. Modifica una configurazione, riavvia il server. Modifica un test, esegui nuovamente la suite.

Abbiamo rilasciato sandbox.watch() a marzo. Questa opzione restituisce un flusso SSE supportato da inotify nativo, il meccanismo del kernel che Linux utilizza per gli eventi del filesystem.

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' });
  }
}

È una di quelle primitive che cambia silenziosamente ciò che gli agenti possono fare. Un agente in grado di osservare il filesystem in tempo reale può partecipare agli stessi cicli di feedback di uno sviluppatore umano.

Immagina uno sviluppatore (umano) che lavora sul proprio laptop. Clonano un repository con git clone, eseguono npm install, scrivono il codice, inviano una richiesta pull e poi chiudono il portatile in attesa della revisione del codice. Quando è il momento di riprendere il lavoro, riaprono semplicemente il laptop e continuano da dove avevano interrotto.

Se un agente desidera replicare questo flusso di lavoro su una piattaforma container semplice, ti imbatti in un intoppo. Come riprendere rapidamente da dove eri rimasto? Potresti mantenere in esecuzione una sandbox, ma poi pagheresti per il calcolo inattivo. Potresti ripartire da zero dall'immagine del container, ma poi dovresti aspettare un lungo git clone e npm install.

La nostra risposta sono le istantanee, che verranno implementate nelle prossime settimane.

Una istantanea conserva lo stato completo del disco di un container, la configurazione del sistema operativo, le dipendenze installate, i file modificati, i file di dati e altro ancora. Quindi ti consente di ripristinarlo rapidamente in un secondo momento.

Puoi configurare una sandbox per eseguire automaticamente l'istantanea quando va in modalità di sospensione.

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

Puoi anche acquisire un'istantanea a livello di codice e ripristinarla manualmente. Questo è utile per salvare i punti di controllo o per creare sessioni fork. Ad esempio, se volessi eseguire quattro istanze di un agente in parallelo, potreste facilmente avviare quattro sandbox dallo stesso stato.

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);
}

Le istantanee vengono archiviate in R2 all'interno del tuo account, offrendoti resistenza e indipendenza dalla posizione. Il sistema di tiered caching di R2 consente ripristini rapidi in tutto il mondo.

Nelle versioni future, verrà acquisito anche lo stato della memoria in tempo reale, consentendo ai processi in esecuzione di riprendere esattamente da dove si erano interrotti. Il terminale e l'editor si riapriranno esattamente nello stato in cui si trovavano al momento della chiusura.

Se sei interessato a ripristinare lo stato della sessione prima che gli snapshot vengano pubblicati, puoi utilizzare i metodi di backup e ripristino oggi stesso. Anche questi metodi mantengono e ripristinano le directory utilizzando R2, ma non sono performanti quanto le istantanee a livello di macchina virtuale. Sebbene possano comunque portare a notevoli miglioramenti in termini di velocità rispetto alla ricreazione ingenua dello stato della sessione.

^{L'avvio di un ambiente sandbox, la clonazione di 'axios' e l'installazione tramite npm richiedono 30 secondi. Il ripristino da un backup richiede due secondi.}

Resta sintonizzato per il rilascio ufficiale dell'istantanea.

Dal nostro lancio iniziale, abbiamo costantemente aumentato la capacità. Gli utenti con il nostro piano tariffario standard possono ora eseguire 15.000 istanze simultanee di tipo lite, 6.000 istanze di base e oltre 1.000 istanze simultanee più grandi. Contattaci per saperne di più!

Abbiamo anche cambiato il nostro modello di prezzo per renderlo più conveniente su larga scala. Le sandbox ora addebitano solo i cicli della CPU utilizzati attivamente. Ciò significa che non pagherai per la CPU inattiva mentre il tuo agente è in attesa della risposta di un LLM.

Nove mesi fa abbiamo distribuito una sandbox in grado di eseguire comandi e accedere a un filesystem. Questo è stato sufficiente per dimostrare il concetto.

Ciò che abbiamo ora è di natura diversa. Oggi una sandbox è un ambiente di sviluppo completo: un terminale a cui è possibile collegare un browser, un interprete di codice con stato persistente, processi in background con URL di anteprima in tempo reale, un file system che emette eventi di modifica in tempo reale, proxy in uscita per l'iniezione sicura delle credenziali e un meccanismo di snapshot che rende gli avvii a caldo quasi istantanei. 

Partendo da questo presupposto, emerge uno schema soddisfacente: agenti che svolgono un vero e proprio lavoro di ingegneria. Clona un repository, installalo, esegui i test, leggi gli errori, modifica il codice, esegui nuovamente i test. Quel tipo di circuito di feedback serrato che rende efficace un ingegnere umano, ora anche l'agente ne beneficia.

Siamo alla versione 0.8.9 dell'SDK. Inizia oggi stesso:

npm i @cloudflare/sandbox@latest