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-Filter, 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. Aktualisierte allowed_domains und blocked_domains gelten für den Rest der Session.

Nur die tools und mcp_servers des Agents können sich ändern, nachdem eine Session erstellt wurde. Um eine Session mit anderen model-, system- oder skills-Werten als denen des Agents auszuführen, verwende Überschreibungen der Agent-Konfiguration, wenn du die Session erstellst. Die Modellkonfiguration des Agents, einschließlich seiner inference_geo-Festlegung, kann sich ebenfalls nicht mitten in der Session ändern: Setze die Festlegung, wenn du den Agent speicherst, oder setze bzw. entferne sie für eine einzelne Session mit einer model-Überschreibung, wenn du sie erstellst. Das konfigurierte system-Feld des Agents ist für die Lebensdauer der Session fest. 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 vollständiges Ersetzen: 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 allein und warte, bis die Session idle wird.

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

Aktualisieren des Session-Budgets

Eine Session, die mit einem Budget erstellt wurde, akzeptiert zwei Arten von Budget-Aktualisierungen: das Ersetzen der Obergrenze durch einen neuen max_list_cost und das Entfernen der Obergrenze, indem budget auf null gesetzt wird. Beide setzen automatisch Arbeit fort, die pausiert wurde, als die Session ihre Obergrenze erreichte. Eine Ersatz-Obergrenze kann höher oder niedriger als die aktuelle sein, muss aber strikt größer als die verbrauchten Listenkosten der Session sein, und das Entfernen ist unumkehrbar: Ein budget ungleich null wird nur bei einer Session akzeptiert, die aktuell eines hat, sodass du ein entferntes Budget nicht erneut hinzufügen oder einer ohne Budget erstellten Session eines hinzufügen kannst. Siehe Session-Budgets für Anfragebeispiele, das Fehlerverhalten und was zu den Listenkosten zählt.

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 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.

# --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; um eine solche zu archivieren, sende ein user.interrupt-Event allein und warte, bis die Session idle wird.

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; um eine solche zu löschen, sende ein user.interrupt-Event allein und warte, bis die Session idle wird.

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.

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