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

Sitzungen starten und fortsetzen

Starte eine Aufgabe, verfolge den Fortschritt und setze das Gespräch fort.

In einer Sitzung bleiben die Konfiguration des Agenten, der Gesprächsverlauf und die gespeicherten Arbeitsergebnisse erhalten. Verwende dieselbe Sitzung, um weitere Nachrichten zu senden und die Arbeit fortzusetzen.

Sitzungen und Durchläufe

Ein Durchlauf ist ein Arbeitszyklus innerhalb einer Sitzung. Wenn gerade kein Durchlauf aktiv ist, startet eine Nachricht an die Sitzung einen neuen Durchlauf. Während eines aktiven Durchlaufs kannst du mit einer Nachricht den weiteren Ablauf steuern.

Durchläufe laufen asynchron ab. Deine Anwendung kann den Fortschritt per Streaming verfolgen oder über Webhooks erfahren, wenn sich der Sitzungsstatus ändert.

Mit geplanten Automatisierungen kannst du Aufgaben zu einem späteren Zeitpunkt oder in regelmäßigen Abständen starten. Eine Automatisierung kann bei jeder Ausführung eine neue Sitzung erstellen oder ein bestehendes Gespräch fortsetzen.

Eine Aufgabe starten

Erstelle eine Sitzung mit einer Agentenkonfiguration und einer ersten Eingabe im Feld input. Setze stream auf true, um die Ereignisse des ersten Durchlaufs im Rahmen derselben Anfrage zu empfangen.

Sobald du deinen API-Schlüssel und das SDK konfiguriert hast, führe dieses Beispiel aus, um ein Skript zu erstellen und auszuführen. OpenAI verwaltet die Umgebung, in der das Skript läuft.

Eine Sitzung erstellen und die Ereignisse des ersten Durchlaufs streamen
from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ).with_result_collection() as stream:
        for event in stream:
            print(event.to_json(indent=None), flush=True)
        result = stream.get_final_result()
    print(result.output_text)
    session_id = result.session_id

Speichere die session_id zusammen mit dem Gesprächsstatus in deiner Anwendung. Mit dieser ID kannst du weitere Nachrichten senden und die gespeicherten Arbeitsergebnisse für dieses Gespräch abrufen.

Wenn du in einem Projekt mit aktivierter automatischer Überprüfung eine Sitzung erstellst, die diesen Modus unterstützt, setze review auf "auto_review", um die automatische Überprüfung von Aktionen für diese Sitzung zu aktivieren. Du kannst die Einstellung ändern, wenn die Hauptaufgabe ruht und keine Eingabeübermittlung mehr aussteht. Der Leitfaden Automatische Überprüfung beschreibt die Prüfmodi, die Voraussetzungen für die Umgebung und den Ablauf von Genehmigungen.

Wie du Agenteneinstellungen wiederverwendest, erfährst du im Leitfaden Agenten konfigurieren. Der Leitfaden zur Architektur beschreibt die verfügbaren Umgebungen. Sitzungen mit environment.type: "none" erfordern beim Erstellen eine Eingabe. Die API-Referenz zum Erstellen einer Sitzung listet die Anfragefelder auf.

Wenn die Sitzung Dateianhänge aus der Files API verwendet, kann eine Dateiprüfung den HTTP-Statuscode 429 mit dem Fehlercode files_api_rate_limit_exceeded zurückgeben. Wie du danach fortfährst, erfährst du im Abschnitt zu den Ratenlimits der Files API.

Eingabegröße

Die Laufzeitumgebung des Agenten akzeptiert Anfragen mit einer Größe von bis zu 4 MiB (4.194.304 Byte). Die Eingabe in input und das Ausgabeschema (agent.text.format.schema) müssen zusammen unter diesem Limit bleiben. Plane etwas Platz für die Metadaten ein, die die Agents API hinzufügt. Für Dateien, die du in die Umgebung hochlädst, gelten eigene Dateilimits.

Fortschritt verfolgen und auf Ergebnisse reagieren

Während der Agent arbeitet, melden Ereignisse seine Ausgaben und Änderungen. Prüfe, ob der Durchlauf abgeschlossen wurde, fehlgeschlagen ist oder abgebrochen wurde. Allein daran, dass die Sitzung gerade inaktiv ist, erkennst du nicht, ob der Durchlauf erfolgreich war.

Achte auf agent.session.turn.completed, agent.session.turn.failed oder agent.session.turn.cancelled. Prüfe auch die Ausgabe des Agenten. Selbst bei einem abgeschlossenen Durchlauf können einzelne Tool-Aufrufe fehlgeschlagen sein.

Wenn die Sitzung ein Funktionsergebnis oder eine Verbindung zur Umgebung benötigt, rufe die Sitzung ab und prüfe required_actions. Damit der Agent weiterarbeiten kann, muss dein Code den Funktionsaufruf verarbeiten oder die Verbindung zur Umgebung herstellen.

Der Leitfaden Ereignisse und Sitzungselemente beschreibt die Ereignistypen und ihre Nutzdaten.

Die Arbeit fortsetzen oder steuern

Sende eine weitere Nachricht vom Typ agent.session.input.message an dieselbe Sitzung. Arbeitet der Agent gerade, steuerst du mit der Nachricht den aktiven Durchlauf. Ist die Sitzung inaktiv, startet die Nachricht einen neuen Durchlauf auf Basis des bisherigen Gesprächs.

Für weitere Nachrichten gilt dasselbe Größenlimit für Eingaben.

Änderungen an einem gespeicherten Agenten gelten nur für neue Sitzungen. Wenn du das Modell, den Reasoning-Aufwand oder die Servicestufe für spätere Durchläufe in dieser Sitzung ändern möchtest, aktualisiere die Sitzungseinstellungen.

Verwende die Sitzungs-ID des Gesprächs, um Eingaben zu senden. Abonniere den Ereignisstream der Sitzung, bevor du die Nachricht sendest. So empfängt deine Anwendung auch die ersten Ereignisse des Durchlaufs.

Erzeuge für jeden eigenständigen Sendevorgang einen Idempotenzschlüssel. Speichere ihn zusammen mit der Nachricht, bevor du sie sendest. Verwende beim Senden den gespeicherten Schlüssel.

Eine weitere Nachricht senden
from uuid import uuid4


# Reuse the same submission key when retrying this message.
def send_message(
    client: OpenAI, session_id: str, text: str, submission_key: str
) -> None:
    client.beta.agents.sessions.events.create(
        session_id,
        idempotency_key=submission_key,
        events=[
            {
                "type": "agent.session.input.message",
                "input": [
                    {
                        "role": "user",
                        "content": [
                            {
                                "type": "input_text",
                                "text": text,
                            }
                        ],
                    }
                ],
            }
        ],
    )


submission_key = str(uuid4())
# Save this key with the message before submitting it.

Sende den Schlüssel im Header Idempotency-Key und verwende ihn auch für automatische Wiederholungsversuche. Wenn deine Anwendung die Anfrage nach einer Zeitüberschreitung oder einer verlorenen Antwort erneut sendet, verwende denselben Schlüssel, dieselbe Sitzungs-ID und dieselbe Nachricht. Erzeuge für jeden eigenständigen Sendevorgang einen neuen Schlüssel, auch wenn der Nachrichtentext identisch ist.

Ein Beispiel, das Senden und Streaming kombiniert, findest du im Leitfaden Ereignisse und Sitzungselemente.

Gespeicherte Arbeitsergebnisse abrufen

Ereignisse zeigen den Fortschritt in Echtzeit. Zu den gespeicherten Sitzungselementen gehören Nachrichten und Tool-Aufrufe einschließlich der vollständigen Antworten. Rufe die Elemente ab, um bisherige Arbeitsergebnisse anzuzeigen oder die Ergebnisse nach Ende eines Durchlaufs zu prüfen.

Sitzungselemente abrufen
# Pass your saved session ID to this helper.
def list_items(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)

Wie du den Sitzungsstatus und den Ausgang einzelner Durchläufe prüfst, erfährst du im Leitfaden Sitzungen verwalten. Wie du Dateien abrufst, beschreibt der Leitfaden Dateien und Artefakte.

Streams übertragen verpasste Ereignisse nicht erneut. Rufe nach einem Verbindungsabbruch die Sitzung und ihre gespeicherten Elemente ab, um die Arbeitsergebnisse wiederherzustellen. Wie du die Verbindung wiederherstellst, erfährst du im Abschnitt Einen unterbrochenen Stream wiederherstellen.

Einen aktiven Durchlauf abbrechen

Brich den aktuellen Durchlauf ab, wenn der Agent seine Arbeit beenden soll. Die Sitzung und die bisherigen Arbeitsergebnisse bleiben verfügbar.

Den aktiven Durchlauf abbrechen
# Pass your saved session ID to this helper.
def cancel_turn(client: OpenAI, session_id: str) -> None:
    client.beta.agents.sessions.events.create(
        session_id, events=[{"type": "agent.session.input.cancel"}]
    )