- Membatalkan perubahan yang tidak diinginkan dengan memulihkan file ke status yang diketahui baik
- Menjelajahi alternatif dengan memulihkan ke checkpoint dan mencoba pendekatan berbeda
- Pulih dari kesalahan ketika agen membuat modifikasi yang salah
Cara kerja checkpointing
Ketika Anda mengaktifkan file checkpointing, SDK membuat cadangan file sebelum memodifikasinya melalui alat Write, Edit, atau NotebookEdit. Pesan pengguna dalam aliran respons menyertakan UUID checkpoint yang dapat Anda gunakan sebagai titik pemulihan. Checkpoint bekerja dengan alat bawaan ini yang digunakan agen untuk memodifikasi file:| Alat | Deskripsi |
|---|---|
| Write | Membuat file baru atau menimpa file yang ada dengan konten baru |
| Edit | Membuat pengeditan bertarget ke bagian tertentu dari file yang ada |
| NotebookEdit | Memodifikasi sel dalam notebook Jupyter (file .ipynb) |
Pemulihan file mengembalikan file di disk ke status sebelumnya. Ini tidak mengembalikan percakapan itu sendiri. Riwayat percakapan dan konteks tetap utuh setelah memanggil
rewindFiles() (TypeScript) atau rewind_files() (Python).- File yang dibuat selama sesi
- File yang dimodifikasi selama sesi
- Konten asli file yang dimodifikasi
Implementasikan checkpointing
Untuk menggunakan file checkpointing, aktifkan dalam opsi Anda, tangkap UUID checkpoint dari aliran respons, kemudian panggilrewindFiles() (TypeScript) atau rewind_files() (Python) ketika Anda perlu memulihkan.
Contoh berikut menunjukkan alur lengkap: aktifkan checkpointing, tangkap UUID checkpoint dan ID sesi dari aliran respons, kemudian lanjutkan sesi nanti untuk mengembalikan file. Setiap langkah dijelaskan secara detail di bawah.
Aktifkan checkpointing
Konfigurasi opsi SDK Anda untuk mengaktifkan checkpointing dan menerima UUID checkpoint:
| Opsi | Python | TypeScript | Deskripsi |
|---|---|---|---|
| Aktifkan checkpointing | enable_file_checkpointing=True | enableFileCheckpointing: true | Melacak perubahan file untuk pemulihan |
| Terima UUID checkpoint | extra_args={"replay-user-messages": None} | extraArgs: { 'replay-user-messages': null } | Diperlukan untuk mendapatkan UUID pesan pengguna dalam aliran |
Tangkap UUID checkpoint dan ID sesi
Dengan opsi
replay-user-messages yang diatur (ditunjukkan di atas), setiap pesan pengguna dalam aliran respons memiliki UUID yang berfungsi sebagai checkpoint.Untuk sebagian besar kasus penggunaan, tangkap UUID pesan pengguna pertama (message.uuid); mengembalikan ke sana memulihkan semua file ke status asli mereka. Untuk menyimpan beberapa checkpoint dan mengembalikan ke status perantara, lihat Beberapa titik pemulihan.Menangkap ID sesi (message.session_id) bersifat opsional; Anda hanya membutuhkannya jika Anda ingin mengembalikan nanti, setelah aliran selesai. Jika Anda memanggil rewindFiles() segera saat masih memproses pesan (seperti yang dilakukan contoh di Checkpoint sebelum operasi berisiko), Anda dapat melewatkan penangkapan ID sesi.Kembalikan file
Untuk mengembalikan setelah aliran selesai, lanjutkan sesi dengan prompt kosong dan panggil Jika Anda menangkap ID sesi dan ID checkpoint, Anda juga dapat mengembalikan dari CLI:
rewind_files() (Python) atau rewindFiles() (TypeScript) dengan UUID checkpoint Anda. Anda juga dapat mengembalikan selama aliran; lihat Checkpoint sebelum operasi berisiko untuk pola itu.Pola umum
Pola ini menunjukkan cara berbeda untuk menangkap dan menggunakan UUID checkpoint tergantung pada kasus penggunaan Anda.Checkpoint sebelum operasi berisiko
Pola ini menyimpan hanya UUID checkpoint terbaru, memperbaruinya sebelum setiap putaran agen. Jika ada yang salah selama pemrosesan, Anda dapat segera mengembalikan ke status terakhir yang aman dan keluar dari loop.Beberapa titik pemulihan
Jika Claude membuat perubahan di beberapa putaran, Anda mungkin ingin mengembalikan ke titik tertentu daripada semuanya. Misalnya, jika Claude merefaktor file di putaran satu dan menambahkan tes di putaran dua, Anda mungkin ingin menyimpan refaktor tetapi membatalkan tes. Pola ini menyimpan semua UUID checkpoint dalam array dengan metadata. Setelah sesi selesai, Anda dapat mengembalikan ke checkpoint sebelumnya:Coba sekarang
Contoh lengkap ini membuat file utilitas kecil, meminta agen menambahkan komentar dokumentasi, menunjukkan perubahan kepada Anda, kemudian menanyakan apakah Anda ingin mengembalikan. Sebelum Anda mulai, pastikan Anda telah menginstal Claude Agent SDK.Buat file uji
Buat file baru bernama
utils.py (Python) atau utils.ts (TypeScript) dan tempel kode berikut:Jalankan contoh interaktif
Buat file baru bernama Contoh ini mendemonstrasikan alur kerja checkpointing lengkap:
try_checkpointing.py (Python) atau try_checkpointing.ts (TypeScript) di direktori yang sama dengan file utilitas Anda, dan tempel kode berikut.Skrip ini meminta Claude untuk menambahkan komentar doc ke file utilitas Anda, kemudian memberi Anda opsi untuk mengembalikan dan memulihkan yang asli.- Aktifkan checkpointing: konfigurasi SDK dengan
enable_file_checkpointing=Truedanpermission_mode="acceptEdits"untuk menyetujui pengeditan file secara otomatis - Tangkap data checkpoint: saat agen berjalan, simpan UUID pesan pengguna pertama (titik pemulihan Anda) dan ID sesi
- Minta pemulihan: setelah agen selesai, periksa file utilitas Anda untuk melihat komentar doc, kemudian putuskan apakah Anda ingin membatalkan perubahan
- Lanjutkan dan kembalikan: jika ya, lanjutkan sesi dengan prompt kosong dan panggil
rewind_files()untuk memulihkan file asli
Keterbatasan
File checkpointing memiliki keterbatasan berikut:| Keterbatasan | Deskripsi |
|---|---|
| Hanya alat Write/Edit/NotebookEdit | Perubahan yang dilakukan melalui perintah Bash tidak dilacak |
| Sesi yang sama | Checkpoint terikat pada sesi yang membuatnya |
| Konten file saja | Membuat, memindahkan, atau menghapus direktori tidak dibatalkan oleh pemulihan |
| File lokal | File jarak jauh atau jaringan tidak dilacak |
Troubleshooting
Opsi checkpointing tidak dikenali
JikaenableFileCheckpointing atau rewindFiles() tidak tersedia, Anda mungkin menggunakan versi SDK yang lebih lama.
Solusi: Perbarui ke versi SDK terbaru:
- Python:
pip install --upgrade claude-agent-sdk - TypeScript:
npm install @anthropic-ai/claude-agent-sdk@latest
Pesan pengguna tidak memiliki UUID
Jikamessage.uuid adalah undefined atau hilang, Anda tidak menerima UUID checkpoint.
Penyebab: Opsi replay-user-messages tidak diatur.
Solusi: Tambahkan extra_args={"replay-user-messages": None} (Python) atau extraArgs: { 'replay-user-messages': null } (TypeScript) ke opsi Anda.
Kesalahan “No file checkpoint found for message”
Kesalahan ini terjadi ketika data checkpoint tidak ada untuk UUID pesan pengguna yang ditentukan. Penyebab umum:- File checkpointing tidak diaktifkan pada sesi asli (
enable_file_checkpointingatauenableFileCheckpointingtidak diatur ketrue) - Sesi tidak diselesaikan dengan benar sebelum mencoba melanjutkan dan mengembalikan
enable_file_checkpointing=True (Python) atau enableFileCheckpointing: true (TypeScript) diatur pada sesi asli, kemudian gunakan pola yang ditunjukkan dalam contoh: tangkap UUID pesan pengguna pertama, selesaikan sesi sepenuhnya, kemudian lanjutkan dengan prompt kosong dan panggil rewindFiles() sekali.
Kesalahan “ProcessTransport is not ready for writing”
Kesalahan ini terjadi ketika Anda memanggilrewindFiles() atau rewind_files() setelah Anda selesai mengulangi respons. Koneksi ke proses CLI ditutup ketika loop selesai.
Solusi: Lanjutkan sesi dengan prompt kosong, kemudian panggil rewind pada kueri baru:
Langkah berikutnya
- Sessions: pelajari cara melanjutkan sesi, yang diperlukan untuk pemulihan setelah aliran selesai. Mencakup ID sesi, melanjutkan percakapan, dan forking sesi.
- Permissions: konfigurasi alat mana yang dapat digunakan Claude dan bagaimana modifikasi file disetujui. Berguna jika Anda menginginkan kontrol lebih besar atas kapan pengeditan terjadi.
- Referensi SDK TypeScript: referensi API lengkap termasuk semua opsi untuk
query()dan metoderewindFiles(). - Referensi SDK Python: referensi API lengkap termasuk semua opsi untuk
ClaudeAgentOptionsdan metoderewind_files().