Agen LangGraph akhirnya mendapatkan cara yang andal untuk mempertahankan status mereka setelah berminggu-minggu mengalami kehilangan data secara diam-diam. Setelah tiga trik checkpointing yang gagal—SQLite, penyimpanan objek mentah (raw object storage), dan versi yang rusak dari masing-masing metode tersebut—penulis akhirnya menemukan pola pembaruan atomik (atomic-update pattern) yang menghentikan agen agar tidak memulai ulang dari awal setiap kali permintaan tiba.

Mengapa checkpointing penting untuk LangGraph

LangGraph memungkinkan pengembang merangkai panggilan LLM menjadi "agen" yang dapat digunakan kembali dan dapat mengingat apa yang terjadi sebelumnya dalam sebuah percakapan. Agen-agen tersebut memecah permintaan pengguna menjadi sub-tugas, menyimpan hasil antara, dan melanjutkan dari titik terakhir mereka berhenti pada panggilan berikutnya. Jika status yang disimpan hilang, agen akan menghitung ulang semuanya, membuang daya komputasi, meningkatkan latensi, dan memberikan pengalaman pengguna yang buruk. Pada bot produksi yang menangani pesan Telegram, kehilangan data tersebut menghapus riwayat percakapan selama berminggu-minggu.

Perbaikan pertama: SQLite saver

SqliteSaver bawaan berfungsi dengan baik ketika hanya satu instansi yang menjalankan agen. Ia menulis setiap checkpoint sebagai blob JSON dalam file SQLite lokal. Masalah dimulai ketika pengembang menambahkan bidang (field) baru ke tipe AgentState dan melakukan penyebaran ulang (redeploy). Checkpoint yang sudah ada, yang dibuat sebelum perubahan skema, tidak memiliki bidang baru tersebut. Karena SqliteSaver tidak pernah menjalankan migrasi, LangGraph memuat JSON yang tidak lengkap, membuang data yang hilang, dan agen pun memulai ulang dari awal.

Poin kunci: Penyimpanan SQLite adalah alat demo, bukan solusi siap produksi ketika evolusi skema diperlukan.

Perbaikan kedua: Object storage

Untuk mendapatkan kendali atas format serialisasi, penulis menulis saver khusus yang mengunggah checkpoint JSON ke Oracle Cloud Object Storage. Langkah ini memberikan fleksibilitas untuk mengelola versi skema secara manual, tetapi memperkenalkan mode kegagalan baru. Ketika dua permintaan mengenai utas percakapan yang sama secara bersamaan, keduanya mencoba menimpa objek yang sama. Layanan penyimpanan objek dioptimalkan untuk pola write-once, read-many; mereka tidak menyediakan semantik penimpaan atomik. Kondisi balapan (race condition) tersebut menghasilkan file JSON yang rusak atau terpotong, dan agen kembali kehilangan konteksnya.

Poin kunci: Penimpaan biasa dalam penyimpanan objek tidak aman ketika beberapa worker dapat menyentuh kunci yang sama pada waktu yang bersamaan.

Perbaikan ketiga: Pembaruan atomik dengan penomoran versi

Desain akhir yang stabil menggabungkan dua ide: nomor versi eksplisit dan penulisan kondisional berdasarkan ETag objek (pengidentifikasi checksum dari layanan penyimpanan).

  1. Baca checkpoint saat ini dan tangkap ETag-nya.
  2. Naikkan (increment) bidang versi di dalam pembungkus (envelope) checkpoint.
  3. Tulis checkpoint yang telah diperbarui menggunakan permintaan kondisional yang hanya berhasil jika ETag cocok dengan yang dibaca sebelumnya.
  4. Ulangi (retry) seluruh loop baca-naikkan-tulis jika penulisan kondisional gagal karena proses lain telah mengubah objek tersebut.

Karena penulisan hanya berhasil jika tidak ada proses lain yang mengubah file, hanya satu worker yang dapat mengirimkan status baru pada satu waktu. Bidang versi juga memudahkan deteksi checkpoint usang dan melakukan migrasi ke depan ketika skema berubah.

Pola ini berfungsi dengan penyimpanan objek yang mendukung penulisan kondisional berbasis ETag.

Pelajaran bagi insinyur AI

  • Gunakan SQLite hanya untuk prototipe. Agen produksi membutuhkan penyimpan yang dapat menangani perubahan skema dan penulisan konkuren.
  • Rencanakan migrasi skema Anda sendiri. Typed dictionaries mendeskripsikan bentuk untuk analisis statis tetapi tidak memaksakan struktur saat runtime.
  • Anggap status sebagai sumber daya bersama. Bug konkurensi muncul sebagai kehilangan data secara diam-diam; mereka lebih sulit didebug daripada pengecualian (exception) yang nyata.
  • Gunakan primitif cloud. Penulisan kondisional berbasis ETag memberikan penguncian optimis (optimistic locking) yang murah tanpa memerlukan layanan penguncian terpisah.
  • Catat setiap langkah. Kegagalan diam-diam—seperti bidang yang hilang yang diabaikan oleh LangGraph—adalah yang paling sulit untuk dilacak.

Apa selanjutnya untuk checkpointing LangGraph?

Bagi tim yang sudah menemui hambatan yang sama, resep pembaruan atomik ini menawarkan perbaikan yang cepat dan berbiaya rendah. Ini menunjukkan bahwa alur produksi yang andal tidak memerlukan penyimpan status yang berat—hanya penanganan konkurensi dan penomoran versi yang cermat.

Intisari: Pembungkus berversi yang sederhana ditambah penulisan kondisional mengubah sistem yang tidak stabil menjadi sistem yang andal, memungkinkan insinyur AI fokus pada logika agen daripada proses debugging kehilangan data yang tak ada habisnya.