Eine Session starten

Eine Session ist eine Agenten-Instanz innerhalb einer Umgebung. Jede Session verweist auf einen Agenten und eine Umgebung (beide werden separat erstellt) und behält den Gesprächsverlauf über mehrere Interaktionen hinweg bei. Sessions folgen einem zweistufigen Lebenszyklus: Zuerst erstellst du die Session, um ihre Sandbox bereitzustellen, dann sendest du ein User-Event, um die Arbeit zu starten.



Eine Session erstellen

Eine Session benötigt eine agent-ID und eine environment-ID. Agenten sind versionierte Ressourcen; wenn du die agent-ID als String übergibst, wird die Session mit der neuesten Agenten-Version gestartet.

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

Um eine Session an eine bestimmte Agenten-Version zu binden, übergibst du ein Objekt. So kannst du genau steuern, welche Version ausgeführt wird, und Rollouts neuer Versionen unabhängig voneinander staffeln.

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML



Agenten-Konfiguration für eine Session überschreiben

Du kannst agent in drei Formen übergeben: als Agenten-ID-String, als Objekt mit fixierter Version (type: "agent") oder als Overrides-Objekt. Die Overrides-Form ändert Teile der Agenten-Konfiguration für eine einzelne Session. Verwende sie, um ein anderes Modell auszuprobieren oder in einer Session ein zusätzliches Tool zu gewähren, ohne den Agenten zu versionieren. Für die Overrides-Form setzt du type auf agent_with_overrides und übergibst die id des Agenten sowie optional eine version (lass version weg, um die neueste Version des Agenten zu verwenden). Füge dann beliebige der Felder model, system, tools, mcp_servers oder skills mit den Werten hinzu, die die Session verwenden soll.

Jedes überschreibbare Feld folgt denselben drei Regeln:

• Feld weglassen: Die Session erbt den Wert von der Agenten-Version, auf die sie verweist.
• Feld auf null setzen, oder bei Listenfeldern auf ein leeres Array: Die Session läuft mit diesem Feld als geleert. Diese Regel gilt vollständig für system, mcp_servers und skills. Es gibt zwei Ausnahmen:
  • model kann nie geleert werden. Eine Session benötigt immer ein Modell, daher gibt model: null einen 400-Fehler agent_model_required zurück.
  • Das Leeren von tools gibt einen 400-Fehler zurück, wenn die effektiven skills der Session nicht leer sind, da Skills das read-Tool benötigen. Andernfalls leeren tools: null und tools: [] das Feld.
• Feld auf einen Wert setzen: Der Wert ersetzt den Wert des Agenten vollständig. Overrides werden nie mit der Konfiguration des Agenten zusammengeführt, daher muss ein tools-Override jedes Tool auflisten, das die Session haben soll.

Overrides gelten nur für die Session, die du erstellst. Sie verändern weder die Agenten-Ressource noch erstellen sie eine neue Agenten-Version, sodass andere Sessions, die auf denselben Agenten verweisen, nicht betroffen sind.

In der Antwort spiegelt das agent-Objekt die Konfiguration wider, mit der die Session nach Anwendung der Overrides läuft. Seine id und version identifizieren weiterhin den Agenten und die Version, auf die die Overrides angewendet werden. So kannst du eine Session zu ihrem Basis-Agenten zurückverfolgen.

# Das `agent` der Antwort ist der aufgelöste Snapshot: jedes Override ersetzt dieses
# Feld nur für diese Session, und die Agent-Ressource behält ihre ID und Version.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML



MCP-Authentifizierung über Vaults

Wenn dein Agent MCP-Tools verwendet, die eine Authentifizierung erfordern, übergib vault_ids bei der Session-Erstellung, um auf einen Vault mit gespeicherten OAuth-Anmeldedaten zu verweisen. Anthropic verwaltet die Token-Aktualisierung für dich. Siehe Mit Vaults authentifizieren, um zu erfahren, wie du Vaults erstellst und Anmeldedaten registrierst.

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML



Die Session starten

Das Erstellen einer Session stellt die Sandbox der Umgebung bereit, startet aber keine Arbeit. Um eine Aufgabe zu delegieren, sendest du Events an die Session mithilfe eines User-Events. Die Session fungiert als Zustandsautomat, der den Fortschritt verfolgt, während Events die eigentliche Ausführung antreiben.

ant beta:sessions:events send \
  --session-id "$SESSION_ID" <<'YAML'
events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML

Siehe Session-Event-Stream, um zu erfahren, wie du die Antworten des Agenten streamst und Tool-Bestätigungen handhabst.

Siehe Session-Status für die Status, die eine Session durchläuft, und Session-Operationen für das Abrufen, Auflisten, Aktualisieren, Archivieren und Löschen von Sessions.

Um Sessions automatisch nach einem wiederkehrenden Zeitplan zu erstellen, siehe Geplante Deployments.