Il tuo agente ha bisogno di un computer, non di un container: ecco @cloudflare/computer

Gli agenti più capaci hanno una cosa semplice in comune: a ciascuno viene fornito un computer personale da utilizzare.

Gli agenti di codifica funzionano in questo modo. Si fornisce loro un filesystem, una shell, strumenti, pacchetti e la capacità di eseguire codice. Esaminano l'ambiente, apportano modifiche, testano il loro lavoro e continuano. Il computer fornisce al modello un modo familiare di interagire con il mondo. Noi di Cloudflare ci impegniamo a fondo per fornire gli elementi base necessari per costruire gli agenti più performanti.

Oggi presentiamo un'anteprima di @cloudflare/computer. Il pacchetto @cloudflare/computer fornisce un ambiente di runtime per l'agente in cui i dettagli e i meccanismi relativi al codice eseguito in un ambiente isolato e a quello eseguito in una sandbox di container sono gestiti dalla piattaforma. Ogni agente dispone di un computer, l'esecuzione è ottimizzata per efficienza e scalabilità.

Riteniamo che, per soddisfare la crescente domanda di potenza di calcolo richiesta dai sistemi agenti, sia necessario esplorare soluzioni che vadano oltre la tradizionale containerizzazione. 

Cambiare il modo in cui vengono creati gli agenti

Negli ultimi sei mesi, abbiamo assistito a una sottile evoluzione di questa storia. All'inizio dell'anno, avviare un container ed eseguire un agente al suo interno era la norma. Negli ultimi mesi, abbiamo assistito a una rapida evoluzione degli strumenti basati su agenti per fornire l'esecuzione di codice in un ambiente sandbox tramite appositi strumenti. Questo separa le mani (la sandbox in cui si lavora) dal cervello (il loop dell'agente).

Indipendentemente da dove passi l'harness, fornire un container a ogni agente rappresenta una sfida: tra tutti i cloud e tutti gli hyperscaler, non c'è neanche lontanamente abbastanza potenza di calcolo al mondo perché ogni azienda possa fornire a ciascun agente dei propri utenti un ambiente di calcolo containerizzato dedicato. Questa soluzione non è scalabile a centinaia di milioni, e poi miliardi, di agenti simultanei. Ecco perché c'è una domanda disperata e disperata da parte dell'industria per la potenza di calcolo delle CPU, non solo per quella delle GPU.

Noi di Cloudflare lavoriamo da tempo a questo problema, creando una primitiva di calcolo più efficiente: gli isolati. Abbiamo fatto quella scommessa controcorrente quasi 10 anni fa, quando abbiamo introdotto Cloudflare Workers. E poi l'abbiamo fatta di nuovo quando abbiamo introdotto Durable Objects quasi sei anni fa. Abbiamo fatto questa scommessa perché gli isolati sono scalabili orizzontalmente all'infinito. Si creano e si distruggono in modo incredibilmente rapido Possono ibernarsi quando l'agente è inattivo, memorizzare il proprio stato e persino avviare i propri isolati per eseguire codice non attendibile. Gli isolati sono il modo migliore per scalare orizzontalmente, e la scalabilità orizzontale è ciò che gli agenti richiedono.

L'anno scorso, abbiamo dato agli isolati la possibilità di avviare i propri ambienti sandbox di container. Fin dal primo giorno, l'architettura di Cloudflare è stata progettata per eseguire l'agente all'interno dell'isolato (in un Durable Object) e richiamare un container collegato su richiesta come strumento. Ciò consente di utilizzare primitive di calcolo più complesse solo quando necessario, ottimizzando prestazioni e costi. I Durable Objects scalano orizzontalmente in modo infinito e il container allegato consente di scalare verticalmente per eseguire qualsiasi compito. È così che costruiamo noi stessi gli agenti e vediamo i nostri clienti realizzare cose incredibili in questo stesso modo.

Ma se consideriamo la necessità di disporre di molteplici primitive di calcolo sottostanti per costruire agenti (isolati e container) e la necessità per i nostri clienti e sviluppatori di combinarli autonomamente nello spazio utente, riteniamo di poter fare di meglio. Riteniamo di poter fornire un'astrazione più semplice.

Ecco perché stiamo avviando questo esperimento distribuendo @cloudflare/computer come libreria open source, per imparare insieme ai nostri clienti che stanno spingendo al limite le capacità di esecuzione di agenti su larga scala.

Un filesystem condiviso tra isolati e container

Il pacchetto @cloudflare/computer parte da una premessa semplice: e se fornissimo a un agente un filesystem preconfigurato, definito in modo dichiarativo, contenente tutto il necessario per l'attività in questione, e una selezione di ambienti di esecuzione per operare su tali file, ognuno con i propri vantaggi e svantaggi in termini di velocità, capacità e costi?

A quanto pare, gli agenti odierni sono sorprendentemente capaci di selezionare l'ambiente più adatto al compito da svolgere. Un processo che deve solo manipolare file, elaborare dati o gestire un repository Git può essere eseguito all'interno di un isolato. Un comando che richiede Linux, npm o un binario nativo può essere eseguito all'interno di un container. Entrambi operano sugli stessi file, che vengono mantenuti sincronizzati con il filesystem di origine.

Il pacchetto @cloudflare/computer fornisce un filesystem robusto che puoi utilizzare con repository Git, bucket di archiviazione o qualsiasi file tu scelga. Fornisce strumenti che consentono di leggere, scrivere e modificare file utilizzando la modalità codice o i comandi bash. Tutte le operazioni sono controllate, monitorate e osservate, dandoti un controllo dettagliato sui cambiamenti che l'agente è autorizzato a eseguire, oltre a una chiara documentazione che mostra cosa ha fatto l'agente.

Come si usa

È possibile creare un'istanza di un'area di lavoro @cloudflare/computer su qualsiasi Durable Object per fornire un filesystem virtuale e un ambiente di runtime per l'esecuzione.

Viene installato tramite npm:

npm install @cloudflare/computer

L'utilizzo principale consiste nel fornire tale filesystem e gli strumenti necessari a un agente. Ad esempio, ecco come creare un'istanza dello spazio di lavoro su un agente basato su @cloudflare/think, destinato alla gestione delle segnalazioni di bug.

import { Think } from "@cloudflare/think";
import { Workspace, type DurableObjectStorageLike } from "@cloudflare/computer";
import { createWorkersAI } from "workers-ai-provider";

export class Agent extends Think {
  override workspaceBash = false;

  override workspace = new Workspace({
    storage: this.ctx.storage,
    useThink: true, // soon will not be needed
  });

  override getModel() {
    return createWorkersAI({ binding: this.env.AI })("@cf/zai-org/glm-5.2");
  }

  override getSystemPrompt() {
    return `
You are a bug triage agent.

Use the project in /workspace/repo to reproduce the bug, inspect the
code, make a focused fix when it is safe, and run verification. In your
final answer, include what you changed, which commands you ran, and
whether verification passed.`;
  }
}

Il pacchetto @cloudflare/computer fornisce diversi backend di esecuzione, oppure è possibile scriverne uno personalizzato. Qui configuriamo un container Cloudflare.

import { Think } from "@cloudflare/think";
import { Workspace, WorkspaceProxy } from "@cloudflare/computer";
import {
  CloudflareContainerBackend,
  withWorkspaceContainer,
} from "@cloudflare/computer/backends/container";

export { WorkspaceProxy };

export class Agent extends withWorkspaceContainer(Think) {
  override workspaceBash = false;

  override workspace = new Workspace({
    storage: this.ctx.storage,
    useThink: true, // soon will not be needed
    backends: [
      new CloudflareContainerBackend({
        container: () => this,
        workspace: {
          binding: "Agent",
          id: this.ctx.id.toString(),
        },
      }),
    ],
  });

  /* Example code truncated for readability... */
}

Mettiamo a disposizione strumenti per la gestione di file, Git e la shell, insieme a strumenti specifici del prodotto, per rispondere ai problemi segnalati.

import { createAITools } from "@cloudflare/computer/tools";
import type { ToolSet } from "ai";
import { replyToIssue } from "./tools/github";

export class Agent extends withWorkspaceContainer(Think) {
  override workspaceBash = false;

  /* Example code truncated for readability... */

  override getTools(): ToolSet {
    return {
      ...createAITools({
        workspace: this.workspace,
        shell: {
          defaultBackend: "container",
          backends: {
            container: {
              description:
                "Cloudflare Container with a full Linux userland: " +
                "npm, node, package managers, test runners, and real " +
                "binaries on $PATH. Use it when a task needs more than " +
                "file manipulation.",
            },
          },
        },
      }),
      replyToIssue,
    };
  }
}

Il modello può utilizzare strumenti durante il ciclo dell'agente, ma è anche possibile utilizzare direttamente l'API dello spazio di lavoro, ad esempio per preparare l'ambiente prima di avviare l'agente.

export class Agent extends withWorkspaceContainer(Think) {
  override workspaceBash = false;

  /* Example code truncated for readability... */

  async startTriage(report: { title: string; body: string; repoUrl: string }) {
    await this.workspace.fs.mkdir("/workspace", { recursive: true });
    await this.workspace.fs.writeFile(
      "/workspace/BUG_REPORT.md",
      `# ${report.title}\n\n${report.body}\n`,
    );

    await this.workspace.git.clone({
      url: report.repoUrl,
      dir: "/workspace/repo",
    });

    return this.submitMessages([
      {
        id: crypto.randomUUID(),
        role: "user",
        parts: [
          {
            type: "text",
            text: [
              `Triage this bug: ${report.title}`,
              "The bug report is in /workspace/BUG_REPORT.md.",
              "The repository is checked out at /workspace/repo.",
            ].join("\n"),
          },
        ],
      },
    ]);
  }
}

Consulta il repository dello spazio di lavoro per ulteriori esempi su come utilizzare i diversi backend e strumenti, incluso un tutorial passo passoche illustra come creare un agente da zero.

Come funziona

L'elemento centrale di @cloudflare/computer è lo spazio di lavoro. Un filesystem virtuale basato su SQLite che può essere popolato da varie origini, tra cui l'archiviazione cloud e i sistemi di controllo versione.

Lo spazio di lavoro supporta runtime di esecuzione opzionali che consentono di eseguire codice direttamente sul file system. Tutti i runtime supportano la stessa interfaccia exec(string, options) e attualmente ne sono forniti due di default (ma è possibile scriverne di propri):

• Un ambiente di runtime basato su isolate che utilizza just-bash per tradurre il codice shell in JavaScript viene eseguito in un worker dinamico. In questo caso, il filesystem è disponibile direttamente tramite i binding dei worker.
• Un runtime per container che utilizza container Cloudflare per fornire un ambiente Linux completo. In questo caso, il filesystem viene fornito tramite un montaggio FUSE (Filesystem in Userspace), che garantisce la disponibilità dei file per il container e la sincronizzazione delle modifiche.

La classe Workspace fornisce un'interfaccia API per manipolare direttamente il filesystem, nonché un wrapper compatibile con node:fs che ne facilita l'utilizzo con librerie JavaScript di terze parti.

Per l'utilizzo con gli agenti, forniamo un toolkit compatibile con l'SDK di intelligenza artificiale che include gli strumenti più comuni: lettura, scrittura, modifica, ls ed esecuzione. Lo strumento exec è un po' particolare perché funziona su diversi runtime accettando un argomento backend. La descrizione dello strumento guida l'agente nella scelta del runtime corretto per l'attività da svolgere: un backend di lavoro veloce ed economico oppure un container completo di tutte le funzionalità. Nei nostri test, i modelli di frontiera si sono dimostrati molto efficaci nel prendere la decisione corretta e nel ricorrere all'utilizzo dei container solo quando necessario.

E poi?

Qui in Cloudflare stiamo già notando che gli agenti utilizzano esclusivamente gli isolati per creare, testare e distribuire applicazioni JavaScript con strumenti moderni, generare documentazione personalizzata per ciascuno dei nostri clienti e utilizzare i browser web per eseguire attività complesse.

Il nostro obiettivo con @cloudflare/computer è fornire un agente con un runtime in cui un container sia necessario per meno del 10% del suo lavoro, e le attività di programmazione, la manipolazione audio/video e la creazione di documenti possano essere gestite dagli isolati. 

Prova subito l'anteprima: non vediamo l'ora di sapere cosa ne pensi.