Travailler avec les sessions

Comment les sessions conservent l'historique des conversations de l'agent, et quand utiliser continue, resume et fork pour revenir à une exécution antérieure.

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.

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 :

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())

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 :

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

// First query: creates a new session
try {
  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);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result,
  // so the follow-up query below still runs.
  console.error(`Session ended with an error: ${error}`);
}

// 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);
  }
}

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

try:
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)
except Exception as error:
# A single-shot query() raises after yielding an error result. If the
# failure was an error result, the loop above already captured session_id;
# connection or process failures yield no result message, so session_id stays None.
print(f"Session ended with an error: {error}")

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


session_id = asyncio.run(main())

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

let sessionId: string | undefined;

try {
for await (const message of query({
prompt: "Analyze the auth module and suggest improvements",
options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
if (message.type === "result") {
sessionId = message.session_id;
if (message.subtype === "success") {
console.log(message.result);
}
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the loop above already captured sessionId;
// connection or process failures yield no result message, so sessionId stays undefined.
console.error(`Session ended with an error: ${error}`);
}

console.log(`Session ID: ${sessionId}`);

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 :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

session_id = "..."  # The ID you captured in the previous example


async def main():
# 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)


asyncio.run(main())

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

const sessionId = "..."; // The ID you captured in the previous example

// Earlier session analyzed the code; now build on that analysis
for await (const message of query({
prompt: "Now implement the refactoring you suggested",
options: {
resume: sessionId,
allowedTools: ["Read", "Edit", "Write", "Glob", "Grep"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

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.

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.

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 :

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

session_id = "..."  # The ID you captured in the previous example


async def main():
# Fork: branch from session_id into a new session
forked_id = None
try:
async for message in query(
prompt="Instead of JWT, outline how OAuth2 would work for the auth module",
options=ClaudeAgentOptions(
resume=session_id,
fork_session=True,
max_turns=5,
),
):
if isinstance(message, ResultMessage):
forked_id = message.session_id  # The fork's ID, distinct from session_id
if message.subtype == "success":
print(message.result)
except Exception as error:
# A single-shot query() raises after yielding an error result. If the
# failure was an error result, forked_id was already captured by the
# loop above; connection or process failures yield no result message.
print(f"Session ended with an error: {error}")

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

# Original session is untouched; resuming it continues the JWT thread
try:
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)
except Exception as error:
# A single-shot query() raises after yielding an error result.
print(f"Session ended with an error: {error}")


asyncio.run(main())

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

const sessionId = "..."; // The ID you captured in the previous example

// Fork: branch from sessionId into a new session
let forkedId: string | undefined;

try {
for await (const message of query({
prompt: "Instead of JWT, outline how OAuth2 would work for the auth module",
options: {
resume: sessionId,
forkSession: true,
maxTurns: 5
}
})) {
if (message.type === "system" && message.subtype === "init") {
forkedId = message.session_id; // The fork's ID, distinct from sessionId
}
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, forkedId was already captured by the loop
// above; connection or process failures yield no result message.
console.error(`Session ended with an error: ${error}`);
}

console.log(`Forked session: ${forkedId}`);

// Original session is untouched; resuming it continues the JWT thread
try {
for await (const message of query({
prompt: "Continue with the JWT approach",
options: { resume: sessionId }
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result.
console.error(`Session ended with an error: ${error}`);
}

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.

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