Im OpenAI Cookbook findest du Beispiele für die Bereitstellung über eine Anwendung und per Webhook.
Funktionsweise
DigitalOcean startet über Managed Agents Runtime Services (M.A.R.S.) eine Firecracker-MicroVM mit dem Image codex-agentapi. Das Image enthält Codex und startet den Executor, der eine ausgehende Verbindung zur Agents API aufbaut.
Wähle die Bereitstellung per Webhook, um Sandboxes als Reaktion auf OpenAI-Ereignisse zu starten oder fortzusetzen. Mit der Bereitstellung über deine Anwendung steuerst du die Sandboxes direkt aus deiner Anwendung. Für einen interaktiven Einstieg kannst du die DigitalOcean CLI ausprobieren. Wie Verbindungen hergestellt und wiederhergestellt werden, erfährst du im Abschnitt Lebenszyklus einer Sandbox.
DigitalOcean Managed Agents ist als öffentliche Vorschau verfügbar. Informationen zum Zugang und zur Einrichtung findest du in der Dokumentation von DigitalOcean.
Voraussetzungen
Du brauchst ein für Sandboxes freigeschaltetes DigitalOcean-Konto mit Zugriff auf codex-agentapi und ein OpenAI-Projekt mit Zugriff auf die Agents API.
Verwende OPENAI_API_KEY für deine Anwendung oder die CLI. Setze OPENAI_EXECUTOR_API_KEY auf einen Umgebungsschlüssel. Übergib der Sandbox als CODEX_API_KEY ausschließlich den Umgebungsschlüssel.
Für Webhook-Controller oder Python-Anwendungen setzt du DIGITALOCEAN_TOKEN und installierst das PyDo SDK ab Version 0.41.0 mit Unterstützung für asynchrone Aufrufe (pydo[aio]). Verwende für Anfragen an die Agents API das OpenAI SDK. Die CLI musst du nur installieren, wenn du die Bereitstellung über die CLI ausprobieren möchtest.
Bereitstellung per Webhook
- Erstelle einen gespeicherten Agenten und speichere seine ID als
OPENAI_AGENT_ID. Stelle auf der DigitalOcean App Platform einen HTTPS-Webhook-Controller bereit. Übergib ihm diese ID,OPENAI_API_KEYzum Abrufen von Sitzungsdaten sowieDIGITALOCEAN_TOKENundOPENAI_EXECUTOR_API_KEY. - Registriere den Endpunkt
/webhookdes Controllers in deinem OpenAI-Projekt. Aktiviereagent.session.action_requiredundagent.session.failed. Speichere dann das Signaturgeheimnis alsOPENAI_WEBHOOK_SECRETund stelle den Controller erneut bereit. - Folge der Anleitung zum Ausführen einer Sitzung. Verwende dieselbe
OPENAI_AGENT_IDund gib/workspaceals Arbeitsverzeichnis an. Öffne den Ereignisstream und sende eine Eingabe. Wenn OpenAI eineenvironment_connectionanfordert, prüft der Controller die Signatur, ruft die aktuelle Sitzung ab und prüft deren Agenten-ID und die erforderlichen Aktionen. Er sucht bei DigitalOcean nachmars-{session_id}und setzt eine pausierte Sandbox fort oder erstellt eine, wenn keine aktiv ist. - Rufe bei
agent.session.faileddie Sitzung erneut ab. Lösche die zugehörige Sandbox nur, wenn die Sitzung weiterhin den Statusfailedhat.
Das Image verbindet den Executor mit der Umgebung der Sitzung. Deine Anwendung sendet Eingaben und empfängt die Ergebnisse als Stream über die Agents API. Der Controller übernimmt die Bereitstellung und stellt bei Bedarf die Verbindung wieder her. Verarbeite Bereitstellungsanfragen für dieselbe Sitzung nacheinander, damit der Controller auch mehrfach oder gleichzeitig zugestellte Ereignisse korrekt behandelt. Die Anforderungen an den Controller findest du im Leitfaden zum Lebenszyklus von per Webhook verwalteten Sandboxes.
DigitalOcean CLI ausprobieren
Die CLI erstellt die Sitzung und die Sandbox. Du kannst dann direkt im Terminal mit dem Agenten interagieren. Die CLI stellt die Sandbox ohne Webhook-Controller bereit.
Installiere doctl ab Version 1.170.0. Ab dieser Version ist harness-runtime enthalten. Melde dich anschließend an:
doctl auth init
Speichere dieses Manifest als environment.yaml:
name: openai-codex-session
agent: codex-agentapi
config:
agent:
model: gpt-6.1-sol
instructions: Work from the files in /workspace.
environment:
type: self_hosted
workspace_directory: /workspace
egress:
- api.openai.com
- codex-cloud-environments.chatgpt.com
env:
CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}
Der Block config enthält die Anfrage, mit der die CLI die Sitzung bei OpenAI erstellt. Die CLI authentifiziert die Anfrage mit OPENAI_API_KEY, setzt ${ENV_ID} auf den Wert aus der Antwort und übergibt der Sandbox ausschließlich den Umgebungsschlüssel. Manifeste mit eingesetzten Variablenwerten dürfen weder in Protokolle noch in die Versionsverwaltung gelangen. Trage unter egress alle weiteren Ziele ein, die deine Tools erreichen müssen.
Erstelle die Sitzung und die Sandbox:
doctl harness-runtime create --spec environment.yaml
Der Befehl wartet standardmäßig bis zu 300 Sekunden, bis die Ressourcen bereit sind. Speichere die OpenAI-Sitzungs-ID und die DigitalOcean-Sitzungs-ID aus den Sitzungsdetails. Verbinde dann dein Terminal mit der Sitzung:
doctl harness-runtime launch openai-codex-session
Bitte den Agenten, hello in die Datei /workspace/hello.txt zu schreiben und den Inhalt wieder auszulesen. Drücke Strg+D, um die Verbindung zu trennen, ohne die Sitzung zu löschen. Mit demselben launch-Befehl kannst du dich erneut verbinden. Wenn du fertig bist, folge der Anleitung zum Aufräumen.
Bereitstellung über deine Anwendung
Nutze diese Variante, wenn deine Anwendung die Sitzung erstellt und die Sandbox bereitstellt. Erstelle zuerst die OpenAI-Sitzung:
import OpenAI from "openai";
const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions:
"You are a helpful coding assistant. Write clean code and verify that it works.",
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
},
});
console.log(session);Speichere session.id und die Umgebungs-ID wie im Abschnitt Eine Sandbox verbinden beschrieben. Speichere das folgende Manifest als sandbox.yaml. Es enthält nur die Angaben zur Sandbox, da die Agentenkonfiguration bereits an OpenAI gesendet wurde:
agent: codex-agentapi
egress:
- api.openai.com
- codex-cloud-environments.chatgpt.com
env:
CODEX_ENVIRONMENT_ID: ${ENV_ID}
secrets:
CODEX_API_KEY: ${OPENAI_EXECUTOR_API_KEY}
- Erstelle eine Instanz von
pydo.aio.ClientmitDIGITALOCEAN_TOKENund rufeclient.agents.create_sessionauf. Setzeparams.openai_session_idauf die OpenAI-Sitzungs-ID undbody.manifestauf den Inhalt vonsandbox.yaml. Übergib inbody.variableseine Zuordnung vonENV_IDundOPENAI_EXECUTOR_API_KEYzu ihren jeweiligen Werten. Speichere die von DigitalOcean zurückgegebenesession_id. - Öffne den Ereignisstream und sende eine Eingabe, in der du den Agenten bittest, in die Datei
/workspace/hello.txtzu schreiben und sie wieder auszulesen. Die Eingabe wartet, bis der Executor die Verbindung hergestellt hat. Vergewissere dich, dass das Verbindungsereignis eingegangen ist und der Agent seinen Durchlauf abgeschlossen hat. Prüfe die Ausgabe des Agenten auf fehlgeschlagene Tool-Aufrufe. - Lade die Datei mit
workspace_downloadüber den relativen Pfadhello.txtherunter. Behalte beide Ressourcen für weitere Durchläufe oder räume sie auf.
Lege in deiner Anwendung Zeitlimits für die Einrichtung und die Ausführung fest und behandle Verbindungsfehler. Verknüpfe Sitzungen, die deine Anwendung oder die CLI direkt verwaltet, nicht mit einem Webhook-Handler für die Bereitstellung.
Aufräumen
Sichere alle Dateien, die du noch brauchst. Lösche dann die OpenAI-Sitzung und entferne die DigitalOcean-Sandbox. Beim Löschen der Sitzung wird kein Webhook ausgelöst. Führe deshalb beide Schritte aus und melde Fehler beim Aufräumen.
Wenn du PyDo verwendest, rufe client.agents.destroy_session mit der DigitalOcean-Sitzungs-ID auf. In der CLI kannst du diese ID oder den Namen der Sandbox angeben:
doctl harness-runtime remove openai-codex-session
Entferne die Webhook-Registrierung bei OpenAI, bevor du einen Webhook-Controller löschst.
Weiterführende Informationen
- Lies die Anleitung zum Einrichten einer DigitalOcean-Sandbox.
- Lies die Dokumentation zum Python SDK von DigitalOcean.
- Sieh dir die veröffentlichten Versionen der DigitalOcean CLI an.