Eine Session starten

Eine Session ist eine Agenteninstanz innerhalb einer Umgebung. Jede Session referenziert 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, dann sendest du ein User-Event, um die Arbeit zu beginnen. Du kannst beide Schritte auch mit initial_events in einem einzigen Aufruf zusammenfassen.



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

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

Um eine Session an eine bestimmte Agentenversion zu binden, übergib 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



Die Session mit initialen Events vorbelegen

Du kannst eine Session erstellen und ihre Arbeit in einem einzigen Aufruf starten. initial_events ist ein optionales Array von initialen Events, die bei der Erstellung an die Session gesendet und der Reihe nach verarbeitet werden. Es unterstützt user.message- und user.define_outcome-Events und akzeptiert maximal 50 Events. Eine nicht-leere Liste startet die Agentenschleife im selben Aufruf: Die Session wird direkt im Status running erstellt, ohne weitere Anfrage.

Das folgende Beispiel erstellt eine Session mit einer einzelnen user.message in initial_events:

SEEDED_SESSION_ID=$(ant beta:sessions create \
  --transform id --raw-output <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: List the files in the working directory.
YAML
)

# initial_events werden in der Create-Antwort nicht zurückgegeben; liste die Events
# der Session auf, um die geseedete Nachricht zu sehen.
echo "Seeded event: $(ant beta:sessions:events list \
  --session-id "$SEEDED_SESSION_ID" \
  --format raw \
  --transform 'data.#(type=="user.message").content.0.text' --raw-output)"

Kein anderer Event-Typ wird akzeptiert. Events, die auf einen Agenten-Turn antworten (user.tool_confirmation, user.tool_result und user.custom_tool_result), werden nicht akzeptiert, weil noch kein Agenten-Turn existiert, und user.interrupt wird nicht akzeptiert, weil es keinen Turn gibt, der gestoppt werden könnte. Anders als initial_events bei einem geplanten Deployment akzeptieren die initial_events einer Session kein system.message.

Jedes Event in initial_events wird validiert und persistiert, bevor die Create-Antwort zurückkehrt, in Listenreihenfolge, mit einer vom Server zugewiesenen ID, genau so, als hättest du es unmittelbar nach der Erstellung an den Send-Events-Endpunkt gesendet. Die Inhaltsregeln pro Event sind ebenfalls dieselben wie bei diesem Endpunkt. Eine leere Liste ist gleichbedeutend mit dem Weglassen des Feldes. Die Validierung erfolgt nach dem Alles-oder-nichts-Prinzip: Wenn ein Event die Validierung nicht besteht, wird die gesamte Anfrage abgelehnt und keine Session erstellt.

Die Create-Anfrage wird in den folgenden Fällen abgelehnt:

Ein user.define_outcome-Event in initial_events wird unter denselben Bedingungen akzeptiert wie das Senden eines solchen Events an eine bestehende Session; siehe Outcomes definieren.



Agentenkonfiguration für eine Session überschreiben

Du kannst agent in drei Formen übergeben: als Agenten-ID-String, als Objekt mit gepinnter Version (type: "agent") oder als Overrides-Objekt. Die Overrides-Form ändert Teile der Agentenkonfiguration 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 Agentenversion, die sie referenziert.
• Feld auf null setzen, oder bei Listenfeldern auf ein leeres Array: Die Session läuft mit geleertem Feld. Diese Regel gilt vollständig für system und skills. Es gibt drei 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, weil Skills das read-Tool benötigen. Andernfalls leeren tools: null und tools: [] das Feld.
  • Das Leeren von mcp_servers gibt einen 400-Fehler zurück, wenn die effektiven tools der Session noch ein mcp_toolset enthalten, das einen der Server des Agenten referenziert. Überschreibe tools in derselben Anfrage, um diese mcp_toolset-Einträge zu entfernen, und leere dann mcp_servers.
• 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. Es gibt eine Ausnahme:
  • Ein effort-Level innerhalb eines sessionspezifischen model-Overrides wird nicht angewendet. Setze effort stattdessen auf dem Agenten.

Overrides gelten nur für die Session, die du erstellst. Sie ändern weder die Agentenressource noch erstellen sie eine neue Agentenversion, sodass andere Sessions, die denselben Agenten referenzieren, 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 folgende Beispiel startet eine Session, die das Modell überschreibt und den System-Prompt leert:

# Das `agent` in der Antwort ist der aufgelöste Snapshot: Jeder 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 bei der Session-Erstellung vault_ids, um einen Vault zu referenzieren, der gespeicherte OAuth-Anmeldedaten enthält. Anthropic übernimmt die Token-Aktualisierung für dich. Siehe Authentifizierung mit Vaults, 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 ohne initial_events registriert die Session, startet aber keine Arbeit; die Sandbox der Umgebung wird bereitgestellt, sobald die Session sie zum ersten Mal benötigt. Um eine Aufgabe zu delegieren, sende Events mit einem User-Event an die Session. Um das erste Event stattdessen in der Create-Anfrage mitzuliefern, siehe Die Session mit initialen Events vorbelegen. Die Session fungiert als Zustandsautomat, der den Fortschritt verfolgt, während Events die eigentliche Ausführung steuern.

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.



Nächste Schritte