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 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 die agent.tools und agent.mcp_servers einer Session, einschließlich der Berechtigungsrichtlinien, mitten in 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 der Erstellung 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, wenn du die Session erstellst. Das konfigurierte system-Feld des Agents ist für die Lebensdauer der Session festgelegt. Bei Modellen, die dies unterstützen, kannst du dennoch mitten in der Session Anweisungen auf Systemebene anhängen, 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 zu erhalten, rufe die Session mit GET ab, ändere das Array und sende es mit POST zurück.

Die Session muss idle sein, um den Agent zu aktualisieren. Unterbrich die Session, wenn du den Agent aktualisieren musst, während sie 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

Die 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; andere Query-Parameter, einschließlich Filter und limit, können sich zwischen paginierten Anfragen ändern. Für die Paginierungsfelder, die von allen List-Endpunkten gemeinsam genutzt werden, siehe Paginierung.

# --format raw gibt einen Page-Envelope mit seinen prev_page- und next_page-Cursorn
# zurück; 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, 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 auf demselben Weg zurückzugehen.



Archivieren einer Session

Archiviere eine Session, um zu verhindern, dass neue Events gesendet werden, während ihr Verlauf erhalten bleibt. Eine running-Session 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 running-Session 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"