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

Automatische Überprüfung

Richte die automatische Überprüfung von Aktionen für eine Agentensitzung ein, damit deine Agenten selbstständiger arbeiten können.

Die automatische Überprüfung genehmigt unterstützte Genehmigungsanfragen oder lehnt sie ab, während ein Agent arbeitet. Sie funktioniert ähnlich wie die automatische Genehmigung in ChatGPT und Codex. Konfiguriere sie über das Feld review, wenn du eine Sitzung für deinen Agenten erstellst. Die Einstellung gilt für die Turns des Hauptagenten und für alle Subagenten, die er in diesen Turns erstellt.

  • Aktionen überprüfen

    Lass unterstützte Anfragen des Agenten und seiner Subagenten automatisch genehmigen oder ablehnen.

  • Überprüfungsmodus zwischen Aufgaben ändern

    Wähle den Überprüfungsmodus für den nächsten Turn des Hauptagenten.

  • Netzwerkbeschränkungen beibehalten

    Bei der Überprüfung gelten weiterhin die Beschränkungen der Umgebung für ausgehende Netzwerkverbindungen.

API-Ressourcen

  • Sitzungen

    /v1/agents/sessions

    Lege den Überprüfungsmodus fest und sieh dir ausstehende Aktionen an.

  • Agenten

    /v1/agents

    Verwende die Anweisungen und Tools für die Aufgabe erneut.

  • Umgebungsvorlagen

    /v1/agents/environments/templates

    Verwende die Konfiguration der Ausführungsumgebung erneut.

  • Sitzungsereignisse

    /v1/agents/sessions/{session_id}/events

    Verfolge den Fortschritt und prüfe, wie der Turn ausgegangen ist.

So funktioniert die automatische Überprüfung

Mit der automatischen Überprüfung können deine Agenten die Funktion „Für mich genehmigen“ des Codex-Harness nutzen. Wenn ein Agent während einer Sitzung eine Aktion plant, für die er zusätzliche Berechtigungen benötigt, kann dies eine Genehmigungsanfrage auslösen. Beispiele dafür sind:

  • Shell-Befehle und Terminaleingaben, die eine Genehmigung erfordern, etwa Befehle, die erweiterte Berechtigungen anfordern oder potenziell gefährlich sind.
  • Dateiänderungen, die eine Genehmigung erfordern.
  • Anfragen nach zusätzlichen Berechtigungen, etwa für einen umfassenderen Zugriff auf das Dateisystem oder das Netzwerk.
  • Anfragen nach Netzwerkzugriff, die eine Genehmigung erfordern. Dabei gelten die Netzwerkbeschränkungen der Umgebung.
  • MCP-Toolaufrufe, deren Genehmigungsregeln eine Bestätigung verlangen.

Ein von OpenAI verwaltetes Modell beurteilt anhand des Gesprächskontexts, was die Aktion bewirken würde, welche Risiken sie birgt und ob sie der Absicht der Person entspricht, die den Auftrag erteilt hat. Anschließend genehmigt das Modell die Anfrage oder lehnt sie ab.

Die Token für die Überprüfung werden zusätzlich zur Modellnutzung deines Agenten abgerechnet.

Deine Anwendung bearbeitet weiterhin Anfragen zum Zugriff auf einen Origin im Browser sowie Anmeldeanfragen. Für MCP-Formulare, die eine Eingabe erfordern, und für Anfragen, die eine Person zu einer URL weiterleiten, gelten die bisherigen Abläufe. Für die automatische Überprüfung brauchst du keine neuen Handler für Genehmigungsereignisse. Wie du den Fortschritt des Agenten verfolgst und das Ergebnis eines Turns prüfst, erfährst du im Abschnitt Ereignisse und Elemente.

Überprüfungsmodus auswählen

Lege über das Feld review der Sitzung fest, wie Anfragen behandelt werden:

Wert Verhalten
"auto_review" Die automatische Überprüfung genehmigt unterstützte Anfragen oder lehnt sie ab. Grundlage sind die Risiken der Aktion und die Anweisungen der Person, die im Gespräch den Auftrag erteilt hat.
"none" Die automatische Überprüfung ist deaktiviert. Die meisten Aktionen werden direkt ausgeführt, soweit die Berechtigungen und Beschränkungen der Umgebung dies zulassen.

Wenn du review weglässt, gilt der Standardwert "none". Die Einstellung bleibt erhalten, wenn du die Sitzung fortsetzt. Um sie zu ändern, sende "auto_review" oder "none". Die API akzeptiert null nicht. Wenn du review auf "none" setzt, werden diese Aktionen nicht zur manuellen Genehmigung an deine Anwendung gesendet.

Ausführungsumgebung vorbereiten

Wenn OpenAI die Ausführungsumgebung hostet, erstelle die Sitzung mit einer neuen Umgebung. Dafür kannst du eine Umgebungsvorlage verwenden. Wenn du über environment_id eine vorhandene gehostete Umgebung wiederverwendest, steht die automatische Überprüfung nicht zur Verfügung.

Wenn du die Ausführungsumgebung selbst hostest, folge der Anleitung zum Einrichten einer selbst gehosteten Umgebung und erfülle die Sandbox-Voraussetzungen für dein Betriebssystem, bevor du die automatische Überprüfung aktivierst. Das Setzen von review allein richtet das Sandboxing in deiner Umgebung nicht ein.

Die Netzwerkbeschränkungen der Umgebung gelten auch bei der automatischen Überprüfung. Konfiguriere den ausgehenden Netzwerkzugriff über die Netzwerkeinstellungen der Umgebung. Auch wenn du den Zugriff auf einen Origin im Browser genehmigst, gelten diese Beschränkungen weiterhin.

Sitzung mit automatischer Überprüfung erstellen

Setze review beim Erstellen einer Sitzung auf "auto_review". In diesem Beispiel erhält der Agent den Auftrag, npm install in /workspace auszuführen.

Nachdem du deinen API-Schlüssel und das SDK eingerichtet hast, verwende einen vorhandenen Agenten und eine Umgebungsvorlage, die Node.js und ein Projekt mit der Datei /workspace/package.json bereitstellt. Ersetze die Agenten-ID und die Vorlagen-ID aus dem Beispiel durch deine eigenen IDs.

npm install mit automatischer Überprüfung ausführen
from openai import OpenAI

client = OpenAI()
session = client.beta.agents.sessions.create(
    agent_id="agt_123",
    environment={
        "type": "openai_hosted",
        "environment_template_id": "envtmpl_123",
    },
    review="auto_review",
    input="Run npm install in /workspace.",
)
print(session.id)

Mit der zurückgegebenen Sitzungs-ID (id) kannst du zwischen Aufgaben den Überprüfungsmodus ändern. Die Anfragefelder findest du in der API-Referenz zum Erstellen einer Sitzung.

Dein Projekt muss Zugriff auf die automatische Überprüfung haben. Fehlt dieser Zugriff, lehnt die API Anfragen zur Aktivierung ab und nennt review als betroffenen Parameter.

Überprüfungsmodus ändern

Aktualisiere das Feld review der Sitzung zwischen zwei Aufgaben. Bevor du den Modus änderst, muss die Hauptaufgabe ruhen und die Übermittlung von Eingaben abgeschlossen sein. Das folgende Beispiel deaktiviert die automatische Überprüfung. Ersetze sess_123 durch die Sitzungs-ID, die du oben erhalten hast:

Automatische Überprüfung deaktivieren
updated_session = client.beta.agents.sessions.update("sess_123", review="none")
print(updated_session.id)

Die API gibt 200 OK und die aktualisierte Sitzung zurück. Lass review bei anderen Sitzungsaktualisierungen weg, um die Einstellung beizubehalten. Um die automatische Überprüfung wieder zu aktivieren, sende "review": "auto_review". Die Anfragefelder findest du in der API-Referenz zum Aktualisieren einer Sitzung.

Wenn du versuchst, den Modus zu ändern, während die Hauptaufgabe aktiv ist oder die Übermittlung von Eingaben noch läuft, gibt die API 409 Conflict zurück. Sie übernimmt keine der Änderungen aus dieser Anfrage. Versuche es erneut, sobald die Hauptaufgabe ruht und die Übermittlung von Eingaben abgeschlossen ist. Behandle 409 auch dann, wenn du den Sitzungsstatus bereits geprüft hast, da vor der Aktualisierung neue Eingaben eintreffen können. Den aktuellen Wert des Überprüfungsmodus darfst du auch bei laufender Aufgabe senden.

Rufe eine Sitzung ab oder liste die Sitzungen auf, um den gespeicherten Wert von review zu prüfen. Fehlt das Feld in der Antwort, gehe vom Wert "none" aus.