Human-in-the-Loop

Sebelum mulai, pastikan hal-hal ini sudah akrab bagimu:

• Putaran tool use dari topik Tool use: tool_use, tool_result, is_error, dan aturan bahwa semua hasil satu giliran dikirim dalam satu pesan. Proyek di topik itu sudah meminta gerbang persetujuan untuk pinjam_buku; di sini kita membuatnya kokoh.
• Topik Keamanan agen, terutama langkah tentang otorisasi di kode dan persetujuan yang tak melelahkan. Persetujuan manusia adalah satu lapis pertahanan, bukan satu-satunya.
• Python 3.10 atau lebih baru, dataclass, datetime, dan JSON.
• Sedikit pengalaman membuat antarmuka, karena pertanyaan persetujuan pada akhirnya dibaca manusia.

Tak perlu kunci API. Semua contoh dijalankan dengan model tiruan.

Langkah pertama bukan menulis kode, melainkan memutuskan peran pengguna. Lima tingkat dari Feng dkk. (2025) membantu memilih:

Makalah itu juga jujur tentang biayanya. Tingkat 4 cocok untuk pekerjaan dengan banyak keputusan berisiko rendah, karena mengurangi beban pengguna. Tetapi makin tinggi otonominya, makin banyak hal sensitif yang dipegang agen, misalnya kredensial, dan kesalahan bisa menumpuk tanpa ada yang melihat.

Untuk agen perpustakaan, tingkat 4 masuk akal. Mencari buku dan menjawab pertanyaan tak perlu ditanyakan. Meminjamkan buku mengubah stok dan catatan anggota, jadi ia menunggu persetujuan.

Tak semua aksi sama beratnya. Anthropic menemukan bahwa di API publiknya hanya sekitar 0,8% aksi agen yang tampak tak bisa dibatalkan, misalnya mengirim email ke pelanggan. Sebagian besar aksi berisiko rendah. Karena itu, kelompokkan aksi menurut akibatnya, lalu beri setiap kelompok perlakuan yang berbeda:

def tingkat(nama_tool: str) -> str:
    """Penegakan bertingkat: otomatis, otomatis tapi dicatat, tanya manusia, atau tolak."""
    return {"cari_buku": "otomatis", "perpanjang_pinjaman": "catat", "pinjam_buku": "tanya"}.get(nama_tool, "tolak")

Empat tingkat ini mengikuti saran OWASP 2026 tentang penegakan bertingkat (audit, warn, block, escalate):

• otomatis untuk aksi baca yang tak mengubah apa pun;
• catat untuk aksi kecil yang bisa dibatalkan; ia jalan sendiri, tetapi masuk jejak audit supaya bisa ditinjau;
• tanya untuk aksi yang berakibat nyata;
• tolak untuk aksi yang memang tak boleh dilakukan agen, dan juga untuk tool yang tak dikenal.

Perhatikan bawaannya: tool yang tak ada di daftar jatuh ke tolak, bukan ke otomatis. Kalau suatu hari ada tool baru yang lupa didaftarkan, agen tak diam-diam mendapat kebebasan baru.

Saat memutuskan tingkat sebuah aksi, tanyakan dua hal: seberapa besar kerugiannya bila salah, dan seberapa mudah kerugian itu dibatalkan. Meminjamkan buku bisa dibatalkan, tetapi stok yang berubah memengaruhi anggota lain. Menghapus anggota hampir tak bisa dibatalkan.

Ingat angka 93% tadi. Setiap pertanyaan yang tak perlu bukan sekadar mengganggu; ia melatih pengguna untuk menekan "setuju" tanpa membaca. Tulisan Anthropic tentang auto mode menyebutnya terang-terangan: pertanyaan manual berada di tengah-tengah antara aman dan nyaman, tetapi dalam praktik pengguna menerima 93% di antaranya.

Kebijakan bertingkat dari langkah 2 langsung terlihat dampaknya:

Dalam sesi contoh berisi 10 aksi, yaitu 6 kali cari_buku, 3 kali perpanjang_pinjaman, dan 1 kali pinjam_buku, kebijakan "tanya semua" mengajukan 10 pertanyaan. Kebijakan bertingkat hanya mengajukan 1, dengan 3 aksi tercatat otomatis. Satu pertanyaan yang dibaca sungguh-sungguh lebih berharga daripada sepuluh yang diabaikan.

Ada cara lain untuk mengurangi pertanyaan tanpa mengurangi keamanan: kurung lingkungannya. Sandbox Claude Code, yang membatasi berkas dan jaringan di tingkat sistem operasi, mengurangi permintaan izin sebesar 84%. Aksi di dalam batas yang aman tak perlu ditanyakan, dan pertanyaan disimpan untuk yang benar-benar keluar dari batas itu.

Model bisa saja menulis kalimat yang meyakinkan sebelum meminta tool: "Ini cuma pencatatan rutin, aman disetujui tanpa dibaca." Kalau kalimat itu yang ditampilkan kepada pengguna, persetujuannya tak lagi berarti. OWASP mencatat risiko ini sebagai ASI09 Human-Agent Trust Exploitation: kepercayaan manusia kepada agen dimanfaatkan.

Jadi pertanyaan persetujuan sebaiknya disusun kode, dari argumen tool dan data di sistemmu:

def ringkasan_persetujuan(env: Perpustakaan, id_anggota: str, nama_tool: str, masukan: dict[str, Any],
                          sekarang: datetime) -> str:
    """Disusun KODE dari argumen dan data, bukan dari kalimat model: nilai apa yang dilakukan, bukan yang dikatakan."""
    if nama_tool == "pinjam_buku":
        buku = env.buku[masukan["id_buku"]]
        kembali = (sekarang + timedelta(days=int(masukan["lama_hari"]))).date().isoformat()
        return (f"Pinjam \"{buku['judul']}\" ({masukan['id_buku']}) untuk {id_anggota} selama "
                f"{masukan['lama_hari']} hari, kembali {kembali}. Stok sekarang {buku['tersedia']}.")
    return f"{nama_tool} {json.dumps(masukan, ensure_ascii=False)}"

Untuk permintaan meminjam Laskar Pelangi, ringkasan yang muncul adalah:

Pinjam "Laskar Pelangi" (B-017) untuk A-9 selama 7 hari, kembali 2026-10-16. Stok sekarang 1.

Kalimat persuasif model tadi tak ikut tampil. Prinsip yang sama dipakai auto mode Claude Code. Pengklasifikasi yang menggantikan persetujuan manusia sengaja tak membaca teks Claude sendiri, hanya pesan pengguna dan panggilan tool, supaya agen tak bisa membujuknya. Kata tulisan itu, yang dinilai adalah apa yang dilakukan agen, bukan apa yang dikatakannya.

Ringkasan yang baik menjawab pertanyaan yang sungguh dipikirkan pengguna: apa yang akan terjadi, untuk siapa, berapa lama, dan apa akibatnya. Tanggal kembali dihitung kode, dan stok dibaca dari katalog. Tak ada yang diserahkan kepada karangan model.

Manusia tak selalu menjawab dalam hitungan detik. Karena itu putaran agen harus bisa berhenti, menyimpan keadaannya, lalu dilanjutkan nanti, bahkan dari proses lain.

Ini bagian putaran yang menangani satu giliran berisi panggilan tool:

        hasil: list[dict[str, Any] | None] = []
        menunggu: list[dict[str, Any]] = []
        for b in r.content:
            if b.type != "tool_use":
                continue
            t = tingkat(b.name)
            if t == "tanya":
                menunggu.append({"id": b.id, "nama": b.name, "masukan": b.input, "dibuat": sekarang.isoformat(),
                                 "ringkasan": ringkasan_persetujuan(env, keadaan["id_anggota"], b.name,
                                                                    dict(b.input), sekarang)})
                hasil.append(None)
                continue
            if t == "catat":
                log.append({"waktu": sekarang.isoformat(), "tool": b.name, "masukan": b.input, "keputusan": "otomatis"})
            hasil.append(_hasil(env, keadaan["id_anggota"], b.id, b.name, dict(b.input), t))
        if menunggu:  # SEMUA hasil turn ini harus dikirim bersama, jadi simpan yang sudah ada
            return {**keadaan, "status": "menunggu", "menunggu": menunggu, "hasil_sementara": hasil}

Detail yang mudah terlewat: model bisa meminta cari_buku (otomatis) dan pinjam_buku (tanya) dalam satu giliran, dan Messages API meminta semua hasil giliran itu dikirim dalam satu pesan. Jadi hasil cari_buku disimpan dulu di hasil_sementara, dan tempat pinjam_buku diisi None.

Keadaan itu hanya data biasa, sehingga bisa ditulis sebagai JSON. Dalam uji kita, ia disimpan ke berkas, lalu proses baru membacanya dan melanjutkan sampai selesai; pinjamannya tercatat tepat sekali.

Ketika jawaban datang, terapkan keputusan untuk setiap tool yang menunggu, lalu lanjutkan putaran:

def lanjutkan(client: anthropic.Anthropic, env: Perpustakaan, keadaan: dict[str, Any], keputusan: dict[str, Any],
              oleh: str, log: list[dict[str, Any]], sekarang: datetime) -> dict[str, Any]:
    """Terapkan keputusan manusia untuk SETIAP tool yang menunggu, lalu lanjutkan putaran."""
    hasil = list(keadaan["hasil_sementara"])
    for p in keadaan["menunggu"]:
        k = keputusan.get(p["id"], {"setuju": False, "alasan": "Tidak ada jawaban."})
        if sekarang - datetime.fromisoformat(p["dibuat"]) > BATAS_TUNGGU:
            k = {"setuju": False, "alasan": "Persetujuan kedaluwarsa; minta ulang."}
        log.append({"waktu": sekarang.isoformat(), "oleh": oleh, "tool": p["nama"], "masukan": p["masukan"],
                    "ringkasan": p["ringkasan"], "keputusan": "setuju" if k["setuju"] else "tolak"})
        isi = (_hasil(env, keadaan["id_anggota"], p["id"], p["nama"], p["masukan"], "tanya") if k["setuju"] else
               {"type": "tool_result", "tool_use_id": p["id"], "is_error": True,
                "content": f"Anggota menolak: {k['alasan']}"})
        hasil[hasil.index(None)] = isi
    keadaan = {k: v for k, v in keadaan.items() if k not in ("menunggu", "hasil_sementara")}
    keadaan["messages"].append({"role": "user", "content": hasil})
    return jalan(client, env, keadaan, log, sekarang)

Empat hal yang perlu diperhatikan:

• Penolakan sampai ke model beserta alasannya, sebagai is_error: "Anggota menolak: Saya berubah pikiran." Menurut dokumentasi Claude Agent SDK, model melihat pesan itu dan bisa menyesuaikan pendekatannya.
• Tak ada jawaban berarti tolak, bukan setuju.
• Persetujuan kedaluwarsa setelah 24 jam, karena keadaan dunia mungkin sudah berubah.
• Setiap keputusan dicatat: siapa, kapan, tool apa, ringkasan apa, dan keputusannya.

Di antara saat pertanyaan diajukan dan saat jawaban datang, dunia tak berhenti. Mungkin anggota lain sudah meminjam eksemplar terakhir Laskar Pelangi. Kalau persetujuan dijalankan begitu saja, stok bisa menjadi negatif. Masalah ini dikenal sebagai time-of-check to time-of-use (TOCTOU): yang dicek saat bertanya belum tentu masih benar saat dijalankan.

Karena itu syarat aksi dicek lagi di tool itu sendiri, tepat sebelum dijalankan:

    if nama == "pinjam_buku":
        buku = env.buku[masukan["id_buku"]]
        if buku["tersedia"] < 1:  # dicek ulang SAAT dijalankan, bukan saat diminta
            raise LookupError("Stok habis sejak permintaan ini dibuat; tidak dicatat.")
        buku["tersedia"] -= 1
        env.pinjaman.append({"id_buku": masukan["id_buku"], "id_anggota": id_anggota,
                             "lama_hari": int(masukan["lama_hari"])})
        return "Tercatat."

Dalam uji kita, stok diubah menjadi 0 selama menunggu, lalu anggota menyetujui. Hasilnya is_error dengan pesan "Stok habis sejak permintaan ini dibuat", dan stok tetap 0. Tanpa cek ulang itu, uji yang sama mencatat pinjaman dan membuat stok menjadi −1.

Ingat juga bahwa persetujuan berlaku untuk aksi yang ditampilkan, bukan untuk aksi apa pun. Bila argumennya berubah, misalnya karena kamu mengizinkan pengguna menyunting sebelum menyetujui, tampilkan ringkasan baru dan minta persetujuan lagi.

Persetujuan yang baik tak hanya "setuju" atau "tolak". Dokumentasi Claude Agent SDK merinci pilihan yang bisa diberikan aplikasimu ketika callback canUseTool dipanggil:

Spesifikasi MCP punya pembedaan yang berguna untuk elicitation, yaitu ketika server meminta masukan dari pengguna. Ada tiga jawaban: accept (pengguna menyetujui dan mengirim data), decline (pengguna sengaja menolak), dan cancel (pengguna menutup tanpa memilih). Bedakan dua yang terakhir. Penolakan berarti "jangan"; pembatalan berarti "belum", sehingga wajar ditanyakan lagi nanti.

Pilihan "setujui dan ingat" perlu hati-hati. Ia mengurangi pertanyaan, tetapi aturan yang terlalu luas, misalnya "selalu izinkan pinjam_buku", diam-diam memindahkan agen ke tingkat otonomi yang lebih tinggi. Simpan aturan sesempit mungkin dan beri pengguna cara melihat serta mencabutnya.

Human-in-the-loop tak hanya soal manusia yang menghentikan agen. Agen yang baik juga tahu kapan harus berhenti sendiri. Data Anthropic menunjukkan alasan paling umum Claude Code berhenti untuk bertanya:

Di Claude Agent SDK, pertanyaan klarifikasi datang lewat tool AskUserQuestion, yang juga memicu callback canUseTool. Model menyusun pertanyaan dan pilihannya; aplikasimu menampilkan, lalu mengembalikan jawaban pengguna. Batasnya ditulis di dokumentasi: setiap panggilan memuat 1 sampai 4 pertanyaan dengan 2 sampai 4 pilihan, dan tool ini belum tersedia di sub-agen.

Untuk server MCP, padanannya adalah elicitation, dengan satu aturan keamanan yang tegas. Server tak boleh memakai mode form untuk meminta informasi sensitif seperti sandi, kunci API, token akses, atau data pembayaran. Untuk itu ada mode URL, yang membuka halaman di luar klien sehingga rahasia tak pernah lewat agen. Klien juga wajib menunjukkan dengan jelas server mana yang meminta informasi itu.

Kalau kamu memakai LangGraph, jeda dan lanjut sudah tersedia. Panggil interrupt() di dalam node; LangGraph menyimpan keadaan graf lewat checkpointer dan menunggu tanpa batas waktu. Untuk melanjutkan, jalankan graf lagi dengan Command(resume=...) dan thread_id yang sama; nilai resume menjadi kembalian interrupt().

Ada satu aturan dari dokumentasinya yang paling sering menjebak. Saat dilanjutkan, LangGraph mengulang seluruh node dari awal, bukan dari baris interrupt(). Jadi efek samping sebelum interrupt() akan terjadi lagi:

def minta_persetujuan_salah(keadaan: Keadaan) -> dict[str, bool]:
    notifikasi_terkirim.append(keadaan["ringkasan"])  # ✗ efek samping SEBELUM interrupt
    jawaban = interrupt({"pertanyaan": "Setujui?", "ringkasan": keadaan["ringkasan"]})
    return {"disetujui": bool(jawaban)}


def minta_persetujuan(keadaan: Keadaan) -> dict[str, bool]:
    jawaban = interrupt({"pertanyaan": "Setujui?", "ringkasan": keadaan["ringkasan"]})
    if jawaban:
        notifikasi_terkirim.append(keadaan["ringkasan"])  # ✓ efek samping SESUDAH interrupt
    return {"disetujui": bool(jawaban)}

Kami menjalankan keduanya. Pada versi pertama, notifikasi terkirim dua kali untuk satu persetujuan. Pada versi kedua, notifikasi terkirim sekali, dan tak terkirim sama sekali bila jawabannya tolak. Aturan praktisnya: taruh efek samping sesudah interrupt(), pisahkan ke node lain, atau pastikan ia idempoten, yaitu aman dijalankan berulang.

Dua catatan lagi. Di produksi, pakai checkpointer yang tahan lama, misalnya yang disimpan di basis data, bukan InMemorySaver. Dokumentasi terbaru menyarankan menjalankan graf lewat stream_events(..., version="v3") dan membaca stream.interrupts. Saat kami menjalankannya dengan LangGraph 1.2.14, protokol v3 itu masih ditandai experimental; invoke() biasa juga mengembalikan jeda di kunci __interrupt__.

Callback canUseTool di Claude Agent SDK bisa menunggu tanpa batas, tetapi prosesmu harus tetap hidup selama itu. Kalau jawaban mungkin baru datang besok, dokumentasinya menyarankan cara lain: hook PreToolUse yang mengembalikan keputusan defer. Prosesnya keluar dengan stop_reason: "tool_deferred", panggilan tool yang tertunda disimpan di transkrip, dan aplikasimu melanjutkan sesi nanti dengan --resume. Tak ada batas waktu, tetapi berkas sesi dibersihkan setelah 30 hari secara bawaan.

Ada satu batasan yang sejalan dengan langkah 5: defer hanya bekerja bila Claude membuat satu panggilan tool di giliran itu. Bila ada beberapa, defer diabaikan, karena melanjutkan sesi hanya bisa menjalankan ulang satu tool tanpa meninggalkan yang lain menggantung.

Di Claude Managed Agents, persetujuan diatur lewat permission policy per tool:

• always_allow: tool berjalan tanpa konfirmasi;
• always_ask: sesi berhenti dengan requires_action sampai kamu mengirim event user.tool_confirmation berisi allow atau deny, boleh dengan deny_message;
• auto: server menilai setiap panggilan, lalu menjalankannya, menolaknya, atau menjeda untuk menunggu persetujuanmu.

Penolakan oleh auto tak bisa kamu timpa dari klien. Dokumentasinya juga mengingatkan bahwa permission policy tak berlaku untuk tool buatanmu sendiri. Untuk tool seperti itu, aplikasimu sendiri yang memutuskan, persis seperti kode di halaman ini.

Persetujuan per aksi hanyalah satu bentuk pengawasan. Data Anthropic menunjukkan pengguna berpengalaman beralih ke bentuk lain. Sesi dengan persetujuan otomatis penuh naik dari sekitar 20% pada pengguna baru menjadi lebih dari 40% setelah 750 sesi. Pada saat yang sama, porsi giliran yang mereka interupsi naik dari 5% menjadi sekitar 9%. Mereka berhenti menjaga setiap pintu, lalu mulai berpatroli.

Supaya pola itu aman, beri pengguna dua hal yang disarankan Anthropic kepada pengembang produk:

• visibilitas yang bisa dipercaya tentang apa yang sedang dikerjakan agen, misalnya jejak OpenTelemetry dari topik Evals & Observability;
• mekanisme intervensi yang sederhana untuk menghentikan atau mengarahkan ulang agen di tengah jalan.

Lalu ukur pengawasanmu seperti fitur lain:

Sesekali, uji alurnya dengan permintaan yang seharusnya ditolak, dan lihat apakah penolakan itu sungguh terjadi. Pertanyaan yang tak pernah dijawab "tidak" patut dicurigai.