​
Session-Verwaltung

Das Claude Agent SDK bietet Session-Verwaltungsfunktionen für die Handhabung von Gesprächszuständen und -wiederaufnahme. Sessions ermöglichen es Ihnen, Gespräche über mehrere Interaktionen hinweg fortzusetzen, während der vollständige Kontext beibehalten wird.

​
Wie Sessions funktionieren

Wenn Sie eine neue Abfrage starten, erstellt das SDK automatisch eine Session und gibt eine Session-ID in der ersten Systemnachricht zurück. Sie können diese ID erfassen, um die Session später wieder aufzunehmen.

​
Abrufen der Session-ID

import { query } from "@anthropic-ai/claude-agent-sdk"

let sessionId: string | undefined

const response = query({
  prompt: "Hilf mir beim Erstellen einer Webanwendung",
  options: {
    model: "claude-sonnet-4-5"
  }
})

for await (const message of response) {
  // Die erste Nachricht ist eine System-Init-Nachricht mit der Session-ID
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session gestartet mit ID: ${sessionId}`)
    // Sie können diese ID für spätere Wiederaufnahme speichern
  }

  // Andere Nachrichten verarbeiten...
  console.log(message)
}

// Später können Sie die gespeicherte sessionId verwenden, um fortzufahren
if (sessionId) {
  const resumedResponse = query({
    prompt: "Dort weitermachen, wo wir aufgehört haben",
    options: {
      resume: sessionId
    }
  })
}

​
Sessions wiederaufnehmen

Das SDK unterstützt die Wiederaufnahme von Sessions aus vorherigen Gesprächszuständen und ermöglicht kontinuierliche Entwicklungsworkflows. Verwenden Sie die resume-Option mit einer Session-ID, um ein vorheriges Gespräch fortzusetzen. 
import { query } from "@anthropic-ai/claude-agent-sdk"

// Eine vorherige Session mit ihrer ID wiederaufnehmen
const response = query({
  prompt: "Setze die Implementierung des Authentifizierungssystems dort fort, wo wir aufgehört haben",
  options: {
    resume: "session-xyz", // Session-ID aus vorherigem Gespräch
    model: "claude-sonnet-4-5",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// Das Gespräch wird mit vollständigem Kontext aus der vorherigen Session fortgesetzt
for await (const message of response) {
  console.log(message)
}
Das SDK übernimmt automatisch das Laden der Gesprächshistorie und des Kontexts, wenn Sie eine Session wiederaufnehmen, wodurch Claude genau dort fortfahren kann, wo es aufgehört hat.

​
Sessions verzweigen

Beim Wiederaufnehmen einer Session können Sie wählen, ob Sie die ursprüngliche Session fortsetzen oder sie in einen neuen Zweig verzweigen möchten. Standardmäßig setzt die Wiederaufnahme die ursprüngliche Session fort. Verwenden Sie die forkSession-Option (TypeScript) oder fork_session-Option (Python), um eine neue Session-ID zu erstellen, die vom wiederaufgenommenen Zustand ausgeht.

​
Wann eine Session verzweigt werden sollte

Verzweigung ist nützlich, wenn Sie:
  • Verschiedene Ansätze vom gleichen Ausgangspunkt aus erkunden möchten
  • Mehrere Gesprächszweige erstellen möchten, ohne das Original zu verändern
  • Änderungen testen möchten, ohne die ursprüngliche Session-Historie zu beeinträchtigen
  • Separate Gesprächspfade für verschiedene Experimente beibehalten möchten

​
Verzweigen vs. Fortsetzen

VerhaltenforkSession: false (Standard)forkSession: true
Session-IDGleich wie OriginalNeue Session-ID generiert
HistorieWird an ursprüngliche Session angehängtErstellt neuen Zweig vom Wiederaufnahmepunkt
Ursprüngliche SessionVerändertUnverändert erhalten
AnwendungsfallLineares Gespräch fortsetzenVerzweigen, um Alternativen zu erkunden

​
Beispiel: Eine Session verzweigen

import { query } from "@anthropic-ai/claude-agent-sdk"

// Zuerst die Session-ID erfassen
let sessionId: string | undefined

const response = query({
  prompt: "Hilf mir beim Entwerfen einer REST-API",
  options: { model: "claude-sonnet-4-5" }
})

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Ursprüngliche Session: ${sessionId}`)
  }
}

// Die Session verzweigen, um einen anderen Ansatz zu versuchen
const forkedResponse = query({
  prompt: "Lass uns das jetzt stattdessen als GraphQL-API neu entwerfen",
  options: {
    resume: sessionId,
    forkSession: true,  // Erstellt eine neue Session-ID
    model: "claude-sonnet-4-5"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Verzweigte Session: ${message.session_id}`)
    // Dies wird eine andere Session-ID sein
  }
}

// Die ursprüngliche Session bleibt unverändert und kann weiterhin wiederaufgenommen werden
const originalContinued = query({
  prompt: "Füge Authentifizierung zur REST-API hinzu",
  options: {
    resume: sessionId,
    forkSession: false,  // Ursprüngliche Session fortsetzen (Standard)
    model: "claude-sonnet-4-5"
  }
})