- Annuler les modifications indésirables en restaurant les fichiers à un état connu et bon
- Explorer les alternatives en restaurant à un point de contrôle et en essayant une approche différente
- Récupérer après les erreurs lorsque l’agent effectue des modifications incorrectes
Comment fonctionne le point de contrôle
Lorsque vous activez le point de contrôle de fichier, le SDK crée des sauvegardes de fichiers avant de les modifier via les outils Write, Edit ou NotebookEdit. Les messages utilisateur dans le flux de réponse incluent un UUID de point de contrôle que vous pouvez utiliser comme point de restauration. Le point de contrôle fonctionne avec ces outils intégrés que l’agent utilise pour modifier les fichiers :| Outil | Description |
|---|---|
| Write | Crée un nouveau fichier ou remplace un fichier existant par un nouveau contenu |
| Edit | Effectue des modifications ciblées sur des parties spécifiques d’un fichier existant |
| NotebookEdit | Modifie les cellules dans les notebooks Jupyter (fichiers .ipynb) |
Le rembobinage de fichier restaure les fichiers sur le disque à un état antérieur. Il ne remboîne pas la conversation elle-même. L’historique de la conversation et le contexte restent intacts après l’appel de
rewindFiles() (TypeScript) ou rewind_files() (Python).- Les fichiers créés pendant la session
- Les fichiers modifiés pendant la session
- Le contenu original des fichiers modifiés
Implémenter le point de contrôle
Pour utiliser le point de contrôle de fichier, activez-le dans vos options, capturez les UUID de point de contrôle du flux de réponse, puis appelezrewindFiles() (TypeScript) ou rewind_files() (Python) lorsque vous devez restaurer.
L’exemple suivant montre le flux complet : activez le point de contrôle, capturez l’UUID du point de contrôle et l’ID de session du flux de réponse, puis reprenez la session plus tard pour rembobiner les fichiers. Chaque étape est expliquée en détail ci-dessous.
Activer le point de contrôle
Configurez vos options SDK pour activer le point de contrôle et recevoir les UUID de point de contrôle :
| Option | Python | TypeScript | Description |
|---|---|---|---|
| Activer le point de contrôle | enable_file_checkpointing=True | enableFileCheckpointing: true | Suit les modifications de fichiers pour le rembobinage |
| Recevoir les UUID de point de contrôle | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | Requis pour obtenir les UUID de message utilisateur dans le flux |
Capturer l'UUID du point de contrôle et l'ID de session
Avec l’option
replay-user-messages définie (comme indiqué ci-dessus), chaque message utilisateur dans le flux de réponse a un UUID qui sert de point de contrôle.Pour la plupart des cas d’utilisation, capturez l’UUID du premier message utilisateur (message.uuid) ; le rembobinage vers celui-ci restaure tous les fichiers à leur état d’origine. Pour stocker plusieurs points de contrôle et rembobiner vers des états intermédiaires, consultez Points de restauration multiples.La capture de l’ID de session (message.session_id) est facultative ; vous n’en avez besoin que si vous souhaitez rembobiner plus tard, après la fin du flux. Si vous appelez rewindFiles() immédiatement tout en traitant les messages (comme le fait l’exemple dans Point de contrôle avant les opérations risquées), vous pouvez ignorer la capture de l’ID de session.Rembobiner les fichiers
Pour rembobiner après la fin du flux, reprenez la session avec une invite vide et appelez Si vous capturez l’ID de session et l’UUID de point de contrôle, vous pouvez également rembobiner à partir de la CLI :
rewind_files() (Python) ou rewindFiles() (TypeScript) avec votre UUID de point de contrôle. Vous pouvez également rembobiner pendant le flux ; consultez Point de contrôle avant les opérations risquées pour ce modèle.Modèles courants
Ces modèles montrent différentes façons de capturer et d’utiliser les UUID de point de contrôle en fonction de votre cas d’utilisation.Point de contrôle avant les opérations risquées
Ce modèle conserve uniquement l’UUID de point de contrôle le plus récent, le mettant à jour avant chaque tour d’agent. Si quelque chose se passe mal pendant le traitement, vous pouvez immédiatement rembobiner vers le dernier état sûr et sortir de la boucle.Points de restauration multiples
Si Claude effectue des modifications sur plusieurs tours, vous pouvez souhaiter rembobiner à un point spécifique plutôt que tout le chemin en arrière. Par exemple, si Claude refactorise un fichier au tour un et ajoute des tests au tour deux, vous pouvez souhaiter conserver la refactorisation mais annuler les tests. Ce modèle stocke tous les UUID de point de contrôle dans un tableau avec des métadonnées. Après la fin de la session, vous pouvez rembobiner à n’importe quel point de contrôle antérieur :Essayez-le
Cet exemple complet crée un petit fichier utilitaire, demande à l’agent d’ajouter des commentaires de documentation, vous montre les modifications, puis vous demande si vous souhaitez rembobiner. Avant de commencer, assurez-vous que vous avez installé le Claude Agent SDK.Créer un fichier de test
Créez un nouveau fichier appelé
utils.py (Python) ou utils.ts (TypeScript) et collez le code suivant :Exécuter l'exemple interactif
Créez un nouveau fichier appelé Cet exemple démontre le flux de travail complet du point de contrôle :
try_checkpointing.py (Python) ou try_checkpointing.ts (TypeScript) dans le même répertoire que votre fichier utilitaire, et collez le code suivant.Ce script demande à Claude d’ajouter des commentaires de documentation à votre fichier utilitaire, puis vous donne la possibilité de rembobiner et de restaurer l’original.- Activer le point de contrôle : configurez le SDK avec
enable_file_checkpointing=Trueetpermission_mode="acceptEdits"pour approuver automatiquement les modifications de fichiers - Capturer les données de point de contrôle : pendant que l’agent s’exécute, stockez l’UUID du premier message utilisateur (votre point de restauration) et l’ID de session
- Demander le rembobinage : après la fin de l’agent, vérifiez votre fichier utilitaire pour voir les commentaires de documentation, puis décidez si vous souhaitez annuler les modifications
- Reprendre et rembobiner : si oui, reprenez la session avec une invite vide et appelez
rewind_files()pour restaurer le fichier d’origine
Exécuter l'exemple
Exécutez le script à partir du même répertoire que votre fichier utilitaire.Vous verrez l’agent ajouter des commentaires de documentation, puis une invite vous demandant si vous souhaitez rembobiner. Si vous choisissez oui, le fichier est restauré à son état d’origine.
- Python
- TypeScript
Limitations
Le point de contrôle de fichier a les limitations suivantes :| Limitation | Description |
|---|---|
| Outils Write/Edit/NotebookEdit uniquement | Les modifications effectuées via les commandes Bash ne sont pas suivies |
| Même session | Les points de contrôle sont liés à la session qui les a créés |
| Contenu du fichier uniquement | La création, le déplacement ou la suppression de répertoires ne sont pas annulés par le rembobinage |
| Fichiers locaux | Les fichiers distants ou réseau ne sont pas suivis |
Dépannage
Les options de point de contrôle ne sont pas reconnues
SienableFileCheckpointing ou rewindFiles() n’est pas disponible, vous utilisez peut-être une version plus ancienne du SDK.
Solution : Mettez à jour vers la dernière version du SDK :
- Python :
pip install --upgrade claude-agent-sdk - TypeScript :
npm install @anthropic-ai/claude-agent-sdk@latest
Les messages utilisateur n’ont pas d’UUID
Simessage.uuid est undefined ou manquant, vous ne recevez pas les UUID de point de contrôle.
Cause : L’option replay-user-messages n’est pas définie.
Solution : Ajoutez extra_args={"replay-user-messages": None} (Python) ou extraArgs: { 'replay-user-messages': null } (TypeScript) à vos options.
Erreur « No file checkpoint found for message »
Cette erreur se produit lorsque les données de point de contrôle n’existent pas pour l’UUID de message utilisateur spécifié. Causes courantes :- Le point de contrôle de fichier n’a pas été activé sur la session d’origine (
enable_file_checkpointingouenableFileCheckpointingn’a pas été défini surtrue) - La session n’a pas été correctement complétée avant de tenter de reprendre et de rembobiner
enable_file_checkpointing=True (Python) ou enableFileCheckpointing: true (TypeScript) a été défini sur la session d’origine, puis utilisez le modèle montré dans les exemples : capturez l’UUID du premier message utilisateur, complétez la session entièrement, puis reprenez avec une invite vide et appelez rewindFiles() une fois.
Erreur « ProcessTransport is not ready for writing »
Cette erreur se produit lorsque vous appelezrewindFiles() ou rewind_files() après avoir terminé l’itération dans la réponse. La connexion au processus CLI se ferme lorsque la boucle se termine.
Solution : Reprenez la session avec une invite vide, puis appelez rewind sur la nouvelle requête :
Étapes suivantes
- Sessions : apprenez à reprendre les sessions, ce qui est nécessaire pour rembobiner après la fin du flux. Couvre les ID de session, la reprise des conversations et le forking de session.
- Permissions : configurez les outils que Claude peut utiliser et comment les modifications de fichiers sont approuvées. Utile si vous souhaitez plus de contrôle sur le moment où les modifications se produisent.
- Référence du SDK TypeScript : référence API complète incluant toutes les options pour
query()et la méthoderewindFiles(). - Référence du SDK Python : référence API complète incluant toutes les options pour
ClaudeAgentOptionset la méthoderewind_files().