Mulai dari TypeScript Agent SDK 0.3.142 dan Claude Code v2.1.142, sesi menggunakan alat Task terstruktur
TaskCreate, TaskUpdate, TaskGet, dan TaskList sebagai pengganti TodoWrite. Python SDK mendapatkan perubahan ini dari Claude Code CLI yang diluncurkannya, bukan dari versi paket Python: pengalihan berlaku setelah CLI tersebut — salinan yang disertakan dalam paket pip, atau yang Anda tunjuk dengan cli_path — adalah v2.1.142 atau lebih baru. Lihat Migrasi ke alat Task untuk cara memantau perubahan kode. Contoh di halaman ini menetapkan CLAUDE_CODE_ENABLE_TASKS=0 untuk terus menampilkan TodoWrite untuk sesi yang belum bermigrasi.Siklus Hidup Todo
Todos mengikuti siklus hidup yang dapat diprediksi:- Dibuat sebagai
pendingketika tugas diidentifikasi - Diaktifkan menjadi
in_progressketika pekerjaan dimulai - Diselesaikan ketika tugas selesai dengan sukses
- Dihapus ketika semua tugas dalam grup selesai
Kapan Todos Digunakan
SDK membuat todos untuk sebagian besar pekerjaan multi-langkah, seperti:- Tugas multi-langkah yang kompleks memerlukan 3 atau lebih tindakan yang berbeda
- Daftar tugas yang disediakan pengguna ketika beberapa item disebutkan
- Operasi non-trivial yang mendapat manfaat dari pelacakan kemajuan
- Permintaan eksplisit ketika pengguna meminta organisasi todo
Contoh
Sebelum menjalankan contoh-contoh ini, instal Claude Agent SDK dengan mengikuti quickstart. Setiap contoh berjalan sampai agen selesai dan menghasilkan pesan hasil akhirnya. Jika sesi mencapai batas giliran terlebih dahulu, pesan hasil tersebut memiliki subtipeerror_max_turns. Periksa subtype untuk mendeteksi penghentian tersebut.
Contoh-contoh ini menggunakan panggilan query() single-shot. Setelah menghasilkan hasil error_max_turns, query() melempar kesalahan yang mencakup Reached maximum number of turns. Setiap contoh membungkus loop-nya dalam blok try untuk keluar dengan bersih ketika itu terjadi.
Lihat Handle the result untuk subtipe hasil.
Memantau Perubahan Todo
Tampilan Kemajuan Real-time
Migrasi ke alat Task
Alat Task membagi panggilanTodoWrite tunggal menjadi TaskCreate untuk setiap item baru dan TaskUpdate untuk setiap perubahan status, dengan TaskList dan TaskGet tersedia untuk model membaca kembali daftar saat ini. Kode pemantauan Anda masih memeriksa blok tool_use dalam aliran asisten, tetapi mempertahankan peta yang dikunci berdasarkan ID tugas alih-alih mengganti seluruh daftar pada setiap panggilan. Alat Task adalah default mulai dari TypeScript Agent SDK 0.3.142 dan Claude Code v2.1.142, jadi tidak ada perubahan options.env yang diperlukan.
ID tugas yang ditugaskan tidak ada dalam input
TaskCreate. Ini kembali dalam tool_result yang cocok sebagai { task: { id, subject } }, jadi tangkap dari blok hasil untuk mengunci peta Anda. Contoh berikut menunjukkan perubahan minimal ke loop Memantau Perubahan Todo. Ini membaca hanya input tool_use dan melewatkan penangkapan ID dari blok tool_result. Untuk merender daftar lengkap, pantau hasil alat TaskList dalam aliran atau akumulasi hasil TaskCreate dan input TaskUpdate ke dalam peta.
Input tool_use yang dialirkan adalah bentuk mentah yang dipancarkan model. Claude Code memperbaiki beberapa nama kunci yang hampir-tetapi-tidak-benar sebelum eksekusi, memetakan id atau task_id ke taskId dan active_form ke activeForm, tetapi perbaikan itu tidak tercermin dalam aliran. Baca bidang input TaskUpdate secara defensif, seperti yang dilakukan sampel di bawah ini, daripada mengasumsikan nama kanonik selalu ada.