Eine Agentensitzung kann länger bestehen als ihre Umgebung. Deine Anwendung verwaltet die Rechenressourcen und Dateien, die eine Umgebung vom Typ self_hosted verwendet.
Eine Umgebung starten
Deine Anwendung kann nach dem Erstellen einer Sitzung Rechenressourcen starten. Verwende das SDK oder die API deines Anbieters und verbinde anschließend den Executor mit der Umgebungs-ID der Sitzung und einem Umgebungsschlüssel.
Sieh dir die Beispiele für anwendungsverwaltete Sandboxes im OpenAI Cookbook an.
Verwende eine Komponente, um die Umgebung jeder Sitzung zu verwalten. Speichere die Zuordnung zwischen der Sitzung und den Rechenressourcen des Anbieters. Wiederholte oder gleichzeitige Anfragen dürfen keine doppelten Umgebungen erzeugen.
Rechenressourcen über Webhooks starten
Du kannst auch warten, bis eine Eingabe eine Verbindung zur Umgebung benötigt. Die API gibt agent.session.action_required mit required_action.type: "environment_connection" aus, bevor sie auf den Executor wartet. Dein Webhook-Handler startet die Umgebung oder verbindet sie erneut.
Sieh dir die Beispiele für per Webhook verwaltete Sandboxes im OpenAI Cookbook an.
Folge der Anleitung zum Webhook-Setup, um deinen Handler für agent.session.action_required und agent.session.failed zu registrieren. Halte sein Signiergeheimnis und seine Zugangsdaten zum Lesen von Sitzungen vom Umgebungsschlüssel des Executors getrennt. Wenn mehrere Anbieter-Handler dasselbe Projekt nutzen, leite Ereignisse an den für die Sitzung zuständigen Handler weiter.
Handler und Worker haben unterschiedliche Aufgaben:
- Verifizieren und in die Warteschlange stellen. Verifiziere die Webhook-Signatur. Stelle Verbindungsanfragen nur dann in die Warteschlange, wenn
data.required_action.typeden Wertenvironment_connectionhat. Stelle auch Sitzungsfehler in die Warteschlange. Gib erst dann eine erfolgreiche HTTP-Antwort zurück, wenn das Einreihen erfolgreich war. - Aktuellen Zustand prüfen. Der Worker ruft die Sitzung ab. Ignoriere gelöschte Sitzungen und 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. Gib die Rechenressourcen einer Sitzung frei, die sich weiterhin im Fehlerzustand befindet.
Der Sitzungsstream meldet dieselbe Anfrage als agent.session.requires_action. Eine erforderliche Aktion vom Typ function_call benötigt ein Funktionsergebnis, keinen Start der Umgebung. Das Erstellen eines Durchlaufs und Ereignisse vom Typ agent.session.in_progress erfolgen zu spät, um einen Executor zu starten, der offline ist.
Nachdem du den Handler bereitgestellt hast, erstelle eine selbst gehostete Sitzung und sende eine Eingabe. Achte darauf, dass das Arbeitsverzeichnis und gegebenenfalls konfigurierte Agentenfilter mit den Einstellungen deines Handlers übereinstimmen. Die ursprüngliche Übermittlung wird fortgesetzt, wenn sich der Executor vor Ablauf der Frist verbindet.
Die Umgebung verfügbar halten oder stoppen
Lass die Rechenressourcen zwischen Durchläufen weiterlaufen, um sie wiederzuverwenden, oder warte nach dem Ende eines Durchlaufs eine gewisse Zeit, bevor du sie stoppst. Stimme das Herunterfahren mit eingehenden Aufgaben ab. Brich ein geplantes Herunterfahren ab, wenn eine Verbindung angefordert wird oder die Ausführung beginnt. Prüfe den Zustand erneut, bevor du die Rechenressourcen stoppst.
Ein Ereignis, das einen Leerlauf meldet, ist allein kein verlässliches Signal zum Herunterfahren. Es kann eintreffen, wenn eine Verbindungsanfrage erledigt ist, aber der Durchlauf für eine wartende Eingabe noch nicht begonnen hat. Wenn deine Anwendung das Herunterfahren nicht mit eingehenden Aufgaben abstimmen kann, lass die Umgebung weiterlaufen.
Nach einer Verbindungstrennung erneut verbinden
Verbindungsereignisse melden den Zustand. Verwende agent.session.environment.connected und agent.session.environment.disconnected, um Verbindungen zu beobachten. Beim Setup können auch agent.session.environment.pending oder agent.session.environment.failed ausgegeben werden. Diese Ereignisse fordern keine Rechenressourcen an. Verwende die erforderliche Aktion vom Typ environment_connection, um den Start auszulösen, und prüfe den Betriebszustand des Anbieters separat.
Eine Verbindungstrennung während eines Durchlaufs kann dazu führen, dass ein Werkzeug fehlschlägt, selbst wenn der Durchlauf abgeschlossen wird. Prüfe die Werkzeugergebnisse und die abschließende Antwort des Agenten. Die Verbindungstrennung fordert weder automatisch über einen Webhook eine erneute Verbindung an noch startet sie einen abgebrochenen Befehl neu. Eine spätere Eingabe kann eine erneute Verbindung anfordern.
Die API wartet bei einer Eingabe bis zu fünf Minuten auf eine Verbindung. Konfiguriere die Zeitlimits von Client und Proxy für diese Wartezeit. Läuft sie ab, schlägt die Übermittlung fehl. Die erste Eingabe kann asynchron fehlschlagen und die Sitzung im Zustand failed zurücklassen.
Die API garantiert nicht, dass ausstehende Eingaben nach einem Prozessabsturz wiederhergestellt werden. Prüfe das Ergebnis der Anfrage oder Sitzung, bevor du es erneut versuchst. Sende die Eingabe nicht erneut, solange die ursprüngliche Anfrage wartet. Eine verspätete Verbindung führt nicht dazu, dass Eingaben nach Ablauf ihres Zeitlimits erneut verarbeitet werden.
Die Wiederverwendung der Umgebungs-ID stellt keine Dateien auf neu bereitgestellten Rechenressourcen wieder her. Verwende Speicher oder Snapshots des Anbieters, um sie zu erhalten.
Aufräumen
Nimm keine neuen Eingaben mehr an. Stimme das Aufräumen mit bereits laufenden Startvorgängen ab, damit keine Rechenressourcen weiterlaufen.
Lösche die Sitzung und stoppe die Rechenressourcen des Anbieters separat. Das Löschen einer Sitzung stoppt weder ihre Umgebung noch löst es einen Webhook zum Löschen aus.