SpyBara
Go Premium

agent-sdk/sessions.md 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC

324 added, 0 removed.

2026
Sun 31 06:39 Sat 30 06:23 Fri 29 06:38 Thu 28 06:37 Wed 27 06:42 Tue 26 06:33 Sun 24 06:25 Sat 23 06:18 Fri 22 06:33 Thu 21 06:36 Wed 20 06:35 Tue 19 06:34 Mon 18 23:59 Sun 17 01:01 Fri 15 22:58 Thu 14 17:02 Wed 13 23:01 Tue 12 22:57 Mon 11 23:00 Sun 10 23:03 Sat 9 04:57 Fri 8 22:00 Thu 7 22:59 Tue 5 23:00 Mon 4 22:58 Sat 2 18:14 Fri 1 18:19

Mit Sitzungen arbeiten

Wie Sitzungen die Gesprächsverlauf des Agenten speichern, und wann Sie continue, resume und fork verwenden, um zu einem früheren Durchlauf zurückzukehren.

Eine Sitzung ist der Gesprächsverlauf, den das SDK während der Arbeit Ihres Agenten sammelt. Sie enthält Ihren Prompt, jeden Werkzeugaufruf, den der Agent durchgeführt hat, jedes Werkzeugergebnis und jede Antwort. Das SDK schreibt sie automatisch auf die Festplatte, damit Sie später zu ihr zurückkehren können.

Zu einer Sitzung zurückzukehren bedeutet, dass der Agent den vollständigen Kontext von zuvor hat: Dateien, die er bereits gelesen hat, Analysen, die er bereits durchgeführt hat, Entscheidungen, die er bereits getroffen hat. Sie können eine Anschlussfrage stellen, sich von einer Unterbrechung erholen oder einen anderen Ansatz ausprobieren.

Dieser Leitfaden behandelt, wie Sie den richtigen Ansatz für Ihre App wählen, die SDK-Schnittstellen, die Sitzungen automatisch verfolgen, wie Sie Sitzungs-IDs erfassen und resume und fork manuell verwenden, und was Sie über das Fortsetzen von Sitzungen über Hosts hinweg wissen müssen.

Wählen Sie einen Ansatz

Wie viel Sitzungsverwaltung Sie benötigen, hängt von der Form Ihrer Anwendung ab. Die Sitzungsverwaltung kommt ins Spiel, wenn Sie mehrere Prompts senden, die Kontext teilen sollten. Innerhalb eines einzelnen query()-Aufrufs nimmt der Agent bereits so viele Durchläufe vor, wie nötig, und Berechtigungsprompts und AskUserQuestion werden in-loop verarbeitet (sie beenden den Aufruf nicht).

Was Sie erstellen Was Sie verwenden
Einmalige Aufgabe: einzelner Prompt, keine Anschlussfrage Nichts Zusätzliches. Ein query()-Aufruf verarbeitet es.
Multi-Turn-Chat in einem Prozess ClaudeSDKClient (Python) oder continue: true (TypeScript). Das SDK verfolgt die Sitzung für Sie ohne ID-Verwaltung.
Dort weitermachen, wo Sie nach einem Prozessneustart aufgehört haben continue_conversation=True (Python) / continue: true (TypeScript). Setzt die neueste Sitzung im Verzeichnis fort, keine ID erforderlich.
Eine bestimmte frühere Sitzung fortsetzen (nicht die neueste) Erfassen Sie die Sitzungs-ID und übergeben Sie sie an resume.
Einen alternativen Ansatz ausprobieren, ohne das Original zu verlieren Forken Sie die Sitzung.
Zustandslose Aufgabe, möchten nichts auf die Festplatte geschrieben haben (nur TypeScript) Setzen Sie persistSession: false. Die Sitzung existiert nur im Speicher für die Dauer des Aufrufs. Python speichert immer auf der Festplatte.

Continue, resume und fork

Continue, resume und fork sind Optionsfelder, die Sie auf query() setzen (ClaudeAgentOptions in Python, Options in TypeScript).

Continue und resume holen beide eine vorhandene Sitzung ab und fügen sie hinzu. Der Unterschied liegt darin, wie sie diese Sitzung finden:

  • Continue findet die neueste Sitzung im aktuellen Verzeichnis. Sie müssen nichts verfolgen. Funktioniert gut, wenn Ihre App jeweils ein Gespräch führt.
  • Resume nimmt eine bestimmte Sitzungs-ID. Sie verfolgen die ID. Erforderlich, wenn Sie mehrere Sitzungen haben (z. B. eine pro Benutzer in einer Multi-User-App) oder zu einer zurückkehren möchten, die nicht die neueste ist.

Fork ist anders: Es erstellt eine neue Sitzung, die mit einer Kopie des Verlaufs des Originals beginnt. Das Original bleibt unverändert. Verwenden Sie fork, um eine andere Richtung auszuprobieren und gleichzeitig die Möglichkeit zu behalten, zurückzugehen.

Automatische Sitzungsverwaltung

Beide SDKs bieten eine Schnittstelle, die den Sitzungszustand für Sie über Aufrufe hinweg verfolgt, sodass Sie IDs nicht manuell weitergeben müssen. Verwenden Sie diese für Multi-Turn-Gespräche innerhalb eines einzelnen Prozesses.

Python: ClaudeSDKClient

ClaudeSDKClient verwaltet Sitzungs-IDs intern. Jeder Aufruf von client.query() setzt automatisch die gleiche Sitzung fort. Rufen Sie client.receive_response() auf, um über die Nachrichten für die aktuelle Abfrage zu iterieren. Der Client muss als asynchroner Kontext-Manager verwendet werden.

Dieses Beispiel führt zwei Abfragen gegen denselben client aus. Die erste fordert den Agent auf, ein Modul zu analysieren; die zweite fordert ihn auf, dieses Modul zu refaktorieren. Da beide Aufrufe durch die gleiche Client-Instanz gehen, hat die zweite Abfrage den vollständigen Kontext aus der ersten, ohne explizites resume oder Sitzungs-ID:

import asyncio
from claude_agent_sdk import (
    ClaudeSDKClient,
    ClaudeAgentOptions,
    AssistantMessage,
    ResultMessage,
    TextBlock,
)


def print_response(message):
    """Print only the human-readable parts of a message."""
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(block.text)
    elif isinstance(message, ResultMessage):
        cost = (
            f"${message.total_cost_usd:.4f}"
            if message.total_cost_usd is not None
            else "N/A"
        )
        print(f"[done: {message.subtype}, cost: {cost}]")


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Glob", "Grep"],
    )

    async with ClaudeSDKClient(options=options) as client:
        # First query: client captures the session ID internally
        await client.query("Analyze the auth module")
        async for message in client.receive_response():
            print_response(message)

        # Second query: automatically continues the same session
        await client.query("Now refactor it to use JWT")
        async for message in client.receive_response():
            print_response(message)


asyncio.run(main())

Siehe die Python SDK-Referenz für Details, wann Sie ClaudeSDKClient gegenüber der eigenständigen query()-Funktion verwenden sollten.

TypeScript: continue: true

Das stabile TypeScript SDK (die query()-Funktion, die in diesen Dokumenten verwendet wird, manchmal V1 genannt) hat kein Sitzungs-Halter-Client-Objekt wie Pythons ClaudeSDKClient. Übergeben Sie stattdessen continue: true bei jedem nachfolgenden query()-Aufruf und das SDK holt die neueste Sitzung im aktuellen Verzeichnis ab. Keine ID-Verfolgung erforderlich.

Dieses Beispiel macht zwei separate query()-Aufrufe. Der erste erstellt eine neue Sitzung; der zweite setzt continue: true, was dem SDK mitteilt, die neueste Sitzung auf der Festplatte zu finden und fortzusetzen. Der Agent hat den vollständigen Kontext aus dem ersten Aufruf:

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

// First query: creates a new session
for await (const message of query({
  prompt: "Analyze the auth module",
  options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

// Second query: continue: true resumes the most recent session
for await (const message of query({
  prompt: "Now refactor it to use JWT",
  options: {
    continue: true,
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Verwenden Sie Sitzungsoptionen mit query()

Erfassen Sie die Sitzungs-ID

Resume und fork erfordern eine Sitzungs-ID. Lesen Sie sie aus dem session_id-Feld in der Ergebnismeldung (ResultMessage in Python, SDKResultMessage in TypeScript), die bei jedem Ergebnis unabhängig von Erfolg oder Fehler vorhanden ist. In TypeScript ist die ID auch früher als direktes Feld in der Init-SystemMessage verfügbar; in Python ist sie in SystemMessage.data verschachtelt.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
session_id = None

async for message in query(
prompt="Analyze the auth module and suggest improvements",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"],
),
):
if isinstance(message, ResultMessage):
session_id = message.session_id
if message.subtype == "success":
print(message.result)

print(f"Session ID: {session_id}")
return session_id


session_id = asyncio.run(main())

Fortsetzen nach ID

Übergeben Sie eine Sitzungs-ID an resume, um zu dieser bestimmten Sitzung zurückzukehren. Der Agent setzt mit vollständigem Kontext von dort fort, wo die Sitzung endete. Häufige Gründe zum Fortsetzen:

  • Folgen Sie einer abgeschlossenen Aufgabe. Der Agent hat bereits etwas analysiert; jetzt möchten Sie, dass er auf dieser Analyse handelt, ohne Dateien erneut zu lesen.
  • Erholen Sie sich von einem Limit. Der erste Durchlauf endete mit error_max_turns oder error_max_budget_usd (siehe Verarbeiten Sie das Ergebnis); setzen Sie mit einem höheren Limit fort.
  • Starten Sie Ihren Prozess neu. Sie haben die ID vor dem Herunterfahren erfasst und möchten das Gespräch wiederherstellen.

Dieses Beispiel setzt die Sitzung aus Erfassen Sie die Sitzungs-ID mit einem Anschlussfrage fort. Da Sie fortsetzen, hat der Agent die vorherige Analyse bereits im Kontext:

# Earlier session analyzed the code; now build on that analysis
async for message in query(
prompt="Now implement the refactoring you suggested",
options=ClaudeAgentOptions(
resume=session_id,
allowed_tools=["Read", "Edit", "Write", "Glob", "Grep"],
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)

Um Sitzungen über Maschinen hinweg oder in serverlosen Umgebungen fortzusetzen, spiegeln Sie Transkripte mit einem SessionStore-Adapter zu gemeinsam genutztem Speicher.

Forken Sie, um Alternativen zu erkunden

Das Forken erstellt eine neue Sitzung, die mit einer Kopie des Verlaufs des Originals beginnt, aber von diesem Punkt an abweicht. Der Fork erhält seine eigene Sitzungs-ID; die ID und der Verlauf des Originals bleiben unverändert. Sie erhalten zwei unabhängige Sitzungen, die Sie separat fortsetzen können.

Dieses Beispiel baut auf Erfassen Sie die Sitzungs-ID auf: Sie haben bereits ein Auth-Modul in session_id analysiert und möchten OAuth2 erkunden, ohne den JWT-fokussierten Thread zu verlieren. Der erste Block forkt die Sitzung und erfasst die ID des Forks (forked_id); der zweite Block setzt die ursprüngliche session_id fort, um den JWT-Pfad fortzusetzen. Sie haben jetzt zwei Sitzungs-IDs, die auf zwei separate Verläufe verweisen:

# Fork: branch from session_id into a new session
forked_id = None
async for message in query(
prompt="Instead of JWT, implement OAuth2 for the auth module",
options=ClaudeAgentOptions(
resume=session_id,
fork_session=True,
),
):
if isinstance(message, ResultMessage):
forked_id = message.session_id  # The fork's ID, distinct from session_id
if message.subtype == "success":
print(message.result)

print(f"Forked session: {forked_id}")

# Original session is untouched; resuming it continues the JWT thread
async for message in query(
prompt="Continue with the JWT approach",
options=ClaudeAgentOptions(resume=session_id),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)

Fortsetzen über Hosts hinweg

Sitzungsdateien sind lokal auf dem Computer, der sie erstellt hat. Um eine Sitzung auf einem anderen Host fortzusetzen (CI-Worker, kurzlebige Container, serverlos), haben Sie zwei Optionen:

  • Verschieben Sie die Sitzungsdatei. Speichern Sie ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl aus dem ersten Durchlauf und stellen Sie es auf dem neuen Host auf dem gleichen Pfad wieder her, bevor Sie resume aufrufen. Das cwd muss übereinstimmen.
  • Verlassen Sie sich nicht auf Sitzungsfortsetzen. Erfassen Sie die Ergebnisse, die Sie benötigen (Analyseergebnis, Entscheidungen, Datei-Diffs) als Anwendungszustand und übergeben Sie sie in den Prompt einer neuen Sitzung. Dies ist oft robuster als das Verschiffen von Transkriptdateien.

Beide SDKs stellen Funktionen zum Aufzählen von Sitzungen auf der Festplatte und zum Lesen ihrer Nachrichten bereit: listSessions() und getSessionMessages() in TypeScript, list_sessions() und get_session_messages() in Python. Verwenden Sie sie, um benutzerdefinierte Sitzungsauswähler, Bereinigungslogik oder Transkript-Viewer zu erstellen.

Beide SDKs stellen auch Funktionen zum Nachschlagen und Mutieren einzelner Sitzungen bereit: get_session_info(), rename_session() und tag_session() in Python, und getSessionInfo(), renameSession() und tagSession() in TypeScript. Verwenden Sie sie, um Sitzungen nach Tag zu organisieren oder ihnen menschenlesbare Titel zu geben.

Verwandte Ressourcen