Skip to main content
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).

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
Chaque requête affiche la réponse textuelle de l’agent suivie d’une ligne d’état du message de résultat, telle que [done: success, cost: $0.0042]. 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
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.
Lorsque la requête se termine, le script affiche la réponse de l’agent suivie d’une ligne telle que Session ID: 5b3f2c1a-8d4e-4f6b-9a7c-2e1d0f9b8a6c. Dans les sections suivantes, vous transmettez cet ID à resume.

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 Gérer le résultat) ; reprenez avec une limite plus élevée. Dans un appel query() unique, le SDK lève une exception après avoir cédé ce résultat d’erreur, donc capturez l’erreur avant de reprendre.
  • 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 :
Vous devriez voir une réponse qui s’appuie sur l’analyse antérieure au lieu de recommencer à zéro. Cela confirme que l’agent a repris la session avec son contexte antérieur intact.
Claude Code stocke les sessions sous ~/.claude/projects/<encoded-cwd>/*.jsonl. Si vous définissez la variable d’environnement CLAUDE_CONFIG_DIR, cherchez plutôt sous $CLAUDE_CONFIG_DIR/projects/.Pour trouver le répertoire de votre session, remplacez chaque caractère non alphanumérique du répertoire de travail absolu par - : /Users/me/proj devient -Users-me-proj. Pour un répertoire de travail dont le nom converti dépasse 200 caractères, Claude Code tronque le nom et ajoute un hash, donc faites correspondre les 200 premiers caractères du nom converti lorsque vous listez projects/.Si vous définissez CLAUDE_CODE_PROJECT_DIR_NAME à côté de CLAUDE_CONFIG_DIR, cherchez plutôt sous ce nom dans projects/. Nécessite TypeScript Agent SDK v0.3.234 ou ultérieur, ou Python Agent SDK v0.2.140 ou ultérieur.Vous pouvez reprendre à partir de n’importe quel répertoire de travail :
  • Recherche inter-répertoires : Claude Code cherche au-delà du répertoire de projet actuel pour trouver l’ID ; voir Reprendre une session pour l’ordre de recherche exact et comment les copies en double sont gérées.
  • Même machine uniquement : le fichier de session doit toujours exister sur la machine actuelle.
Avant v2.1.223, la recherche était limitée au répertoire de projet actuel et à ses git worktrees ; les versions du SDK qui regroupent une CLI plus ancienne se comportent toujours de cette façon.
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 :
Vous devriez voir que forkedId diffère de l’ID de session original. Reprendre la session originale continue toujours le fil JWT, ce qui confirme que la bifurcation n’a pas modifié l’historique original.

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), choisissez l’approche qui convient :
  • Passer un magasin de session. Attachez un adaptateur sessionStore / session_store afin que le SDK reflète les transcriptions vers votre propre backend et un autre hôte puisse les reprendre. La clé de recherche du magasin dérive du répertoire de travail, donc reprenez à partir d’un cwd correspondant à l’exécution d’origine.
  • Déplacer le fichier de session. Persistez ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl de la première exécution et restaurez-le à l’intérieur de n’importe quel répertoire sous ~/.claude/projects/ sur le nouvel hôte avant d’appeler resume. Claude Code recherche au-delà du répertoire de projet actuel pour trouver l’ID ; consultez Reprendre une session pour l’ordre de recherche exact et la façon dont les copies en double sont traitées. Avant v2.1.223, la recherche était limitée au répertoire de projet actuel et à ses git worktrees ; les versions du SDK qui regroupent une CLI plus ancienne se comportent toujours de cette façon.
  • 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.