In einer von OpenAI gehosteten Sandbox erhält dein Agent eine Linux-Arbeitsumgebung mit Python, Node.js und Kommandozeilenwerkzeugen. OpenAI stellt die Sandbox bereit und verbindet sie mit dem Agenten. Deine Anwendung übergibt die Aufgabe und ruft die Ergebnisse ab. Wähle eine selbst gehostete Sandbox, wenn du ein eigenes Image, eigene Rechenressourcen oder ein privates Netzwerk benötigst.
Wie dein Agent über einen Browser mit Websites interagieren kann, erfährst du im Leitfaden zur Computernutzung.
Wie du die Arbeitsumgebung vorbereitest, bevor du eine Sitzung erstellst, erfährst du im Leitfaden Sandboxes vorab vorbereiten.
Sandbox konfigurieren
Setze environment.type in der Anfrage zum Erstellen der Sitzung auf openai_hosted. Gib nur die Einstellungen an, die deine Aufgabe erfordert. Das Arbeitsverzeichnis der Sandbox ist /workspace.
Mit container_size und network legst du fest, welche Ressourcen und welchen Netzwerkzugriff deine Aufgabe erhält. Wenn du eine Umgebungsvorlage verwendest, gelten für alle Einstellungen, die du weglässt, die Werte aus der Vorlage.
Pakete und Dateien vorbereiten
Mit diesen Einstellungen stellst du Abhängigkeiten und Eingabedateien in der Sandbox bereit:
packages: Installiere Python-Pakete, Systempakete oder globalenpm-Pakete, indem du sie in den Listenpython,systemodernpmangibst. Lege bei Bedarf die genaue Version fest, zum Beispielpandas==2.2.3.files: Stelle Eingabedateien bereit, indem du ihre ID aus der Files API angibst oder ihren Inhalt direkt Base64-codiert einfügst.
Setup-Befehle ausführen
Mit setup_commands führst du Shell-Befehle in der angegebenen Reihenfolge aus, bevor der Agent startet. Zum Beispiel erstellt [{ "command": "mkdir -p reports" }] ein Verzeichnis. Für jeden Befehl kannst du mit cwd ein eigenes Arbeitsverzeichnis festlegen. Standardmäßig gilt /workspace.
Pakete und Eingabedateien stehen bereit, bevor die Setup-Befehle ausgeführt werden. Mit einem Setup-Befehl kannst du prüfen, ob die benötigten Abhängigkeiten oder Dateien vorhanden sind. Endet das Setup mit einem Exit-Code ungleich null, startet der Agent nicht.
Umgebungsvariablen setzen
Mit env setzt du Umgebungsvariablen, deren Werte Zeichenketten sind. Vom Agenten generierter Code kann diese Werte lesen.
Verwende für Secrets Zugangsdaten aus einem Vault, damit die tatsächlichen Werte außerhalb der Sandbox bleiben. Die Laufzeitumgebung lehnt reservierte Namen wie PATH, CODEX_* und OPENAI_API_KEY ab.
Containergröße wählen
Mit environment.container_size legst du beim Erstellen einer Sitzung fest, wie viele vCPUs und wie viel Arbeitsspeicher der Sandbox zur Verfügung stehen. Der Standardwert ist medium.
| Größe | vCPU | Arbeitsspeicher |
|---|---|---|
small |
1 | 1 GB |
medium |
2 | 4 GB |
large |
4 | 16 GB |
Gib beispielsweise in deiner Anfrage an POST /v1/agents/sessions die folgende Umgebung an, um die Größe small zu wählen:
{
"environment": {
"type": "openai_hosted",
"container_size": "small"
}
}
In den zurückgegebenen Sitzungsdaten steht die gewählte Größe in environment.container_size. Diese Einstellung gilt nur für von OpenAI gehostete Sandboxes.
Netzwerkzugriff steuern
network.access |
Verhalten |
|---|---|
enabled |
Erlaubt ausgehende Verbindungen. Das ist die Standardeinstellung, sofern du keine Netzwerkrichtlinie aus einer Vorlage übernimmst. |
disabled |
Blockiert ausgehende Verbindungen. |
restricted |
Erlaubt nur Verbindungen zu Hosts, die in allowed_domains aufgeführt sind. |
Im eingeschränkten Modus kannst du 1 bis 100 exakte Hostnamen angeben, zum Beispiel api.example.com. Gib keine Platzhalter, Protokolle, Pfade oder Ports an. Subdomains und Weiterleitungsziele benötigen jeweils einen eigenen Eintrag. Gehostete MCP-Server, die über stdio kommunizieren, benötigen derzeit die Zugriffseinstellung enabled. Weitere Informationen findest du in den Anforderungen für MCP-Server mit stdio.
Skills und Plugins hinzufügen
Mit skills, plugins und capability_directories fügst du Skills und Plugins hinzu.
Konfiguration für mehrere Sitzungen verwenden
Setze environment_template_id, um eine gespeicherte Konfiguration wiederzuverwenden. Für Einstellungen, die du weglässt, gelten die Werte aus der Vorlage. Wenn du die Netzwerkeinstellungen überschreibst, kannst du den Zugriff nur im Rahmen der Richtlinie der Vorlage erlauben. Vorlagen speichern nur die Konfiguration. Eine laufende Arbeitsumgebung lässt sich damit nicht speichern.
Erfolg des Setups prüfen
Die Antwort auf die Anfrage zum Erstellen einer Sitzung zeigt an, dass das Setup begonnen hat. Prüfe den Status mit GET /v1/agents/environments/{environment_id}. Verwende dafür die environment.id der Sitzung.
| Status | Nächster Schritt |
|---|---|
provisioning |
Warte, bis das Setup abgeschlossen ist. |
connected |
Das Setup war erfolgreich. Du kannst Dateien in der laufenden Sandbox hinzufügen oder auflisten. |
failed |
Lies environment.error im Ereignis agent.session.environment.failed. |
Warte auf den Status connected, bevor du Dateien in der laufenden Sandbox hinzufügst oder auflistest.
Dateien und Lebensdauer
Jede Sitzung hat eine eigene Arbeitsumgebung. Solange die Sandbox besteht, bleiben Dateien über mehrere Durchläufe hinweg erhalten. Am Ende eines Durchlaufs werden Dateien unter /workspace/outputs als unveränderliche Artefakte veröffentlicht. Diese Kopien kannst du auch nach Ablauf der Sandbox herunterladen.
Im Leitfaden Dateien und Artefakte findest du Informationen zu Uploads, Pfadregeln, Dateioperationen in der laufenden Sandbox, Downloads und geltenden Beschränkungen. Sichere die benötigten Ergebnisse, bevor du die Sitzung löschst.
Ablauf der Sandbox
Verbundene Sandboxes empfangen auch zwischen Durchläufen Keep-alive-Signale. Bleiben sowohl Aktivitäten als auch Keep-alive-Signale eine Stunde lang aus, kann die Sandbox gelöscht werden. Diese Frist lässt sich nicht ändern.
Lösche die Sitzung, sobald du fertig bist, um die Bereinigung der Sandbox anzufordern. Falls die Löschanfrage 409 zurückgibt, weil das Setup oder die Ausführung noch läuft, warte und versuche es erneut. Begrenze dabei die Anzahl der Versuche. Wenn du den Ereignisstream schließt, läuft die Aufgabe weiter.
Preise
Für von OpenAI gehostete Sandboxes gelten die regulären Containerpreise. Die Modellnutzung wird separat zu den API-Preisen des gewählten Modells abgerechnet.
Beispiel: Einen Bericht erstellen
Übergib dem Agenten eine CSV-Datei mit den Werten 10, 20 und 30. Er berechnet die Summe mit Python und schreibt das Ergebnis in /workspace/outputs/summary.json.
Setze OPENAI_API_KEY im Terminal deiner Anwendung wie in den Voraussetzungen für den Schnellstart beschrieben. Bewahre diesen Schlüssel außerhalb der Sandbox auf. Verwende eine Version des OpenAI SDK, die die Betaversion der Agents API enthält.
from openai import OpenAI
client = OpenAI()
stream = client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra"},
environment={
"type": "openai_hosted",
"network": {"access": "disabled"},
"files": [
{
"type": "inline",
"path": "/workspace/amounts.csv",
"data": "YW1vdW50CjEwCjIwCjMwCg==",
}
],
},
input="Use Python to sum the amount column in /workspace/amounts.csv. Write a JSON object with the total to /workspace/outputs/summary.json, then read it back to verify it.",
stream=True,
)
with stream.with_result_collection():
for event in stream:
print(event.model_dump_json())
result = stream.get_final_result()
client.beta.agents.sessions.artifacts.for_result(result).download(
"/workspace/outputs/summary.json", to="summary.json"
)Der Base64-Wert in files enthält die CSV-Eingabedaten. Der Code gibt die Sitzungsereignisse aus. Speichere session.id aus dem Ereignis agent.session.created. Sobald du agent.session.turn.completed erhältst, liste die Artefakte auf, suche summary.json und lade die Datei herunter. Sie sollte folgenden Inhalt haben:
{ "total": 60 }
Auch bei einem abgeschlossenen Durchlauf können einzelne Tool-Aufrufe fehlgeschlagen sein. Wenn die Aufgabe fehlschlägt oder der Stream vor Abschluss des Durchlaufs endet, prüfe die gespeicherten Sitzungselemente. Lösche die Sitzung, sobald du fertig bist.
Fehlerbehebung
| Problem | Was du prüfen kannst |
|---|---|
| Das Setup schlägt fehl | Prüfe das Ereignis, das den Fehler in der Umgebung meldet. Behebe den Fehler im Paket, in der Eingabedatei oder im Setup-Befehl, bevor du eine weitere Sitzung erstellst. |
| Eine Anfrage aus der Sandbox wird blockiert | Prüfe network und alle Hosts, die über Weiterleitungen erreicht werden. |
| Eine Dateioperation in der laufenden Sandbox schlägt fehl | Prüfe, ob die Sandbox den Status connected hat. Falls sie abgelaufen ist, erstelle eine neue Sitzung und stelle die Eingabedaten erneut bereit. |
Eine Anfrage zum Abrufen des Status oder der Dateiliste gibt 5xx zurück |
Wiederhole die Anfrage mit zunehmend längeren Wartezeiten und lege eine Frist für die Wiederholungsversuche fest. Bewahre die Anfrage-ID auf, falls der Fehler weiterhin auftritt. |