Eine Session starten

Eine Session ist eine Agenteninstanz innerhalb einer Umgebung. Jede Session referenziert einen Agenten und eine Umgebung (beide werden separat erstellt) und verwaltet 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 zu 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 erstellt.

session = client.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.

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

Die Session mit initialen Events befüllen

Du kannst eine Session in einem einzigen Aufruf erstellen und ihre Arbeit 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 = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
# initial_events werden in der Create-Antwort nicht zurückgegeben; lies sie
# aus der Event-Liste der Session zurück.
for event in client.beta.sessions.events.list(seeded_session.id):
    if event.type == "user.message":
        for block in event.content:
            if block.type == "text":
                print(f"Seeded event: {block.text}")

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 zum Anhalten gibt. 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 gespeichert, bevor die Antwort auf die Erstellung zurückgegeben wird – in Listenreihenfolge und mit einer vom Server zugewiesenen ID, genau so, als hättest du es unmittelbar nach der Erstellung an den Endpunkt zum Senden von Events gesendet. Auch die inhaltlichen Regeln pro Event sind 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 Erstellungsanfrage 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 Ergebnisse 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 freizugeben, ohne den Agenten zu versionieren. Setze für die Overrides-Form 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 übernimmt den Wert aus 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 Konfiguration des Agenten zusammengeführt, daher muss ein tools-Override jedes Tool auflisten, das die Session haben soll. Ebenso ersetzt ein model-Override das model-Objekt des Agenten vollständig, sodass der eigene effort des Agenten nicht übernommen wird. Um die Session mit einem bestimmten Effort-Level auszuführen, setze effort innerhalb des model-Objekts des Overrides. Ein Level, das das Modell nicht unterstützt, gibt einen 400-Fehler zurück, und ein model-Override ohne effort läuft mit dem Standard-Effort-Level dieses Modells.

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 auf ihren Basisagenten zurückverfolgen.

Das folgende Beispiel startet eine Session, die das Modell überschreibt und den System-Prompt leert:

override_session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        "model": {"id": "claude-sonnet-5-5"},
        "system": None,  # clear the agent's system prompt for this session
    },
    environment_id=environment.id,
)
# Der Agent in der Antwort ist der aufgelöste Snapshot mit angewendeten Overrides.
print(f"Model: {override_session.agent.model.id}")
print(f"System: {override_session.agent.system}")

Die Inferenz-Geo für eine Session fixieren

Da ein model-Override das model-Objekt des Agenten vollständig ersetzt, setzt oder entfernt es auch die Fixierung der Inferenz-Geo des Modells für die Session: Ein Override, das inference_geo enthält, fixiert die Region, die die Modellanfragen der Session bedient, und eines, das es weglässt, entfernt die Fixierung des Agenten, sodass die Session der 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 es inference_geo in den model-Override aufnimmt, und gibt den Wert aus, der in agent.model der Antwort zurückgegeben wird:

session = client.beta.sessions.create(
    agent={
        "type": "agent_with_overrides",
        "id": agent.id,
        # Ersetzt das `model` des Agents vollständig: gib `id` erneut an, füge `inference_geo` zum Fixieren hinzu.
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
    },
    environment_id=environment.id,
)
print(f"Inference geo: {session.agent.model.inference_geo}")

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 "125" für 1,25 $. 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 wird mit dem Stop-Grund budget_reached inaktiv. 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 liegen können. Ein Budget kann nur bei der Erstellung angehängt werden: Du kannst es später ändern oder entfernen, aber du kannst keines zu einer Session hinzufügen, die ohne Budget erstellt wurde.

Das folgende Beispiel erstellt eine Session mit einem Budget von 1,25 $:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

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-Anmeldedaten zu referenzieren. Anthropic übernimmt die Token-Aktualisierung für dich. Unter Mit Vaults authentifizieren erfährst du, wie du Vaults erstellst und Anmeldedaten registrierst.

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

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 an die Session mithilfe eines User-Events. Um das erste Event stattdessen in der Erstellungsanfrage 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 steuern.

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

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

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

Nächste Schritte