Passer au contenu principal
Une session est l’historique des conversations que le SDK accumule pendant que votre agent travaille. Elle contient votre prompt, chaque appel d’outil que l’agent a effectué, chaque résultat d’outil et chaque réponse. Le SDK l’écrit automatiquement sur le disque pour que vous puissiez y revenir plus tard. Revenir à une session signifie que l’agent a le contexte complet d’avant : les fichiers qu’il a déjà lus, l’analyse qu’il a déjà effectuée, les décisions qu’il a déjà prises. Vous pouvez poser une question de suivi, récupérer après une interruption ou vous brancher pour essayer une approche différente.
Les sessions conservent la conversation, pas le système de fichiers. Pour créer un instantané et annuler les modifications de fichiers que l’agent a apportées, utilisez file checkpointing.
Ce guide couvre comment choisir la bonne approche pour votre application, les interfaces du SDK qui suivent automatiquement les sessions, comment capturer les ID de session et utiliser resume et fork manuellement, et ce qu’il faut savoir sur la reprise des sessions sur plusieurs hôtes.

Choisir une approche

La quantité de gestion de session dont vous avez besoin dépend de la forme de votre application. La gestion des sessions entre en jeu lorsque vous envoyez plusieurs prompts qui doivent partager le contexte. Dans un seul appel query(), l’agent prend déjà autant de tours qu’il en a besoin, et les prompts de permission et AskUserQuestion sont gérés en boucle (ils ne terminent pas l’appel).
Ce que vous construisezCe qu’il faut utiliser
Tâche unique : prompt unique, pas de suiviRien d’extra. Un seul appel query() le gère.
Chat multi-tours dans un seul processusClaudeSDKClient (Python) ou continue: true (TypeScript). Le SDK suit la session pour vous sans gestion d’ID.
Reprendre là où vous vous êtes arrêté après un redémarrage de processuscontinue_conversation=True (Python) / continue: true (TypeScript). Reprend la session la plus récente du répertoire, aucun ID nécessaire.
Reprendre une session passée spécifique (pas la plus récente)Capturez l’ID de session et passez-le à resume.
Essayer une approche alternative sans perdre l’originalBifurquez la session.
Tâche sans état, ne voulez rien écrire sur le disque (TypeScript uniquement)Définissez persistSession: false. La session existe uniquement en mémoire pendant la durée de l’appel. Python persiste toujours sur le disque.

Continue, resume et fork

Continue, resume et fork sont des champs d’options que vous définissez sur query() (ClaudeAgentOptions en Python, Options en TypeScript). Continue et resume reprennent tous les deux une session existante et l’ajoutent. La différence est la façon dont ils trouvent cette session :
  • Continue trouve la session la plus récente dans le répertoire courant. Vous ne suivez rien. Fonctionne bien lorsque votre application exécute une conversation à la fois.
  • Resume prend un ID de session spécifique. Vous suivez l’ID. Requis lorsque vous avez plusieurs sessions (par exemple, une par utilisateur dans une application multi-utilisateurs) ou que vous voulez revenir à une qui n’est pas la plus récente.
Fork est différent : il crée une nouvelle session qui commence par une copie de l’historique de l’original. L’original reste inchangé. Utilisez fork pour essayer une direction différente tout en gardant la possibilité de revenir en arrière.

Gestion automatique des sessions

Les deux SDK offrent une interface qui suit l’état de la session pour vous entre les appels, vous n’avez donc pas besoin de passer les ID manuellement. Utilisez-les pour les conversations multi-tours dans un seul processus.

Python : ClaudeSDKClient

ClaudeSDKClient gère les ID de session en interne. Chaque appel à client.query() continue automatiquement la même session. Appelez client.receive_response() pour itérer sur les messages de la requête actuelle. Utilisez le client comme gestionnaire de contexte asynchrone afin que la configuration et l’arrêt de la connexion soient gérés pour vous, ou appelez connect() et disconnect() manuellement. Cet exemple exécute deux requêtes contre le même client. La première demande à l’agent d’analyser un module ; la seconde lui demande de refactoriser ce module. Parce que les deux appels passent par la même instance de client, la deuxième requête a le contexte complet de la première sans aucun resume ou ID de session explicite :
Python
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())
Consultez la référence du SDK Python pour plus de détails sur quand utiliser ClaudeSDKClient par rapport à la fonction query() autonome.

TypeScript : continue: true

Le SDK TypeScript n’a pas d’objet client tenant une session comme le ClaudeSDKClient de Python. À la place, passez continue: true sur chaque appel query() suivant et le SDK reprend la session la plus récente dans le répertoire courant. Aucun suivi d’ID requis. Cet exemple effectue deux appels query() séparés. Le premier crée une session nouvelle ; le second définit continue: true, ce qui indique au SDK de trouver et reprendre la session la plus récente sur le disque. L’agent a le contexte complet du premier appel :
TypeScript
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);
  }
}
L’API de session V2 expérimentale , qui fournissait createSession() avec un modèle send / stream, a été supprimée dans TypeScript Agent SDK 0.3.142. Utilisez la fonction query() et les options de session décrites sur cette page à la place.

Utiliser les options de session avec query()

Capturer l’ID de session

Resume et fork nécessitent un ID de session. Lisez-le à partir du champ session_id sur le message de résultat (ResultMessage en Python, SDKResultMessage en TypeScript), qui est présent sur chaque résultat indépendamment du succès ou de l’erreur. En TypeScript, l’ID est également disponible plus tôt en tant que champ direct sur le SystemMessage d’initialisation ; en Python, il est imbriqué dans SystemMessage.data.
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())

Reprendre par ID

Passez un ID de session à resume pour revenir à cette session spécifique. L’agent reprend avec le contexte complet d’où la session s’est arrêtée. Les raisons courantes de reprendre :
  • Faire un suivi sur une tâche terminée. L’agent a déjà analysé quelque chose ; maintenant vous voulez qu’il agisse sur cette analyse sans relire les fichiers.
  • Récupérer d’une limite. La première exécution s’est terminée avec error_max_turns ou error_max_budget_usd (voir Handle the result) ; reprenez avec une limite plus élevée.
  • Redémarrer votre processus. Vous avez capturé l’ID avant l’arrêt et voulez restaurer la conversation.
Cet exemple reprend la session de Capturer l’ID de session avec un prompt de suivi. Parce que vous reprenez, l’agent a déjà l’analyse antérieure en contexte :
# 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)
Si un appel resume retourne une session nouvelle au lieu de l’historique attendu, la cause la plus courante est un cwd non correspondant. Les sessions sont stockées sous ~/.claude/projects/<encoded-cwd>/*.jsonl, où <encoded-cwd> est le répertoire de travail absolu avec chaque caractère non alphanumérique remplacé par - (donc /Users/me/proj devient -Users-me-proj). Si votre appel resume s’exécute à partir d’un répertoire différent, le SDK cherche au mauvais endroit. Le fichier de session doit également exister sur la machine actuelle.
Pour reprendre les sessions sur plusieurs machines ou dans des environnements sans serveur, mettez en miroir les transcriptions vers un stockage partagé avec un adaptateur SessionStore.

Bifurquer pour explorer les alternatives

La bifurcation crée une nouvelle session qui commence par une copie de l’historique de l’original mais diverge à partir de ce point. La bifurcation obtient son propre ID de session ; l’ID et l’historique de l’original restent inchangés. Vous vous retrouvez avec deux sessions indépendantes que vous pouvez reprendre séparément.
La bifurcation branche l’historique de la conversation, pas le système de fichiers. Si un agent bifurqué modifie des fichiers, ces modifications sont réelles et visibles pour toute session travaillant dans le même répertoire. Pour brancher et annuler les modifications de fichiers, utilisez file checkpointing.
Cet exemple s’appuie sur Capturer l’ID de session : vous avez déjà analysé un module d’authentification dans session_id et voulez explorer OAuth2 sans perdre le fil axé sur JWT. Le premier bloc bifurque la session et capture l’ID de la bifurcation (forked_id) ; le deuxième bloc reprend le session_id original pour continuer sur le chemin JWT. Vous avez maintenant deux ID de session pointant vers deux historiques séparés :
# 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)

Reprendre sur plusieurs hôtes

Les fichiers de session sont locaux à la machine qui les a créés. Pour reprendre une session sur un hôte différent (travailleurs CI, conteneurs éphémères, sans serveur), vous avez deux options :
  • Déplacer le fichier de session. Persistez ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl de la première exécution et restaurez-le au même chemin sur le nouvel hôte avant d’appeler resume. Le cwd doit correspondre.
  • Ne pas compter sur la reprise de session. Capturez les résultats dont vous avez besoin (sortie d’analyse, décisions, diffs de fichiers) en tant qu’état d’application et passez-les dans le prompt d’une session nouvelle. C’est souvent plus robuste que d’expédier des fichiers de transcription.
Les deux SDK exposent des fonctions pour énumérer les sessions sur le disque et lire leurs messages : listSessions() et getSessionMessages() en TypeScript, list_sessions() et get_session_messages() en Python. Utilisez-les pour construire des sélecteurs de session personnalisés, une logique de nettoyage ou des visionneuses de transcription. Les deux SDK exposent également des fonctions pour rechercher et muter des sessions individuelles : get_session_info(), rename_session() et tag_session() en Python, et getSessionInfo(), renameSession() et tagSession() en TypeScript. Utilisez-les pour organiser les sessions par tag ou leur donner des titres lisibles par l’homme.

Ressources connexes