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

Ereignisse und Elemente

Verarbeite Aktualisierungen in Echtzeit und rufe gespeicherte Ergebnisse ab.

Ereignisse melden, was passiert, während ein Agent arbeitet. Elemente sind gespeicherte Nachrichten und Toolaufrufe, die du später abrufen kannst. Mit Ereignissen aktualisierst du deine Anwendung in Echtzeit. Mit Elementen zeigst du den gespeicherten Verlauf an.

Deine Anwendung sendet Eingabeereignisse, um Nachrichten zu übermitteln, Turns abzubrechen oder Toolergebnisse zurückzugeben. Der Agent meldet über Ereignisse seine Ausgaben und Änderungen an der Sitzung. Wie du Eingaben sendest, erfährst du im Abschnitt Sitzungen ausführen und fortsetzen.

Einen Stream verarbeiten

Abonniere den Stream, bevor du eine Aufgabe sendest. So empfängt deine Anwendung auch die ersten Ereignisse des Turns. Übergib deinen API-Client, die Sitzungs-ID der Unterhaltung und einen Ereignishandler.

Sitzungsereignisse per Stream empfangen
# Pass your saved session ID to this helper.
def stream_session(client: OpenAI, session_id: str, handle_event):
    with client.beta.agents.sessions.events.stream(session_id) as events:
        for event in events:
            handle_event(event)
            match event.type:
                case "agent.session.idle":
                    continue
                case "error":
                    raise RuntimeError(event.error.message)
                case "agent.session.failed" | "agent.session.environment.failed":
                    raise RuntimeError(f"Agent lifecycle failure: {event.type}")
                case "agent.session.turn.failed":
                    if event.turn.subagent_id is None:
                        detail = event.turn.error.message if event.turn.error else ""
                        raise RuntimeError(f"{event.type}: {detail}")
                case "agent.session.turn.cancelled":
                    if event.turn.subagent_id is None:
                        raise RuntimeError("The agent turn was cancelled")
                case "agent.session.turn.completed":
                    if event.turn.subagent_id is None:
                        return
    raise RuntimeError("Stream closed before a turn ended. Retrieve the saved state.")

Die Hilfsfunktion übergibt jedes Ereignis an deinen Handler und prüft anschließend auf gängige Ereignistypen. Bei agent.session.idle läuft sie weiter. Sobald der Turn des Hauptagenten erfolgreich abgeschlossen ist, kehrt sie zurück. Sie löst einen Fehler aus, wenn der Turn des Hauptagenten fehlschlägt oder abgebrochen wird, wenn die Sitzung oder die Umgebung fehlschlägt oder wenn ein error-Ereignis eintrifft. Ereignisse aus Turns von Subagenten beenden den Stream nicht. Dein Handler bestimmt, wie die Ausgabe angezeigt wird. Der aufrufende Code behandelt Fehler der Hilfsfunktion. Schließt sich der Stream, bevor ein Turn endet, löst die Hilfsfunktion einen Fehler aus. Siehe Einen unterbrochenen Stream wiederherstellen.

Nach dem Abonnieren eine Nachricht senden

Diese Variante nimmt eine Nachricht entgegen und sendet sie, nachdem sie den Stream geöffnet hat.

Eine Nachricht senden und Ereignisse per Stream empfangen
# Pass your saved session ID and message to this helper.
def send_and_stream(client: OpenAI, session_id: str, text, handle_event):
    with client.beta.agents.sessions.events.stream(session_id) as events:
        client.beta.agents.sessions.events.create(
            session_id,
            events=[
                {
                    "type": "agent.session.input.message",
                    "input": [
                        {
                            "role": "user",
                            "content": [{"type": "input_text", "text": text}],
                        }
                    ],
                }
            ],
        )
        for event in events:
            handle_event(event)
            match event.type:
                case "agent.session.idle":
                    continue
                case "error":
                    raise RuntimeError(event.error.message)
                case "agent.session.failed" | "agent.session.environment.failed":
                    raise RuntimeError(f"Agent lifecycle failure: {event.type}")
                case "agent.session.turn.failed":
                    if event.turn.subagent_id is None:
                        detail = event.turn.error.message if event.turn.error else ""
                        raise RuntimeError(f"{event.type}: {detail}")
                case "agent.session.turn.cancelled":
                    if event.turn.subagent_id is None:
                        raise RuntimeError("The agent turn was cancelled")
                case "agent.session.turn.completed":
                    if event.turn.subagent_id is None:
                        return
    raise RuntimeError("Stream closed before a turn ended. Retrieve the saved state.")

Aktualisierungen verarbeiten

Entscheide anhand des Ereignisfelds type, wie deine Anwendung reagieren soll.

  • Text anzeigen: Hänge den Text aus agent.session.turn.output_text.delta an den zugehörigen Inhaltsabschnitt an. Sobald agent.session.turn.output_text.done eintrifft, ersetze den bisherigen Text dieses Abschnitts durch den vollständigen Text. Delta-Ereignisse können ausbleiben.
  • Fortschritt verfolgen: Ereignisse zu Sitzungen, Turns und Elementen melden den Fortschritt. Prüfe, ob agent.session.turn.completed, agent.session.turn.failed oder agent.session.turn.cancelled eintrifft, um festzustellen, wie der Turn geendet hat.
  • Erforderliche Eingaben bereitstellen: Rufe bei agent.session.requires_action die Sitzung ab und prüfe required_actions. Je nach Anforderung muss dein Code ein Funktionsergebnis zurückgeben, eine Umgebung verbinden oder Zugriffsanfragen für einen Origin oder die Anmeldung im Browser verarbeiten.

Eine inaktive Sitzung oder ein geschlossener Stream allein belegt keinen Erfolg. Auch ein erfolgreich abgeschlossener Turn garantiert nicht, dass jeder Toolaufruf erfolgreich war. Prüfe die Ausgabe des Agenten.

Ordne Textaktualisierungen anhand von item_id, output_index und content_index demselben Inhaltsabschnitt zu. Die folgenden gekürzten Ereignisse aktualisieren beispielsweise denselben Abschnitt.

{
  "type": "agent.session.turn.output_text.delta",
  "item_id": "msg_789",
  "output_index": 0,
  "content_index": 0,
  "delta": "Acme competes"
}
{
  "type": "agent.session.turn.output_text.done",
  "item_id": "msg_789",
  "output_index": 0,
  "content_index": 0,
  "text": "Acme competes on price and distribution."
}

Jedes Ereignis hat eine eigene event_id. Die gemeinsame item_id bezeichnet das gespeicherte Element. Es enthält den Inhalt, den Status und die Phase der Nachricht. Siehe Gespeicherte Ergebnisse abrufen.

Alle Ereignistypen und Felder findest du in der Referenz zu Streaming-Ereignissen. Diese Stream-Ereignisse unterscheiden sich von Webhooks. Wie du die Aktivitäten von Subagenten verfolgst und feststellst, welcher Agent einen Befehl ausgeführt hat, erfährst du im Abschnitt Delegation beobachten.

Elemente und Turns abrufen

Rufe gespeicherte Ergebnisse mit der Sitzungs-ID ab, die deine Anwendung im Zustand der Unterhaltung speichert.

Listenendpunkte geben jeweils eine Seite zurück. Verwende die Paginierungshilfen des SDK oder den Cursor after, um weitere Ergebnisse abzurufen. Eine einzelne Seite enthält möglicherweise nur einen Teil der Elemente eines Turns. Mit order: "asc" liest du die Elemente vom ältesten bis zum neuesten.

Einen unterbrochenen Stream wiederherstellen

Ausgaben, die du verpasst hast, kannst du aus den gespeicherten Elementen wiederherstellen. So stellst du die Ansicht deiner Anwendung wieder her:

  1. Öffne einen neuen Stream und puffere eingehende Ereignisse.
  2. Rufe die Sitzung und ihre gespeicherten Elemente ab, während die Verbindung zum Stream besteht.
  3. Stelle den lokalen Zustand anhand dieser Elemente wieder her. Verwende die jeweilige Element-ID als Schlüssel.
  4. Wende die gepufferten Aktualisierungen anhand von item_id auf die jeweiligen Elemente an. Verwirf Aktualisierungen für Elemente, die im abgerufenen Verlauf bereits ihren Endzustand erreicht haben.
  5. Verarbeite wieder Ereignisse in Echtzeit.

Wenn du die Verbindung zu einer fehlgeschlagenen Sitzung erneut herstellst, meldet der Stream den gespeicherten Fehler und schließt sich. Wenn die abgerufene Sitzung status: "failed" aufweist oder du agent.session.failed empfängst, beende die Verbindungsversuche und folge der Anleitung zur Wiederherstellung von Sitzungen.

Stelle die Formulare für ausstehende Eingaben anhand von required_actions aus der abgerufenen Sitzung wieder her. Aus den Elementen im Verlauf geht nicht hervor, welche Anfragen noch eine Antwort erfordern. Ordne bei Genehmigungen im Browser die Formulare anhand von request_id den Anfragen zu und entferne die Formulare für Anfragen, die nicht mehr ausstehen. Sobald die Verbindung wieder besteht, musst du weder die Aufgabe noch frühere Genehmigungen erneut senden.

Mit einem output_text.done-Ereignis kannst du den Inhalt eines temporären Textpuffers durch den vollständigen Text ersetzen. Aus gespeicherten Elementen kannst du die Ergebnisse abgeschlossener Arbeit wiederherstellen, aber nicht jedes zwischenzeitlich verpasste Ereignis.