Eine Session starten

Eine „session“ (Sitzung) ist eine Agenteninstanz innerhalb einer Umgebung. Jede Session referenziert einen Agenten und eine Umgebung (beide werden separat erstellt) und bewahrt den Gesprächsverlauf über mehrere Interaktionen hinweg. Sessions folgen einem zweistufigen Lebenszyklus: Zuerst erstellst du die Session, dann sendest du ein User-Event, um die Arbeit zu starten. Du kannst beide Schritte auch mit initial_events in einem einzigen Aufruf zusammenfassen.

Eine Session erstellen

Eine Session erfordert 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 erstellt.

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 davon stufenweise durchführen.

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

Die Session mit initialen Events befüllen

Du kannst eine Session erstellen und ihre Arbeit in einem einzigen Aufruf starten. initial_events ist ein optionales Array initialer 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, da noch kein Agenten-Turn existiert, und user.interrupt wird nicht akzeptiert, da 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 vergebenen ID, genau so, als hättest du es unmittelbar nach der Erstellung an den Endpunkt zum Senden von Events gesendet. Die inhaltlichen Regeln 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: Schlägt die Validierung eines Events fehl, 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 beim Senden 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 fixierter Version (type: "agent") oder als Overrides-Objekt. Die Overrides-Form ändert Teile der Agentenkonfiguration für eine einzelne Session. Verwende sie, um in einer Session ein anderes Modell auszuprobieren oder ein zusätzliches Tool zu gewähren, ohne den Agenten zu versionieren. Für die Overrides-Form setze type auf agent_with_overrides und übergib 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, da 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 Agentenkonfiguration 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, und da der Override das model-Objekt des Agenten vollständig ersetzt, wird auch der eigene effort-Wert des Agenten nicht übernommen: Eine mit einem model-Override erstellte Session läuft mit dem Standard-Effort-Level des Modells. Um mit einem bestimmten Effort-Level zu laufen, setze effort am Agenten und überschreibe model für diese Session nicht.

Overrides gelten nur für die Session, die du erstellst. Sie verändern weder die Agentenressource noch erstellen sie eine neue Agentenversion, sodass andere Sessions, die denselben Agenten referenzieren, unberührt bleiben.

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 auf ihren Basisagenten 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

Die Inferenz-Geo für eine Session fixieren

Da ein model-Override das model-Objekt des Agenten vollständig ersetzt, setzt oder leert er auch die inference_geo-Fixierung des Modells für die Session: Ein Override, der inference_geo enthält, fixiert die Geografie, die die Modellanfragen der Session bedient, und einer, der es weglässt, leert die Fixierung des Agenten, sodass die Session dem default_inference_geo des Workspace folgt. Der überschriebene Wert wird bei der Erstellung der Session gegen die allowed_inference_geos des Workspace validiert.

Das folgende Beispiel startet eine Session von einem Agenten, dessen Modell keine Geo-Fixierung hat, fixiert die Modellanfragen der Session auf US-Inferenz, indem inference_geo in den model-Override aufgenommen wird, und gibt den im agent.model der Antwort zurückgegebenen Wert aus:

# Ersetzt das `model` des Agents vollständig: gib `id` erneut an, füge `inference_geo` zum Fixieren hinzu.
session=$(ant beta:sessions create <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-opus-5
    inference_geo: us
environment_id: $ENVIRONMENT_ID
YAML
)
echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"

Ein Session-Budget festlegen

Um zu begrenzen, was eine Session ausgeben kann, übergib beim Erstellen das optionale budget-Objekt. Ein Budget ist eine harte Obergrenze für die Listenkosten der Session: Die Plattform bepreist alles, was die Session verbraucht, zu öffentlichen Listenpreisen, und die Session stellt keine neuen Modellanfragen mehr, sobald diese laufende Summe max_list_cost erreicht. Setze type auf limit und gib max_list_cost einen amount und eine currency. amount ist eine ganze Zahl von US-Cent, geschrieben als String, etwa "2500" für 25,00 $; die API nimmt einen String statt einer Zahl entgegen, damit niemals eine Gleitkomma-Rundung angewendet wird. USD ist derzeit die einzige unterstützte Währung. Wenn die Session die Obergrenze erreicht, pausiert sie und geht mit dem Stop-Grund budget_reached in den Leerlauf. Die Obergrenze wird zwischen Modellanfragen durchgesetzt, sodass die Anfrage, die sie überschreitet, zuerst abgeschlossen wird und die endgültigen Listenkosten der Session geringfügig über der Obergrenze landen können. Ein Budget kann nur bei der Erstellung angehängt werden: Du kannst es später ändern oder entfernen, aber du kannst einer ohne Budget erstellten Session keines hinzufügen.

Das folgende Beispiel erstellt eine Session mit einem Budget von 25,00 $; die Antwort gibt das budget in der Session-Ressource zurück:

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF

Unter Session-Budgets erfährst du, wie die Durchsetzung funktioniert, was zu den Listenkosten zählt und wie sich Budgets in Multiagenten-Sessions verhalten.

MCP-Authentifizierung über Vaults

Wenn dein Agent MCP-Tools verwendet, die eine Authentifizierung erfordern, übergib bei der Session-Erstellung vault_ids, um einen Vault mit gespeicherten OAuth-Zugangsdaten zu referenzieren. Anthropic verwaltet die Token-Aktualisierung in deinem Namen. Unter Mit Vaults authentifizieren erfährst du, wie du Vaults erstellst und Zugangsdaten 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 beginnt mit der Bereitstellung, sobald die Session erstellt ist, sodass der erste Tool-Aufruf nicht darauf warten muss. Um eine Aufgabe zu delegieren, sende Events mithilfe eines User-Events an die Session. Um das erste Event stattdessen in der Create-Anfrage mitzugeben, siehe Die Session mit initialen Events befüllen. 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

Unter Session-Event-Stream erfährst du, wie du die Antworten des Agenten streamst und Tool-Bestätigungen handhabst.

Unter Session-Status findest du die Status, die eine Session durchläuft.

Nächste Schritte