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

DigitalOcean

Verbinde eine DigitalOcean-Sandbox mit einer Sitzung der Agents API.

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

  1. 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_KEY zum Abrufen von Sitzungsdaten sowie DIGITALOCEAN_TOKEN und OPENAI_EXECUTOR_API_KEY.
  2. Registriere den Endpunkt /webhook des Controllers in deinem OpenAI-Projekt. Aktiviere agent.session.action_required und agent.session.failed. Speichere dann das Signaturgeheimnis als OPENAI_WEBHOOK_SECRET und stelle den Controller erneut bereit.
  3. Folge der Anleitung zum Ausführen einer Sitzung. Verwende dieselbe OPENAI_AGENT_ID und gib /workspace als Arbeitsverzeichnis an. Öffne den Ereignisstream und sende eine Eingabe. Wenn OpenAI eine environment_connection anfordert, 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 nach mars-{session_id} und setzt eine pausierte Sandbox fort oder erstellt eine, wenn keine aktiv ist.
  4. Rufe bei agent.session.failed die Sitzung erneut ab. Lösche die zugehörige Sandbox nur, wenn die Sitzung weiterhin den Status failed hat.

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:

Eine selbst gehostete Sitzung erstellen
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}
  1. Erstelle eine Instanz von pydo.aio.Client mit DIGITALOCEAN_TOKEN und rufe client.agents.create_session auf. Setze params.openai_session_id auf die OpenAI-Sitzungs-ID und body.manifest auf den Inhalt von sandbox.yaml. Übergib in body.variables eine Zuordnung von ENV_ID und OPENAI_EXECUTOR_API_KEY zu ihren jeweiligen Werten. Speichere die von DigitalOcean zurückgegebene session_id.
  2. Öffne den Ereignisstream und sende eine Eingabe, in der du den Agenten bittest, in die Datei /workspace/hello.txt zu 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.
  3. Lade die Datei mit workspace_download über den relativen Pfad hello.txt herunter. 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