Eine Agentensitzung kann länger bestehen als ihre Umgebung. Deine Anwendung verwaltet die Rechenressourcen und Dateien, die eine Umgebung vom Typ self_hosted nutzt.
Eine Umgebung starten
Nachdem deine Anwendung eine Sitzung erstellt hat, kann sie die Rechenressourcen starten. Nutze dafür das SDK oder die API deines Anbieters. Verbinde anschließend den Executor mit der Umgebungs-ID der Sitzung und einem Umgebungsschlüssel.
Im OpenAI Cookbook findest du Beispiele für Sandboxes, die eine Anwendung verwaltet.

Verwende für jede Sitzung genau eine Komponente, die ihre Umgebung verwaltet. Speichere die Zuordnung zwischen der Sitzung und den Rechenressourcen des Anbieters. Wiederholte oder gleichzeitige Anfragen dürfen keine doppelten Umgebungen erzeugen.
Rechenressourcen per Webhook starten
Du kannst auch warten, bis eine Eingabe eine Verbindung zur Umgebung benötigt. Die API sendet agent.session.action_required mit required_action.type: "environment_connection" und wartet dann auf den Executor. Dein Webhook-Handler startet die Umgebung oder stellt die Verbindung zu ihr wieder her.
Im OpenAI Cookbook findest du Beispiele für die Verwaltung von Sandboxes per Webhook.

Folge der Anleitung zum Einrichten eines Webhooks, um deinen Handler für agent.session.action_required und agent.session.failed zu registrieren. Halte das Signaturgeheimnis des Handlers und seine Zugangsdaten für den Lesezugriff auf Sitzungen vom Umgebungsschlüssel des Executors getrennt. Wenn sich mehrere Anbieter-Handler ein Projekt teilen, leite Ereignisse an den Handler weiter, der die jeweilige Sitzung verwaltet.
Handler und Worker haben unterschiedliche Aufgaben.
- Signatur prüfen und Anfragen einreihen. Prüfe die Webhook-Signatur. Nimm Verbindungsanfragen nur dann in die Warteschlange auf, wenn
data.required_action.typeden Wertenvironment_connectionhat. Nimm auch Meldungen über fehlgeschlagene Sitzungen auf. Antworte erst mit einem HTTP-Erfolgsstatus, wenn der Eintrag in der Warteschlange steht. - Aktuellen Zustand prüfen. Der Worker ruft die Sitzung ab. Ignoriere gelöschte Sitzungen und bereits erledigte Aktionen. Wenn eine selbst gehostete Sitzung weiterhin eine Verbindung benötigt, starte ihren Executor oder verbinde ihn erneut. Verwende dazu
session.environment.idundsession.environment.remote_url. Befindet sich die Sitzung weiterhin im Fehlerzustand, gib ihre Rechenressourcen frei.
Der Ereignisstream der Sitzung meldet dieselbe Anfrage als agent.session.requires_action. Für eine erforderliche Aktion vom Typ function_call musst du ein Funktionsergebnis liefern. Dafür brauchst du die Umgebung nicht zu starten. Wenn ein Turn erstellt wird oder ein Ereignis vom Typ agent.session.in_progress eintrifft, ist es bereits zu spät, um einen offline befindlichen Executor zu starten.
Nachdem du den Handler bereitgestellt hast, erstelle eine selbst gehostete Sitzung und sende eine Eingabe. Verwende das im Handler konfigurierte Arbeitsverzeichnis und achte darauf, dass der Agent einem gegebenenfalls konfigurierten Agentenfilter entspricht. Wenn der Executor die Verbindung vor Ablauf der Frist herstellt, wird die ursprüngliche Eingabe weiterverarbeitet.
Die Umgebung verfügbar halten oder stoppen
Lass die Rechenressourcen zwischen den Turns weiterlaufen, damit du sie wiederverwenden kannst. Alternativ kannst du nach dem Ende eines Turns eine gewisse Zeit warten, bevor du sie stoppst. Stimme das Herunterfahren auf neu eingehende Aufgaben ab. Brich ein geplantes Herunterfahren ab, sobald eine Verbindung angefordert wird oder die Ausführung beginnt. Prüfe den Zustand erneut, bevor du die Rechenressourcen stoppst.
Ein Ereignis, das Leerlauf meldet, reicht allein nicht aus, um die Umgebung sicher herunterzufahren. Es kann eintreffen, sobald eine Verbindungsanfrage erledigt ist, noch bevor der Turn für eine wartende Eingabe beginnt. Wenn deine Anwendung das Herunterfahren nicht auf eingehende Aufgaben abstimmen kann, lass die Umgebung weiterlaufen.
Die Verbindung nach einem Abbruch wiederherstellen
Verbindungsereignisse melden den aktuellen Zustand. Mit agent.session.environment.connected und agent.session.environment.disconnected kannst du Verbindungen überwachen. Beim Verbindungsaufbau kann die API auch agent.session.environment.pending oder agent.session.environment.failed melden. Keines dieser Ereignisse fordert Rechenressourcen an. Löse den Start über die erforderliche Aktion environment_connection aus und prüfe den Betriebszustand des Anbieters separat.
Bricht die Verbindung während eines Turns ab, kann ein Tool-Aufruf fehlschlagen, selbst wenn der Turn abgeschlossen wird. Prüfe die Tool-Ergebnisse und die abschließende Antwort des Agenten. Ein Verbindungsabbruch löst weder automatisch eine Webhook-Anfrage zum Wiederverbinden aus noch startet er einen abgebrochenen Befehl neu. Eine spätere Eingabe kann eine erneute Verbindung anfordern.
Benötigt eine Eingabe eine Verbindung, wartet die API bis zu fünf Minuten darauf. Konfiguriere die Zeitlimits für Client und Proxy entsprechend. Läuft die Wartezeit ab, schlägt die Übermittlung fehl. Die erste Eingabe kann asynchron fehlschlagen und die Sitzung im Zustand failed hinterlassen.
Die API garantiert nicht, dass ausstehende Eingaben nach einem Prozessabsturz wiederhergestellt werden. Prüfe vor einem erneuten Versuch das Ergebnis der Anfrage oder der Sitzung. Sende die Eingabe nicht erneut, solange die ursprüngliche Anfrage noch wartet. Eine verspätete Verbindung löst keine erneute Verarbeitung einer Eingabe aus, deren Wartezeit abgelaufen ist.
Wenn du Rechenressourcen ersetzt, werden die Dateien durch die Wiederverwendung der Umgebungs-ID nicht wiederhergestellt. Nutze den Speicher des Anbieters oder Snapshots, um die Dateien zu erhalten.
Ressourcen freigeben
Nimm keine neuen Eingaben mehr an. Stimme die Freigabe der Ressourcen mit bereits laufenden Startvorgängen ab, damit keine Rechenressourcen weiterlaufen.
Lösche die Sitzung und stoppe die Rechenressourcen beim Anbieter separat. Das Löschen einer Sitzung stoppt weder ihre Umgebung noch löst es einen Webhook für die Löschung aus.