Architektur

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

Die Komponenten

• Harness: Die von OpenAI gehostete Codex-Instanz, die die Schleife aus Modell- und Werkzeugaufrufen ausführt und die Sitzung des Agenten verwaltet.
• Umgebung: Hier führt der Agent Befehle und Code aus und arbeitet mit Dateien. Eine Umgebung kann eine Remote-Sandbox, dein Laptop, ein Docker-Container oder eine AWS Lambda-Funktion sein.
• Anwendungsserver: Dein Code, der den Agenten mit deinem Produkt verbindet. Er übermittelt Aufgaben, empfängt Ereignisse und verarbeitet Funktionswerkzeuge. Wenn du die Umgebung bereitstellst, verwaltet dein Code auch deren Lebenszyklus.

Beginne mit den Komponenten, die deine Aufgabe erfordert. Der Harness kann ohne Umgebung arbeiten, und deine Anwendung kann Fortschrittsmeldungen über Streaming oder Webhooks empfangen.

Ohne Umgebung starten

Ein Agent, der Fragen beantwortet oder über Werkzeuge auf externe Dienste zugreift, benötigt möglicherweise keine eigenen Rechenressourcen oder Dateien. Setze environment.type auf none. Dieser Ausschnitt zeigt die Einstellung für die Umgebung. Zum Erstellen einer Sitzung sind außerdem ein Agent und eine erste Eingabe erforderlich:

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

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

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

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

Die hier gezeigte optionale virtuelle Laufzeitumgebung stellt Dateien und Shell-Befehle über die Funktionswerkzeuge 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 den Netzwerkzugriff, 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 gegebenenfalls Funktionswerkzeuge.

Der gestrichelte Pfeil gilt nur, wenn du die Umgebung wie unten beschrieben selbst verwaltest.

Konfigurationsoptionen findest du unter Von OpenAI gehostete Umgebungen.

Deine eigene Umgebung verbinden

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

Dein Code startet die Umgebung und verbindet einen Executor mit der Sitzung. Der Executor führt die Befehle und Werkzeuge aus, die der Harness anfordert. Deine Anwendung verwaltet die Verbindung und den Lebenszyklus, ohne jeden einzelnen Befehl weiterzuleiten.

Du bist für die Bereitstellung, das Wiederherstellen der Verbindung, das Herunterfahren und alle Dateien verantwortlich, die du aufbewahren musst. Dein Anwendungsserver oder ein Webhook-Handler kann diese Aufgaben übernehmen.

Koordiniere eingehende Aufgaben und stelle sicher, dass keine Ausführung aussteht, bevor du die Rechenressourcen stoppst.

Anforderungen für das Setup und das Herunterfahren findest du unter Eine Sandbox verbinden und Sandbox-Lebenszyklus.

Fortschrittsmeldungen und Ergebnisse empfangen

Unabhängig von der gewählten Umgebung kannst du eine oder beide dieser Optionen nutzen:

• Streaming: Empfange detaillierte Ereignisse, während der Agent arbeitet, etwa Ausgaben zur Anzeige in deinem Produkt.
• Webhooks: Empfange Änderungen am Sitzungsstatus, ohne einen Stream offen zu halten. Dein Handler kann Ergebnisse abrufen, Funktionswerkzeuge ausführen oder eine selbst gehostete Umgebung verwalten.

Funktionswerkzeuge benötigen einen Handler, der Aufrufe empfängt und Ergebnisse zurückgibt. Ist dieser Handler nicht verfügbar, kann es passieren, dass der Agent weiterhin auf ein Ergebnis wartet. Fehler in deinen Ereignis- oder Lebenszyklus-Handlern können außerdem Fortschrittsmeldungen oder die Verwaltung der Umgebung unterbrechen.

Details zur Integration findest du unter Sitzungsereignisse und Webhooks.