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.
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 chiamataquery(), 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).
| Cosa stai costruendo | Cosa usare |
|---|---|
| Attività una tantum: singolo prompt, nessun follow-up | Niente di extra. Una singola chiamata query() la gestisce. |
| Chat multi-turno in un processo | ClaudeSDKClient (Python) o continue: true (TypeScript). L’SDK traccia la sessione per te senza gestione degli ID. |
| Riprendere da dove hai lasciato dopo un riavvio del processo | continue_conversation=True (Python) / continue: true (TypeScript). Riprende la sessione più recente nella directory, nessun ID necessario. |
| Riprendere una sessione passata specifica (non la più recente) | Acquisisci l’ID di sessione e passalo a resume. |
| Provare un approccio alternativo senza perdere l’originale | Fai un fork della sessione. |
| Attività senza stato, non vuoi che nulla sia scritto su disco (solo TypeScript) | Imposta persistSession: false. La sessione esiste solo in memoria per la durata della chiamata. Python persiste sempre su disco. |
Continue, resume e fork
Continue, resume e fork sono campi opzionali che imposti suquery() (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.
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
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 camposession_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.
Riprendi per ID
Passa un ID di sessione aresume 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_turnsoerror_max_budget_usd(vedi Gestisci il risultato); riprendi con un limite più alto. - Riavvia il tuo processo. Hai acquisito l’ID prima dell’arresto e vuoi ripristinare la conversazione.
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.
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:
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), hai due opzioni:- Sposta il file di sessione. Persisti
~/.claude/projects/<encoded-cwd>/<session-id>.jsonldalla prima esecuzione e ripristinalo nello stesso percorso sul nuovo host prima di chiamareresume. Ilcwddeve corrispondere. - 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.
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.
Risorse correlate
- Come funziona il ciclo dell’agente: Comprendi i turni, i messaggi e l’accumulo del contesto all’interno di una sessione
- File checkpointing: Traccia e ripristina i cambiamenti ai file tra le sessioni
- Python
ClaudeAgentOptions: Riferimento completo delle opzioni di sessione per Python - TypeScript
Options: Riferimento completo delle opzioni di sessione per TypeScript