Eine Sitzung starten

Eine Sitzung starten - Claude API Docs

Eine Sitzung ist eine laufende Agent-Instanz innerhalb einer Umgebung. Jede Sitzung verweist auf einen Agent und eine Umgebung (beide werden separat erstellt) und verwaltet den Gesprächsverlauf über mehrere Interaktionen hinweg.

Alle Managed Agents API-Anfragen erfordern den Beta-Header managed-agents-2026-04-01. Das SDK setzt den Beta-Header automatisch.

Eine Sitzung erstellen

Eine Sitzung erfordert eine agent-ID und eine environment-ID. Agenten sind versionierte Ressourcen; wenn Sie die agent-ID als Zeichenkette übergeben, wird die Sitzung mit der neuesten Agent-Version gestartet.

session=$(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"
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

Um eine Sitzung an eine bestimmte Agent-Version zu binden, übergeben Sie ein Objekt. Dies ermöglicht es Ihnen, genau zu kontrollieren, welche Version ausgeführt wird, und Rollouts neuer Versionen unabhängig zu inszenieren.

Der Agent definiert, wie Claude sich innerhalb der Sitzung verhält, einschließlich des Modells, des System-Prompts, der Tools und der MCP-Server. Weitere Informationen finden Sie unter Agent-Setup.

MCP-Authentifizierung über Vaults

Wenn Ihr Agent MCP-Tools verwendet, die eine Authentifizierung erfordern, übergeben Sie vault_ids bei der Sitzungserstellung, um auf einen Vault zu verweisen, der gespeicherte OAuth-Anmeldedaten enthält. Anthropic verwaltet die Token-Aktualisierung in Ihrem Namen. Weitere Informationen zum Erstellen von Vaults und zum Registrieren von Anmeldedaten finden Sie unter Mit Vaults authentifizieren.

Die Sitzung starten

Das Erstellen einer Sitzung stellt die Umgebung und den Agent bereit, startet aber keine Arbeit. Um eine Aufgabe zu delegieren, senden Sie Ereignisse an die Sitzung mit einem Benutzerereignis. Die Sitzung fungiert als eine Zustandsmaschine, die den Fortschritt verfolgt, während Ereignisse die tatsächliche Ausführung antreiben.

Weitere Informationen zum Streamen der Antworten des Agenten und zum Verarbeiten von Tool-Bestätigungen finden Sie unter Ereignisse und Streaming.

Sitzungsstatus

Sitzungen durchlaufen diese Status:

Status	Beschreibung
`idle`	Agent wartet auf Eingabe, einschließlich Benutzernachrichten oder Tool-Bestätigungen. Sitzungen beginnen im Status `idle`.
`running`	Agent führt aktiv aus
`rescheduling`	Vorübergehender Fehler aufgetreten, wird automatisch erneut versucht
`terminated`	Sitzung wurde aufgrund eines nicht behebbaren Fehlers beendet

Andere Sitzungsvorgänge

Eine Sitzung abrufen

Sitzungen auflisten

Eine Sitzung archivieren

Archivieren Sie eine Sitzung, um zu verhindern, dass neue Ereignisse gesendet werden, während Sie ihren Verlauf beibehalten:

Eine Sitzung löschen

Löschen Sie eine Sitzung, um ihren Datensatz, ihre Ereignisse und den zugehörigen Container dauerhaft zu entfernen. Eine running-Sitzung kann nicht gelöscht werden; senden Sie ein Interrupt-Ereignis, wenn Sie es sofort löschen müssen.

Dateien, Memory Stores, Umgebungen und Agenten sind unabhängige Ressourcen und werden durch das Löschen von Sitzungen nicht beeinflusst.

pinned_session=$(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": {"type": "agent", "id": "$AGENT_ID", "version": 1},
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")

vault_session=$(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",
  "vault_ids": ["$VAULT_ID"]
}
EOF
)
VAULT_SESSION_ID=$(jq -r '.id' <<< "$vault_session")

curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -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'
{
  "events": [
    {
      "type": "user.message",
      "content": [{"type": "text", "text": "List the files in the working directory."}]
    }
  ]
}
EOF

retrieved=$(curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
echo "Status: $(jq -r '.status' <<< "$retrieved")"

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" \
  | jq -r '.data[] | "\(.id): \(.status)"'

curl -fsSL -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

curl -fsSL -X DELETE "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"