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

Cloudflare

Verbinde Cloudflare Containers mit einer Sitzung der Agents API.

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

  1. Deine Anwendung erstellt eine Sitzung über die Agents API und sendet eine Eingabe.
  2. OpenAI sendet Sitzungs-Webhooks an einen Worker in deinem Cloudflare-Konto.
  3. 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.created
  • agent.session.action_required
  • agent.session.in_progress
  • agent.session.idle
  • agent.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.

Status des Workers prüfen
# 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.

Sandbox des Workers bereinigen
# 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