- Deshacer cambios no deseados restaurando archivos a un estado conocido y bueno
- Explorar alternativas restaurando a un checkpoint e intentando un enfoque diferente
- Recuperarse de errores cuando el agente realiza modificaciones incorrectas
Cómo funciona el checkpointing
Cuando habilita el checkpointing de archivos, el SDK crea copias de seguridad de archivos antes de modificarlos a través de las herramientas Write, Edit o NotebookEdit. Los mensajes de usuario en el flujo de respuesta incluyen un UUID de checkpoint que puede usar como punto de restauración. Checkpoint funciona con estas herramientas integradas que el agente usa para modificar archivos:| Herramienta | Descripción |
|---|---|
| Write | Crea un archivo nuevo o sobrescribe un archivo existente con contenido nuevo |
| Edit | Realiza ediciones dirigidas a partes específicas de un archivo existente |
| NotebookEdit | Modifica celdas en cuadernos Jupyter (archivos .ipynb) |
La reversión de archivos restaura archivos en disco a un estado anterior. No revierte la conversación en sí. El historial de conversación y el contexto permanecen intactos después de llamar a
rewindFiles() (TypeScript) o rewind_files() (Python).- Archivos creados durante la sesión
- Archivos modificados durante la sesión
- El contenido original de archivos modificados
Implementar checkpointing
Para usar el checkpointing de archivos, habilítelo en sus opciones, capture UUIDs de checkpoint del flujo de respuesta, luego llame arewindFiles() (TypeScript) o rewind_files() (Python) cuando necesite restaurar.
El siguiente ejemplo muestra el flujo completo: habilitar checkpointing, capturar el UUID de checkpoint y el ID de sesión del flujo de respuesta, luego reanudar la sesión más tarde para revertir archivos. Cada paso se explica en detalle a continuación.
Habilitar checkpointing
Configure sus opciones de SDK para habilitar checkpointing y recibir UUIDs de checkpoint:
| Opción | Python | TypeScript | Descripción |
|---|---|---|---|
| Habilitar checkpointing | enable_file_checkpointing=True | enableFileCheckpointing: true | Rastrea cambios de archivos para reversión |
| Recibir UUIDs de checkpoint | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | Requerido para obtener UUIDs de mensajes de usuario en el flujo |
Capturar UUID de checkpoint e ID de sesión
Con la opción
replay-user-messages establecida (mostrada arriba), cada mensaje de usuario en el flujo de respuesta tiene un UUID que sirve como checkpoint.Para la mayoría de los casos de uso, capture el UUID del primer mensaje de usuario (message.uuid); revertir a él restaura todos los archivos a su estado original. Para almacenar múltiples checkpoints y revertir a estados intermedios, consulte Múltiples puntos de restauración.Capturar el ID de sesión (message.session_id) es opcional; solo lo necesita si desea revertir más tarde, después de que se complete el flujo. Si está llamando a rewindFiles() inmediatamente mientras aún procesa mensajes (como lo hace el ejemplo en Checkpoint antes de operaciones arriesgadas), puede omitir la captura del ID de sesión.Revertir archivos
Para revertir después de que se complete el flujo, reanude la sesión con un mensaje vacío y llame a Si captura el ID de sesión y el ID de checkpoint, también puede revertir desde la CLI:
rewind_files() (Python) o rewindFiles() (TypeScript) con su UUID de checkpoint. También puede revertir durante el flujo; consulte Checkpoint antes de operaciones arriesgadas para ese patrón.Patrones comunes
Estos patrones muestran diferentes formas de capturar y usar UUIDs de checkpoint según su caso de uso.Checkpoint antes de operaciones arriesgadas
Este patrón mantiene solo el UUID de checkpoint más reciente, actualizándolo antes de cada turno del agente. Si algo sale mal durante el procesamiento, puede revertir inmediatamente al último estado seguro y salir del bucle.Múltiples puntos de restauración
Si Claude realiza cambios en múltiples turnos, es posible que desee revertir a un punto específico en lugar de volver completamente. Por ejemplo, si Claude refactoriza un archivo en el turno uno y agrega pruebas en el turno dos, es posible que desee mantener la refactorización pero deshacer las pruebas. Este patrón almacena todos los UUIDs de checkpoint en una matriz con metadatos. Después de que se complete la sesión, puede revertir a cualquier checkpoint anterior:Pruébelo
Este ejemplo completo crea un pequeño archivo de utilidad, hace que el agente agregue comentarios de documentación, le muestra los cambios, luego pregunta si desea revertir. Antes de comenzar, asegúrese de tener el Claude Agent SDK instalado.Crear un archivo de prueba
Cree un nuevo archivo llamado
utils.py (Python) o utils.ts (TypeScript) y pegue el siguiente código:Ejecutar el ejemplo interactivo
Cree un nuevo archivo llamado Este ejemplo demuestra el flujo de trabajo completo de checkpointing:
try_checkpointing.py (Python) o try_checkpointing.ts (TypeScript) en el mismo directorio que su archivo de utilidad, y pegue el siguiente código.Este script le pide a Claude que agregue comentarios de documentación a su archivo de utilidad, luego le da la opción de revertir y restaurar el original.- Habilitar checkpointing: configure el SDK con
enable_file_checkpointing=Trueypermission_mode="acceptEdits"para aprobar automáticamente ediciones de archivos - Capturar datos de checkpoint: mientras el agente se ejecuta, almacene el UUID del primer mensaje de usuario (su punto de restauración) y el ID de sesión
- Solicitar reversión: después de que el agente termine, verifique su archivo de utilidad para ver los comentarios de documentación, luego decida si desea deshacer los cambios
- Reanudar y revertir: si es así, reanude la sesión con un mensaje vacío y llame a
rewind_files()para restaurar el archivo original
Limitaciones
El checkpointing de archivos tiene las siguientes limitaciones:| Limitación | Descripción |
|---|---|
| Solo herramientas Write/Edit/NotebookEdit | Los cambios realizados a través de comandos Bash no se rastrean |
| Misma sesión | Los checkpoints están vinculados a la sesión que los creó |
| Solo contenido de archivo | Crear, mover o eliminar directorios no se deshace al revertir |
| Archivos locales | Los archivos remotos o de red no se rastrean |
Solución de problemas
Las opciones de checkpointing no se reconocen
SienableFileCheckpointing o rewindFiles() no está disponible, es posible que esté en una versión anterior del SDK.
Solución: Actualice a la última versión del SDK:
- Python:
pip install --upgrade claude-agent-sdk - TypeScript:
npm install @anthropic-ai/claude-agent-sdk@latest
Los mensajes de usuario no tienen UUIDs
Simessage.uuid es undefined o está faltando, no está recibiendo UUIDs de checkpoint.
Causa: La opción replay-user-messages no está establecida.
Solución: Agregue extra_args={"replay-user-messages": None} (Python) o extraArgs: { 'replay-user-messages': null } (TypeScript) a sus opciones.
Error “No file checkpoint found for message”
Este error ocurre cuando los datos de checkpoint no existen para el UUID de mensaje de usuario especificado. Causas comunes:- El checkpointing de archivos no estaba habilitado en la sesión original (
enable_file_checkpointingoenableFileCheckpointingno estaba establecido entrue) - La sesión no se completó correctamente antes de intentar reanudar y revertir
enable_file_checkpointing=True (Python) o enableFileCheckpointing: true (TypeScript) estuviera establecido en la sesión original, luego use el patrón mostrado en los ejemplos: capture el UUID del primer mensaje de usuario, complete la sesión completamente, luego reanude con un mensaje vacío y llame a rewindFiles() una sola vez.
Error “ProcessTransport is not ready for writing”
Este error ocurre cuando llama arewindFiles() o rewind_files() después de haber terminado de iterar a través de la respuesta. La conexión al proceso de CLI se cierra cuando se completa el bucle.
Solución: Reanude la sesión con un mensaje vacío, luego llame a rewind en la nueva consulta:
Próximos pasos
- Sessions: aprenda cómo reanudar sesiones, que es necesario para revertir después de que se complete el flujo. Cubre IDs de sesión, reanudación de conversaciones y bifurcación de sesiones.
- Permissions: configure qué herramientas puede usar Claude y cómo se aprueban las modificaciones de archivos. Útil si desea más control sobre cuándo ocurren las ediciones.
- TypeScript SDK reference: referencia completa de API incluyendo todas las opciones para
query()y el métodorewindFiles(). - Python SDK reference: referencia completa de API incluyendo todas las opciones para
ClaudeAgentOptionsy el métodorewind_files().