Artefatti: archiviazione versionata che parla Git

Gli agenti hanno cambiato il nostro modo di pensare al controllo del codice sorgente, ai file system e alla persistenza dello stato. Gli sviluppatori e gli agenti stanno generando più codice che mai: nei prossimi 5 anni verrà scritto più codice che in tutta la storia della programmazione, e questo ha determinato un cambiamento di un ordine di grandezza nella scala dei sistemi necessari per soddisfare questa domanda. Le piattaforme di controllo del codice sorgente stanno incontrando particolari difficoltà in questo contesto: sono state create per soddisfare le esigenze degli esseri umani, non per un aumento di volume di dieci volte dovuto a un sistema automatizzato che non dorme mai, può gestire più problemi contemporaneamente e non si stanca mai.

Riteniamo che ci sia bisogno di una nuova primitiva: un filesystem distribuito e versionato, progettato principalmente per gli agenti e in grado di supportare le tipologie di applicazioni che vengono sviluppate oggi.

Chiamiamo questo sistema Artifacts: un file system versionato che comunica con Git. È possibile creare repository a livello di programmazione, insieme ad agenti, sandbox, Workers o qualsiasi altro paradigma di calcolo, e connettersi ad essi da qualsiasi client Git standard.

Vuoi assegnare un repository a ogni sessione dell'agente? Artifacts può farlo. A ogni istanza sandbox? Sempre Artifacts. Vuoi creare 10.000 fork partendo da un punto di partenza collaudato? Hai indovinato: di nuovo Artifacts. Artifacts espone un'API REST e un'API Workers nativa per la creazione di repository, la generazione di credenziali e i commit in ambienti in cui un client Git non è la soluzione ideale (ad esempio, in qualsiasi funzione serverless).

Artifacts è disponibile in versione beta privata per tutti gli sviluppatori con il piano Workers a pagamento e puntiamo ad aprirlo come beta pubblica entro l'inizio di maggio.

// Create a repo
const repo = await env.AGENT_REPOS.create(name)
// Pass back the token & remote to your agent
return { repo.remote, repo.token }

# Clone it and use it like any regular git remote
$ git clone https://x:${TOKEN}@123def456abc.artifacts.cloudflare.net/git/repo-13194.git

Questo è tutto. Un repository vuoto, pronto all'uso, creato al volo, su cui qualsiasi client Git può operare.

E se vuoi avviare un repository Artifacts da un repository git esistente in modo che il tuo agente possa lavorarci in modo indipendente e inviare modifiche indipendenti, puoi farlo anche con .import():

interface Env {
  ARTIFACTS: Artifacts
}

export default {
  async fetch(request: Request, env: Env) {
    // Import from GitHub
    const { remote, token } = await env.ARTIFACTS.import({
      source: {
        url: "https://github.com/cloudflare/workers-sdk",
        branch: "main",
      },
      target: {
        name: "workers-sdk",
      },
    })

    // Get a handle to the imported repo
    const repo = await env.ARTIFACTS.get("workers-sdk")

    // Fork to an isolated, read-only copy
    const fork = await repo.fork("workers-sdk-review", {
      readOnly: true,
    })

    return Response.json({ remote: fork.remote, token: fork.token })
  },
}

Consulta la documentazione per iniziare, oppure, se vuoi capire come viene utilizzato Artifacts, come è stato creato e come funziona a livello tecnico, continua a leggere.

Gli agenti conoscono Git. Si trova in profondità nei dati di addestramento della maggior parte dei modelli. Il percorso ideale e i casi limite sono ben noti agli agenti, e i modelli (e/o i framework) ottimizzati per il codice sono particolarmente bravi a usare git.

Inoltre, il modello dati di Git non è solo adatto al controllo del codice sorgente, ma a qualsiasi cosa in cui è necessario tenere traccia dello stato, del viaggio nel tempo e rendere persistenti grandi quantità di dati di piccole dimensioni. Codice, configurazione, prompt di sessione e cronologia dell'agente: tutti questi sono elementi ("oggetti") che spesso si desidera memorizzare in piccoli blocchi ("commit") e a cui si desidera poter tornare indietro o ripristinare la versione precedente ("cronologia"). 

Avremmo potuto inventare un protocollo completamente nuovo e su misura... ma poi si sarebbe presentato il problema del bootstrap. I modelli di intelligenza artificiale non lo sanno, quindi devi distribuire competenze, o un'interfaccia a riga di comando, o sperare che gli utenti siano collegati alla tua documentazione MCP... tutto ciò crea attrito. E se potessimo semplicemente fornire agli agenti un URL remoto Git HTTPS autenticato e sicuro, e farli operare come se si trattasse di un repository Git? In questo modo, la soluzione si rivelerebbe piuttosto efficace. Per i client che non utilizzano Git, come ad esempio Cloudflare Worker, una funzione Lambda o un'applicazione Node.js, abbiamo reso disponibile un'API REST e (presto) SDK specifici per ciascun linguaggio. Questi client possono anche utilizzare isomorphic-git, ma in molti casi un'API TypeScript più semplice può ridurre la superficie API necessaria.

L'API Git di Artifacts potrebbe far pensare che serva solo per il controllo della versione, ma in realtà l'API Git e il modello dati sono un modo potente per rendere persistente lo stato in un modo che consente di creare fork, viaggiare nel tempo e confrontare lo stato di qualsiasi dato.

All'interno di Cloudflare, utilizziamo Artifacts per i nostri agenti interni: persistono automaticamente lo stato corrente del filesystem e la cronologia della sessione in un repository Artifacts per sessione. Ciò ci consente di:

• Mantenere lo stato della sandbox senza dover eseguire il provisioning (e mantenere) l'archiviazione a blocchi.

• Condividere le sessioni con altri e consentire loro di tornare indietro nel tempo sia attraverso lo stato della sessione (prompt) che attraverso lo stato del file, indipendentemente dal fatto che siano stati effettuati commit nel repository "effettivo" (controllo del codice sorgente).

• E la cosa migliore: esegui il fork di una sessione da qualsiasi punto, consentendo al nostro team di condividere le sessioni con un collega e di fargliela riprendere da lui. Stai eseguendo il debug di qualcosa e ti serve un secondo parere? Invia un URL ed eseguine il fork. Vuoi sperimentare con un'API? Chiedi a un collega di crearne una copia (fork) e di riprendere da dove avevi interrotto.

Abbiamo anche parlato con team che vogliono usare Artifacts nei casi in cui il protocollo Git non è affatto un requisito, ma la semantica (reverting, cloning, diffing) sono. Memorizzi la configurazione per ciascun cliente come parte del tuo prodotto e desideri la possibilità di ripristinarla? Artifacts può essere una buona rappresentazione.

Siamo entusiasti di vedere i team esplorare i casi d'uso di Artifacts non legati a Git tanto quanto quelli incentrati su Git.

Gli artefatti sono costruiti a partire da Durable Objects. La capacità di creare milioni (o decine di milioni e oltre) di istanze di elaborazione isolate e con stato è intrinseca al funzionamento attuale dei Durable Objects, ed è esattamente ciò di cui avevamo bisogno per supportare milioni di repository Git per namespace.

La Major League Baseball (per la gestione dei tifosi durante le partite in diretta), le lavagne interattive Confluence e il nostro Agents SDK utilizzano Durable Objects su larga scala, quindi stiamo sviluppando questa funzionalità basandoci su un elemento primitivo che abbiamo in produzione da tempo.

Ciò di cui avevamo bisogno, tuttavia, era un'implementazione di Git che potesse essere eseguita su Cloudflare Workers. Doveva essere piccolo, il più completo possibile, estensibile (note, LFS) ed efficiente. Quindi ne abbiamo creato uno in Zig e lo abbiamo compilato in Wasm.

Perché abbiamo usato Zig? Per tre motivi:

1.  L'intero motore del protocollo git è scritto interamente in Zig (senza libc) e compilato in un binario WASM di circa 100 KB (con margine di ottimizzazione). Implementa SHA-1, zlib inflate/deflate, codifica/decodifica delta, analisi dei pacchetti e il protocollo HTTP smart completo di git, tutto da zero, senza dipendenze esterne a parte la libreria standard.

2.  Zig ci offre il controllo manuale sull'allocazione della memoria, aspetto importante in ambienti con risorse limitate come quelli basati su Durable Objects. Il sistema di build Zig ci permette di condividere facilmente il codice tra il runtime WASM (produzione) e le build native (per i test con libgit2 a scopo di verifica della correttezza).

3. Il modulo WASM comunica con l'host JS tramite una sottile interfaccia di callback: 11 funzioni importate dall'host per le operazioni di archiviazione (host_get_object, host_put_object, ecc.) e una per l'output in streaming (host_emit_bytes). Il lato WASM è completamente testabile in isolamento.

Dietro le quinte, Artifacts utilizza anche R2 (per gli snapshot) e KV (per il tracciamento dei token di autenticazione):

^{Come funziona Artifacts (Workers, Durable Objects e WebAssembly)}

Un Worker funge da frontend, gestendo l'autenticazione e l'autorizzazione, le metriche chiave (errori, latenza) e la ricerca al volo di ciascun repository di Artifacts (Durable Object). 

In particolare:

• I file vengono archiviati nel database SQLite del Durable Object sottostante.

  • L'archiviazione di Durable Object ha una dimensione massima di riga di 2 MB, quindi gli oggetti Git di grandi dimensioni vengono suddivisi in blocchi e archiviati su più righe.

  • Utilizziamo l'API KV di sincronizzazione (state.storage.kv)  che è supportata da SQLite alla base.

•  Le entità di dominio (DO) hanno un limite di memoria di circa 128 MB: questo significa che possiamo generarne decine di milioni (sono veloci e leggere), ma dobbiamo operare entro tali limiti.

  • Facciamo ampio uso dello streaming sia nel percorso di recupero che in quello di invio, restituendo direttamente un `ReadableStream` costruito a partire dai blocchi di output WASM grezzi.

  • Evitiamo di calcolare i nostri delta git; invece, i delta grezzi e gli hash di base vengono memorizzati insieme all'oggetto risolto. Al momento del recupero, se il client richiedente possiede già l'oggetto base, Zig emette il delta invece dell'oggetto completo, risparmiando larghezza di banda e memoria.

• Supporto per entrambe le versioni del protocollo Git, v1 e v2.

  • Supportiamo funzionalità quali ls-refs, cloni superficiali (deepen, deepen-since, deepen-relative) e recupero incrementale con negoziazione have/want.

  • Disponiamo di una suite di test completa che include test di conformità con client Git e test di verifica con un server libgit2, progettati per convalidare il supporto del protocollo.

Inoltre, abbiamo il supporto nativo per git-notes. Artifacts è progettato per essere incentrato sull'agente e le note consentono agli agenti di aggiungere note (metadati) agli oggetti Git. Ciò include prompt, attribuzione dell'agente e altri metadati che possono essere letti/scritti dal repository senza modificare gli oggetti stessi.

La maggior parte dei repository non è così grande e Git è progettato per essere estremamente efficiente in termini di archiviazione: la maggior parte dei repository richiede solo pochi secondi per essere clonata al massimo, e questo tempo è dominato dalla configurazione della rete, dall'autenticazione e dal checksum. Nella maggior parte degli scenari con agenti o sandbox, è fattibile: basta clonare il repository all'avvio della sandbox e mettersi al lavoro.

Ma che dire di un repository di diversi gigabyte e/o di repository con milioni di oggetti? Come possiamo clonare rapidamente quel repository, senza bloccare l'agente per minuti e senza consumare risorse di calcolo?

Un framework Web molto diffuso (che pesa 2,4 GB e ha una lunga storia!) richiede circa 2 minuti per essere clonato. Una clonazione superficiale è più veloce, ma non abbastanza da scendere a pochi secondi, e non sempre vogliamo omettere la cronologia (gli agenti la trovano utile).

Possiamo ridurre i tempi di elaborazione dei repository di grandi dimensioni a circa 10-15 secondi, in modo che il nostro agente possa iniziare a lavorare? Ebbene sì, ma con alcuni trucchi.

Nell'ambito del lancio di Artifacts, stiamo rendendo open source ArtifactFS, un driver di filesystem progettato per montare repository Git di grandi dimensioni il più rapidamente possibile, idratando il contenuto dei file al volo invece di bloccarsi durante la clonazione iniziale. È ideale per agenti, sandbox, container e altri casi d'uso in cui il tempo di avvio è critico. Se riesci a ridurre di circa 90-100 secondi il tempo di avvio della sandbox per ogni repository di grandi dimensioni, e gestisci 10.000 di questi job sandbox al mese, avrai risparmiato 2.778 ore di sandbox.

Si può pensare ad ArtifactFS come a un "clone Git asincrono":

• ArtifactFS esegue una clonazione senza blob di un repository Git: recupera la struttura delle cartelle e i riferimenti, ma non il contenuto dei file. Può farlo durante l'avvio della sandbox, consentendo così al tuo agente di entrare in funzione.

• In background, tramite un daemon leggero, inizia a scaricare (idratare) il contenuto dei file contemporaneamente.

• Dà priorità ai file su cui gli agenti in genere vogliono operare per primi: manifest dei pacchetti (package.json, go.mod), file di configurazione e codice, declassando i blob binari (immagini, eseguibili e altri file non di testo) ove possibile, in modo che gli agenti possano scansionare la struttura delle cartelle mentre i file stessi vengono caricati.

• Se un file non è completamente idratato quando l'agente tenta di leggerlo, la lettura si bloccherà finché non lo sarà.

Il filesystem non tenta di "sincronizzare" i file con il repository remoto: con migliaia o milioni di oggetti, questa operazione è in genere molto lenta e, dato che stiamo usando Git, non è necessaria. Il tuo agente deve semplicemente effettuare il commit e il push, come farebbe con qualsiasi repository. Nessuna nuova API da imparare.

È importante sottolineare che ArtifactFS funziona con qualsiasi repository remoto Git, non solo con il nostro Artifacts. Se stai clonando repository di grandi dimensioni da GitHub, GitLab o da un'infrastruttura Git self-hosted, puoi comunque utilizzare ArtifactFS.

La versione che rilasciamo oggi è solo una versione beta e stiamo già lavorando su diverse funzionalità che vedrete implementate nelle prossime settimane:

• Espandendo le metriche disponibili che esponiamo. Oggi pubblichiamo metriche relative al numero di operazioni chiave per namespace, repository e byte memorizzati per repository, in modo che la gestione di milioni di artefatti non sia un'impresa ardua.

• Supporto per le sottoscrizioni agli eventi per eventi a livello di repository, in modo da poter emettere eventi su push, pull, cloni e fork in qualsiasi repository all'interno di un namespace. Questo ti permetterà anche di gestire gli eventi, scrivere webhook e utilizzare tali eventi per notificare gli utenti finali, gestire gli eventi del ciclo di vita all'interno dei tuoi prodotti e/o eseguire processi successivi al rilascio (come CI/CD).

• SDK client nativi in TypeScript, Go e Python per interagire con l'API Artifacts

• API di ricerca a livello di repository e API di ricerca a livello di namespace, ad esempio “trova tutti i repository con un file package.json”. 

Stiamo inoltre pianificando un'API per le build di Workers, che ti permetterà di eseguire processi CI/CD su qualsiasi flusso di lavoro guidato da agenti.

Siamo ancora nelle fasi iniziali di Artifacts, ma vogliamo che la nostra politica dei prezzi funzioni su larga scala per gli agenti: deve essere economicamente vantaggioso avere milioni di repository, i repository inutilizzati (o usati raramente) non devono rappresentare un problema e la nostra politica dei prezzi deve essere in linea con la natura massivamente mono-tenant degli agenti.

Inoltre, non dovresti doverti preoccupare se un repository verrà utilizzato o meno, se è attivo o inattivo e/o se un agente lo riattiverà. Ti addebiteremo lo spazio di archiviazione che consumi e le operazioni (ad esempio cloni, fork, push e pull) rispetto a ciascun repository.

I repository di grandi dimensioni e molto utilizzati costeranno di più rispetto a quelli più piccoli e meno utilizzati, indipendentemente dal fatto che ne abbiate 1.000, 100.000 o 10 milioni.

Inoltre, nel corso della fase beta, introdurremo Artifacts anche nel piano gratuito di Workers (con alcune limitazioni ragionevoli) e forniremo aggiornamenti durante tutta la versione beta qualora i prezzi dovessero cambiare, prima di qualsiasi addebito relativo all'utilizzo.

Artifacts verrà lanciato in versione beta privata e prevediamo che la versione beta pubblica sarà pronta all'inizio di maggio (2026, per essere precisi). Nelle prossime settimane consentiremo l'accesso progressivamente ai clienti e puoi registrare il tuo interesse per la beta privata direttamente.

Nel frattempo, puoi saperne di più su Artifacts come segue:

• Leggendo la guida introduttiva nella documentazione.

• Visitando il dashboard di Cloudflare (Build > Storage e database > Artifacts)

• Leggendo gli esempi di API REST

• Scopri di più su come funziona Artifacts dietro le quinte

Segui il registro delle modifiche per monitorare lo sviluppo della versione beta.