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.
# 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.
# 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.deltaan den zugehörigen Inhaltsabschnitt an. Sobaldagent.session.turn.output_text.doneeintrifft, 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.failedoderagent.session.turn.cancelledeintrifft, um festzustellen, wie der Turn geendet hat. - Erforderliche Eingaben bereitstellen: Rufe bei
agent.session.requires_actiondie Sitzung ab und prüferequired_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.
- Sitzungselemente: Liste die Elemente auf, um die Nachrichten und Toolaufrufe des Hauptagenten über mehrere Turns hinweg abzurufen.
- Turns: Liste die Turns auf, um dir einen Überblick über den Sitzungsverlauf zu verschaffen. Rufe einen Turn anhand seiner ID ab, um Status, Zeitstempel, Nutzungsdaten und etwaige Fehler zu prüfen.
- Elemente eines einzelnen Turns: Verwende für einen Turn des Hauptagenten den Endpunkt Elemente eines Turns auflisten. Jeder Subagent hat einen eigenen Elementverlauf und einen Endpunkt zum Abrufen der Elemente eines einzelnen Turns.
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:
- Öffne einen neuen Stream und puffere eingehende Ereignisse.
- Rufe die Sitzung und ihre gespeicherten Elemente ab, während die Verbindung zum Stream besteht.
- Stelle den lokalen Zustand anhand dieser Elemente wieder her. Verwende die jeweilige Element-ID als Schlüssel.
- Wende die gepufferten Aktualisierungen anhand von
item_idauf die jeweiligen Elemente an. Verwirf Aktualisierungen für Elemente, die im abgerufenen Verlauf bereits ihren Endzustand erreicht haben. - 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.