Handoff manusia dan agen: persetujuan harus melekat pada versi

Agen menyiapkan draf, editor menyetujui, lalu sebuah proses otomatis memperbarui angka di draf sebelum publikasi. Apakah persetujuan tadi masih berlaku? Jika sistem hanya menyimpan boolean approved, jawabannya tidak dapat dipertanggungjawabkan. Persetujuan perlu menunjuk objek dan versi yang benar-benar dilihat manusia.

LangGraph interrupts memberi contoh mekanisme menghentikan eksekusi untuk menunggu input, sementara persistence menyimpan state agar pekerjaan dapat dilanjutkan. Artikel ini menggunakan konsep tersebut untuk merancang protokol handoff editorial yang independen dari framework.

Paket review harus konkret

Jangan meminta editor menyetujui “hasil agen” yang masih berubah. Tampilkan judul, isi, sumber, aset, tujuan distribusi, dan tindakan yang akan dijalankan. Untuk pengiriman pesan, penerima serta lampiran merupakan bagian dari objek review.

Simpan job_id, revisi output, revisi sumber, dan status pekerjaan. Jika sumber berubah tetapi teks belum berubah, editor tetap perlu tahu apakah hasil lama masih sesuai. Kebijakan dapat menentukan bagian mana yang perlu diperiksa ulang.

Contoh kontrak pekerjaan:

{
  "job_id": "PUB-042",
  "state": "waiting_review",
  "output_revision": 3,
  "source_revisions": ["S01:r7", "S02:r2"],
  "action": "publish_article",
  "destination": "website",
  "review_deadline": "2026-10-24T00:00:00+00:00"
}

Ini record aplikasi fiktif, bukan payload resmi LangGraph. Label publish_article sendiri tidak menjalankan publikasi. Pelaksana tindakan tetap memerlukan otorisasi dan pemeriksaan status.

State machine memperjelas keputusan yang sah

Gunakan transisi yang eksplisit, misalnya drafting → waiting_review → approved → executing → completed. Jalur lain dapat menuju revision_requested, rejected, atau expired. Tentukan transisi yang boleh dilakukan tiap peran.

Perubahan output saat waiting_review menghasilkan revisi baru. Perubahan setelah approved membatalkan persetujuan lama dan mengembalikan pekerjaan ke review sesuai kebijakan. Hindari status gabungan yang ambigu seperti approved_but_maybe_changed.

Status pekerjaan dan status satu tindakan dapat berbeda. Artikel mungkin sudah terbit, sementara pembuatan versi newsletter masih gagal. Model satu status untuk seluruh kampanye akan menyulitkan pemulihan tanpa mengulang langkah yang sudah selesai.

Fingerprint membantu mengikat persetujuan ke isi

Contoh Python berikut membuat digest dari objek yang sudah memenuhi kontrak aplikasi:

import hashlib
import json


def review_digest(payload):
    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"),
                         ensure_ascii=False, allow_nan=False).encode("utf-8")
    return hashlib.sha256(encoded).hexdigest()


def approval_matches(payload, approval):
    return (approval["decision"] == "approve"
            and approval["job_id"] == payload["job_id"]
            and approval["digest"] == review_digest(payload))

Serializer ini adalah konvensi aplikasi Python contoh, bukan implementasi standar canonical JSON lintas bahasa. Bila beberapa bahasa menghasilkan fingerprint, tetapkan canonicalization yang sama atau hash byte artefak final yang disimpan. Jangan menghitung digest dari representasi yang berbeda antara layar review dan pelaksana tindakan.

Digest bukan tanda tangan atau bukti identitas pemberi persetujuan. approval harus berasal dari penyimpanan server setelah autentikasi, pengecekan peran, dan pencatatan waktu. Aplikasi juga perlu memeriksa kedaluwarsa, pencabutan, dan status pekerjaan sebelum resume.

Resume dapat mengulang sebagian eksekusi

Dokumentasi interrupts menjelaskan bahwa saat node dilanjutkan, kode pada bagian awal node dapat dieksekusi kembali. Karena itu, menaruh pengiriman email sebelum titik interrupt dapat menyebabkan efek samping berulang bila desainnya tidak idempoten.

Pisahkan penyiapan data, permintaan review, dan tindakan. Simpan hasil langkah yang mahal atau memiliki efek samping dengan identitas operasi. Saat resume, baca hasil yang sudah tersimpan daripada berasumsi semua kode hanya akan dijalankan sekali.

Pada sistem dengan beberapa pekerja, gunakan pembaruan status atomik. Dua permintaan resume yang datang bersamaan tidak boleh sama-sama mengubah pekerjaan menjadi executing. Periksa revisi yang diharapkan dalam kondisi update; bila tidak cocok, tampilkan konflik dan ambil state terbaru.

Antarmuka review harus menjelaskan apa yang berubah

Ketika editor kembali setelah beberapa jam, tampilkan diff terhadap versi yang terakhir dilihat, sumber yang berubah, dan alasan pekerjaan menunggu. Jangan memaksa pengguna membaca ulang seluruh riwayat tool hanya untuk mengetahui keputusan yang dibutuhkan.

Usulan agen dapat membantu merangkum perubahan, tetapi ringkasan itu perlu tautan ke diff atau bukti yang dapat dibuka. Keputusan manusia tetap membutuhkan akses ke objek sebenarnya.

Uji kegagalan di sekitar batas persetujuan

Buat kasus: editor menyetujui versi 3 tetapi versi 4 aktif; persetujuan kedaluwarsa; dua resume bersamaan; proses mati setelah tindakan berhasil tetapi sebelum status tersimpan; sumber dicabut setelah review. Tulis hasil yang diharapkan untuk masing-masing kasus.

Pastikan pengguna dapat melanjutkan tanpa membuat pekerjaan baru ketika state lama masih valid. Sebaliknya, jangan memaksakan resume bila objek review sudah berubah. Recovery yang baik mempertahankan pekerjaan yang benar sambil menolak keputusan yang sudah tidak berlaku.

Tambahkan satu latihan ketika editor kehilangan hak akses setelah memberi persetujuan. Pelaksana perlu memeriksa kembali apakah keputusan itu masih berwenang menurut kebijakan aplikasi. Simpan alasan penolakan tanpa menghapus jejak keputusan lama. Dengan begitu, audit dapat membedakan persetujuan yang pernah sah dari tindakan yang tidak lagi boleh dijalankan saat resume.

Untuk penanganan efek samping dan pengiriman ulang, lanjutkan ke antrean, idempotensi, dan outbox. Untuk kebiasaan kerja sehari-hari, panduan coding agent menunjukkan bagaimana kontrak tugas dan bukti tes mempermudah handoff sebelum persetujuan diminta.