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, um eine Session zu erstellen und ihr Arbeit zu senden.



Session-Status

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



Die Agent-Konfiguration aktualisieren

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. Die Modellkonfiguration des Agents, einschließlich seiner inference_geo-Festlegung, kann ebenfalls nicht während der Session geändert werden: Lege die Festlegung beim Speichern des Agents fest, oder setze bzw. entferne sie für eine einzelne Session mit einem model-Override beim Erstellen. Das konfigurierte system-Feld des Agents ist für die Lebensdauer der Session festgelegt. Bei Modellen, die dies unterstützen, kannst du dennoch während 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 beizubehalten, rufe die Session per GET ab, ändere das Array und sende es per POST zurück.

Die Session muss im Status idle sein, 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



Das Session-Budget aktualisieren

Eine Session, die mit einem Budget erstellt wurde, akzeptiert zwei Arten von Budget-Aktualisierungen: das Ersetzen der Obergrenze durch einen neuen max_list_cost-Wert und das Entfernen der Obergrenze durch Setzen von budget auf null. Beide setzen automatisch die Arbeit fort, die pausiert wurde, als die Session ihre Obergrenze erreicht hat. Eine Ersatz-Obergrenze kann höher oder niedriger als die aktuelle sein, muss aber strikt größer sein als die bereits verbrauchten Listenkosten der Session, und das Entfernen ist eine Einbahnstraße: Ein nicht-null budget wird nur bei einer Session akzeptiert, die derzeit eines hat, du kannst also ein entferntes Budget nicht wieder hinzufügen oder eines zu einer Session hinzufügen, die ohne Budget erstellt wurde. Siehe Session-Budgets für Request-Beispiele, das Fehlerverhalten und was zu den Listenkosten zählt.



Eine Session abrufen

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



Sessions auflisten

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 Standardwert 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. Für die Paginierungsfelder, die von allen List-Endpunkten gemeinsam verwendet 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.



Eine Session archivieren

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"



Eine Session löschen

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.

Memory Stores, Vaults, Skills, Environments und Agents sind unabhängige Ressourcen und werden durch das Löschen einer Session nicht beeinflusst. Dateien, die du über die Files API hochgeladen hast, sind ebenfalls nicht betroffen, aber Dateien, die die Session selbst erzeugt hat, sind an sie gebunden und werden zusammen mit ihrem Dateisystem dauerhaft gelöscht. Lade alles herunter, was du behalten möchtest, bevor du die Session löschst.

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