Guida alla sandbox nativa e al Manifest di OpenAI Agents SDK

OpenAI ha rilasciato l’importante aggiornamento di Agents SDK il 15 aprile 2026, e l’indizio era la riga di installazione nel post di lancio: pip install "openai-agents>=0.14.0" (OpenAI). Quella riga di versione conta. Non era un nuovo template di prompt o l’ennesimo wrapper per function calling. Era OpenAI che spostava lavoro sui file, lavoro da shell, patching, ciclo di vita della sandbox e descrizione del workspace dentro primitive a livello di SDK.

Per gli sviluppatori che creano coding agent, agent per documenti, agent di pulizia dati o bot di manutenzione repo, il cambio di design è semplice: smettere di far ricostruire a ogni team lo stesso fragile harness attorno a Docker, directory temporanee, schemi di tool, staging dei file e logica di retry. Ora l’SDK offre un harness nativo per il modello, esecuzione nativa in sandbox, tool per il filesystem, MCP, AGENTS.md, accesso shell, apply_patch e un’astrazione Manifest per descrivere workspace portabili.

Il cambiamento: dalle chiamate ai tool a un vero workspace

L’Agents SDK originale era già utile per l’orchestrazione: agent, tool, handoff, guardrail, tracing. L’aggiornamento di aprile aggiunge la forma runtime mancante per gli agent che devono lavorare con i file nel tempo.

OpenAI descrive l’SDK aggiornato come un aiuto per gli sviluppatori che vogliono creare agent in grado di ispezionare file, eseguire comandi, modificare codice e lavorare su task di lungo respiro dentro ambienti sandbox controllati (OpenAI). L’espressione “workspace controllato” è la chiave. Un agent serio che lavora sui file ha bisogno di più di un elenco di tool. Ha bisogno di una directory radice, input montati, posizioni di output, una shell, permessi, snapshot e un modo per riprendere quando il container muore.

Prima di questo aggiornamento, una configurazione di produzione tipica assomigliava a questa:

• creare un workspace temporaneo
• copiarci dentro i file
• esporre tool di lettura, scrittura, shell e patch
• validare manualmente i path
• avviare una sandbox o un container
• raccogliere gli artefatti
• fare snapshot dello stato se il job dura a lungo
• tradurre tutto questo in istruzioni rivolte al modello

Quel codice collante è il punto in cui molti progetti agent diventano silenziosamente disordinati. Il nuovo SDK trasforma gran parte di tutto ciò in configurazione di prima classe.

Il post di lancio di OpenAI elencava il supporto integrato per Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop e Vercel come provider sandbox, oltre a un percorso “bring your own sandbox” (OpenAI). Sono sette provider hosted al lancio, più percorsi per lo sviluppo locale.

Manifest è il livello di portabilità

L’astrazione Manifest è la parte più pratica del rilascio. Descrive cosa deve contenere il workspace della sandbox prima che il modello inizi a lavorare.

Nella documentazione Python, i Sandbox Agents sono contrassegnati come beta, richiedono Python 3.10 o superiore e vengono presentati come un modo per dare al modello un workspace persistente in cui può cercare in insiemi di documenti, modificare file, eseguire comandi, generare artefatti e riprendere da uno stato sandbox salvato (documentazione Python di OpenAI Agents SDK).

Una forma Python compatta assomiglia a questa:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Repo maintainer",
    model="gpt-5.5",
    instructions="Read repo/task.md, edit with apply_patch, then run the targeted test.",
    default_manifest=Manifest(entries={"repo": LocalDir(src="./repo")}),
)

result = await Runner.run(
    agent,
    "Fix the failing test and summarize the change.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

La parte importante non è la sintassi. È il contratto. Il Manifest può descrivere file locali, directory, repo Git, file sintetici, variabili d’ambiente, utenti, gruppi, directory di output e mount di storage remoto. La documentazione JavaScript dice che i path delle entry del Manifest sono relativi al workspace, non possono essere assoluti e non possono uscire dal workspace con ..: esattamente il tipo di vincolo noioso che vuoi sia applicato dal runtime, invece di doverlo ricordare in ogni prompt (documentazione JS di OpenAI Agents SDK).

Capability: shell, filesystem, skill, memoria, compaction

Un SandboxAgent non è solo un agent normale con una cartella temporanea. Porta con sé capability specifiche della sandbox.

La documentazione JS sui concetti elenca capability integrate tra cui shell(), filesystem(), skills(), memory() e compaction() (documentazione JS di OpenAI Agents SDK). Qui i default contano: la documentazione afferma che Capabilities.default() include filesystem, shell e compaction. Questo significa che il loop comune di un coding agent non è più un mucchio di definizioni di tool su misura.

La capability filesystem espone modifiche ai file in stile patch. La capability shell espone l’esecuzione di comandi dentro la sessione sandbox. Le skill permettono di rivelare progressivamente istruzioni o procedure specializzate. Memoria e compaction aiutano le esecuzioni più lunghe a conservare stato utile senza reinserire ogni token precedente nel turno successivo.

Questo corrisponde a come lavorano davvero i coding agent più forti. Ispezionano. Eseguono un comando. Modificano un file. Eseguono un comando più piccolo. Ispezionano il diff. Riassumono cosa è cambiato. Se il tuo harness tratta ogni passo come una chiamata API scollegata, il modello spende troppa attenzione a ricostruire il proprio mondo. Una sessione sandbox dà al modello un punto d’appoggio.

Anche AGENTS.md si inserisce naturalmente in questo modello. Il sito aperto AGENTS.md lo descrive come un formato Markdown per guidare i coding agent e dice che viene usato da più di 60.000 progetti open-source (AGENTS.md). Quel file dovrebbe contenere comandi di build, istruzioni di test, regole di stile e avvisi specifici del repo. Nel mondo sandbox, AGENTS.md diventa contesto operativo locale al workspace, invece di un enorme prompt incollato in ogni task.

Python-first, TypeScript in recupero

Al lancio, l’approccio era Python-first. TechCrunch ha riportato il 15 aprile che il nuovo harness e le capability sandbox sarebbero stati lanciati prima in Python, con il supporto TypeScript previsto in seguito (TechCrunch). PyPI conferma la data: le versioni 0.14.0 e 0.14.1 di openai-agents sono state caricate il 15 aprile 2026 (PyPI).

Al 16 giugno 2026, il quadro pratico è più bilanciato. La documentazione JS ufficiale ora include i Sandbox Agents in beta, richiede Node.js 22 o superiore e mostra Manifest, SandboxAgent, UnixLocalSandboxClient, supporto Docker e client per provider hosted tramite @openai/agents-extensions (quickstart JS di OpenAI Agents SDK). La documentazione JS nota anche che Deno e Bun possono funzionare quando la risoluzione dei package e le API runtime sono compatibili.

Area	Python	TypeScript / JavaScript
Stato al lancio il 15 aprile	Primo percorso supportato	Previsto in seguito
Documentazione sandbox attuale	Beta, Python 3.10+	Beta, Node.js 22+
Sandbox locale	UnixLocalSandboxClient	UnixLocalSandboxClient
Sandbox Docker	openai-agents[docker]	DockerSandboxClient
Provider hosted	Supportati tramite integrazioni SDK	Percorsi provider @openai/agents-extensions

Questo non significa che i due ecosistemi siano identici. Python è stata la superficie di lancio originale e molti esempi arrivano ancora lì per primi. TypeScript ora ha abbastanza superficie ufficiale per prototipare veri sandbox agent, ma dettagli sui provider hosted, comportamento PTY, mount e supporto al ciclo di vita richiedono ancora una lettura attenta backend per backend.

Come strutturerei oggi un agent che lavora sui file

L’errore è trattare la sandbox come una scatola di sicurezza magica. È un confine runtime, non una specifica di prodotto. Devi comunque progettare il workspace.

Una struttura pulita assomiglia a questa:

• repo/: il working tree o repository montato
• task.md: la specifica del task che il modello deve leggere per prima
• inputs/: documenti, dataset, screenshot o log in sola lettura
• output/: l’unico posto in cui dovrebbero finire gli artefatti finali generati
• AGENTS.md: istruzioni di build, test, stile e sicurezza
• utente sandbox: un’identità non-root dove il backend lo supporta
• env del Manifest: configurazione non segreta persistita di default, segreti marcati come effimeri

Il Manifest dovrebbe descrivere gli input. Le istruzioni dell’agent dovrebbero descrivere il workflow. Il prompt dell’utente dovrebbe descrivere il task una tantum. Tieni separate queste cose. La documentazione JS avverte esplicitamente di non infilare materiale di riferimento lungo in instructions quando appartiene al Manifest (documentazione JS di OpenAI Agents SDK).

Per la produzione, scegli il backend in base al blast radius, non al percorso demo. Unix-local va bene per lo sviluppo. Docker è un default migliore quando ti serve ripetibilità. I provider hosted hanno senso quando ti servono isolamento pulito per ogni run, esecuzione remota, scaling o comportamento di snapshot specifico del provider. La documentazione JS sui client afferma che il supporto ai provider hosted varia e che gli sviluppatori dovrebbero controllare la documentazione del provider per variabili d’ambiente, porte, PTY, snapshot e comportamento di cleanup (client JS di OpenAI Agents SDK).

Lettura dell’ecosistema

Questo aggiornamento è importante perché standardizza la forma degli agent che lavorano sui file. Il settore è già convergente su alcune primitive: MCP per tool esterni, AGENTS.md per istruzioni di repo, shell per ispezione reale, patching per modifiche revisionabili e sandbox per il contenimento. OpenAI Agents SDK ora impacchetta questi pezzi in un runtime che gli sviluppatori possono davvero comporre.

Lo spigolo vivo resta quello dei permessi. Un agent sandboxed con rete ampia, mount scrivibili, credenziali longeve e istruzioni vaghe può comunque fare danni. Il Manifest aiuta perché rende visibili input e grant del workspace. Non elimina la necessità di policy di approvazione, igiene dei segreti, pinning delle dipendenze e revisione degli artefatti.

Il caso d’uso migliore oggi non è “l’agent fa tutto”. È più stretto e più prezioso: dai al modello un workspace delimitato, un file di task chiaro, istruzioni locali al repo, tool shell e patch, e un percorso di verifica esplicito. Lascialo lavorare come un junior engineer in un ambiente usa e getta. Poi ispeziona il diff.

È un’astrazione molto più sana che costruire a mano l’ennesima mezza sandbox attorno a un loop di chat.

I lettori che vogliono provare questi modelli direttamente possono chiamarli tramite onehop con un’API compatibile con OpenAI cambiando un solo base_url. È più economico del provider first-party, e i nuovi account ricevono $10 di credito gratuito senza carta richiesta: chiama Claude e altri modelli su onehop, oppure registrati per ottenere $10 di credito gratuito.