OpenAI Agents SDK Sandbox 2026: Abnahme vor dem Start

Ein erfolgreicher Sandbox-Lauf beweist nur, dass ein einzelner Ablauf funktioniert. Die offizielle Sandbox-Dokumentation beschreibt Sandbox Agents weiterhin als Beta; API, Standardeinstellungen und unterstützte Fähigkeiten können sich vor der allgemeinen Verfügbarkeit ändern. Gewinner der Abnahme ist deshalb nicht der schnellste Demo-Lauf, sondern die Kombination aus reproduzierbarer Sandbox und belegter Rückfallstrategie. Für den Start müssen sechs Schranken nacheinander bestanden werden: Arbeitsbereich, deterministische Orchestrierung, reale Integration, Rechte, Wiederherstellung und Rollback. Eine isolierte Cloud-Mac-Umgebung kommt erst hinzu, wenn macOS-Werkzeuge, parallele Tests oder die Reproduzierbarkeit dies tatsächlich verlangen.

Für wen dieser Leitfaden gedacht ist: Für Entwickler, die ein SandboxAgent-Beispiel bereits ausgeführt haben, aber noch keine Freigabeschwelle besitzen. Für Plattformingenieure, die Datei-, Befehls-, Netzwerk- und Geheimnisgrenzen prüfen müssen. Und für technische Leiter, die zwischen lokalem Rechner, Container und Cloud-Mac-Testumgebung entscheiden.

Zuletzt aktualisiert am 26.08.2026; die Aussagen wurden gegen die offiziellen Dokumentationen zu Sandbox Agents, SandboxRunConfig, Tests und Tracing geprüft. Der Beta-Status ist keine Zusage für einen stabilen Produktionsumfang.

Die Abnahme beginnt mit einem eingefrorenen Arbeitsbereich

Der häufigste Fehler liegt nicht im Agent-Code. Er liegt in einem Arbeitsbereich, der auf dem Entwicklerrechner „zufällig“ vollständig ist. Dort liegen möglicherweise Konfigurationsdateien, vorinstallierte Werkzeuge, SSH-Schlüssel oder bereits erzeugte Artefakte. Ein neuer Lauf wirkt erfolgreich, obwohl der Agent stillschweigend auf diese Umgebung zugreift.

Vor dem ersten Test wird deshalb ein Workspace-Vertrag erstellt. Dieser Vertrag ist kein allgemeiner Sicherheitstext, sondern eine konkrete Liste:

• Welche Dateien darf der Agent lesen?
• Welche Verzeichnisse darf er verändern?
• Wo dürfen neue Artefakte entstehen?
• Welche Befehle sind für die Aufgabe notwendig?
• Welche Netzwerkziele sind erlaubt?
• Welche Umgebungsvariablen werden benötigt?
• Welche Pfade, Zugangsdaten und Host-Verzeichnisse sind ausdrücklich verboten?

Der Vertrag sollte mit einem versionierten Manifest verbunden werden. Zusätzlich werden die erwartete Laufzeitidentität, die verfügbaren Werkzeuge, die Einbindung des Arbeitsbereichs und die Konfiguration in SandboxRunConfig festgehalten. Die Referenz zu SandboxRunConfig ist dabei die maßgebliche Quelle für die aktuell verfügbaren Konfigurationsgrenzen.

Die Abnahme erhält erst dann Aussagekraft, wenn die Umgebung wiederholbar erzeugt werden kann. Ein leerer Workspace ist ein wichtiger Gegencheck. Wenn der Agent nur deshalb startet, weil im lokalen Verzeichnis eine nicht dokumentierte Datei liegt, ist das kein „kleiner Unterschied“, sondern ein Blocker für die Freigabe.

Freigabe: Manifest, Identität, erlaubte Pfade und benötigte Werkzeuge sind versioniert.
Ergänzende Prüfung: Ein neuer Lauf ist möglich, aber einzelne Abhängigkeiten sind noch nicht vollständig dokumentiert.
Blockade: Ein Agent erreicht Pfade, Dateien oder Zugangsdaten außerhalb des Vertrags oder benötigt manuelle Änderungen auf dem Host.

Die Orchestrierung wird ohne echte Ausführung geprüft

Im zweiten Abschnitt wird bewusst noch keine Aussage über Dateisystem-Isolation oder Prozessgrenzen getroffen. Zuerst muss feststehen, dass die SDK-Orchestrierung selbst korrekt reagiert. Dafür werden deterministische Testwerkzeuge eingesetzt, die Modellantworten und Sandbox-Aktionen kontrolliert vorgeben. Die offizielle Testanleitung für das Agents SDK beschreibt diesen Ansatz und trennt die Ablaufprüfung von der realen Ausführung.

Das Testset sollte mindestens diese Pfade enthalten:

1. Ein Werkzeugaufruf erhält gültige Parameter und liefert ein erwartetes Ergebnis.
2. Ein Befehl schlägt fehl und erzeugt den vorgesehenen Fehlerpfad.
3. Eine Datei fehlt, ohne dass der Agent daraus einen falschen Erfolg ableitet.
4. Ein Werkzeug liefert ein unerwartetes oder unvollständiges Ergebnis.
5. Ein Wiederholungsversuch wird ausgelöst, begrenzt oder korrekt beendet.
6. Der Ablauf endet vorzeitig und hinterlässt einen eindeutig beschriebenen Status.

Die Testfälle prüfen nicht nur den finalen Text. Entscheidend sind die Übergänge: Wird nach einem fehlgeschlagenen Befehl trotzdem ein Erfolg gemeldet? Wird ein nicht vorhandener Pfad erneut und ohne neue Information aufgerufen? Wird ein Abbruch als abgeschlossen gespeichert? Werden Werkzeugparameter vor dem Aufruf validiert?

Mit scripted_sandbox_session lässt sich eine vorhersehbare Sandbox-Sitzung für solche Tests nachbilden. Die API-Beschreibung von scripted_sandbox_session sollte vor der Implementierung geprüft werden, da sich Beta-Schnittstellen ändern können.

Diese Phase hat eine klare Grenze: Ein bestandener deterministischer Test beweist keine echte Isolation. Er zeigt, dass Routing, Parameter, Fehlerbehandlung und Ergebnisverarbeitung der erwarteten Choreografie folgen. Er beweist nicht, dass ein realer Prozess keine unerlaubte Datei lesen kann.

Freigabe: Jeder definierte Normal-, Fehler- und Abbruchpfad besitzt ein reproduzierbares Testergebnis.
Ergänzende Prüfung: Die Orchestrierung ist korrekt, aber die Fehlerklassifikation oder die Abbruchsemantik bleibt unklar.
Blockade: Der Ablauf meldet Erfolg trotz Werkzeugfehler, wiederholt riskante Aktionen unkontrolliert oder kann einen Zwischenstatus nicht eindeutig beschreiben.

Die reale Integration trennt lokale Bequemlichkeit von reproduzierbarer Umgebung

Erst jetzt wird der Agent in einer echten Sandbox ausgeführt. Die Testumgebung muss dem vorgesehenen Ziel möglichst genau entsprechen: gleiches Abhängigkeitsmodell, gleiche Verzeichnisstruktur, gleicher Startweg und ein kontrollierter Ausgangszustand. Die offizielle Beschreibung des Sandbox-Lebenszyklus dient als Referenz für Erstellung, Ausführung, Sitzung und Zustandsverwaltung.

Der Ablauf sollte nicht mit dem vollständigen Erfolgsfall beginnen. Zuerst wird ein repräsentativer Auftrag mit leerem oder sauber erzeugtem Arbeitsbereich ausgeführt. Danach folgen Aufgaben mit:

• erlaubtem Lesen und Schreiben,
• absichtlich fehlendem Eingabepfad,
• fehlerhaftem Kommando,
• erzeugtem Zwischenartefakt,
• großen, aber für die Aufgabe typischen Dateien,
• unerwartetem Prozessende,
• erneutem Lauf mit demselben Auftrag.

Jeder Lauf erhält eine Beweisakte. Darin stehen Manifest-Version, Konfigurationsversion, Startzustand, Werkzeugaufrufe, erzeugte Dateien, Fehler, Sitzungsstatus und Bereinigungsstatus. Logs allein genügen nicht, wenn nicht feststellbar ist, welcher Workspace tatsächlich verwendet wurde.

Für macOS-spezifische Anforderungen gilt eine harte Grenze: Signierung, systemnahe Werkzeuge, Keychain-Interaktionen, Xcode-nahe Abläufe und andere Systemkomponenten müssen auf einem echten Mac geprüft werden. Ein Container auf einem anderen Betriebssystem kann die Orchestrierung testen, aber keine Aussage über macOS-Kompatibilität liefern. Die Entscheidung für einen Cloud-Mac sollte daher aus den Testfällen entstehen, nicht aus einer pauschalen Annahme, dass jede Sandbox dort besser läuft.

Wenn Tracing eingesetzt wird, sollte der Datensatz auf die Abnahmefrage zugeschnitten sein. Die Tracing-Dokumentation des Agents SDK erklärt, welche Lauf- und Werkzeugereignisse nachvollziehbar gemacht werden können. Sensible Inhalte gehören nicht unkontrolliert in Traces. Für personenbezogene oder vertrauliche Daten müssen Aufbewahrung, Zugriff und Löschung mit der eigenen DSGVO-Bewertung abgestimmt werden. ProxyMac beschreibt die relevanten Datenschutzinformationen; diese ersetzen keine projektbezogene Datenschutzprüfung.

Freigabe: Ein neuer Lauf erzeugt mit dokumentiertem Ausgangszustand dieselben erwarteten Dateitypen und Statusübergänge.
Ergänzende Prüfung: Das Ergebnis ist fachlich richtig, aber Startzustand, Abhängigkeit oder Bereinigung ist noch nicht vollständig nachvollziehbar.
Blockade: Der Agent benötigt manuelle Host-Eingriffe, findet lokale Geheimnisse, erzeugt nicht reproduzierbare Ergebnisse oder funktioniert bei identischer Konfiguration nur auf dem Entwicklerrechner.

Erfahrung aus der Abnahme: Wenn ein Test nur mit dem persönlichen Benutzerprofil, einem offenen Terminal oder einer bereits gefüllten Cache-Struktur funktioniert, sollte der Lauf als fehlgeschlagen gelten. „Auf meinem Mac läuft es“ ist ein Hinweis auf eine versteckte Abhängigkeit, kein Nachweis für Isolation.

Rechte und Geheimnisse werden vor der Hochrisikoaktion geprüft

Datei- und Befehlsrechte dürfen nicht aus dem sichtbaren Verhalten des Agenten abgeleitet werden. Ein Agent kann einen erlaubten Auftrag korrekt erfüllen und trotzdem über einen nicht benötigten Pfad, eine Umgebungsvariable oder ein externes Speichermedium zu weitreichende Möglichkeiten besitzen.

Die Prüfung erfolgt als Positiv- und Negativtest. Für jede Fähigkeit wird zunächst der notwendige Zugriff beschrieben. Danach wird geprüft, ob ein Zugriff außerhalb dieser Beschreibung verweigert oder einem Menschen zur Freigabe vorgelegt wird.

Besonders relevant sind:

• Lesen außerhalb des vorgesehenen Arbeitsbereichs,
• Schreiben in übergeordnete oder gemeinsam genutzte Verzeichnisse,
• Ausführung von Shell-Befehlen mit Lösch- oder Überschreibwirkung,
• Weitergabe von Dateien an nicht erlaubte Netzwerkziele,
• Übernahme von Zugangsdaten aus der Umgebung,
• Zugriff auf SSH-Material, Token, Keychain oder CI/CD-Geheimnisse,
• Ausnutzung symbolischer Verknüpfungen und relativer Pfade,
• Weiterverwendung eines alten Arbeitsbereichs in einer neuen Sitzung.

Ein schreibbarer Mount sollte die Ausnahme bleiben. Für reine Analyseaufgaben ist ein schreibgeschützter Arbeitsbereich die belastbarere Ausgangslage. Für riskante Operationen werden explizite Genehmigungs- oder Ablehnungspfade benötigt. Die Ablehnung muss dabei nicht nur in der Benutzeroberfläche erscheinen; sie muss auch im Laufprotokoll und im Endstatus erkennbar sein.

Die lokale Client-Anwendung ist nicht automatisch eine Sicherheitsgrenze. Sie kann Bedienung und Entwicklung vereinfachen, garantiert aber keine produktionsartige Prozessisolation. Diese Grenze muss in einer Container- oder verwalteten Ausführungsumgebung separat nachgewiesen werden. Die offizielle Schnellstart-Dokumentation zu Sandbox Agents zeigt den aktuellen Einstieg, ist aber wegen des Beta-Status keine dauerhafte Sicherheitszusage.

Freigabe: Jeder Zugriff ist auf die Aufgabe begrenzt, sensible Werte sind nicht unnötig verfügbar und riskante Aktionen besitzen einen nachvollziehbaren Kontrollpunkt.
Ergänzende Prüfung: Die Rechte wirken ausreichend, aber einzelne Netzwerk-, Speicher- oder Geheimnisflüsse sind noch nicht beobachtet.
Blockade: Ein Agent kann außerhalb des Workspace lesen oder schreiben, Geheimnisse abfragen, Daten unerwartet ausleiten oder gefährliche Befehle ohne Kontrolle ausführen.

Unterbrechung und Wiederanlauf zeigen die tatsächliche Zustandsqualität

Ein vollständiger Erfolgslauf ist der bequemste und zugleich schwächste Wiederherstellungstest. Für lange Aufgaben wird der Agent absichtlich unterbrochen. Danach wird geprüft, ob der gespeicherte Zustand der Spezifikation entspricht und ob die Fortsetzung sicher ist.

Die Unterbrechung sollte an mehreren Stellen erfolgen:

• vor dem Schreiben eines wichtigen Artefakts,
• unmittelbar nach dem Schreiben,
• vor einer externen oder schwer rückgängig zu machenden Aktion,
• nach einem Werkzeugfehler,
• während ein Prozess noch aktiv ist.

Anschließend wird die Sitzung fortgesetzt oder eine neue Umgebung aus dem vorgesehenen Snapshot erzeugt. Die Abnahme fragt nicht nur, ob der Agent „weiterläuft“. Sie fragt:

• Wird eine bereits abgeschlossene riskante Aktion erneut ausgeführt?
• Sind erzeugte Dateien vollständig oder nur teilweise vorhanden?
• Wird ein alter Auftrag in einer neuen Sitzung sichtbar?
• Stimmen Session-Status, Workspace-Inhalt und Traces überein?
• Wird eine fehlende oder beschädigte Momentaufnahme erkannt?
• Wird eine nicht bereinigte Umgebung gesperrt?

Für jede Fehlerklasse braucht das Team eine Entscheidung. Ist eine Wiederherstellung nicht sicher möglich, wird die Umgebung verworfen und neu erzeugt. Das ist oft besser als ein halbautomatischer Reparaturversuch, der alte Artefakte und neue Aktionen vermischt. Besonders kritisch ist ein scheinbar erfolgreicher Lauf mit inkonsistentem Workspace. Er darf nicht automatisch in die nächste Pipeline-Stufe gelangen.

Freigabe: Unterbrechung, Wiederherstellung und Fortsetzung ergeben einen dokumentierten, konsistenten Zustand.
Ergänzende Prüfung: Der Lauf kann fortgesetzt werden, aber die Wiederholbarkeit einzelner Aktionen oder die Bereinigung ist nicht ausreichend belegt.
Blockade: Der Agent wiederholt Hochrisikoaktionen, übernimmt Dateien aus einer fremden Sitzung, verschweigt Bereinigungsfehler oder erzeugt nach der Wiederherstellung einen widersprüchlichen Status.

FAQ zur Abnahme vor dem produktiven Start

Welche Prüfungen gehören vor dem Start eines OpenAI Agents SDK Sandbox-Projekts dazu?

Vor der Freigabe sollten Sie zuerst den Workspace-Vertrag festhalten. Danach folgen deterministische Tests der Orchestrierung, reale Dateisystem- und Prozessprüfungen, Berechtigungs- und Geheimnistests, Unterbrechungen mit Wiederanlauf sowie ein dokumentierter Rollback. Ein einmal erfolgreich ausgeführtes Beispiel reicht nicht aus, weil es weder Isolation noch reproduzierbare Zustände beweist.

Wie lässt sich ein SandboxAgent bei Datei- und Befehlszugriffen überprüfen?

Legen Sie für jede Aufgabe erlaubte Dateien, schreibbare Verzeichnisse, Befehle und Netzwerkziele fest. Testen Sie anschließend erlaubte und verweigerte Fälle getrennt. Besonders wichtig sind Pfadwechsel, symbolische Verknüpfungen, Umgebungsvariablen, Geheimnisse und Befehle mit Lösch- oder Exportwirkung. Jeder verweigerte Zugriff muss als überprüfbares Ereignis und nicht nur als sichtbare Fehlermeldung vorliegen.

Warum kann ein lokal erfolgreicher Agent nach der Bereitstellung scheitern?

Entwicklerrechner enthalten häufig zusätzliche Dateien, Rechte, Programme, Umgebungsvariablen oder Zugangsdaten. Dadurch besteht die Gefahr, dass ein Prototyp unbewusst von lokalen Voraussetzungen abhängt. In der Zielumgebung fehlen diese Annahmen. Reproduzierbare Images, ein expliziter Manifest-Entwurf und ein Test mit leerem Arbeitsbereich zeigen, ob der Agent wirklich selbstständig startet.

Wie werden Snapshot-Wiederherstellung und das Fortsetzen einer Agent-Aufgabe getestet?

Unterbrechen Sie eine laufende Aufgabe an mehreren definierten Punkten: vor einem Dateischreibvorgang, danach und vor einer externen Aktion. Prüfen Sie, welcher Zustand gespeichert wurde, ob abgeschlossene riskante Aktionen erneut ausgeführt werden und ob alte Dateien in einer neuen Sitzung auftauchen. Bei widersprüchlichem Zustand oder fehlgeschlagener Bereinigung sollte die Regel „Umgebung verwerfen und neu erzeugen“ greifen.

Welche Sandbox-Tests brauchen eine unabhängige Mac-Umgebung?

Eine unabhängige Mac-Umgebung ist sinnvoll, wenn die Aufgabe macOS-spezifische Werkzeuge, Signierung, Systemkomponenten oder eine parallele Regression benötigt. Sie ersetzt keine Berechtigungsprüfung und macht aus einer Beta-Funktion keine Produktionsgarantie. Die Umgebung sollte isoliert, reproduzierbar und nur für den tatsächlichen Prüfzeitraum bereitgestellt werden. Nach der Abnahme bleiben Konfiguration und Belege versioniert.

Die Freigabe trennt bestanden, nachzubessern und blockiert

Am Ende wird nicht mit einem einzigen „grün“ gearbeitet. Jede Prüfung landet in einer von drei Klassen:

• Bestanden: Die erwartete Eigenschaft ist nachgewiesen, die Beweisakte ist vollständig und der Test kann reproduziert werden.
• Nachzubessern: Es gibt keinen akuten Sicherheitsbruch, aber ein Nachweis, eine Dokumentation oder ein Randfall fehlt.
• Blockiert: Die Umgebung verletzt den Vertrag oder kann einen sicheren, reproduzierbaren Zustand nicht garantieren.

Als Blocker gelten insbesondere unautorisierter Datei- oder Netzwerkzugriff, offengelegte Geheimnisse, nicht reproduzierbare Umgebungen, inkonsistente Wiederherstellung und ein fehlender Rollback. Auch ein Beta-API-Wechsel ohne Versionsstrategie sollte die Freigabe stoppen. Die laufende Dokumentation muss deshalb nicht nur den erfolgreichen Output speichern. Sie enthält mindestens Manifest-Version, SandboxRunConfig, verwendeten Client, Workspace-Startzustand, Werkzeug- und Fehlerprotokolle, Zustandsübergänge, Bereinigung, Testverantwortlichen und die Entscheidung.

Die ProxyMac-Hilfe für die Nutzung der Umgebung kann bei der organisatorischen Vorbereitung eines Testzugangs herangezogen werden. Sie ersetzt nicht die technische Abnahme des Agenten.

Die Umgebung folgt den Tests, nicht umgekehrt

Ein lokaler Mac ist für schnelle Entwicklung und erste reproduzierbare Checks sinnvoll. Ein Container eignet sich für viele deterministische Abläufe und standardisierte Abhängigkeiten. Ein unabhängiger Cloud-Mac wird interessant, wenn mehrere Prüfer parallel arbeiten, macOS-spezifische Toolchains beteiligt sind oder ein kurzer, sauberer Regressionstest ohne Eingriff in den Entwicklerrechner benötigt wird.

Dabei sollte der Cloud-Mac nicht als Abkürzung für die Sicherheitsprüfung missverstanden werden. Auch dort gelten Workspace-Vertrag, minimale Rechte, Geheimniskontrolle, Zustandsprüfung und Rollback. Die Umgebung ist nur dann hilfreich, wenn sie mit definiertem Ausgangszustand bereitgestellt, nach jedem Lauf bereinigt und nach der Abnahme wieder entkoppelt wird.

Für Teams, die lokale, Container- und Cloud-Varianten organisatorisch vergleichen, ist der ProxyMac-Anmeldebereich ein möglicher Einstieg in die Prüfung eines separaten Testzugangs. Entscheidend bleibt der konkrete Testplan: macOS-Abhängigkeit, Parallelität und Laufzeit des Projekts bestimmen, ob sich eine zusätzliche Umgebung lohnt.

Die Checkliste entscheidet über Freigabe oder Neuaufbau

Vor der Übergabe an Testbetrieb oder Produktion sollten Verantwortliche jeden Punkt einzeln abhaken:

• [ ] Workspace-Vertrag mit erlaubten und verbotenen Pfaden ist versioniert.
• [ ] Manifest und SandboxRunConfig entsprechen der vorgesehenen Zielumgebung.
• [ ] Der Agent startet aus einem reproduzierbaren, dokumentierten Ausgangszustand.
• [ ] Normale Werkzeugaufrufe sind deterministisch geprüft.
• [ ] Befehlsfehler, fehlende Dateien und vorzeitige Abbrüche besitzen eigene Testfälle.
• [ ] Der deterministische Test wird nicht als Nachweis echter Isolation verwendet.
• [ ] Reale Datei-, Prozess- und Bereinigungsvorgänge sind in der Sandbox geprüft.
• [ ] macOS-spezifische Werkzeuge wurden auf echtem macOS getestet.
• [ ] Lese-, Schreib-, Netzwerk- und Geheimnisgrenzen sind als Positiv- und Negativfälle belegt.
• [ ] Löschung, Überschreibung, Export und privilegierte Befehle haben Ablehnungs- oder Freigabepfade.
• [ ] Unterbrechung und Fortsetzung wurden an mehreren Zustandsgrenzen ausgeführt.
• [ ] Abgeschlossene Hochrisikoaktionen werden beim Wiederanlauf nicht unkontrolliert wiederholt.
• [ ] Neue Sitzungen übernehmen keine Dateien aus alten Aufgaben.
• [ ] Fehler bei Snapshot, Wiederherstellung oder Bereinigung führen zu einer definierten Neu-Erzeugung.
• [ ] Jede Abweichung ist als „bestanden“, „nachzubessern“ oder „blockiert“ klassifiziert.
• [ ] Rollback, Konfigurationsversion und verantwortliche Person sind dokumentiert.
• [ ] Beta-Änderungen werden vor der nächsten Freigabe erneut gegen die offiziellen Referenzen geprüft.

Wenn macOS-Abhängigkeiten, parallele Regressionen oder eine kurzfristig reproduzierbare Testumgebung die Freigabe blockieren, ist eine isolierte Cloud-Mac-Instanz eine sachliche Option. Die Alternative hat jedoch reale Nachteile: Der lokale Rechner besitzt oft versteckte Zustände, parallele Teamtests beeinflussen sich gegenseitig, und ein Container kann macOS-Verhalten nicht vollständig abbilden. Ein zeitweise gemieteter Mac von ProxyMac bietet in diesem Fall die bessere Trennung zwischen Entwicklungsrechner und Abnahmeumgebung, sofern der Workspace nach diesem Leitfaden vorbereitet und vor der Übergabe nochmals vollständig geprüft wird. Für dauerhaft hohe Last, zwingende physische Schnittstellen oder eine langfristig unveränderte Umgebung kann der Kauf eines eigenen Macs sinnvoller sein. Für eine begrenzte Validierungsphase sollte die Umgebung dagegen nur so lange bestehen, wie die Beweisakte sie benötigt.

FAQ