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

Architektur

Erfahre, wie Harness, Umgebung und Anwendungsserver zusammenspielen.

OpenAI betreibt den Agenten-Harness. Deine Anwendung sendet ihm Aufgaben und erhält die Ergebnisse. Füge eine Umgebung hinzu, wenn der Agent Rechenressourcen oder Dateien benötigt.

Die Komponenten

  • Harness: Die von OpenAI gehostete Codex-Instanz steuert die Schleife aus Modell- und Tool-Aufrufen und hält die Sitzung des Agenten aufrecht.
  • Umgebung: Hier führt der Agent Befehle und Code aus und arbeitet mit Dateien. Als Umgebung kommen eine Remote-Sandbox, dein Laptop, ein Docker-Container oder eine AWS-Lambda-Funktion infrage.
  • Anwendungsserver: Dein Code verbindet den Agenten mit deinem Produkt. Er übermittelt Aufgaben, empfängt Ereignisse und verarbeitet Aufrufe von Funktions-Tools. Wenn du die Umgebung bereitstellst, verwaltet dein Code auch ihren Lebenszyklus.

Beginne mit den Komponenten, die du für deine Aufgabe brauchst. Der Harness kann ohne Umgebung arbeiten. Deine Anwendung kann per Streaming oder Webhook verfolgen, wie die Aufgabe vorankommt.

Ohne Umgebung starten

Ein Agent, der Fragen beantwortet oder über Tools auf externe Dienste zugreift, braucht dafür möglicherweise weder eigene Rechenressourcen noch Dateien. Setze environment.type auf none. Der folgende Ausschnitt zeigt die Konfiguration der Umgebung. Um eine Sitzung zu erstellen, brauchst du außerdem einen Agenten und eine erste Eingabe.

{
  "environment": {
    "type": "none"
  }
}

Deine Anwendung sendet Eingaben an eine Sitzung. Der Harness ruft das Modell auf, nutzt die konfigurierten Tools und gibt die Ergebnisse zurück. OpenAI hält die Sitzung für spätere Aufgaben aufrecht.

Der Harness kann MCP-Tools auf Remote-Servern direkt aufrufen. Bei Funktions-Tools empfängt dein Code jeden Aufruf, führt die Funktion aus und gibt ihr Ergebnis zurück.

Ohne Umgebung stehen die integrierten Tools Bash und apply-patch, die Dateien im Workspace und die Executor-MCPs nicht zur Verfügung.

Ohne Sandbox stellt die Anwendung Funktions-Tools oder eine virtuelle Shell bereit. Die Agents API kann entfernte MCP-Server aufrufen. Es gibt weder einen Executor noch eine integrierte Shell.

Die hier gezeigte optionale virtuelle Laufzeitumgebung stellt Dateien und Shell-Befehle über die Funktions-Tools deiner Anwendung bereit.

Eine von OpenAI gehostete Umgebung hinzufügen

Wenn der Agent Skripte ausführen, Dateien bearbeiten oder Artefakte erstellen muss, setze environment.type auf openai_hosted. OpenAI erstellt und verwaltet eine Sandbox für die Sitzung.

Du konfigurierst die Pakete, Dateien und Netzwerkzugriffe, die der Agent benötigt. Der Harness führt Befehle direkt in der Sandbox aus. Deine Anwendung sendet weiterhin Aufgaben, empfängt Ereignisse und verarbeitet Aufrufe von Funktions-Tools.

Eine Anwendung startet Sitzungen und empfängt Ereignisse von der Agents API. Die API betreibt den verwalteten Codex-Harness und tauscht Tool-Aufrufe und Ergebnisse mit einer Sandbox aus. Nur bei selbst gehosteten Sandboxen steuert die Anwendung die Rechenressourcen.

Der gestrichelte Pfeil gilt nur, wenn du die Umgebung selbst verwaltest, wie im nächsten Abschnitt beschrieben.

Die Konfigurationsoptionen findest du im Leitfaden zu von OpenAI gehosteten Umgebungen.

Deine eigene Umgebung anbinden

Verwende environment.type: "self_hosted", wenn der Agent deine Infrastruktur, dein privates Netzwerk oder spezielle Software benötigt.

Dein Code startet die Umgebung und verbindet einen Executor mit der Sitzung. Der Executor führt die vom Harness angeforderten Befehle und Tools aus. Deine Anwendung verwaltet die Verbindung und den Lebenszyklus der Umgebung, ohne jeden einzelnen Befehl weiterleiten zu müssen.

Du bist dafür verantwortlich, die Umgebung bereitzustellen und herunterzufahren, die Verbindung bei Bedarf wiederherzustellen und Dateien zu sichern, die du behalten möchtest. Dein Anwendungsserver oder ein Webhook-Handler kann diese Aufgaben übernehmen.

Die Anwendung erstellt eine Sitzung mit einer selbst gehosteten Umgebung, startet die Rechenressourcen und verbindet einen Executor mit der Sitzung. Sie empfängt Ereignisse und prüft das Ergebnis des Agentenschritts, bevor sie die Rechenressourcen herunterfährt.

Bevor du die Rechenressourcen herunterfährst, koordiniere die Bearbeitung eingehender Aufgaben und vergewissere dich, dass keine Ausführung mehr aussteht.

Die Anforderungen für das Setup und das Herunterfahren findest du in den Leitfäden Sandbox anbinden und Lebenszyklus einer Sandbox.

Fortschritt verfolgen und Ergebnisse empfangen

Unabhängig von der Umgebung kannst du eine oder beide Optionen nutzen.

  • Streaming: Während der Agent arbeitet, empfängst du detaillierte Ereignisse, etwa mit Ausgaben, die du in deinem Produkt anzeigen kannst.
  • Webhooks: Du erfährst, wenn sich der Sitzungsstatus ändert, ohne einen Stream offen halten zu müssen. Dein Handler kann Ergebnisse abrufen, Funktions-Tools ausführen oder eine selbst gehostete Umgebung verwalten.

Funktions-Tools benötigen einen Handler, der Aufrufe empfängt und Ergebnisse zurückgibt. Ist der Handler nicht verfügbar, kann es passieren, dass der Agent weiter auf ein Ergebnis wartet. Fehler in den Handlern für Ereignisse oder den Lebenszyklus der Umgebung können auch die Übermittlung von Fortschrittsmeldungen oder die Verwaltung der Umgebung unterbrechen.

Details zur Integration findest du in den Leitfäden Sitzungsereignisse und Webhooks.