Sesi mempertahankan percakapan, bukan sistem file. Untuk membuat snapshot dan mengembalikan perubahan file yang dibuat agen, gunakan file checkpointing.
resume dan fork secara manual, dan apa yang perlu diketahui tentang melanjutkan sesi di seluruh host.
Pilih pendekatan
Seberapa banyak penanganan sesi yang Anda butuhkan tergantung pada bentuk aplikasi Anda. Manajemen sesi menjadi penting ketika Anda mengirim beberapa prompt yang harus berbagi konteks. Dalam satu panggilanquery(), agen sudah mengambil sebanyak putaran yang diperlukan, dan prompt izin serta AskUserQuestion ditangani dalam loop (mereka tidak mengakhiri panggilan).
| Apa yang Anda bangun | Apa yang digunakan |
|---|---|
| Tugas sekali jalan: prompt tunggal, tanpa lanjutan | Tidak ada yang ekstra. Satu panggilan query() menanganinya. |
| Obrolan multi-putaran dalam satu proses | ClaudeSDKClient (Python) atau continue: true (TypeScript). SDK melacak sesi untuk Anda tanpa penanganan ID. |
| Lanjutkan dari mana Anda berhenti setelah restart proses | continue_conversation=True (Python) / continue: true (TypeScript). Melanjutkan sesi terbaru di direktori, tidak perlu ID. |
| Lanjutkan sesi masa lalu tertentu (bukan yang terbaru) | Tangkap ID sesi dan teruskan ke resume. |
| Coba pendekatan alternatif tanpa kehilangan yang asli | Fork sesi. |
| Tugas stateless, tidak ingin apa pun ditulis ke disk (TypeScript saja) | Atur persistSession: false. Sesi hanya ada dalam memori untuk durasi panggilan. Python selalu bertahan ke disk. |
Continue, resume, dan fork
Continue, resume, dan fork adalah bidang opsi yang Anda atur padaquery() (ClaudeAgentOptions di Python, Options di TypeScript).
Continue dan resume keduanya mengambil sesi yang ada dan menambahkannya. Perbedaannya adalah cara mereka menemukan sesi tersebut:
- Continue menemukan sesi terbaru di direktori saat ini. Anda tidak melacak apa pun. Bekerja dengan baik ketika aplikasi Anda menjalankan satu percakapan pada satu waktu.
- Resume mengambil ID sesi tertentu. Anda melacak ID. Diperlukan ketika Anda memiliki beberapa sesi (misalnya, satu per pengguna dalam aplikasi multi-pengguna) atau ingin kembali ke sesi yang bukan yang terbaru.
Manajemen sesi otomatis
Kedua SDK menawarkan antarmuka yang melacak status sesi untuk Anda di seluruh panggilan, sehingga Anda tidak perlu melewatkan ID secara manual. Gunakan ini untuk percakapan multi-putaran dalam satu proses.Python: ClaudeSDKClient
ClaudeSDKClient menangani ID sesi secara internal. Setiap panggilan ke client.query() secara otomatis melanjutkan sesi yang sama. Panggil client.receive_response() untuk mengulangi pesan untuk kueri saat ini. Gunakan klien sebagai manajer konteks async sehingga penyiapan dan pembongkaran koneksi ditangani untuk Anda, atau panggil connect() dan disconnect() secara manual.
Contoh ini menjalankan dua kueri terhadap client yang sama. Yang pertama meminta agen untuk menganalisis modul; yang kedua memintanya untuk refactor modul tersebut. Karena kedua panggilan melalui instance klien yang sama, kueri kedua memiliki konteks lengkap dari yang pertama tanpa resume atau ID sesi eksplisit:
Python
ClaudeSDKClient versus fungsi query() mandiri.
TypeScript: continue: true
SDK TypeScript tidak memiliki objek klien yang memegang sesi seperti ClaudeSDKClient Python. Sebagai gantinya, teruskan continue: true pada setiap panggilan query() berikutnya dan SDK mengambil sesi terbaru di direktori saat ini. Tidak perlu pelacakan ID.
Contoh ini membuat dua panggilan query() terpisah. Yang pertama membuat sesi segar; yang kedua menetapkan continue: true, yang memberitahu SDK untuk menemukan dan melanjutkan sesi terbaru di disk. Agen memiliki konteks lengkap dari panggilan pertama:
TypeScript
API sesi V2 eksperimental, yang menyediakan
createSession() dengan pola send / stream, sudah dihapus di TypeScript Agent SDK 0.3.142. Gunakan fungsi query() dan opsi sesi yang dijelaskan di halaman ini sebagai gantinya.Gunakan opsi sesi dengan query()
Tangkap ID sesi
Resume dan fork memerlukan ID sesi. Bacanya dari bidangsession_id pada pesan hasil (ResultMessage di Python, SDKResultMessage di TypeScript), yang ada di setiap hasil terlepas dari kesuksesan atau kesalahan. Di TypeScript ID juga tersedia lebih awal sebagai bidang langsung pada SystemMessage init; di Python itu bersarang di dalam SystemMessage.data.
Lanjutkan berdasarkan ID
Teruskan ID sesi keresume untuk kembali ke sesi tertentu tersebut. Agen mengambil dengan konteks lengkap dari mana pun sesi berakhir. Alasan umum untuk melanjutkan:
- Lanjutkan tugas yang selesai. Agen sudah menganalisis sesuatu; sekarang Anda ingin itu bertindak atas analisis tersebut tanpa membaca ulang file.
- Pulih dari batas. Run pertama berakhir dengan
error_max_turnsatauerror_max_budget_usd(lihat Tangani hasil); lanjutkan dengan batas yang lebih tinggi. - Mulai ulang proses Anda. Anda menangkap ID sebelum shutdown dan ingin memulihkan percakapan.
SessionStore.
Fork untuk menjelajahi alternatif
Forking membuat sesi baru yang dimulai dengan salinan riwayat asli tetapi menyimpang dari titik itu. Fork mendapatkan ID sesi sendiri; ID asli dan riwayat tetap tidak berubah. Anda berakhir dengan dua sesi independen yang dapat Anda lanjutkan secara terpisah.Forking membuat cabang riwayat percakapan, bukan sistem file. Jika agen yang di-fork mengedit file, perubahan tersebut nyata dan terlihat oleh sesi apa pun yang bekerja di direktori yang sama. Untuk membuat cabang dan mengembalikan perubahan file, gunakan file checkpointing.
session_id dan ingin menjelajahi OAuth2 tanpa kehilangan utas yang berfokus pada JWT. Blok pertama fork sesi dan menangkap ID fork (forked_id); blok kedua melanjutkan session_id asli untuk melanjutkan jalur yang berfokus pada JWT. Anda sekarang memiliki dua ID sesi yang menunjuk ke dua riwayat terpisah:
Lanjutkan di seluruh host
File sesi bersifat lokal untuk mesin yang membuatnya. Untuk melanjutkan sesi di host berbeda (pekerja CI, kontainer ephemeral, serverless), Anda memiliki dua opsi:- Pindahkan file sesi. Pertahankan
~/.claude/projects/<encoded-cwd>/<session-id>.jsonldari run pertama dan pulihkan ke jalur yang sama di host baru sebelum memanggilresume.cwdharus cocok. - Jangan andalkan resume sesi. Tangkap hasil yang Anda butuhkan (output analisis, keputusan, diff file) sebagai status aplikasi dan teruskan ke prompt sesi segar. Ini sering lebih kuat daripada mengirim file transkrip.
listSessions() dan getSessionMessages() di TypeScript, list_sessions() dan get_session_messages() di Python. Gunakan mereka untuk membangun pemilih sesi kustom, logika pembersihan, atau penampil transkrip.
Kedua SDK juga mengekspos fungsi untuk mencari dan mengubah sesi individual: get_session_info(), rename_session(), dan tag_session() di Python, dan getSessionInfo(), renameSession(), dan tagSession() di TypeScript. Gunakan mereka untuk mengorganisir sesi berdasarkan tag atau memberi mereka judul yang dapat dibaca manusia.
Sumber daya terkait
- Bagaimana loop agen bekerja: Pahami putaran, pesan, dan akumulasi konteks dalam sesi
- File checkpointing: Lacak dan kembalikan perubahan file di seluruh sesi
- Python
ClaudeAgentOptions: Referensi opsi sesi lengkap untuk Python - TypeScript
Options: Referensi opsi sesi lengkap untuk TypeScript