Leitfaden zu nativer Sandbox und Manifest im OpenAI Agents SDK

OpenAI hat das wichtige Update des Agents SDK am 15. April 2026 veröffentlicht, und der Hinweis darauf war die Installationszeile im Launch-Post: pip install "openai-agents>=0.14.0" (OpenAI). Diese Versionszeile ist wichtig. Das war kein neues Prompt-Template und auch kein weiterer Function-Calling-Wrapper. OpenAI hat Dateiarbeit, Shell-Arbeit, Patching, Sandbox-Lebenszyklus und Workspace-Beschreibung zu SDK-Primitiven gemacht.

Für Entwickler, die Coding-Agenten, Dokumenten-Agenten, Datenbereinigungs-Agenten oder Bots zur Repo-Wartung bauen, ist der Designwechsel einfach: Nicht jedes Team sollte denselben fragilen Harness rund um Docker, temporäre Verzeichnisse, Tool-Schemas, File-Staging und Retry-Logik neu bauen müssen. Das SDK bietet jetzt einen modellnativen Harness, sandbox-native Ausführung, Dateisystem-Tools, MCP, AGENTS.md, Shell-Zugriff, apply_patch und eine Manifest-Abstraktion zur Beschreibung portabler Workspaces.

Die Veränderung: von Tool-Calls zu einem echten Workspace

Das ursprüngliche Agents SDK war bereits für Orchestrierung nützlich: Agenten, Tools, Handoffs, Guardrails, Tracing. Das April-Update ergänzt die fehlende Runtime-Form für Agenten, die über längere Zeit mit Dateien arbeiten müssen.

OpenAI beschreibt das aktualisierte SDK als Hilfe für Entwickler beim Bau von Agenten, die Dateien inspizieren, Befehle ausführen, Code bearbeiten und in kontrollierten Sandbox-Umgebungen an langfristigen Aufgaben arbeiten können (OpenAI). Der Ausdruck „kontrollierter Workspace“ ist der Schlüssel. Ein ernstzunehmender dateibasierter Agent braucht mehr als eine Liste von Tools. Er braucht ein Root-Verzeichnis, gemountete Eingaben, Ausgabeorte, eine Shell, Berechtigungen, Snapshots und eine Möglichkeit, fortzufahren, wenn der Container stirbt.

Vor diesem Update sah ein typisches Produktions-Setup so aus:

• einen temporären Workspace erstellen
• Dateien hineinkopieren
• Lese-, Schreib-, Shell- und Patch-Tools bereitstellen
• Pfade manuell validieren
• eine Sandbox oder einen Container starten
• Artefakte einsammeln
• Zustand per Snapshot sichern, wenn der Job lange läuft
• all das in modellseitige Anweisungen übersetzen

Dieser Glue Code ist der Grund, warum viele Agentenprojekte im Stillen unübersichtlich werden. Das neue SDK macht vieles davon zu First-Class-Konfiguration.

OpenAIs Launch-Post nannte integrierte Unterstützung für Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop und Vercel als Sandbox-Anbieter, außerdem einen „Bring your own sandbox“-Pfad (OpenAI). Das sind sieben gehostete Anbieter zum Start, plus lokale Entwicklungspfade.

Manifest ist die Portabilitätsschicht

Die Manifest-Abstraktion ist der praktischste Teil des Releases. Sie beschreibt, was der Sandbox-Workspace enthalten soll, bevor das Modell mit der Arbeit beginnt.

In der Python-Dokumentation sind Sandbox Agents als Beta markiert, erfordern Python 3.10 oder höher und werden als Möglichkeit vorgestellt, dem Modell einen persistenten Workspace zu geben, in dem es Dokumentsammlungen durchsuchen, Dateien bearbeiten, Befehle ausführen, Artefakte erzeugen und aus gespeichertem Sandbox-Zustand fortfahren kann (OpenAI Agents SDK Python docs).

Eine kompakte Python-Form sieht so aus:

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

Wichtig ist nicht die Syntax. Wichtig ist der Vertrag. Das Manifest kann lokale Dateien, Verzeichnisse, Git-Repos, synthetische Dateien, Umgebungsvariablen, Benutzer, Gruppen, Ausgabeverzeichnisse und Remote-Storage-Mounts beschreiben. Die JavaScript-Dokumentation sagt, dass Manifest-Eintragspfade relativ zum Workspace sind, nicht absolut sein dürfen und den Workspace nicht mit .. verlassen können. Genau solche langweiligen Einschränkungen will man von der Runtime durchsetzen lassen, statt sie in jedem Prompt erneut im Kopf behalten zu müssen (OpenAI Agents SDK JS docs).

Fähigkeiten: Shell, Dateisystem, Skills, Memory, Kompaktierung

Ein SandboxAgent ist nicht einfach ein normaler Agent mit temporärem Ordner. Er bringt sandbox-spezifische Fähigkeiten mit.

Die JS-Konzeptdokumentation listet integrierte Fähigkeiten wie shell(), filesystem(), skills(), memory() und compaction() auf (OpenAI Agents SDK JS docs). Defaults sind hier wichtig: Die Dokumentation sagt, dass Capabilities.default() Dateisystem, Shell und Kompaktierung enthält. Das bedeutet, dass die gängige Coding-Agent-Schleife nicht länger ein Haufen maßgeschneiderter Tool-Definitionen ist.

Die Dateisystem-Fähigkeit stellt patch-artige Dateiänderungen bereit. Die Shell-Fähigkeit stellt Befehlsausführung innerhalb der Sandbox-Session bereit. Skills ermöglichen es, spezialisierte Anweisungen oder Abläufe schrittweise offenzulegen. Memory und Kompaktierung helfen längeren Läufen, nützlichen Zustand zu behalten, ohne jedes vorherige Token wieder in den nächsten Turn zu stopfen.

Das entspricht der tatsächlichen Arbeitsweise starker Coding-Agenten. Sie inspizieren. Sie führen einen Befehl aus. Sie bearbeiten eine Datei. Sie führen einen kleineren Befehl aus. Sie inspizieren den Diff. Sie fassen zusammen, was sich geändert hat. Wenn dein Harness jeden Schritt als unabhängigen API-Call behandelt, verbraucht das Modell zu viel Aufmerksamkeit darauf, seine Welt zu rekonstruieren. Eine Sandbox-Session gibt dem Modell einen Ort, an dem es stehen kann.

AGENTS.md passt ebenfalls natürlich in dieses Modell. Die offene AGENTS.md-Website beschreibt es als Markdown-Format zur Anleitung von Coding-Agenten und sagt, dass es von mehr als 60.000 Open-Source-Projekten verwendet wird (AGENTS.md). Diese Datei sollte Build-Befehle, Testanweisungen, Stilregeln und repo-spezifische Warnungen enthalten. In der Sandbox-Welt wird AGENTS.md zu workspace-lokalem Arbeitskontext statt zu einem riesigen Prompt, der in jede Aufgabe kopiert wird.

Python zuerst, TypeScript holt auf

Zum Launch war dies Python-first. TechCrunch berichtete am 15. April, dass der neue Harness und die Sandbox-Fähigkeiten zuerst in Python starten würden, mit später geplanter TypeScript-Unterstützung (TechCrunch). PyPI bestätigt das Datum: Die Versionen 0.14.0 und 0.14.1 von openai-agents wurden am 15. April 2026 hochgeladen (PyPI).

Stand 16. Juni 2026 ist das praktische Bild ausgewogener. Die offiziellen JS-Dokumente enthalten nun Beta-Sandbox-Agents, erfordern Node.js 22 oder höher und zeigen Manifest, SandboxAgent, UnixLocalSandboxClient, Docker-Unterstützung und gehostete Provider-Clients über @openai/agents-extensions (OpenAI Agents SDK JS quickstart). Die JS-Dokumente weisen außerdem darauf hin, dass Deno und Bun funktionieren können, wenn Paketauflösung und Runtime-APIs kompatibel sind.

Bereich	Python	TypeScript / JavaScript
Launch-Status am 15. April	Zuerst unterstützter Pfad	Für später geplant
Aktuelle Sandbox-Dokumente	Beta, Python 3.10+	Beta, Node.js 22+
Lokale Sandbox	UnixLocalSandboxClient	UnixLocalSandboxClient
Docker-Sandbox	openai-agents[docker]	DockerSandboxClient
Gehostete Anbieter	Über SDK-Integrationen unterstützt	Anbieterpfade über @openai/agents-extensions

Das bedeutet nicht, dass die beiden Ökosysteme identisch sind. Python war die ursprüngliche Launch-Oberfläche, und viele Beispiele landen dort weiterhin zuerst. TypeScript hat inzwischen genug offizielle Oberfläche, um echte Sandbox-Agenten zu prototypisieren, aber Details zu gehosteten Anbietern, PTY-Verhalten, Mounts und Lebenszyklusunterstützung müssen weiterhin pro Backend sorgfältig gelesen werden.

Wie ich heute einen dateibasierten Agenten strukturieren würde

Der Fehler besteht darin, die Sandbox als magische Sicherheitsbox zu behandeln. Sie ist eine Runtime-Grenze, keine Produktspezifikation. Du musst den Workspace weiterhin entwerfen.

Eine saubere Struktur sieht so aus:

• repo/: der Working Tree oder das gemountete Repository
• task.md: die Aufgabenbeschreibung, die das Modell zuerst lesen muss
• inputs/: schreibgeschützte Dokumente, Datensätze, Screenshots oder Logs
• output/: der einzige Ort, an dem finale generierte Artefakte abgelegt werden sollten
• AGENTS.md: Build-, Test-, Stil- und Sicherheitsanweisungen
• Sandbox-Benutzer: eine Nicht-Root-Identität, sofern das Backend sie unterstützt
• Manifest-Env: nicht geheime Konfiguration, standardmäßig persistiert; Secrets als ephemer markiert

Das Manifest sollte Eingaben beschreiben. Die Agentenanweisungen sollten den Workflow beschreiben. Der Nutzer-Prompt sollte die einmalige Aufgabe beschreiben. Halte diese Dinge getrennt. Die JS-Dokumentation warnt ausdrücklich davor, langes Referenzmaterial in instructions zu stopfen, wenn es ins Manifest gehört (OpenAI Agents SDK JS docs).

Für die Produktion sollte das Backend anhand des potenziellen Schadensradius gewählt werden, nicht anhand des Demo-Pfads. Unix-local ist für die Entwicklung in Ordnung. Docker ist ein besserer Standard, wenn Wiederholbarkeit wichtig ist. Gehostete Anbieter sind sinnvoll, wenn du saubere Isolation pro Lauf, Remote-Ausführung, Skalierung oder anbieterspezifisches Snapshot-Verhalten brauchst. Die JS-Clients-Dokumentation sagt, dass die Unterstützung gehosteter Anbieter variiert und Entwickler die Anbieter-Dokumentation zu Umgebungsvariablen, Ports, PTY, Snapshots und Cleanup-Verhalten prüfen sollten (OpenAI Agents SDK JS clients).

Einordnung des Ökosystems

Dieses Update ist wichtig, weil es die Form dateibasierter Agenten standardisiert. Die Branche hat sich bereits auf einige Primitive zubewegt: MCP für externe Tools, AGENTS.md für Repo-Anweisungen, Shell für echte Inspektion, Patching für überprüfbare Änderungen und Sandboxes zur Eingrenzung. OpenAIs Agents SDK bündelt diese Teile jetzt in einer Runtime, die Entwickler tatsächlich zusammensetzen können.

Die scharfe Kante bleiben Berechtigungen. Ein sandboxed Agent mit breitem Netzwerkzugriff, beschreibbaren Mounts, langlebigen Zugangsdaten und vagen Anweisungen kann weiterhin Schaden anrichten. Das Manifest hilft, weil es Workspace-Eingaben und Freigaben sichtbar macht. Es ersetzt nicht die Notwendigkeit von Approval-Policies, Secret-Hygiene, Dependency-Pinning und Artefaktprüfung.

Der beste Anwendungsfall heute ist nicht „Agent macht alles“. Er ist enger und wertvoller: Gib dem Modell einen begrenzten Workspace, eine klare Aufgabendatei, repo-lokale Anweisungen, Shell- und Patch-Tools sowie einen expliziten Verifikationspfad. Lass es wie ein Junior Engineer in einer wegwerfbaren Umgebung arbeiten. Inspiziere danach den Diff.

Das ist eine deutlich gesündere Abstraktion, als erneut eine halbe Sandbox um eine Chat-Schleife herum selbst zu bauen.

Leser, die diese Modelle praktisch ausprobieren möchten, können sie über onehop mit einer OpenAI-kompatiblen API aufrufen, indem sie ein einziges base_url ändern. Das ist günstiger als direkt beim Anbieter, und neue Accounts erhalten $10 Gratisguthaben ohne Kreditkarte: Claude und andere Modelle über onehop aufrufen oder für $10 Gratisguthaben registrieren.