- Annullare le modifiche indesiderate ripristinando i file a uno stato noto e funzionante
- Esplorare alternative ripristinando a un checkpoint e provando un approccio diverso
- Recuperare da errori quando l’agente effettua modifiche non corrette
Come funziona il checkpointing
Quando abiliti il checkpointing dei file, l’SDK crea backup dei file prima di modificarli tramite gli strumenti Write, Edit o NotebookEdit. I messaggi dell’utente nel flusso di risposta includono un UUID di checkpoint che puoi utilizzare come punto di ripristino. Checkpoint funziona con questi strumenti integrati che l’agente utilizza per modificare i file:| Tool | Description |
|---|---|
| Write | Crea un nuovo file o sovrascrive un file esistente con nuovo contenuto |
| Edit | Effettua modifiche mirate a parti specifiche di un file esistente |
| NotebookEdit | Modifica le celle nei notebook Jupyter (file .ipynb) |
Il ripristino dei file ripristina i file su disco a uno stato precedente. Non ripristina la conversazione stessa. La cronologia della conversazione e il contesto rimangono intatti dopo la chiamata a
rewindFiles() (TypeScript) o rewind_files() (Python).- File creati durante la sessione
- File modificati durante la sessione
- Il contenuto originale dei file modificati
Implementare il checkpointing
Per utilizzare il checkpointing dei file, abilitalo nelle tue opzioni, acquisisci gli UUID di checkpoint dal flusso di risposta, quindi chiamarewindFiles() (TypeScript) o rewind_files() (Python) quando hai bisogno di ripristinare.
L’esempio seguente mostra il flusso completo: abilita il checkpointing, acquisisci l’UUID di checkpoint e l’ID di sessione dal flusso di risposta, quindi riprendi la sessione in seguito per ripristinare i file. Ogni passaggio è spiegato in dettaglio di seguito.
Abilita il checkpointing
Configura le opzioni dell’SDK per abilitare il checkpointing e ricevere gli UUID di checkpoint:
| Option | Python | TypeScript | Description |
|---|---|---|---|
| Enable checkpointing | enable_file_checkpointing=True | enableFileCheckpointing: true | Traccia le modifiche ai file per il ripristino |
| Receive checkpoint UUIDs | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | Obbligatorio per ottenere gli UUID dei messaggi dell’utente nel flusso |
Acquisisci l'UUID di checkpoint e l'ID di sessione
Con l’opzione
replay-user-messages impostata (mostrata sopra), ogni messaggio dell’utente nel flusso di risposta ha un UUID che funge da checkpoint.Per la maggior parte dei casi d’uso, acquisisci il primo UUID del messaggio dell’utente (message.uuid); il ripristino ad esso ripristina tutti i file al loro stato originale. Per archiviare più checkpoint e ripristinare a stati intermedi, vedi Più punti di ripristino.L’acquisizione dell’ID di sessione (message.session_id) è facoltativa; ne hai bisogno solo se vuoi ripristinare in seguito, dopo il completamento del flusso. Se stai chiamando rewindFiles() immediatamente mentre stai ancora elaborando i messaggi (come fa l’esempio in Checkpoint prima di operazioni rischiose), puoi saltare l’acquisizione dell’ID di sessione.Ripristina i file
Per ripristinare dopo il completamento del flusso, riprendi la sessione con un prompt vuoto e chiama Se acquisisci l’ID di sessione e l’ID di checkpoint, puoi anche ripristinare dalla CLI:
rewind_files() (Python) o rewindFiles() (TypeScript) con il tuo UUID di checkpoint. Puoi anche ripristinare durante il flusso; vedi Checkpoint prima di operazioni rischiose per quel modello.Modelli comuni
Questi modelli mostrano diversi modi per acquisire e utilizzare gli UUID di checkpoint a seconda del tuo caso d’uso.Checkpoint prima di operazioni rischiose
Questo modello mantiene solo l’UUID di checkpoint più recente, aggiornandolo prima di ogni turno dell’agente. Se qualcosa va storto durante l’elaborazione, puoi immediatamente ripristinare all’ultimo stato sicuro e uscire dal ciclo.Più punti di ripristino
Se Claude effettua modifiche su più turni, potresti voler ripristinare a un punto specifico piuttosto che all’inizio. Ad esempio, se Claude effettua il refactoring di un file nel turno uno e aggiunge test nel turno due, potresti voler mantenere il refactoring ma annullare i test. Questo modello archivia tutti gli UUID di checkpoint in un array con metadati. Dopo il completamento della sessione, puoi ripristinare a qualsiasi checkpoint precedente:Prova
Questo esempio completo crea un piccolo file di utilità, fa aggiungere all’agente commenti di documentazione, ti mostra le modifiche, quindi ti chiede se vuoi ripristinare. Prima di iniziare, assicurati di avere Claude Agent SDK installato.Crea un file di test
Crea un nuovo file chiamato
utils.py (Python) o utils.ts (TypeScript) e incolla il seguente codice:Esegui l'esempio interattivo
Crea un nuovo file chiamato Questo esempio dimostra il flusso di lavoro completo del checkpointing:
try_checkpointing.py (Python) o try_checkpointing.ts (TypeScript) nella stessa directory del tuo file di utilità e incolla il seguente codice.Questo script chiede a Claude di aggiungere commenti doc al tuo file di utilità, quindi ti dà la possibilità di ripristinare e ripristinare l’originale.- Abilita il checkpointing: configura l’SDK con
enable_file_checkpointing=Trueepermission_mode="acceptEdits"per approvare automaticamente le modifiche ai file - Acquisisci i dati di checkpoint: mentre l’agente è in esecuzione, archivia il primo UUID del messaggio dell’utente (il tuo punto di ripristino) e l’ID di sessione
- Richiedi il ripristino: dopo che l’agente ha terminato, controlla il tuo file di utilità per vedere i commenti doc, quindi decidi se vuoi annullare le modifiche
- Riprendi e ripristina: se sì, riprendi la sessione con un prompt vuoto e chiama
rewind_files()per ripristinare il file originale
Limitazioni
Il checkpointing dei file ha le seguenti limitazioni:| Limitation | Description |
|---|---|
| Solo strumenti Write/Edit/NotebookEdit | Le modifiche effettuate tramite comandi Bash non vengono tracciate |
| Stessa sessione | I checkpoint sono legati alla sessione che li ha creati |
| Solo contenuto del file | La creazione, lo spostamento o l’eliminazione di directory non vengono annullati dal ripristino |
| File locali | I file remoti o di rete non vengono tracciati |
Troubleshooting
Le opzioni di checkpointing non vengono riconosciute
SeenableFileCheckpointing o rewindFiles() non sono disponibili, potresti essere su una versione SDK più vecchia.
Soluzione: Aggiorna alla versione SDK più recente:
- Python:
pip install --upgrade claude-agent-sdk - TypeScript:
npm install @anthropic-ai/claude-agent-sdk@latest
I messaggi dell’utente non hanno UUID
Semessage.uuid è undefined o mancante, non stai ricevendo gli UUID di checkpoint.
Causa: L’opzione replay-user-messages non è impostata.
Soluzione: Aggiungi extra_args={"replay-user-messages": None} (Python) o extraArgs: { 'replay-user-messages': null } (TypeScript) alle tue opzioni.
Errore “No file checkpoint found for message”
Questo errore si verifica quando i dati di checkpoint non esistono per l’UUID del messaggio dell’utente specificato. Cause comuni:- Il checkpointing dei file non era abilitato sulla sessione originale (
enable_file_checkpointingoenableFileCheckpointingnon era impostato sutrue) - La sessione non è stata completata correttamente prima di tentare di riprendere e ripristinare
enable_file_checkpointing=True (Python) o enableFileCheckpointing: true (TypeScript) fosse impostato sulla sessione originale, quindi utilizza il modello mostrato negli esempi: acquisisci il primo UUID del messaggio dell’utente, completa la sessione completamente, quindi riprendi con un prompt vuoto e chiama rewindFiles() una volta.
Errore “ProcessTransport is not ready for writing”
Questo errore si verifica quando chiamirewindFiles() o rewind_files() dopo aver terminato l’iterazione attraverso la risposta. La connessione al processo CLI si chiude quando il ciclo si completa.
Soluzione: Riprendi la sessione con un prompt vuoto, quindi chiama rewind sulla nuova query:
Passaggi successivi
- Sessions: scopri come riprendere le sessioni, che è obbligatorio per il ripristino dopo il completamento del flusso. Copre gli ID di sessione, la ripresa delle conversazioni e il forking delle sessioni.
- Permissions: configura quali strumenti Claude può utilizzare e come vengono approvate le modifiche ai file. Utile se vuoi più controllo su quando avvengono le modifiche.
- TypeScript SDK reference: riferimento API completo incluse tutte le opzioni per
query()e il metodorewindFiles(). - Python SDK reference: riferimento API completo incluse tutte le opzioni per
ClaudeAgentOptionse il metodorewind_files().