Guide

Gestione delle Sessioni

Comprensione di come Claude Agent SDK gestisce le sessioni e la ripresa delle sessioni

Gestione delle Sessioni

Claude Agent SDK fornisce capacità di gestione delle sessioni per gestire lo stato della conversazione e la ripresa. Le sessioni ti permettono di continuare 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 acquisire questo ID per riprendere la sessione in seguito.

Ottenere l'ID della Sessione

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

let sessionId: string | undefined

const response = query({
  prompt: "Help me build a web application",
  options: {
    model: "claude-opus-4-6"
  }
})

for await (const message of response) {
  // The first message is a system init message with the session ID
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session started with ID: ${sessionId}`)
    // You can save this ID for later resumption
  }

  // Process other messages...
  console.log(message)
}

// Later, you can use the saved sessionId to resume
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue where we left off",
    options: {
      resume: sessionId
    }
  })
}

Ripresa delle Sessioni

L'SDK supporta la ripresa delle sessioni da stati di conversazione precedenti, abilitando flussi di lavoro di sviluppo continuo. Usa l'opzione resume con un ID di sessione per continuare una conversazione precedente.

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

// Resume a previous session using its ID
const response = query({
  prompt: "Continue implementing the authentication system from where we left off",
  options: {
    resume: "session-xyz", // Session ID from previous conversation
    model: "claude-opus-4-6",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// The conversation continues with full context from the previous session
for await (const message of response) {
  console.log(message)
}

L'SDK gestisce automaticamente il caricamento della cronologia della conversazione e del contesto quando riprendi una sessione, permettendo a Claude di continuare esattamente da dove si era fermato.

Per tracciare e ripristinare i cambiamenti dei file tra le sessioni, vedi File Checkpointing.

Diramazione delle Sessioni

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

Quando Diramare una Sessione

La diramazione è utile quando vuoi:

Esplorare approcci diversi dallo stesso punto di partenza
Creare più rami di conversazione senza modificare l'originale
Testare i cambiamenti senza influenzare la cronologia della sessione originale
Mantenere percorsi di conversazione separati per diversi esperimenti

Diramazione vs Continuazione

Comportamento	`forkSession: false` (predefinito)	`forkSession: true`
ID Sessione	Uguale all'originale	Nuovo ID di sessione generato
Cronologia	Aggiunge alla sessione originale	Crea un nuovo ramo dal punto di ripresa
Sessione Originale	Modificata	Preservata invariata
Caso d'Uso	Continua conversazione lineare	Dirama per esplorare alternative

Esempio: Diramazione di una Sessione

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

// First, capture the session ID
let sessionId: string | undefined

const response = query({
  prompt: "Help me design a REST API",
  options: { model: "claude-opus-4-6" }
})

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

// Fork the session to try a different approach
const forkedResponse = query({
  prompt: "Now let's redesign this as a GraphQL API instead",
  options: {
    resume: sessionId,
    forkSession: true,  // Creates a new session ID
    model: "claude-opus-4-6"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Forked session: ${message.session_id}`)
    // This will be a different session ID
  }
}

// The original session remains unchanged and can still be resumed
const originalContinued = query({
  prompt: "Add authentication to the REST API",
  options: {
    resume: sessionId,
    forkSession: false,  // Continue original session (default)
    model: "claude-opus-4-6"
  }
})

Was this page helpful?

Guide

Gestione delle Sessioni

Comprensione di come Claude Agent SDK gestisce le sessioni e la ripresa delle sessioni

Gestione delle Sessioni

Come Funzionano le Sessioni

Ottenere l'ID della Sessione

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

let sessionId: string | undefined

const response = query({
  prompt: "Help me build a web application",
  options: {
    model: "claude-opus-4-6"
  }
})

for await (const message of response) {
  // The first message is a system init message with the session ID
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session started with ID: ${sessionId}`)
    // You can save this ID for later resumption
  }

  // Process other messages...
  console.log(message)
}

// Later, you can use the saved sessionId to resume
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue where we left off",
    options: {
      resume: sessionId
    }
  })
}

Ripresa delle Sessioni

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

// Resume a previous session using its ID
const response = query({
  prompt: "Continue implementing the authentication system from where we left off",
  options: {
    resume: "session-xyz", // Session ID from previous conversation
    model: "claude-opus-4-6",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// The conversation continues with full context from the previous session
for await (const message of response) {
  console.log(message)
}

L'SDK gestisce automaticamente il caricamento della cronologia della conversazione e del contesto quando riprendi una sessione, permettendo a Claude di continuare esattamente da dove si era fermato.

Per tracciare e ripristinare i cambiamenti dei file tra le sessioni, vedi File Checkpointing.

Diramazione delle Sessioni

Quando Diramare una Sessione

La diramazione è utile quando vuoi:

Esplorare approcci diversi dallo stesso punto di partenza
Creare più rami di conversazione senza modificare l'originale
Testare i cambiamenti senza influenzare la cronologia della sessione originale
Mantenere percorsi di conversazione separati per diversi esperimenti

Diramazione vs Continuazione

Comportamento	`forkSession: false` (predefinito)	`forkSession: true`
ID Sessione	Uguale all'originale	Nuovo ID di sessione generato
Cronologia	Aggiunge alla sessione originale	Crea un nuovo ramo dal punto di ripresa
Sessione Originale	Modificata	Preservata invariata
Caso d'Uso	Continua conversazione lineare	Dirama per esplorare alternative

Esempio: Diramazione di una Sessione

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

// First, capture the session ID
let sessionId: string | undefined

const response = query({
  prompt: "Help me design a REST API",
  options: { model: "claude-opus-4-6" }
})

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

// Fork the session to try a different approach
const forkedResponse = query({
  prompt: "Now let's redesign this as a GraphQL API instead",
  options: {
    resume: sessionId,
    forkSession: true,  // Creates a new session ID
    model: "claude-opus-4-6"
  }
})

for await (const message of forkedResponse) {
  if (message.type === 'system' && message.subtype === 'init') {
    console.log(`Forked session: ${message.session_id}`)
    // This will be a different session ID
  }
}

// The original session remains unchanged and can still be resumed
const originalContinued = query({
  prompt: "Add authentication to the REST API",
  options: {
    resume: sessionId,
    forkSession: false,  // Continue original session (default)
    model: "claude-opus-4-6"
  }
})

Was this page helpful?