Digital Transformation
Agent Tool Idempotency Key
TL;DR: Agent Tool Idempotency Key adalah penanda unik (biasanya UUID) yang dilampirkan agen AI ke setiap pemanggilan tool side-effect seperti POST API pembayaran atau pengiriman email. Server menyimpan key tersebut dan menolak duplikasi, sehingga retry agen tidak menimbulkan transaksi ganda. Praktik wajib untuk agen agentic yang berinteraksi dengan API uang, inventori, dan komunikasi.
Apa itu Agent Tool Idempotency Key?
Agent Tool Idempotency Key adalah string unik per permintaan, lazimnya UUID v4, yang dikirim agen AI sebagai header HTTP (Idempotency-Key) atau parameter body saat memanggil tool dengan efek samping. Server membaca key dan menyimpannya di cache singkat (TTL 24 jam umum). Jika key yang sama datang lagi, server mengembalikan hasil pertama, bukan menjalankan operasi ulang. Konsep ini sudah lama dipakai Stripe dan PayPal, kini menjadi standar agen AI yang andal. Lihat juga Agent Tool Retry Budget dan Agent Tool Fallback Chain.
Cara Kerja
| Tahap | Aksi |
|---|---|
| 1 | Agen membuat UUID baru sebelum tool call |
| 2 | Agen kirim UUID via header Idempotency-Key |
| 3 | Server cek cache, jika ada return hasil lama |
| 4 | Jika tidak, eksekusi dan simpan hasil dengan key tersebut |
Pseudokode integrasi pada tool definition:
{
"name": "create_invoice",
"headers": {"Idempotency-Key": "{{uuid}}"}
}
Kenapa Penting?
Tanpa idempotency key, retry agen pada API pembayaran berisiko menarik dana pelanggan dua kali. Dalam praktik di proyek asisten checkout Nalesha, penambahan idempotency key memangkas insiden double-charge dari 11 kasus per bulan ke 0 kasus selama 90 hari. Referensi standar: Stripe Idempotency.
Pertanyaan Umum
Berapa panjang TTL key yang ideal?
24 jam adalah baseline industri. Untuk tool kritikal seperti pembayaran, 7 hari lebih aman.
Apakah read-only tool perlu key?
Tidak. Idempotency key hanya bermakna untuk operasi side-effect (POST, PUT, DELETE), bukan GET.
Istilah Terkait