Loading...
    • Panduan Pengembang
    • Referensi API
    • MCP
    • Sumber daya
    • Catatan rilis
    Search...
    ⌘K
    Langkah pertama
    Pengenalan ClaudeMulai cepat
    Model & harga
    Ikhtisar modelMemilih modelYang baru di Claude 4.6Panduan migrasiPenghentian modelHarga
    Bangun dengan Claude
    Ikhtisar fiturMenggunakan Messages APIMenangani alasan berhentiPraktik terbaik prompting
    Manajemen konteks
    Jendela konteksKompresiPengeditan konteks
    Kemampuan
    Caching promptPemikiran diperpanjangPemikiran adaptifUpayaStreaming pesanPemrosesan batchKutipanDukungan multibahasaPenghitungan tokenEmbeddingsVisiDukungan PDFFiles APIHasil pencarianOutput terstruktur
    Alat
    IkhtisarCara mengimplementasikan penggunaan alatStreaming alat berbutir halusAlat BashAlat eksekusi kodePemanggilan alat terprogramAlat penggunaan komputerAlat editor teksAlat pengambilan webAlat pencarian webAlat memoriAlat pencarian alat
    Keterampilan Agen
    IkhtisarMulai cepatPraktik terbaikKeterampilan untuk perusahaanMenggunakan Keterampilan dengan API
    Agent SDK
    IkhtisarMulai cepatTypeScript SDKTypeScript V2 (pratinjau)Python SDKPanduan migrasi
    Input streamingStreaming respons secara real-timeMenangani alasan berhentiMenangani izinPersetujuan pengguna dan inputKontrol eksekusi dengan hookManajemen sesiCheckpointing fileOutput terstruktur di SDKHosting Agent SDKPenyebaran agen AI dengan amanMemodifikasi prompt sistemMCP di SDKAlat kustomSubagen di SDKPerintah garis miring di SDKKeterampilan agen di SDKPelacakan biaya dan penggunaanDaftar tugasPlugin di SDK
    MCP di API
    Konektor MCPServer MCP jarak jauh
    Claude di platform pihak ketiga
    Amazon BedrockMicrosoft FoundryVertex AI
    Rekayasa prompt
    IkhtisarGenerator promptGunakan template promptPenyempurna promptJadilah jelas dan langsungGunakan contoh (prompting multishot)Biarkan Claude berpikir (CoT)Gunakan tag XMLBerikan Claude peran (prompt sistem)Rantai prompt kompleksTips konteks panjangTips pemikiran diperpanjang
    Uji & evaluasi
    Tentukan kriteria kesuksesanKembangkan kasus ujiMenggunakan alat evaluasiMengurangi latensi
    Perkuat penjaga
    Kurangi halusinasiTingkatkan konsistensi outputMitigasi jailbreakStreaming penolakanKurangi kebocoran promptJaga Claude tetap dalam karakter
    Administrasi dan pemantauan
    Ikhtisar Admin APIResidensi dataRuang kerjaAPI penggunaan dan biayaClaude Code Analytics APIRetensi data nol
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    Panduan

    Kembalikan perubahan file dengan checkpointing

    Lacak perubahan file selama sesi agen dan kembalikan file ke status sebelumnya

    File checkpointing melacak modifikasi file yang dilakukan melalui alat Write, Edit, dan NotebookEdit selama sesi agen, memungkinkan Anda untuk mengembalikan file ke status sebelumnya. Ingin mencobanya? Lompat ke contoh interaktif.

    Dengan checkpointing, Anda dapat:

    • Batalkan perubahan yang tidak diinginkan dengan mengembalikan file ke status yang diketahui baik
    • Jelajahi alternatif dengan mengembalikan ke checkpoint dan mencoba pendekatan berbeda
    • Pulihkan dari kesalahan ketika agen membuat modifikasi yang salah

    Hanya perubahan yang dilakukan melalui alat Write, Edit, dan NotebookEdit yang dilacak. Perubahan yang dilakukan melalui perintah Bash (seperti echo > file.txt atau sed -i) tidak ditangkap oleh sistem checkpoint.

    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 mencakup UUID checkpoint yang dapat Anda gunakan sebagai titik pemulihan.

    Checkpoint bekerja dengan alat bawaan ini yang digunakan agen untuk memodifikasi file:

    AlatDeskripsi
    WriteMembuat file baru atau menimpa file yang ada dengan konten baru
    EditMembuat pengeditan bertarget ke bagian tertentu dari file yang ada
    NotebookEditMemodifikasi sel dalam notebook Jupyter (file .ipynb)

    Pengembalian 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).

    Sistem checkpoint melacak:

    • File yang dibuat selama sesi
    • File yang dimodifikasi selama sesi
    • Konten asli file yang dimodifikasi

    Ketika Anda mengembalikan ke checkpoint, file yang dibuat dihapus dan file yang dimodifikasi dipulihkan ke konten mereka pada titik itu.

    Implementasikan checkpointing

    Untuk menggunakan file checkpointing, aktifkan dalam opsi Anda, tangkap UUID checkpoint dari aliran respons, kemudian panggil rewindFiles() (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.

    import asyncio
    import os
    from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
    
    async def main():
        # Step 1: Enable checkpointing
        options = ClaudeAgentOptions(
            enable_file_checkpointing=True,
            permission_mode="acceptEdits",  # Auto-accept file edits without prompting
            extra_args={"replay-user-messages": None},  # Required to receive checkpoint UUIDs in the response stream
            env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
        )
    
        checkpoint_id = None
        session_id = None
    
        # Run the query and capture checkpoint UUID and session ID
        async with ClaudeSDKClient(options) as client:
            await client.query("Refactor the authentication module")
    
            # Step 2: Capture checkpoint UUID from the first user message
            async for message in client.receive_response():
                if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
                    checkpoint_id = message.uuid
                if isinstance(message, ResultMessage) and not session_id:
                    session_id = message.session_id
    
        # Step 3: Later, rewind by resuming the session with an empty prompt
        if checkpoint_id and session_id:
            async with ClaudeSDKClient(ClaudeAgentOptions(
                enable_file_checkpointing=True,
                resume=session_id
            )) as client:
                await client.query("")  # Empty prompt to open the connection
                async for message in client.receive_response():
                    await client.rewind_files(checkpoint_id)
                    break
            print(f"Rewound to checkpoint: {checkpoint_id}")
    
    asyncio.run(main())
    1. 1

      Atur variabel lingkungan

      File checkpointing memerlukan variabel lingkungan CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING. Anda dapat mengaturnya melalui baris perintah sebelum menjalankan skrip Anda, atau langsung dalam opsi SDK.

      Opsi 1: Atur melalui baris perintah

      Python
      export CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=1

      Opsi 2: Atur dalam opsi SDK

      Lewatkan variabel lingkungan melalui opsi env saat mengonfigurasi SDK:

      import os
      
      options = ClaudeAgentOptions(
          enable_file_checkpointing=True,
          env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
      )
    2. 2

      Aktifkan checkpointing

      Konfigurasikan opsi SDK Anda untuk mengaktifkan checkpointing dan menerima UUID checkpoint:

      OpsiPythonTypeScriptDeskripsi
      Aktifkan checkpointingenable_file_checkpointing=TrueenableFileCheckpointing: trueMelacak perubahan file untuk pengembalian
      Terima UUID checkpointextra_args={"replay-user-messages": None}extraArgs: { 'replay-user-messages': null }Diperlukan untuk mendapatkan UUID pesan pengguna dalam aliran
      options = ClaudeAgentOptions(
          enable_file_checkpointing=True,
          permission_mode="acceptEdits",
          extra_args={"replay-user-messages": None}
      )
      
      async with ClaudeSDKClient(options) as client:
          await client.query("Refactor the authentication module")
    3. 3

      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 mengembalikan 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 dalam Checkpoint sebelum operasi berisiko), Anda dapat melewatkan penangkapan ID sesi.

      checkpoint_id = None
      session_id = None
      
      async for message in client.receive_response():
          # Update checkpoint on each user message (keeps the latest)
          if isinstance(message, UserMessage) and message.uuid:
              checkpoint_id = message.uuid
          # Capture session ID from the result message
          if isinstance(message, ResultMessage):
              session_id = message.session_id
    4. 4

      Kembalikan file

      Untuk mengembalikan setelah aliran selesai, lanjutkan sesi dengan prompt kosong dan panggil rewind_files() (Python) atau rewindFiles() (TypeScript) dengan UUID checkpoint Anda. Anda juga dapat mengembalikan selama aliran; lihat Checkpoint sebelum operasi berisiko untuk pola itu.

      async with ClaudeSDKClient(ClaudeAgentOptions(
          enable_file_checkpointing=True,
          resume=session_id
      )) as client:
          await client.query("")  # Empty prompt to open the connection
          async for message in client.receive_response():
              await client.rewind_files(checkpoint_id)
              break

      Jika Anda menangkap ID sesi dan ID checkpoint, Anda juga dapat mengembalikan dari CLI:

      claude --resume <session-id> --rewind-files <checkpoint-uuid>

    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 paling baru, memperbaruinya sebelum setiap putaran agen. Jika ada yang salah selama pemrosesan, Anda dapat segera mengembalikan ke status terakhir yang aman dan keluar dari loop.

    import asyncio
    import os
    from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage
    
    async def main():
        options = ClaudeAgentOptions(
            enable_file_checkpointing=True,
            permission_mode="acceptEdits",
            extra_args={"replay-user-messages": None},
            env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
        )
    
        safe_checkpoint = None
    
        async with ClaudeSDKClient(options) as client:
            await client.query("Refactor the authentication module")
    
            async for message in client.receive_response():
                # Update checkpoint before each agent turn starts
                # This overwrites the previous checkpoint. Only keep the latest
                if isinstance(message, UserMessage) and message.uuid:
                    safe_checkpoint = message.uuid
    
                # Decide when to revert based on your own logic
                # For example: error detection, validation failure, or user input
                if your_revert_condition and safe_checkpoint:
                    await client.rewind_files(safe_checkpoint)
                    # Exit the loop after rewinding, files are restored
                    break
    
    asyncio.run(main())

    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 mana pun:

    import asyncio
    import os
    from dataclasses import dataclass
    from datetime import datetime
    from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
    
    # Store checkpoint metadata for better tracking
    @dataclass
    class Checkpoint:
        id: str
        description: str
        timestamp: datetime
    
    async def main():
        options = ClaudeAgentOptions(
            enable_file_checkpointing=True,
            permission_mode="acceptEdits",
            extra_args={"replay-user-messages": None},
            env={**os.environ, "CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING": "1"}
        )
    
        checkpoints = []
        session_id = None
    
        async with ClaudeSDKClient(options) as client:
            await client.query("Refactor the authentication module")
    
            async for message in client.receive_response():
                if isinstance(message, UserMessage) and message.uuid:
                    checkpoints.append(Checkpoint(
                        id=message.uuid,
                        description=f"After turn {len(checkpoints) + 1}",
                        timestamp=datetime.now()
                    ))
                if isinstance(message, ResultMessage) and not session_id:
                    session_id = message.session_id
    
        # Later: rewind to any checkpoint by resuming the session
        if checkpoints and session_id:
            target = checkpoints[0]  # Pick any checkpoint
            async with ClaudeSDKClient(ClaudeAgentOptions(
                enable_file_checkpointing=True,
                resume=session_id
            )) as client:
                await client.query("")  # Empty prompt to open the connection
                async for message in client.receive_response():
                    await client.rewind_files(target.id)
                    break
            print(f"Rewound to: {target.description}")
    
    asyncio.run(main())

    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.

    1. 1

      Buat file pengujian

      Buat file baru bernama utils.py (Python) atau utils.ts (TypeScript) dan tempel kode berikut:

      def add(a, b):
          return a + b
      
      def subtract(a, b):
          return a - b
      
      def multiply(a, b):
          return a * b
      
      def divide(a, b):
          if b == 0:
              raise ValueError("Cannot divide by zero")
          return a / b
    2. 2

      Jalankan contoh interaktif

      Buat file baru bernama 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 mengembalikan aslinya.

      import asyncio
      from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage, ResultMessage
      
      async def main():
          # Configure the SDK with checkpointing enabled
          # - enable_file_checkpointing: Track file changes for rewinding
          # - permission_mode: Auto-accept file edits without prompting
          # - extra_args: Required to receive user message UUIDs in the stream
          options = ClaudeAgentOptions(
              enable_file_checkpointing=True,
              permission_mode="acceptEdits",
              extra_args={"replay-user-messages": None}
          )
      
          checkpoint_id = None  # Store the user message UUID for rewinding
          session_id = None     # Store the session ID for resuming
      
          print("Running agent to add doc comments to utils.py...\n")
      
          # Run the agent and capture checkpoint data from the response stream
          async with ClaudeSDKClient(options) as client:
              await client.query("Add doc comments to utils.py")
      
              async for message in client.receive_response():
                  # Capture the first user message UUID - this is our restore point
                  if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
                      checkpoint_id = message.uuid
                  # Capture the session ID so we can resume later
                  if isinstance(message, ResultMessage):
                      session_id = message.session_id
      
          print("Done! Open utils.py to see the added doc comments.\n")
      
          # Ask the user if they want to rewind the changes
          if checkpoint_id and session_id:
              response = input("Rewind to remove the doc comments? (y/n): ")
      
              if response.lower() == "y":
                  # Resume the session with an empty prompt, then rewind
                  async with ClaudeSDKClient(ClaudeAgentOptions(
                      enable_file_checkpointing=True,
                      resume=session_id
                  )) as client:
                      await client.query("")  # Empty prompt opens the connection
                      async for message in client.receive_response():
                          await client.rewind_files(checkpoint_id)  # Restore files
                          break
      
                  print("\n✓ File restored! Open utils.py to verify the doc comments are gone.")
              else:
                  print("\nKept the modified file.")
      
      asyncio.run(main())

      Contoh ini mendemonstrasikan alur kerja checkpointing lengkap:

      1. Aktifkan checkpointing: konfigurasikan SDK dengan enable_file_checkpointing=True dan permission_mode="acceptEdits" untuk menyetujui pengeditan file secara otomatis
      2. Tangkap data checkpoint: saat agen berjalan, simpan UUID pesan pengguna pertama (titik pemulihan Anda) dan ID sesi
      3. Minta pengembalian: setelah agen selesai, periksa file utilitas Anda untuk melihat komentar doc, kemudian putuskan apakah Anda ingin membatalkan perubahan
      4. Lanjutkan dan kembalikan: jika ya, lanjutkan sesi dengan prompt kosong dan panggil rewind_files() untuk mengembalikan file asli
    3. 3

      Jalankan contoh

      Atur variabel lingkungan dan jalankan skrip dari direktori yang sama dengan file utilitas Anda.

      Buka file utilitas Anda (utils.py atau utils.ts) di IDE atau editor Anda sebelum menjalankan skrip. Anda akan melihat file diperbarui secara real-time saat agen menambahkan komentar doc, kemudian kembali ke aslinya ketika Anda memilih untuk mengembalikan.

      Anda akan melihat agen menambahkan komentar doc, kemudian prompt menanyakan apakah Anda ingin mengembalikan. Jika Anda memilih ya, file dipulihkan ke status aslinya.

    Keterbatasan

    File checkpointing memiliki keterbatasan berikut:

    KeterbatasanDeskripsi
    Alat Write/Edit/NotebookEdit sajaPerubahan yang dilakukan melalui perintah Bash tidak dilacak
    Sesi yang samaCheckpoint terikat pada sesi yang membuatnya
    Konten file sajaMembuat, memindahkan, atau menghapus direktori tidak dibatalkan oleh pengembalian
    File lokalFile jarak jauh atau jaringan tidak dilacak

    Pemecahan masalah

    Opsi checkpointing tidak dikenali

    Jika enableFileCheckpointing 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

    Jika message.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:

    • Variabel lingkungan CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING tidak diatur
    • Sesi tidak diselesaikan dengan benar sebelum mencoba melanjutkan dan mengembalikan

    Solusi: Pastikan Anda telah mengatur variabel lingkungan (lihat Atur variabel lingkungan), 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 memanggil rewindFiles() 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:

    # Resume session with empty prompt, then rewind
    async with ClaudeSDKClient(ClaudeAgentOptions(
        enable_file_checkpointing=True,
        resume=session_id
    )) as client:
        await client.query("")
        async for message in client.receive_response():
            await client.rewind_files(checkpoint_id)
            break

    Langkah berikutnya

    • Sesi: pelajari cara melanjutkan sesi, yang diperlukan untuk pengembalian setelah aliran selesai. Mencakup ID sesi, melanjutkan percakapan, dan forking sesi.
    • Izin: konfigurasikan 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 metode rewindFiles().
    • Referensi SDK Python: referensi API lengkap termasuk semua opsi untuk ClaudeAgentOptions dan metode rewind_files().

    Was this page helpful?

    • Cara kerja checkpointing
    • Implementasikan checkpointing
    • Pola umum
    • Checkpoint sebelum operasi berisiko
    • Beberapa titik pemulihan
    • Coba sekarang
    • Keterbatasan
    • Pemecahan masalah
    • Opsi checkpointing tidak dikenali
    • Pesan pengguna tidak memiliki UUID
    • Kesalahan "No file checkpoint found for message"
    • Kesalahan "ProcessTransport is not ready for writing"
    • Langkah berikutnya