​
Gestione delle Sessioni

Il Claude Agent SDK fornisce capacità di gestione delle sessioni per gestire lo stato delle conversazioni e la ripresa. Le sessioni ti permettono di continuare le conversazioni attraverso più interazioni mantenendo il contesto completo.

​
Come Funzionano le Sessioni

Quando avvii una nuova query, l’SDK crea automaticamente una sessione e restituisce un ID di sessione nel messaggio di sistema iniziale. Puoi catturare questo ID per riprendere la sessione in seguito.

​
Ottenere l’ID di Sessione

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

let sessionId: string | undefined

const response = query({
  prompt: "Aiutami a costruire un'applicazione web",
  options: {
    model: "claude-sonnet-4-5"
  }
})

for await (const message of response) {
  // Il primo messaggio è un messaggio di inizializzazione del sistema con l'ID di sessione
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Sessione avviata con ID: ${sessionId}`)
    // Puoi salvare questo ID per la ripresa successiva
  }

  // Elabora altri messaggi...
  console.log(message)
}

// Successivamente, puoi usare il sessionId salvato per riprendere
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continua da dove avevamo lasciato",
    options: {
      resume: sessionId
    }
  })
}

​
Riprendere le Sessioni

L’SDK supporta la ripresa delle sessioni da stati di conversazione precedenti, abilitando flussi di lavoro di sviluppo continui. Usa l’opzione resume con un ID di sessione per continuare una conversazione precedente. 
import { query } from "@anthropic-ai/claude-agent-sdk"

// Riprendi una sessione precedente usando il suo ID
const response = query({
  prompt: "Continua a implementare il sistema di autenticazione da dove avevamo lasciato",
  options: {
    resume: "session-xyz", // ID di sessione dalla conversazione precedente
    model: "claude-sonnet-4-5",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// La conversazione continua con il contesto completo dalla sessione precedente
for await (const message of response) {
  console.log(message)
}
L’SDK gestisce automaticamente il caricamento della cronologia delle conversazioni e del contesto quando riprendi una sessione, permettendo a Claude di continuare esattamente da dove aveva lasciato.

​
Biforcazione delle Sessioni

Quando riprendi una sessione, puoi scegliere di continuare la sessione originale o biforcala in un nuovo ramo. Per impostazione predefinita, la ripresa continua la sessione originale. Usa l’opzione forkSession (TypeScript) o l’opzione fork_session (Python) per creare un nuovo ID di sessione che inizia dallo stato ripreso.

​
Quando Biforcare una Sessione

La biforcazione è utile quando vuoi:
  • Esplorare approcci diversi dallo stesso punto di partenza
  • Creare più rami di conversazione senza modificare l’originale
  • Testare modifiche senza influenzare la cronologia della sessione originale
  • Mantenere percorsi di conversazione separati per esperimenti diversi

​
Biforcazione vs Continuazione

ComportamentoforkSession: false (predefinito)forkSession: true
ID di SessioneStesso dell’originaleNuovo ID di sessione generato
CronologiaSi aggiunge alla sessione originaleCrea un nuovo ramo dal punto di ripresa
Sessione OriginaleModificataPreservata invariata
Caso d’UsoContinua conversazione lineareBiforca per esplorare alternative

​
Esempio: Biforcazione di una Sessione

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

// Prima, cattura l'ID di sessione
let sessionId: string | undefined

const response = query({
  prompt: "Aiutami a progettare un'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(`Sessione originale: ${sessionId}`)
  }
}

// Biforca la sessione per provare un approccio diverso
const forkedResponse = query({
  prompt: "Ora riprogettiamolacome un'API GraphQL invece",
  options: {
    resume: sessionId,
    forkSession: true,  // Crea un nuovo ID di sessione
    model: "claude-sonnet-4-5"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Sessione biforcata: ${message.session_id}`)
    // Questo sarà un ID di sessione diverso
  }
}

// La sessione originale rimane invariata e può ancora essere ripresa
const originalContinued = query({
  prompt: "Aggiungi l'autenticazione all'API REST",
  options: {
    resume: sessionId,
    forkSession: false,  // Continua la sessione originale (predefinito)
    model: "claude-sonnet-4-5"
  }
})