In dieser Anleitung übernimmt der Referenz-Worker von Cloudflare die Bereitstellung der Sandbox über Webhooks.
Im OpenAI Cookbook findest du Beispiele dafür, wie du die Bereitstellung über deine Anwendung oder über Webhooks steuerst.
So funktioniert es
- Deine Anwendung erstellt eine Sitzung über die Agents API und sendet eine Eingabe.
- OpenAI sendet Sitzungs-Webhooks an einen Worker in deinem Cloudflare-Konto.
- Der Worker startet einen Container für diese Sitzung oder stellt die Verbindung zu ihm wieder her. Im Container läuft
codex exec-server. Der Executor baut eine ausgehende Verbindung zu OpenAI auf, damit der Agent Befehle ausführen und mit Dateien arbeiten kann.
Deine Anwendung nutzt die Agents API. Der Referenz-Worker kümmert sich um die Bereitstellung der Sandbox. Wie die Verbindung aufgebaut und nach einer Unterbrechung wiederhergestellt wird, erfährst du im Abschnitt Lebenszyklus der Sandbox.
Voraussetzungen
Du brauchst ein Cloudflare-Konto mit Zugriff auf Cloudflare Containers. Verwende OPENAI_API_KEY für Anfragen deiner Anwendung. Setze OPENAI_EXECUTOR_API_KEY auf einen Umgebungsschlüssel und übergib ausschließlich diesen Schlüssel als CODEX_API_KEY an den Container.
Erstelle einen Agenten und speichere seine ID als OPENAI_AGENT_ID. Verwende in deiner Anwendung und im Referenz-Worker dieselbe Agenten-ID.
Referenz-Worker bereitstellen
Der Referenz-Worker von Cloudflare enthält den Webhook-Handler, das Container-Image, die Konfiguration für die Bereitstellung und einen Endpunkt für die Bereinigung.
Erzeuge ein Secret für den Bereinigungsendpunkt und speichere es als EXECUTOR_CLIENT_SECRET.
openssl rand -hex 32
Stelle den Worker in deinem Cloudflare-Konto bereit.
Auf Cloudflare bereitstellen
Gib die folgenden Werte ein, wenn du dazu aufgefordert wirst.
| Variable | Wert |
|---|---|
OPENAI_API_KEY |
Schlüssel, mit dem der Worker den Sitzungsstatus abruft |
OPENAI_EXECUTOR_API_KEY |
Umgebungsschlüssel, den der Executor als CODEX_API_KEY erhält |
OPENAI_AGENT_ID |
ID des Agenten, dessen Sitzungen dieser Worker betreut |
OPENAI_WEBHOOK_SECRET |
pending-webhook-registration für die erste Bereitstellung |
EXECUTOR_CLIENT_SECRET |
Secret, das du für die Bereinigung erzeugt hast |
Speichere die URL des bereitgestellten Workers als WORKER_URL.
Webhook registrieren
Folge der Anleitung zum Einrichten eines Webhooks, um $WORKER_URL/webhook in deinem OpenAI-Projekt zu registrieren. Aktiviere die Ereignisse, die Cloudflare für die Referenzintegration aufführt.
agent.session.createdagent.session.action_requiredagent.session.in_progressagent.session.idleagent.session.failed
Ersetze den Wert von OPENAI_WEBHOOK_SECRET durch das Signatur-Secret, das du von OpenAI erhältst. Stelle dann die neue Version des Workers bereit und prüfe ihre Konfiguration. Die Beispiele rufen den Worker mit gängigen HTTP-Clients auf.
# Replace the illustrative IDs and URLs below with your own resource values.
import urllib.request
url = "https://worker.example.com".rstrip("/") + "/health"
request = urllib.request.Request(url, method="GET")
with urllib.request.urlopen(request) as response:
print(response.read().decode())Die Antwort sollte sowohl "configured": true als auch "webhook_configured": true enthalten.
Wenn die Sitzung die Aktion environment_connection anfordert, muss die Verbindung zum Executor wiederhergestellt werden, der gerade offline ist. Ein Ereignis, das lediglich Inaktivität meldet, reicht nicht aus, um den Executor sicher herunterzufahren. Weitere Einzelheiten findest du unter Verhalten im Sitzungsverlauf.
Sitzung ausführen
Folge der Anleitung zum Ausführen einer Sitzung. Verwende dabei den OPENAI_API_KEY deiner Anwendung und dieselbe OPENAI_AGENT_ID wie im Worker. Erstelle eine selbst gehostete Sitzung und bitte den Agenten, die Datei /workspace/hello.txt zu schreiben und anschließend zu lesen.
Der Worker empfängt die Sitzungs-Webhooks und verbindet den Sandbox-Executor mit OpenAI. Deine Anwendung streamt die Ausgabe des Agenten über die Agents API.
Speichere die Sitzungs-ID als SESSION_ID. Wenn du die Unterhaltung fortsetzen möchtest, öffne den Ereignisstream der Sitzung, bevor du weitere Eingaben sendest. Ist der Executor offline, löst die neue Eingabe eine Verbindungsanfrage für die Umgebung aus. Die Eingabe wird erst verarbeitet, wenn der Worker die Verbindung zum Executor wiederhergestellt hat. Beim erneuten Verbindungsaufbau werden Dateien aus einem früheren Container nicht automatisch wiederhergestellt.
Deine Anwendung in einem Worker ausführen
Die einfache Worker-Anwendung von Cloudflare verwendet das TypeScript-SDK @openai/agents-api, um Sitzungen zu erstellen, erste und weitere Eingaben zu senden und Ressourcen freizugeben. Ihr Endpunkt POST /demo führt diesen Ablauf aus.
Auch diese Anwendung nutzt die Bereitstellung über Webhooks. Deine Anwendung kann in einem Worker laufen, ohne die Sandbox selbst bereitstellen zu müssen.
Ressourcen freigeben
Wenn deine Anwendung die Sandbox nicht mehr benötigt, rufe den Bereinigungsendpunkt des Referenz-Workers auf. Der Aufruf erfordert eine Authentifizierung.
# Replace the illustrative IDs and URLs below with your own resource values.
import os
from urllib.parse import quote
import urllib.request
url = (
"https://worker.example.com".rstrip("/")
+ "/executors/"
+ quote("sess_123", safe="")
)
request = urllib.request.Request(
url,
method="DELETE",
headers={"Authorization": "Bearer " + os.environ["EXECUTOR_CLIENT_SECRET"]},
)
with urllib.request.urlopen(request) as response:
print(response.read().decode())Lösche die Sitzung der Agents API in einem separaten Schritt. Beim Löschen der Sitzung wird kein Webhook ausgelöst. Führe daher beide Schritte aus, um die Ressourcen sofort freizugeben. Rufe alle Dateien ab, die du noch brauchst, bevor du den Container freigibst.
Für Fortgeschrittene: Bereitstellung über die Anwendung steuern
Wenn du die Bereitstellung der Sandbox direkt steuern möchtest, verwende das Cloudflare Sandbox SDK. Folge dazu den Anleitungen zum Verwalten des Sandbox-Lebenszyklus in deiner Anwendung und zum Verbinden des Executors. Verwende pro Sitzung nur einen Controller für die Bereitstellung.
Weiterführende Dokumentation
- Die Anleitung Cloudflare Containers mit der OpenAI Agents API verwenden beschreibt die Konfiguration, das Verhalten im Sitzungsverlauf, Snapshots und die Anpassung des Container-Images.
- Lies die Dokumentation zu Cloudflare Sandbox.
- Lies die Referenz zum TypeScript-SDK für Cloudflare Sandbox.