Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Sandboxes für den Sitzungsstart vorbereiten

Bereite den Arbeitsbereich vor, bevor du eine Agentensitzung startest.

Schon bevor du eine Agentensitzung erstellst, kannst du eine von OpenAI gehostete Sandbox erstellen, Pakete installieren, Dateien laden und Setup-Befehle ausführen. Sobald eine Aufgabe eingeht, verknüpfst du die vorbereitete Umgebung mit einer Sitzung und startest den Agenten.

Bereite die Umgebung im Voraus vor, wenn kurze Antwortzeiten entscheidend sind. Eine App für Berichte kann zum Beispiel ihre Python-Abhängigkeiten installieren, während jemand einen Datensatz auswählt. Ebenso kann ein Workflow für die Softwareentwicklung den Arbeitsbereich vorbereiten, während jemand eine Anfrage formuliert. Wenn das Setup früher beginnt, kann sich die Wartezeit verkürzen.

So funktioniert es

Die Umgebung ist der Arbeitsbereich, in dem der Agent Tools ausführt. Die Sitzung enthält die Konfiguration des Agenten und den Gesprächsverlauf. Du kannst den Arbeitsbereich unabhängig von der Sitzung vorbereiten und ihn mit einer Sitzung verknüpfen, sobald du sie brauchst.

Der Ablauf umfasst drei Schritte.

  1. Erstelle eine Umgebung. Gib die Pakete, Dateien und Setup-Befehle an, die du für deine Aufgabe brauchst.
  2. Warte, bis die Umgebung bereit ist. Rufe die Umgebung wiederholt ab, bis ihr Status ready lautet, oder verwende einen Webhook.
  3. Starte eine Sitzung. Übergib beim Erstellen der Sitzung die Umgebungs-ID.

Du kannst die Umgebung auch schon während des Setups mit einer Sitzung verknüpfen. Der Agent kann auf den Arbeitsbereich zugreifen, sobald das Setup abgeschlossen ist.

Preise

Das Vorbereiten einer Sandbox ist kostenlos. Das gilt auch für die Container-Nutzung bis zur Verknüpfung mit einer Sitzung. Vorbereitete Sandboxes laufen nach 5 Minuten ab, wenn du sie mit keiner Sitzung verknüpfst.

Sobald du eine vorbereitete Sandbox mit einer Sitzung verknüpfst, gelten die regulären Preise für die Container-Nutzung.

Einen Arbeitsbereich für Berichte vorbereiten

In diesem Beispiel installierst du pandas und lädst eine kleine CSV-Datei, bevor du einen Agenten startest. Der Agent berechnet anschließend im vorbereiteten Arbeitsbereich die Gesamtsumme.

Für diese Anleitung benötigst du mindestens Version 3.28.0 des Python-SDKs, 7.32.0 des Node.js-SDKs, 4.80.0 des Java-SDKs oder 0.103.0 des Ruby-SDKs.

1. Umgebung erstellen

Sende die Konfiguration des Arbeitsbereichs an POST /v1/agents/environments.

from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "packages": {"python": ["pandas==2.2.3"]},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/amounts.csv",
                "data": "YW1vdW50CjEwCjIwCjMwCg==",
            }
        ],
        "setup_commands": [
            {
                "command": 'python -c "import pandas; print(pandas.__version__)"',
                "cwd": "/workspace",
            }
        ],
    }
)
environment_id = environment.id
print(environment_id)

Die SDK-Beispiele speichern die zurückgegebene id für die nächsten Schritte. Wenn du cURL verwendest, speichere die ID in einer Shell-Variablen.

ENVIRONMENT_ID="ccarenv_REPLACE_WITH_RETURNED_ID"

Setze environment.type auf openai_hosted, wenn du eine eigenständige Umgebung erstellst.

2. Prüfen, ob die Umgebung bereit ist

Rufe die Umgebung mit der ID ab, die du in Schritt 1 gespeichert hast.

current = client.beta.agents.environments.retrieve(environment_id)
print(current.status)

Während des Setups lautet der Status pending. Sobald er zu ready wechselt, ist der Arbeitsbereich vorbereitet und du kannst die Umgebung mit einer Sitzung verknüpfen.

Die Umgebung kann bereits den Status ready haben, bevor überhaupt eine Sitzung existiert. Auch bei diesem Status muss noch kein Agent verbunden sein.

Um wiederholte Statusabfragen zu vermeiden, abonniere mit einem Webhook-Endpunkt deines Projekts die folgenden Ereignisse.

  • agent.environment.ready
  • agent.environment.failed

Wenn du die Umgebung vor Abschluss des Setups mit einer Sitzung verknüpfst, verfolge den Setup-Status anhand der Sitzungsereignisse agent.session.environment.ready oder agent.session.environment.failed. Verwende dazu den Antwortstream, den du beim Erstellen der Sitzung mit "stream": true erhältst, oder rufe GET /v1/agents/sessions/{session_id}/events auf. Einzelheiten zum Streaming findest du im Leitfaden zu Sitzungsereignissen.

3. Umgebung verknüpfen und eine Aufgabe ausführen

Erstelle eine Sitzung mit der gespeicherten Umgebungs-ID, einem Agenten und der ersten Eingabe für den Agenten.

stream = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={"type": "openai_hosted", "environment_id": environment_id},
    input="Use pandas to read /workspace/amounts.csv, calculate the sum of the amount column, and report the total.",
    stream=True,
)
with stream:
    for event in stream:
        print(event.model_dump_json())

Häufige Fehler

Entscheide anhand der Fehlermeldung und des aktuellen Status der Umgebung, wie du den Fehler behebst.

Du kannst eine neu erstellte gemeinsame Umgebung mit bis zu 128 Sitzungen verknüpfen. Diese Sitzungen nutzen denselben Arbeitsbereich. Ältere Umgebungen können weiterhin auf eine einzige Sitzung beschränkt sein.

Fehler oder Symptom Abhilfe
Du versuchst, eine abgelaufene Umgebung mit einer Sitzung zu verknüpfen. Erstelle eine neue Umgebung und verwende ihre neue ID. Ungenutzte Umgebungen laufen nach 5 Minuten ab. Ein erneuter Versuch mit einer abgelaufenen ID stellt den Arbeitsbereich nicht wieder her.
404: Umgebung nicht gefunden. Prüfe die Umgebungs-ID und verwende dieselbe Organisation, dasselbe Projekt und dieselbe Identität wie beim Erstellen der Umgebung. Wenn die Umgebung abgelaufen oder nicht mehr verfügbar ist, erstelle eine neue.
409: Die gemeinsame Umgebung hat die maximale Anzahl an Sitzungen erreicht. Eine gemeinsame Umgebung unterstützt bis zu 128 verknüpfte Sitzungen. Verwende eine bestehende Sitzung erneut oder erstelle für weitere Sitzungen eine zusätzliche Umgebung.

Eine gespeicherte Umgebungsvorlage verwenden

Wenn mehrere Aufgaben dieselben Pakete und dasselbe Setup benötigen, speichere die Umgebungskonfiguration als Vorlage. Gib die ID der Vorlage jedes Mal an, wenn du eine Umgebung im Voraus erstellst.

from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "environment_template_id": "envtmpl_REPLACE_WITH_TEMPLATE_ID",
    }
)
print(environment.id)

Eine Sandbox für die Computernutzung vorbereiten

Bereite für Browseraufgaben den verwalteten Browser und den virtuellen Bildschirm vor, bevor die Sitzung startet. Gib beim Erstellen der Umgebung desktop.enabled an.

from openai import OpenAI

client = OpenAI()
environment = client.beta.agents.environments.create(
    environment={
        "type": "openai_hosted",
        "desktop": {"enabled": True},
    }
)
print(environment.id)

Verknüpfe die Sitzung beim Erstellen über die gespeicherte ID mit der Umgebung und stelle dem Agenten das Tool computer_use zur Verfügung. Die Sitzung verwendet die in der Umgebung gespeicherte Desktop-Konfiguration. Informationen zur Tool-Konfiguration und zu Genehmigungen für Browser-Origins findest du im Leitfaden zur Computernutzung.

Deine Umgebungen auflisten

Mit GET /v1/agents/environments findest du die aktiven Umgebungen, die du mit deiner Identität in der aktuellen Organisation und im aktuellen Projekt erstellt hast.

environments = client.beta.agents.environments.list(limit=20, order="desc")
for item in environments.data:
    print(item.model_dump_json())

Die Liste enthält Umgebungen vor und nach der Verknüpfung mit einer Sitzung. Ihr Status kann pending, ready, connected, disconnected oder suspended lauten. Fehlgeschlagene, abgelaufene, gelöschte und beendete Umgebungen erscheinen nicht in der Liste. Eine aufgeführte Umgebung kann bereits mit einer oder mehreren Sitzungen verknüpft sein.

Standardmäßig erscheinen die neuesten Ergebnisse zuerst. Wenn has_more den Wert true hat, setze after auf den Wert von last_id aus der vorherigen Antwort, um die nächste Seite abzurufen. Für limit sind Werte von 1 bis 100 zulässig. Der Standardwert ist 20. Für order kannst du asc oder desc angeben.

Lebensdauer und Wiederverwendung

  • Mehrere Sitzungen können sich eine Umgebung teilen. Übergib beim Erstellen jeder Sitzung dieselbe environment_id. Die Sitzungen teilen sich den laufenden Arbeitsbereich mit seinen Dateien, Prozessen, installierten Paketen und der Umgebungskonfiguration. Jede Sitzung behält ihren eigenen Gesprächsverlauf. Änderungen am Arbeitsbereich sind für andere verknüpfte Sitzungen sichtbar. Erstelle deshalb separate Umgebungen, wenn Aufgaben getrennte Arbeitsbereiche benötigen. Eine gemeinsame Umgebung unterstützt bis zu 128 verknüpfte Sitzungen. Dieses Verhalten gilt für neu erstellte eigenständige Umgebungen. Ältere Umgebungen behalten ihren ursprünglichen Lebenszyklus bei.
  • Ungenutzte Umgebungen laufen ab. Eine Umgebung, die mit keiner Sitzung verknüpft wird, läuft nach 5 Minuten ab. Bereite sie daher erst kurz vor dem erwarteten Beginn einer Aufgabe vor.
  • Verwende dieselbe Identität wie beim Erstellen. Um die Umgebung abzurufen, aufzulisten oder mit einer Sitzung zu verknüpfen, brauchst du dieselbe Organisation, dasselbe Projekt und dieselbe authentifizierte Identität wie beim Erstellen. Verschiedene API-Schlüssel derselben Identität ermöglichen den Zugriff auf dieselben Umgebungen, auch nach einem Schlüsselwechsel.
  • Bei Inaktivität werden die gemeinsam genutzten Rechenressourcen abgeschaltet. Mit der ersten Verknüpfung beginnt eine Inaktivitätsfrist von 20 Minuten. Jede Aktivität in einer verknüpften Sitzung oder über die Datei-API der Umgebung verlängert die Frist. Solange Aufgaben ausstehen oder der Agent eine Eingabe verarbeitet, bleiben die Rechenressourcen aktiv. Bei einer Abschaltung wegen Inaktivität kann die Umgebung in den Status suspended wechseln, anstatt abzulaufen. In diesem Fall bleibt ein Prüfpunkt 7 Tage lang erhalten. Im angehaltenen Zustand ruht die Ausführung, der gemeinsame Arbeitsbereich bleibt erhalten. Wenn du eine Sitzung löschst, wird sie aus der Umgebung entfernt. Der gemeinsame Arbeitsbereich und sein Prüfpunkt bleiben erhalten. Die API bietet keinen eigenen Endpunkt zum Löschen einer Umgebung.

Das Erstellen einer Umgebung sicher wiederholen

Beim Erstellen einer Umgebung kannst du den Header Idempotency-Key mitsenden. Kommt es bei der Anfrage zu einer Zeitüberschreitung oder geht die Antwort verloren, wiederhole die Anfrage mit demselben Schlüssel und demselben Anfrageinhalt, damit keine zusätzliche Umgebung entsteht.

Solange die ursprüngliche Umgebung verfügbar ist, liefert ein abgeschlossener Wiederholungsversuch ihre ID und ihren aktuellen Zustand. Bei einem gespeicherten Schlüssel kann die API 409 zurückgeben, wenn die Erstellung noch läuft, ihr Ergebnis ungewiss ist, die Umgebung nicht mehr verfügbar ist oder die Parameter abweichen. Bei diesen Konflikten entsteht keine Ersatzumgebung. Die API speichert Schlüssel 24 Stunden lang. Danach kann eine Anfrage mit demselben Schlüssel eine neue Umgebung erstellen. Verwende einen neuen Schlüssel, wenn du gezielt eine neue Umgebung erstellen möchtest.