Session-Operationen

Sobald eine Session existiert, kannst du diese Operationen verwenden, um sie zu lesen, zu aktualisieren, zu archivieren oder zu löschen. Siehe Eine Session starten für das Erstellen einer Session und das Senden von Aufgaben an sie.



Session-Status

Sessions durchlaufen die folgenden 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 der Berechtigungsrichtlinien, während der Session aktualisieren, ohne eine neue Agent-Version zu erstellen. Aktualisierungen sind session-lokal und werden nicht auf den zugrunde liegenden Agent zurückübertragen.

Nur die tools und mcp_servers des Agents können nach dem Erstellen einer Session geändert werden. Um eine Session mit anderen model-, system- oder skills-Werten als denen des Agents auszuführen, verwende Agent-Konfigurations-Overrides beim Erstellen der Session. Das konfigurierte system-Feld des Agents ist für die Lebensdauer der Session festgelegt. Bei Modellen, die dies unterstützen, kannst du den effektiven System-Prompt zwischen den Turns dennoch ersetzen, indem du ein system.message-Event sendest.

Die Semantik einer tools- oder mcp_servers-Aktualisierung ist eine vollständige Ersetzung: Das bereitgestellte 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 sich im Status idle befinden, um den Agent zu aktualisieren. Unterbrich die Session, wenn du den Agent aktualisieren musst, während er läuft.

ant beta:sessions update --session-id "$SESSION_ID" <<'YAML'
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
YAML



Abrufen einer Session

ant beta:sessions retrieve --session-id "$SESSION_ID"



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 keine weiteren Ergebnisse vorhanden sind.

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 Standardwert ist desc (neueste zuerst). Die Wiederverwendung eines Cursors mit einer anderen order gibt einen 400-Fehler zurück; andere Query-Parameter, einschließlich Filter und limit, können sich zwischen paginierten Anfragen ändern. Für die Paginierungsfelder, die über alle List-Endpunkte hinweg gemeinsam genutzt werden, siehe Paginierung.

# --format raw liefert eine Seitenhülle mit ihren prev_page- und next_page-
# Cursorn; die Standardausgabe paginiert automatisch und gibt nur die Sessions aus.
cursors=$(ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --format raw \
  --transform '{prev_page,next_page}')
printf '%s\n' "$cursors"

# Übergib den next_page-Cursor als --page zurück, um die nächste Seite abzurufen.
NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")
ant beta:sessions list \
  --agent-id "$AGENT_ID" \
  --limit 1 \
  --page "$NEXT_PAGE" \
  --format raw \
  --transform '{prev_page,next_page}'
# Übergib das prev_page dieser Antwort als --page, um genauso zurückzugehen.



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; sende ein Interrupt-Event, wenn du sie sofort archivieren musst.

ant beta:sessions archive \
  --session-id "$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; sende ein Interrupt-Event, wenn du sie sofort löschen musst.

Dateien, Memory Stores, Vaults, Skills, Environments und Agents sind unabhängige Ressourcen und werden durch das Löschen einer Session nicht beeinflusst.

ant beta:sessions delete \
  --session-id "$SESSION_ID"