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

Lebenszyklus einer Sandbox

Starte die Umgebung deines Agenten, stelle die Verbindung wieder her und stoppe die Umgebung.

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.

Die Anwendung sendet Eingaben, empfängt Ereignisse und steuert die Rechenressourcen des Anbieters. Der Sandbox-Executor baut eine ausgehende Verbindung zur Agents API auf und tauscht darüber Befehle und Ergebnisse aus.

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.

Die Anwendung tauscht Eingaben und Ereignisse mit der Agents API aus. Ein Webhook-Controller verifiziert Verbindungsanfragen, prüft die aktuelle Sitzung und startet eine Sandbox beim Anbieter oder stellt die Verbindung zu ihr wieder her. Der Executor der Sandbox baut eine ausgehende Verbindung auf und tauscht darüber Befehle und Ergebnisse aus.

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.

  1. Signatur prüfen und Anfragen einreihen. Prüfe die Webhook-Signatur. Nimm Verbindungsanfragen nur dann in die Warteschlange auf, wenn data.required_action.type den Wert environment_connection hat. Nimm auch Meldungen über fehlgeschlagene Sitzungen auf. Antworte erst mit einem HTTP-Erfolgsstatus, wenn der Eintrag in der Warteschlange steht.
  2. 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.id und session.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.