- Desfazer alterações indesejadas restaurando arquivos para um estado conhecido e bom
- Explorar alternativas restaurando para um checkpoint e tentando uma abordagem diferente
- Recuperar de erros quando o agente faz modificações incorretas
Como o checkpointing funciona
Quando você ativa o checkpointing de arquivo, o SDK cria backups de arquivos antes de modificá-los através das ferramentas Write, Edit ou NotebookEdit. As mensagens do usuário no fluxo de resposta incluem um UUID de checkpoint que você pode usar como ponto de restauração. O checkpoint funciona com essas ferramentas integradas que o agente usa para modificar arquivos:| Ferramenta | Descrição |
|---|---|
| Write | Cria um novo arquivo ou sobrescreve um arquivo existente com novo conteúdo |
| Edit | Faz edições direcionadas em partes específicas de um arquivo existente |
| NotebookEdit | Modifica células em notebooks Jupyter (arquivos .ipynb) |
A reversão de arquivo restaura arquivos no disco para um estado anterior. Ela não reverte a conversa em si. O histórico de conversa e o contexto permanecem intactos após chamar
rewindFiles() (TypeScript) ou rewind_files() (Python).- Arquivos criados durante a sessão
- Arquivos modificados durante a sessão
- O conteúdo original de arquivos modificados
Implementar checkpointing
Para usar checkpointing de arquivo, ative-o em suas opções, capture UUIDs de checkpoint do fluxo de resposta e, em seguida, chamerewindFiles() (TypeScript) ou rewind_files() (Python) quando precisar restaurar.
O exemplo a seguir mostra o fluxo completo: ativar checkpointing, capturar o UUID de checkpoint e ID de sessão do fluxo de resposta e, em seguida, retomar a sessão mais tarde para reverter arquivos. Cada etapa é explicada em detalhes abaixo.
Ativar checkpointing
Configure suas opções de SDK para ativar checkpointing e receber UUIDs de checkpoint:
| Opção | Python | TypeScript | Descrição |
|---|---|---|---|
| Ativar checkpointing | enable_file_checkpointing=True | enableFileCheckpointing: true | Rastreia alterações de arquivo para reversão |
| Receber UUIDs de checkpoint | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | Necessário para obter UUIDs de mensagem do usuário no fluxo |
Capturar UUID de checkpoint e ID de sessão
Com a opção
replay-user-messages definida (mostrada acima), cada mensagem do usuário no fluxo de resposta tem um UUID que serve como um checkpoint.Para a maioria dos casos de uso, capture o UUID da primeira mensagem do usuário (message.uuid); reverter para ele restaura todos os arquivos para seu estado original. Para armazenar múltiplos checkpoints e reverter para estados intermediários, veja Múltiplos pontos de restauração.Capturar o ID de sessão (message.session_id) é opcional; você só precisa dele se quiser reverter mais tarde, após o fluxo ser concluído. Se você estiver chamando rewindFiles() imediatamente enquanto ainda processa mensagens (como o exemplo em Checkpoint antes de operações arriscadas faz), você pode pular a captura do ID de sessão.Reverter arquivos
Para reverter após o fluxo ser concluído, retome a sessão com um prompt vazio e chame Se você capturar o ID de sessão e o ID de checkpoint, você também pode reverter a partir da CLI:
rewind_files() (Python) ou rewindFiles() (TypeScript) com seu UUID de checkpoint. Você também pode reverter durante o fluxo; veja Checkpoint antes de operações arriscadas para esse padrão.Padrões comuns
Esses padrões mostram diferentes maneiras de capturar e usar UUIDs de checkpoint dependendo do seu caso de uso.Checkpoint antes de operações arriscadas
Este padrão mantém apenas o UUID de checkpoint mais recente, atualizando-o antes de cada turno do agente. Se algo der errado durante o processamento, você pode reverter imediatamente para o último estado seguro e sair do loop.Múltiplos pontos de restauração
Se Claude fizer alterações em múltiplos turnos, você pode querer reverter para um ponto específico em vez de voltar completamente. Por exemplo, se Claude refatorar um arquivo no turno um e adicionar testes no turno dois, você pode querer manter a refatoração mas desfazer os testes. Este padrão armazena todos os UUIDs de checkpoint em um array com metadados. Após a sessão ser concluída, você pode reverter para qualquer checkpoint anterior:Experimente
Este exemplo completo cria um pequeno arquivo utilitário, faz o agente adicionar comentários de documentação, mostra as alterações e pergunta se você quer reverter. Antes de começar, certifique-se de que você tem o Claude Agent SDK instalado.Criar um arquivo de teste
Crie um novo arquivo chamado
utils.py (Python) ou utils.ts (TypeScript) e cole o seguinte código:Executar o exemplo interativo
Crie um novo arquivo chamado Este exemplo demonstra o fluxo de trabalho completo de checkpointing:
try_checkpointing.py (Python) ou try_checkpointing.ts (TypeScript) no mesmo diretório que seu arquivo utilitário e cole o seguinte código.Este script pede ao Claude para adicionar comentários de documentação ao seu arquivo utilitário e, em seguida, oferece a opção de reverter e restaurar o original.- Ativar checkpointing: configure o SDK com
enable_file_checkpointing=Trueepermission_mode="acceptEdits"para aprovar automaticamente edições de arquivo - Capturar dados de checkpoint: conforme o agente é executado, armazene o UUID da primeira mensagem do usuário (seu ponto de restauração) e o ID de sessão
- Solicitar reversão: após o agente terminar, verifique seu arquivo utilitário para ver os comentários de documentação e decida se deseja desfazer as alterações
- Retomar e reverter: se sim, retome a sessão com um prompt vazio e chame
rewind_files()para restaurar o arquivo original
Limitações
O checkpointing de arquivo tem as seguintes limitações:| Limitação | Descrição |
|---|---|
| Apenas ferramentas Write/Edit/NotebookEdit | As alterações feitas através de comandos Bash não são rastreadas |
| Mesma sessão | Os checkpoints estão vinculados à sessão que os criou |
| Apenas conteúdo de arquivo | Criar, mover ou deletar diretórios não é desfeito pela reversão |
| Arquivos locais | Arquivos remotos ou de rede não são rastreados |
Troubleshooting
Opções de checkpointing não reconhecidas
SeenableFileCheckpointing ou rewindFiles() não estiver disponível, você pode estar em uma versão mais antiga do SDK.
Solução: Atualize para a versão mais recente do SDK:
- Python:
pip install --upgrade claude-agent-sdk - TypeScript:
npm install @anthropic-ai/claude-agent-sdk@latest
Mensagens do usuário não têm UUIDs
Semessage.uuid for undefined ou estiver faltando, você não está recebendo UUIDs de checkpoint.
Causa: A opção replay-user-messages não está definida.
Solução: Adicione extra_args={"replay-user-messages": None} (Python) ou extraArgs: { 'replay-user-messages': null } (TypeScript) às suas opções.
Erro “No file checkpoint found for message”
Este erro ocorre quando os dados de checkpoint não existem para o UUID de mensagem do usuário especificado. Causas comuns:- O checkpointing de arquivo não foi ativado na sessão original (
enable_file_checkpointingouenableFileCheckpointingnão foi definido comotrue) - A sessão não foi concluída adequadamente antes de tentar retomar e reverter
enable_file_checkpointing=True (Python) ou enableFileCheckpointing: true (TypeScript) foi definido na sessão original, depois use o padrão mostrado nos exemplos: capture o UUID da primeira mensagem do usuário, conclua a sessão completamente e, em seguida, retome com um prompt vazio e chame rewindFiles() uma vez.
Erro “ProcessTransport is not ready for writing”
Este erro ocorre quando você chamarewindFiles() ou rewind_files() após ter terminado de iterar através da resposta. A conexão com o processo CLI fecha quando o loop é concluído.
Solução: Retome a sessão com um prompt vazio e, em seguida, chame rewind na nova query:
Próximos passos
- Sessions: aprenda como retomar sessões, o que é necessário para reverter após o fluxo ser concluído. Cobre IDs de sessão, retomada de conversas e bifurcação de sessão.
- Permissions: configure quais ferramentas Claude pode usar e como as modificações de arquivo são aprovadas. Útil se você quiser mais controle sobre quando as edições acontecem.
- TypeScript SDK reference: referência completa da API incluindo todas as opções para
query()e o métodorewindFiles(). - Python SDK reference: referência completa da API incluindo todas as opções para
ClaudeAgentOptionse o métodorewind_files().