Skip to main content
Una sessione è la cronologia della conversazione che l’SDK accumula mentre il tuo agente lavora. Contiene il tuo prompt, ogni chiamata di strumento che l’agente ha effettuato, ogni risultato dello strumento e ogni risposta. L’SDK la scrive su disco automaticamente in modo che tu possa tornare ad essa in seguito. Tornare a una sessione significa che l’agente ha il contesto completo da prima: file che ha già letto, analisi che ha già eseguito, decisioni che ha già preso. Puoi fare una domanda di follow-up, recuperare da un’interruzione o diramati per provare un approccio diverso.
Le sessioni mantengono la conversazione, non il filesystem. Per fare uno snapshot e ripristinare i cambiamenti ai file che l’agente ha apportato, utilizza file checkpointing.
Questa guida copre come scegliere l’approccio giusto per la tua app, le interfacce SDK che tracciano automaticamente le sessioni, come acquisire gli ID di sessione e utilizzare manualmente resume e fork, e cosa sapere sul ripristino delle sessioni tra host.

Scegli un approccio

Quanto gestione della sessione hai bisogno dipende dalla forma della tua applicazione. La gestione della sessione entra in gioco quando invii più prompt che dovrebbero condividere il contesto. All’interno di una singola chiamata query(), l’agente già fa tutti i turni di cui ha bisogno, e i prompt di autorizzazione e AskUserQuestion sono gestiti in-loop (non terminano la chiamata).

Continue, resume e fork

Continue, resume e fork sono campi opzionali che imposti su query() (ClaudeAgentOptions in Python, Options in TypeScript). Continue e resume entrambi riprendono una sessione esistente e la aggiungono. La differenza è come trovano quella sessione:
  • Continue trova la sessione più recente nella directory corrente. Non traccia nulla. Funziona bene quando la tua app esegue una conversazione alla volta.
  • Resume accetta un ID di sessione specifico. Traccia l’ID. Richiesto quando hai più sessioni (ad esempio, una per utente in un’app multi-utente) o vuoi tornare a una che non è la più recente.
Fork è diverso: crea una nuova sessione che inizia con una copia della cronologia dell’originale. L’originale rimane invariato. Usa fork per provare una direzione diversa mantenendo l’opzione di tornare indietro.

Gestione automatica della sessione

Entrambi gli SDK offrono un’interfaccia che traccia lo stato della sessione per te tra le chiamate, quindi non passi gli ID in giro manualmente. Usali per conversazioni multi-turno all’interno di un singolo processo.

Python: ClaudeSDKClient

ClaudeSDKClient gestisce gli ID di sessione internamente. Ogni chiamata a client.query() continua automaticamente la stessa sessione. Chiama client.receive_response() per iterare sui messaggi per la query corrente. Usa il client come gestore di contesto asincrono in modo che la configurazione della connessione e lo smontaggio siano gestiti per te, oppure chiama connect() e disconnect() manualmente. Questo esempio esegue due query contro lo stesso client. La prima chiede all’agente di analizzare un modulo; la seconda gli chiede di refactorizzare quel modulo. Poiché entrambe le chiamate passano attraverso la stessa istanza del client, la seconda query ha il contesto completo dalla prima senza alcun resume esplicito o ID di sessione:
Python
Ogni query stampa la risposta di testo dell’agente seguita da una riga di stato dal messaggio di risultato, come [done: success, cost: $0.0042]. Vedi il riferimento Python SDK per i dettagli su quando usare ClaudeSDKClient rispetto alla funzione standalone query().

TypeScript: continue: true

L’SDK TypeScript non ha un oggetto client che tiene la sessione come il ClaudeSDKClient di Python. Invece, passa continue: true su ogni successiva chiamata query() e l’SDK raccoglie la sessione più recente nella directory corrente. Nessun tracciamento degli ID richiesto. Questo esempio effettua due separate chiamate query(). La prima crea una sessione nuova; la seconda imposta continue: true, che dice all’SDK di trovare e riprendere la sessione più recente su disco. L’agente ha il contesto completo dalla prima chiamata:
TypeScript
L’API di sessione sperimentale V2, che forniva createSession() con un pattern send / stream, è stata rimossa in TypeScript Agent SDK 0.3.142. Usa la funzione query() e le opzioni di sessione descritte in questa pagina.

Usa le opzioni di sessione con query()

Acquisisci l’ID di sessione

Resume e fork richiedono un ID di sessione. Leggilo dal campo session_id sul messaggio di risultato (ResultMessage in Python, SDKResultMessage in TypeScript), che è presente su ogni risultato indipendentemente dal successo o dall’errore. In TypeScript l’ID è disponibile anche prima come campo diretto sul SystemMessage di init; in Python è annidato dentro SystemMessage.data.
Quando la query si completa, lo script stampa la risposta dell’agente seguita da una riga come Session ID: 5b3f2c1a-8d4e-4f6b-9a7c-2e1d0f9b8a6c. Nelle sezioni successive, passerai questo ID a resume.

Riprendi per ID

Passa un ID di sessione a resume per tornare a quella sessione specifica. L’agente riprende con il contesto completo da dove la sessione si è fermata. Motivi comuni per riprendere:
  • Seguire un’attività completata. L’agente ha già analizzato qualcosa; ora vuoi che agisca su quell’analisi senza rileggere i file.
  • Recuperare da un limite. La prima esecuzione è terminata con error_max_turns o error_max_budget_usd (vedi Gestisci il risultato); riprendi con un limite più alto. In una singola chiamata query() l’SDK genera un’eccezione dopo aver restituito quel risultato di errore, quindi cattura l’errore prima di riprendere.
  • Riavvia il tuo processo. Hai acquisito l’ID prima dell’arresto e vuoi ripristinare la conversazione.
Questo esempio riprende la sessione da Acquisisci l’ID di sessione con un prompt di follow-up. Poiché stai riprendendo, l’agente ha già l’analisi precedente nel contesto:
Dovresti vedere una risposta che si basa sull’analisi precedente invece di iniziare da zero. Questo conferma che l’agente ha ripreso la sessione con il suo contesto precedente intatto.
Claude Code archivia le sessioni sotto ~/.claude/projects/<encoded-cwd>/*.jsonl. Se imposti la variabile di ambiente CLAUDE_CONFIG_DIR, cerca invece sotto $CLAUDE_CONFIG_DIR/projects/.Per trovare la directory della tua sessione, sostituisci ogni carattere non alfanumerico nella directory di lavoro assoluta con -: /Users/me/proj diventa -Users-me-proj. Per una directory di lavoro il cui nome convertito supera 200 caratteri, Claude Code tronca il nome e aggiunge un hash, quindi fai corrispondere i primi 200 caratteri del nome convertito quando elenchi projects/.Se imposti CLAUDE_CODE_PROJECT_DIR_NAME accanto a CLAUDE_CONFIG_DIR, cerca invece sotto quel nome in projects/. Richiede Agent SDK TypeScript v0.3.234 o successivo, oppure Agent SDK Python v0.2.140 o successivo.Puoi riprendere da qualsiasi directory di lavoro:
  • Ricerca tra directory: Claude Code cerca oltre la directory del progetto corrente per trovare l’ID; vedi Riprendi una sessione per l’ordine di ricerca esatto e come vengono gestite le copie duplicate.
  • Solo sulla stessa macchina: il file di sessione deve ancora esistere sulla macchina corrente.
Prima della v2.1.223, la ricerca era limitata alla directory del progetto corrente e ai suoi git worktrees; le versioni SDK che includono un CLI più vecchio si comportano ancora in questo modo.
Per riprendere sessioni tra macchine o in ambienti serverless, specchia i transcript in un archivio condiviso con un adattatore SessionStore.

Fai un fork per esplorare alternative

Il forking crea una nuova sessione che inizia con una copia della cronologia dell’originale ma diverge da quel punto. Il fork ottiene il suo proprio ID di sessione; l’ID e la cronologia dell’originale rimangono invariati. Finisci con due sessioni indipendenti che puoi riprendere separatamente.
Il forking dirama la cronologia della conversazione, non il filesystem. Se un agente con fork modifica i file, quei cambiamenti sono reali e visibili a qualsiasi sessione che lavora nella stessa directory. Per diramazioni e ripristino dei cambiamenti ai file, utilizza file checkpointing.
Questo esempio si basa su Acquisisci l’ID di sessione: hai già analizzato un modulo di autenticazione in session_id e vuoi esplorare OAuth2 senza perdere il thread focalizzato su JWT. Il primo blocco fa un fork della sessione e acquisisce l’ID del fork (forked_id); il secondo blocco riprende il session_id originale per continuare lungo il percorso JWT. Ora hai due ID di sessione che puntano a due cronologie separate:
Dovresti vedere che forkedId differisce dall’ID di sessione originale. Riprendere la sessione originale continua ancora il thread JWT, il che conferma che il fork non ha modificato la cronologia originale.

Riprendi tra host

I file di sessione sono locali alla macchina che li ha creati. Per riprendere una sessione su un host diverso (worker CI, container effimeri, serverless), scegli l’approccio che si adatta meglio:
  • Passa un session store. Allega un adattatore sessionStore / session_store in modo che l’SDK rispecchi i transcript nel tuo backend e un altro host possa riprenderli. La chiave di ricerca dello store deriva dalla directory di lavoro, quindi riprendi da un cwd che corrisponda all’esecuzione originale.
  • Sposta il file di sessione. Persisti ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl dalla prima esecuzione e ripristinalo all’interno di qualsiasi directory sotto ~/.claude/projects/ sul nuovo host prima di chiamare resume. Claude Code cerca oltre la directory del progetto corrente per trovare l’ID; vedi Riprendi una sessione per l’ordine di ricerca esatto e come vengono gestite le copie duplicate. Prima della v2.1.223, la ricerca era limitata alla directory del progetto corrente e ai suoi worktree git; le versioni dell’SDK che raggruppano un CLI più vecchio si comportano ancora in questo modo.
  • Non fare affidamento sul ripristino della sessione. Acquisisci i risultati di cui hai bisogno (output di analisi, decisioni, diff di file) come stato dell’applicazione e passali nel prompt di una sessione nuova. Questo è spesso più robusto che spedire file di transcript in giro.
Entrambi gli SDK espongono funzioni per enumerare le sessioni su disco e leggere i loro messaggi: listSessions() e getSessionMessages() in TypeScript, list_sessions() e get_session_messages() in Python. Usali per costruire selettori di sessione personalizzati, logica di pulizia o visualizzatori di transcript. Entrambi gli SDK espongono anche funzioni per cercare e mutare sessioni individuali: get_session_info(), rename_session() e tag_session() in Python, e getSessionInfo(), renameSession() e tagSession() in TypeScript. Usali per organizzare le sessioni per tag o dare loro titoli leggibili dall’uomo.