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 verwalten

Finde Sitzungen, führe erforderliche Aktionen aus und lösche gespeicherte Arbeit.

Speichere jede Sitzungs-ID im Datenspeicher deiner Anwendung. Mit der ID kannst du den aktuellen Zustand der Sitzung abrufen, Anfragen des Agenten bearbeiten oder die Sitzung löschen.

Sitzungen finden

Liste die Sitzungen in deinem Projekt auf, um frühere Arbeiten durchzusehen. Mit den Hilfsfunktionen des SDK für die Paginierung kannst du weitere Ergebnisseiten abrufen:

Sitzungen auflisten und die nächste Seite abrufen
from openai import OpenAI

client = OpenAI()
page = client.beta.agents.sessions.list(limit=20)
print(page.to_json())
if page.has_next_page():
    page = page.get_next_page()
    print(page.to_json())

Eine Sitzung prüfen

Rufe eine Sitzung ab, um ihren Status, die Konfiguration des Agenten, die Umgebung und den Inhalt von required_actions einzusehen. Übergib dazu deinen API-Client und die Sitzungs-ID der Unterhaltung:

Eine Sitzung abrufen
# Pass your saved session ID to this helper.
def retrieve_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.retrieve(session_id)

Das vollständige Schema der Antwort findest du in der API-Referenz zum Abrufen einer Sitzung.

Erforderliche Aktionen ausführen

Bei einer Sitzung mit dem Status requires_action muss deine Anwendung eine Aktion ausführen, bevor die Arbeit weitergehen kann. Wenn du das Ereignis agent.session.requires_action empfängst, rufe die Sitzung ab und prüfe jeden Eintrag in required_actions:

  • function_call: Rufe die in name angegebene Funktion mit den Argumenten aus arguments auf. Gib das Ergebnis in derselben Sitzung zurück und verwende dafür turn_id und call_id aus der Aktion. Siehe Funktionen als Tools verwenden.
  • environment_connection: Stelle eine Verbindung zu der in environment_id angegebenen Umgebung her. Siehe Eine Umgebung verbinden.

Das Ereignis signalisiert deiner Anwendung, wann sie die Sitzung prüfen soll. Aus den abgerufenen Sitzungsdaten geht hervor, welche Aktionen sie ausführen muss. Rufe die Sitzung nach einem Neustart oder einer Unterbrechung des Ereignisstreams ab, um ausstehende Aktionen zu finden. Sobald du sie ausgeführt hast, verfolge die weiteren Ereignisse, um zu erfahren, wie der Turn endet.

Wie du gespeicherte Nachrichten, Tool-Aufrufe und Ergebnisse einzelner Turns abrufst, erfährst du im Abschnitt Elemente und Turns abrufen. Wie du feststellst, welcher Agent einen Befehl ausgeführt hat, erfährst du im Abschnitt Delegation nachvollziehen.

Eine Sitzung löschen

Lösche eine Sitzung, sobald deine Anwendung sie nicht mehr benötigt. Dadurch wird die Sitzung aus der API entfernt. Die physische Bereinigung der Daten kann anschließend asynchron weiterlaufen.

Eine Sitzung löschen
# Replace the illustrative IDs and URLs below with your own resource values.

from openai import OpenAI


def delete_session(client: OpenAI, session_id: str):
    return client.beta.agents.sessions.delete(session_id)


if __name__ == "__main__":
    result = delete_session(OpenAI(), "sess_123")
    print(result.to_json())

Wenn du die laufende Arbeit stoppen und die Unterhaltung behalten möchtest, brich den aktiven Turn ab. Die Antwort auf die Löschanfrage findest du in der API-Referenz zum Löschen einer Sitzung.