Guide du sandbox natif et du Manifest de l’OpenAI Agents SDK

OpenAI a livré une mise à jour importante de l’Agents SDK le 15 avril 2026, et l’indice révélateur était la ligne d’installation dans l’article de lancement : pip install "openai-agents>=0.14.0" (OpenAI). Cette ligne de version compte. Ce n’était pas un nouveau modèle de prompt ni une énième surcouche de function calling. C’était OpenAI qui faisait passer le travail sur fichiers, l’exécution shell, les patchs, le cycle de vie du sandbox et la description de l’espace de travail au rang de primitives du SDK.

Pour les développeurs qui créent des agents de codage, des agents documentaires, des agents de nettoyage de données ou des bots de maintenance de dépôts, le changement de conception est simple : arrêter de faire reconstruire à chaque équipe le même harnais fragile autour de Docker, des répertoires temporaires, des schémas d’outils, du staging de fichiers et de la logique de retry. Le SDK fournit désormais un harnais natif pour le modèle, une exécution native en sandbox, des outils de système de fichiers, MCP, AGENTS.md, un accès shell, apply_patch et une abstraction Manifest pour décrire des espaces de travail portables.

Le changement : des appels d’outils à un véritable espace de travail

L’Agents SDK d’origine était déjà utile pour l’orchestration : agents, outils, handoffs, garde-fous, traçage. La mise à jour d’avril ajoute la forme d’exécution qui manquait aux agents devant travailler avec des fichiers dans la durée.

OpenAI décrit le SDK mis à jour comme aidant les développeurs à créer des agents capables d’inspecter des fichiers, d’exécuter des commandes, de modifier du code et de travailler sur des tâches de longue haleine dans des environnements sandbox contrôlés (OpenAI). L’expression « espace de travail contrôlé » est la clé. Un agent sérieux qui travaille sur des fichiers a besoin de plus qu’une liste d’outils. Il lui faut un répertoire racine, des entrées montées, des emplacements de sortie, un shell, des permissions, des snapshots et un moyen de reprendre quand le conteneur meurt.

Avant cette mise à jour, une configuration de production typique ressemblait à ceci :

• créer un espace de travail temporaire
• y copier des fichiers
• exposer des outils de lecture, d’écriture, de shell et de patch
• valider les chemins manuellement
• démarrer un sandbox ou un conteneur
• collecter les artefacts
• snapshotter l’état si la tâche dure longtemps
• traduire tout cela en instructions destinées au modèle

Ce code de collage est l’endroit où beaucoup de projets d’agents deviennent discrètement désordonnés. Le nouveau SDK en fait en grande partie une configuration de premier niveau.

L’article de lancement d’OpenAI listait la prise en charge intégrée de Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop et Vercel comme fournisseurs de sandbox, avec aussi une voie « apportez votre propre sandbox » (OpenAI). Cela représente sept fournisseurs hébergés au lancement, plus des chemins de développement local.

Manifest est la couche de portabilité

L’abstraction Manifest est la partie la plus pratique de cette sortie. Elle décrit ce que l’espace de travail du sandbox doit contenir avant que le modèle commence à travailler.

Dans la documentation Python, les Sandbox Agents sont marqués bêta, exigent Python 3.10 ou supérieur et sont présentés comme un moyen de fournir au modèle un espace de travail persistant où il peut rechercher dans des ensembles de documents, modifier des fichiers, exécuter des commandes, générer des artefacts et reprendre depuis un état de sandbox sauvegardé (docs Python de l’OpenAI Agents SDK).

Une forme Python compacte ressemble à ceci :

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())
    ),
)

L’important n’est pas la syntaxe. C’est le contrat. Le Manifest peut décrire des fichiers locaux, des répertoires, des dépôts Git, des fichiers synthétiques, des variables d’environnement, des utilisateurs, des groupes, des répertoires de sortie et des montages de stockage distant. La documentation JavaScript indique que les chemins des entrées Manifest sont relatifs à l’espace de travail, ne peuvent pas être absolus et ne peuvent pas sortir de l’espace de travail avec .., ce qui est exactement le genre de contrainte ennuyeuse que l’on veut voir imposée par le runtime plutôt que mémorisée dans chaque prompt (docs JS de l’OpenAI Agents SDK).

Capacités : shell, système de fichiers, skills, mémoire, compaction

Un SandboxAgent n’est pas simplement un agent normal avec un dossier temporaire. Il embarque des capacités propres au sandbox.

La documentation des concepts JS liste des capacités intégrées, dont shell(), filesystem(), skills(), memory() et compaction() (docs JS de l’OpenAI Agents SDK). Les valeurs par défaut comptent ici : la documentation indique que Capabilities.default() inclut le système de fichiers, le shell et la compaction. Cela signifie que la boucle courante d’un agent de codage n’est plus un empilement de définitions d’outils sur mesure.

La capacité de système de fichiers expose des modifications de fichiers de type patch. La capacité shell expose l’exécution de commandes dans la session sandbox. Les skills permettent de divulguer progressivement des instructions ou procédures spécialisées. La mémoire et la compaction aident les exécutions longues à conserver un état utile sans réinjecter tous les tokens précédents dans le tour suivant.

Cela correspond à la manière dont les bons agents de codage travaillent réellement. Ils inspectent. Ils exécutent une commande. Ils modifient un fichier. Ils exécutent une commande plus ciblée. Ils inspectent le diff. Ils résument ce qui a changé. Si votre harnais traite chaque étape comme un appel API sans rapport avec les autres, le modèle dépense trop d’attention à reconstruire son monde. Une session sandbox donne au modèle un endroit où prendre appui.

AGENTS.md s’intègre aussi naturellement à ce modèle. Le site ouvert AGENTS.md le décrit comme un format Markdown destiné à guider les agents de codage et indique qu’il est utilisé par plus de 60 000 projets open source (AGENTS.md). Ce fichier doit contenir les commandes de build, les instructions de test, les règles de style et les avertissements propres au dépôt. Dans le monde sandbox, AGENTS.md devient un contexte opérationnel local à l’espace de travail plutôt qu’un énorme prompt collé dans chaque tâche.

Python d’abord, TypeScript rattrape son retard

Au lancement, c’était Python d’abord. TechCrunch a rapporté le 15 avril que le nouveau harnais et les capacités de sandbox étaient lancés d’abord en Python, avec une prise en charge de TypeScript prévue plus tard (TechCrunch). PyPI confirme la date : les versions 0.14.0 et 0.14.1 de openai-agents ont été téléversées le 15 avril 2026 (PyPI).

Au 16 juin 2026, la situation pratique est plus équilibrée. La documentation JS officielle inclut désormais les Sandbox Agents en bêta, exige Node.js 22 ou supérieur et montre Manifest, SandboxAgent, UnixLocalSandboxClient, la prise en charge de Docker et des clients de fournisseurs hébergés via @openai/agents-extensions (quickstart JS de l’OpenAI Agents SDK). La documentation JS note aussi que Deno et Bun peuvent fonctionner lorsque la résolution des paquets et les API runtime sont compatibles.

Domaine	Python	TypeScript / JavaScript
Statut au lancement le 15 avril	Première voie prise en charge	Prévu plus tard
Documentation sandbox actuelle	Bêta, Python 3.10+	Bêta, Node.js 22+
Sandbox local	UnixLocalSandboxClient	UnixLocalSandboxClient
Sandbox Docker	openai-agents[docker]	DockerSandboxClient
Fournisseurs hébergés	Pris en charge via les intégrations SDK	Chemins fournisseurs @openai/agents-extensions

Cela ne veut pas dire que les deux écosystèmes sont identiques. Python était la surface de lancement initiale, et de nombreux exemples y arrivent encore en premier. TypeScript dispose désormais d’une surface officielle suffisante pour prototyper de vrais agents sandbox, mais les détails des fournisseurs hébergés, le comportement PTY, les montages et la gestion du cycle de vie exigent encore une lecture attentive backend par backend.

Comment je structurerais aujourd’hui un agent travaillant sur des fichiers

L’erreur est de traiter le sandbox comme une boîte magique de sécurité. C’est une frontière d’exécution, pas une spécification produit. Vous devez toujours concevoir l’espace de travail.

Une structure propre ressemble à ceci :

• repo/ : l’arbre de travail ou le dépôt monté
• task.md : la spécification de tâche que le modèle doit lire en premier
• inputs/ : documents, jeux de données, captures d’écran ou journaux en lecture seule
• output/ : le seul endroit où les artefacts générés finaux doivent aller
• AGENTS.md : instructions de build, de test, de style et de sécurité
• utilisateur sandbox : une identité non-root lorsque le backend la prend en charge
• env Manifest : configuration non secrète persistée par défaut, secrets marqués éphémères

Le Manifest doit décrire les entrées. Les instructions de l’agent doivent décrire le workflow. Le prompt utilisateur doit décrire la tâche ponctuelle. Gardez ces éléments séparés. La documentation JS met explicitement en garde contre le fait de fourrer de longs documents de référence dans instructions lorsqu’ils relèvent du Manifest (docs JS de l’OpenAI Agents SDK).

Pour la production, choisissez le backend en fonction du rayon d’impact, pas du chemin de démonstration. Unix-local convient au développement. Docker est un meilleur choix par défaut lorsque vous avez besoin de répétabilité. Les fournisseurs hébergés ont du sens quand vous avez besoin d’une isolation propre par exécution, d’une exécution distante, de passage à l’échelle ou d’un comportement de snapshot propre au fournisseur. La documentation des clients JS indique que la prise en charge des fournisseurs hébergés varie et que les développeurs doivent consulter la documentation des fournisseurs pour les variables d’environnement, les ports, PTY, snapshots et comportements de nettoyage (clients JS de l’OpenAI Agents SDK).

Lecture de l’écosystème

Cette mise à jour est importante parce qu’elle standardise la forme des agents qui travaillent sur des fichiers. L’industrie avait déjà convergé vers quelques primitives : MCP pour les outils externes, AGENTS.md pour les instructions de dépôt, le shell pour une inspection réelle, les patchs pour des modifications révisables et les sandboxes pour le confinement. L’Agents SDK d’OpenAI assemble désormais ces pièces dans un runtime que les développeurs peuvent réellement composer.

Le point sensible reste les permissions. Un agent sandboxé avec un accès réseau large, des montages inscriptibles, des identifiants longue durée et des instructions vagues peut toujours causer des dégâts. Le Manifest aide parce qu’il rend visibles les entrées de l’espace de travail et les autorisations. Il ne supprime pas le besoin de politiques d’approbation, d’hygiène des secrets, de verrouillage des dépendances et de revue des artefacts.

Le meilleur cas d’usage aujourd’hui n’est pas « l’agent fait tout ». Il est plus étroit et plus précieux : donner au modèle un espace de travail borné, un fichier de tâche clair, des instructions locales au dépôt, des outils shell et patch, et un chemin de vérification explicite. Le laisser travailler comme un ingénieur junior dans un environnement jetable. Puis inspecter le diff.

C’est une abstraction bien plus saine que de bricoler encore un demi-sandbox autour d’une boucle de chat.

Les lecteurs qui veulent essayer ces modèles eux-mêmes peuvent les appeler via onehop avec une API compatible OpenAI en modifiant un seul base_url. C’est moins cher que l’offre de première partie, et les nouveaux comptes reçoivent 10 $ de crédit gratuit sans carte requise : appeler Claude et d’autres modèles sur onehop, ou s’inscrire pour obtenir 10 $ de crédit gratuit.