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.
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 appelquery(), 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 construisez | Ce qu’il faut utiliser |
|---|---|
| Tâche unique : prompt unique, pas de suivi | Rien d’extra. Un seul appel query() le gère. |
| Chat multi-tours dans un seul processus | ClaudeSDKClient (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 processus | continue_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’original | Bifurquez 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 surquery() (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.
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
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
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 champsession_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.
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_turnsouerror_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.
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.
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 :
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>.jsonlde la première exécution et restaurez-le au même chemin sur le nouvel hôte avant d’appelerresume. Lecwddoit 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.
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
- How the agent loop works : Comprendre les tours, les messages et l’accumulation de contexte dans une session
- File checkpointing : Snapshot et annuler les modifications de fichiers que l’agent a effectuées au cours d’une session
- Python
ClaudeAgentOptions: Référence complète des options de session pour Python - TypeScript
Options: Référence complète des options de session pour TypeScript