Session-Operationen

Sobald eine Session existiert, verwende diese Operationen, um sie zu lesen, zu aktualisieren, zu archivieren oder zu löschen. Siehe Eine Session starten zum Erstellen einer Session und zum Senden von Arbeit an sie.

Session-Status

Sessions durchlaufen diese Status. Siehe Eine Session starten für den Session-Lebenszyklus.

Aktualisieren der Agent-Konfiguration

Du kannst agent.tools und agent.mcp_servers einer Session, einschließlich Berechtigungsrichtlinien und Web-Einstellungen pro Tool wie Domain-Filtern, während der laufenden Session aktualisieren, ohne eine neue Agent-Version zu erstellen. Aktualisierungen gelten nur lokal für die Session und werden nicht an den zugrunde liegenden Agent zurückübertragen. Aktualisierte allowed_domains und blocked_domains gelten für den Rest der Session.

Nur tools und mcp_servers des Agents können nach dem Erstellen einer Session geändert werden. Um eine Session mit anderen Werten für model, system oder skills als denen des Agents auszuführen, verwende beim Erstellen der Session Überschreibungen der Agent-Konfiguration. Auch die Modellkonfiguration des Agents, einschließlich seiner inference_geo-Festlegung, kann während der Session nicht geändert werden: Setze die Festlegung, wenn du den Agent speicherst, oder setze bzw. entferne sie für eine einzelne Session mit einer model-Überschreibung beim Erstellen der Session. Das konfigurierte Feld system des Agents ist für die gesamte Lebensdauer der Session festgelegt. Bei Modellen, die dies unterstützen, kannst du während der Session dennoch Anweisungen auf Systemebene anhängen, indem du ein system.message-Event sendest.

Eine Aktualisierung von tools oder mcp_servers ersetzt den Wert vollständig: Das übergebene Array ist der neue Wert. Um bestehende Einträge beizubehalten, rufe die Session per GET ab, ändere das Array und sende es per POST zurück.

Die Session muss idle sein, um den Agent zu aktualisieren. Um den Agent zu aktualisieren, während die Session läuft, sende ein user.interrupt-Event für sich allein und warte, bis die Session idle wird. Wenn ein Workflow-Run offen ist, egal ob er läuft oder pausiert ist, gibt die Aktualisierung einen 400-Fehler zurück, selbst wenn die Session idle ist. Eine Unterbrechung beendet keinen Run, daher schlägt die Aktualisierung auch nach dem Unterbrechen der Session fehl. Sende eine user.message, die den Agent auffordert, seine Runs zu stoppen, oder warte, bis jeder Run beendet ist.

client.beta.sessions.update(
    session.id,
    agent={
        "tools": [
            {"type": "agent_toolset_20260401"},
            {"type": "mcp_toolset", "mcp_server_name": "linear"},
        ],
        "mcp_servers": [
            {"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"}
        ],
    },
)

Aktualisieren des Session-Budgets

Eine mit einem Budget erstellte Session akzeptiert zwei Arten von Budget-Aktualisierungen: das Ersetzen der Obergrenze durch ein neues max_list_cost und das Entfernen durch Übergabe von budget=None. Beide setzen Arbeit, die pausiert wurde, als die Session ihre Obergrenze erreicht hat, automatisch fort. Eine neue Obergrenze kann höher oder niedriger als die aktuelle sein, muss aber strikt größer als die bereits verbrauchten Listenkosten der Session sein, und das Entfernen ist endgültig: Ein budget ungleich null wird nur bei einer Session akzeptiert, die aktuell eines hat, sodass du ein entferntes Budget nicht erneut hinzufügen und auch keines zu einer ohne Budget erstellten Session hinzufügen kannst. Unter Session-Budgets findest du Anfragebeispiele, das Fehlerverhalten und was zu den Listenkosten zählt.

Abrufen einer Session

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

Auflisten von Sessions

Ergebnisse von GET /v1/sessions sind paginiert. Verwende den Query-Parameter limit, um die Seitengröße zu steuern. Jede Antwort enthält einen next_page-Cursor; übergib ihn als page-Parameter bei der nächsten Anfrage, um die folgende Seite abzurufen. next_page ist null, wenn es keine weiteren Ergebnisse gibt.

Um eine Seite zurückzugehen, übergib prev_page als page-Parameter. prev_page ist null, wenn du dich auf der ersten Seite befindest.

Ein page-Cursor ist opak und kodiert die order der Anfrage, die ihn erzeugt hat. Der Query-Parameter order legt die Sortierrichtung der Ergebnisse fest, asc oder desc nach Erstellungszeit; der Standard ist desc (neueste zuerst). Die Wiederverwendung eines Cursors mit einer anderen order gibt einen 400-Fehler zurück, ebenso wie das Ändern eines created_at-Filters, sodass er die Position des Cursors ausschließt. Andere Query-Parameter, einschließlich der übrigen Filter und limit, können sich zwischen paginierten Anfragen ändern. Zu den Paginierungsfeldern, die alle List-Endpunkte gemeinsam haben, siehe Paginierung.

# Setze `limit` niedrig, damit sich die Ergebnisse über mehr als eine Seite erstrecken.
first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
# `prev_page` ist None auf der ersten Seite; `next_page` ist None auf der letzten.
print(f"prev_page: {first_page.prev_page}")
print(f"next_page: {first_page.next_page}")

# Übergib `next_page` als `page`, um die nächste Seite abzurufen.
second_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=first_page.next_page
)
for listed_session in second_page.data:
    print(f"{listed_session.id}: {listed_session.status}")

# Übergib `prev_page` als `page`, um zur vorherigen Seite zurückzukehren.
previous_page = client.beta.sessions.list(
    limit=1, agent_id=agent.id, page=second_page.prev_page
)
for listed_session in previous_page.data:
    print(f"{listed_session.id}: {listed_session.status}")
# Für reine Vorwärts-Iteration ist das Page-Objekt auch direkt iterierbar.

Archivieren einer Session

Archiviere eine Session, um zu verhindern, dass neue Events gesendet werden, während ihr Verlauf erhalten bleibt. Eine Session im Status running kann nicht archiviert werden; um sie zu archivieren, sende ein user.interrupt-Event für sich allein und warte, bis die Session idle wird. Wenn ein Workflow-Run offen ist, kann das Archivieren einen 400-Fehler zurückgeben, selbst wenn die Session idle ist, oder es kann erfolgreich sein und den Run beenden. Sende vor dem Archivieren eine user.message, die den Agent auffordert, seine Runs zu stoppen, oder warte, bis jeder Run beendet ist. Archiviere die Session dann, sobald sie idle ist.

client.beta.sessions.archive(session.id)

Löschen einer Session

Lösche eine Session, um ihren Datensatz, ihre Events und die zugehörige Sandbox dauerhaft zu entfernen. Eine Session im Status running kann nicht gelöscht werden; um sie zu löschen, sende ein user.interrupt-Event für sich allein und warte, bis die Session idle wird. Wenn ein Workflow-Run offen ist, kann das Löschen einen 400-Fehler zurückgeben, selbst wenn die Session idle ist, oder es kann erfolgreich sein. Nach einem erfolgreichen Löschen meldet kein workflow_run-Event das Ende der Runs der Session. Sende vor dem Löschen eine user.message, die den Agent auffordert, seine Runs zu stoppen, oder warte, bis jeder Run beendet ist. Lösche die Session dann, sobald sie idle ist.

Memory Stores, Vaults, Skills, Umgebungen und Agents sind unabhängige Ressourcen und werden vom Löschen einer Session nicht beeinflusst. Dateien, die du über die Files API hochgeladen hast, bleiben ebenfalls unberührt, aber Dateien, die die Session selbst erzeugt hat, sind auf sie beschränkt und werden zusammen mit ihrem Dateisystem dauerhaft gelöscht. Lade alles herunter, was du behalten möchtest, bevor du die Session löschst. Eine Ausgabedatei, die am Ende des letzten Turns geschrieben wurde, kann einige Sekunden, nachdem die Session zu idle gewechselt ist, benötigen, bis sie in der Dateiliste der Session erscheint. Prüfe daher zuerst, ob die erwarteten Dateien aufgelistet sind.

client.beta.sessions.delete(session.id)