​
Gestion des Sessions

Le SDK Claude Agent fournit des capacités de gestion de session pour gérer l’état de conversation et la reprise. Les sessions vous permettent de continuer les conversations à travers plusieurs interactions tout en maintenant le contexte complet.

​
Comment Fonctionnent les Sessions

Lorsque vous démarrez une nouvelle requête, le SDK crée automatiquement une session et retourne un ID de session dans le message système initial. Vous pouvez capturer cet ID pour reprendre la session plus tard.

​
Obtenir l’ID de Session

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

let sessionId: string | undefined

const response = query({
  prompt: "Aidez-moi à construire une application web",
  options: {
    model: "claude-sonnet-4-5"
  }
})

for await (const message of response) {
  // Le premier message est un message d'initialisation système avec l'ID de session
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session démarrée avec l'ID : ${sessionId}`)
    // Vous pouvez sauvegarder cet ID pour une reprise ultérieure
  }

  // Traiter les autres messages...
  console.log(message)
}

// Plus tard, vous pouvez utiliser le sessionId sauvegardé pour reprendre
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continuez là où nous nous sommes arrêtés",
    options: {
      resume: sessionId
    }
  })
}

​
Reprendre les Sessions

Le SDK prend en charge la reprise de sessions à partir d’états de conversation précédents, permettant des flux de travail de développement continus. Utilisez l’option resume avec un ID de session pour continuer une conversation précédente. 
import { query } from "@anthropic-ai/claude-agent-sdk"

// Reprendre une session précédente en utilisant son ID
const response = query({
  prompt: "Continuez l'implémentation du système d'authentification là où nous nous sommes arrêtés",
  options: {
    resume: "session-xyz", // ID de session de la conversation précédente
    model: "claude-sonnet-4-5",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// La conversation continue avec le contexte complet de la session précédente
for await (const message of response) {
  console.log(message)
}
Le SDK gère automatiquement le chargement de l’historique de conversation et du contexte lorsque vous reprenez une session, permettant à Claude de continuer exactement là où il s’était arrêté.

​
Bifurquer les Sessions

Lors de la reprise d’une session, vous pouvez choisir soit de continuer la session originale soit de la bifurquer en une nouvelle branche. Par défaut, reprendre continue la session originale. Utilisez l’option forkSession (TypeScript) ou l’option fork_session (Python) pour créer un nouvel ID de session qui démarre à partir de l’état repris.

​
Quand Bifurquer une Session

La bifurcation est utile lorsque vous voulez :
  • Explorer différentes approches à partir du même point de départ
  • Créer plusieurs branches de conversation sans modifier l’originale
  • Tester des changements sans affecter l’historique de session original
  • Maintenir des chemins de conversation séparés pour différentes expériences

​
Bifurquer vs Continuer

ComportementforkSession: false (par défaut)forkSession: true
ID de SessionIdentique à l’originalNouvel ID de session généré
HistoriqueS’ajoute à la session originaleCrée une nouvelle branche à partir du point de reprise
Session OriginaleModifiéePréservée inchangée
Cas d’UsageContinuer une conversation linéaireBifurquer pour explorer des alternatives

​
Exemple : Bifurquer une Session

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

// D'abord, capturer l'ID de session
let sessionId: string | undefined

const response = query({
  prompt: "Aidez-moi à concevoir une API REST",
  options: { model: "claude-sonnet-4-5" }
})

for await (const message of response) {
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session originale : ${sessionId}`)
  }
}

// Bifurquer la session pour essayer une approche différente
const forkedResponse = query({
  prompt: "Maintenant, redessinons ceci comme une API GraphQL à la place",
  options: {
    resume: sessionId,
    forkSession: true,  // Crée un nouvel ID de session
    model: "claude-sonnet-4-5"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Session bifurquée : ${message.session_id}`)
    // Ce sera un ID de session différent
  }
}

// La session originale reste inchangée et peut toujours être reprise
const originalContinued = query({
  prompt: "Ajoutez l'authentification à l'API REST",
  options: {
    resume: sessionId,
    forkSession: false,  // Continuer la session originale (par défaut)
    model: "claude-sonnet-4-5"
  }
})