Ajanlarda idempotency nedir?

İdempotency, bir ajanın aynı işi aynı istek için birden fazla kez çalıştırdığında dış dünyada tek bir sonuç oluşturmasıdır. Örneğin kullanıcı “12.000 TL tutarındaki faturayı öde” dediğinde ağ hatası nedeniyle ajan aynı isteği yeniden gönderse bile iki ödeme yapmamalıdır. Bunu sağlamak için her işleme benzersiz bir istek kimliği verilir, işlem sonucu kaydedilir ve aynı kimlikle gelen tekrarlar yeni işlem başlatmak yerine önceki sonucu döndürür.

Ajanlarda idempotency nasıl çalışır?​

Bir ajan genellikle yalnızca metin üretmez; API çağırır, kayıt oluşturur, e-posta gönderir, ödeme başlatır veya başka bir aracı tetikler. Bu eylemlerden biri tamamlandıktan sonra ajanın yanıtı ulaşmazsa sistem işlemin başarısız olduğunu kesin olarak bilemez. Ajan ya da orkestratör isteği yeniden gönderirse aynı eylem ikinci kez çalışabilir.

İdempotent tasarımda işlem şu bilgilerle takip edilir:

• Idempotency key: Aynı mantıksal işleme ait tüm denemelerde kullanılan benzersiz kimlik.
• İşlem durumu: Örneğin bekliyor, tamamlandı veya başarısız.
• İşlem sonucu: Oluşturulan kayıt numarası, gönderim sonucu veya API yanıtı.
• İş kuralı: Aynı anahtar tekrar geldiğinde yeni işlem başlatılmaması ve saklanan sonucun döndürülmesi.

Örneğin varsayımsal bir destek ajanı, kullanıcının isteğini “müşteri kaydı oluştur” aracına iletsin. İlk çağrıda şu kimlik üretilebilir: ticket-20261108-8f31. Araç kaydı oluşturup ticket_id=4721 sonucunu döndürür. Ajanın bağlantısı tam bu sırada koparsa aynı kimlikle yapılan ikinci çağrı, yeni kayıt oluşturmak yerine daha önce 4721 numarasıyla oluşturulan kaydı döndürmelidir. Böylece kullanıcı tek kayıt görür.

İdempotency, isteğin hiç tekrarlanmaması anlamına gelmez. Ağ zaman aşımı, kuyruk yeniden denemesi veya ajan döngüsü nedeniyle tekrar denemeler yine olabilir. Ama tekrar denemeler dış sistemde ikinci bir yan etki oluşturmamalıdır.

Hangi işlemler idempotent, hangileri değildir?​

Bir işlemin idempotent olup olmadığı HTTP yönteminden veya araç adından tek başına anlaşılmaz; işlemin gerçek davranışına bakılır. Aynı isteği tekrar ettiğinizde kaynak aynı duruma geliyorsa işlem idempotenttir. Her tekrar yeni bir yan etki üretiyorsa değildir.
Tabloyu yorumlarken önemli ayrım şudur: “Aynı sonucu döndürmek” ile “aynı yan etkiyi yeniden üretmemek” birbirine bağlıdır ancak aynı şey değildir. Bir ödeme aracı ikinci çağrıda ilk ödemenin sonucunu döndürüyorsa idempotent davranabilir. Buna karşılık yalnızca “bu ödeme daha önce yapıldı” mesajı vermesi, ilk ödemenin gerçekten başarıyla sonuçlandığını kanıtlamaz; işlem kaydı ve durum bilgisi güvenilir bir kaynaktan okunmalıdır.

Bir ajanda uygulanabilir tasarım kalıbı​

Ajanın aracı çağırmadan önce idempotency anahtarını belirlemesi gerekir. Bu anahtar her denemede yeniden üretilmemeli; aynı mantıksal iş için korunmalıdır. Anahtarı kullanıcı veya kurum kapsamı ve işlem girdilerinin özetiyle ilişkilendirin; aynı anahtarla farklı tutar, alıcı veya başka değiştirilmiş girdi gelirse eski sonucu yeni işin sonucu gibi kullanmak yerine isteği reddedin. Örneğin kullanıcı aynı faturayı ödeme isteğini tekrar ediyorsa fatura numarası, kullanıcı kimliği ve iş akışı kimliğinden türetilen bir anahtar kullanılabilir. Aynı faturanın daha sonra yapılacak yeni ve bilinçli ödemesi ise farklı bir iş kimliğine sahip olmalıdır.

Basit akış şöyledir: Ajan önce anahtarı işlem deposunda arar. tamamlandı kaydı varsa saklanan sonucu döndürür. bekliyor kaydı varsa aynı işin başka bir deneme tarafından yürütüldüğünü kabul eder ve eşzamanlı ikinci çağrıyı engeller. Kayıt yoksa anahtarı ayırır, dış aracı çağırır, sonucu kalıcı olarak kaydeder ve kullanıcıya bu sonucu bildirir.

Dış sistem de idempotency destekliyorsa anahtarı API isteğine iletmek daha güvenlidir. Desteklemiyorsa ajan katmanında kayıt tutmak tek başına yeterli olmayabilir; iki farklı çalışan aynı anda kontrol edip ikisi de “kayıt yok” sonucunu aldıktan sonra işlemi başlatabilir. Bu nedenle işlem deposunda benzersiz kısıt veya atomik ayırma gibi eşzamanlılığı önleyen bir mekanizma gerekir. Bu koruma dış işlem tamamlandıktan sonra yerel sonuç kaydedilmeden yaşanan çökmeyi tek başına çözmez. Böyle bir kayıt belirsiz veya sürüyor durumunda kalmalı; dış sistemin aynı anahtarı tekilleştirmesi ya da güvenilir sorguyla sonucu uzlaştırma olmadan yeni yan etki başlatılmamalıdır.

İdempotency neyi garanti etmez?​

İdempotency, işlemin başarılı olacağını garanti etmez. Yalnızca aynı mantıksal isteğin tekrar yürütülmesi durumunda fazladan yan etki oluşmasını önlemeye çalışır. İlk çağrı geçersiz veri, yetki hatası, yetersiz bakiye veya dış sistem arızası nedeniyle başarısız olabilir.

Ayrıca idempotency, tüm araçların güvenli olduğu anlamına gelmez. Ajanın “e-posta gönder”, “dosyayı sil” veya “bakiye artır” gibi eylemleri için hangi kimliğin aynı işi temsil ettiği açıkça tanımlanmalıdır. Kullanıcı isteğinin içeriğini her seferinde yeniden yorumlayan bir dil modeli, aynı görünen iki isteği farklı iş olarak değerlendirebilir. Bu nedenle kritik eylemlerde iş kimliği, hedef kaynak ve onay bilgisi yapılandırılmış alanlar olarak tutulmalıdır.

Pratik kontrol için her kritik araç çağrısında şu soruları yanıtlayın: Aynı istek ağ hatası sonrası yeniden gönderilirse hangi kimlik korunacak? İkinci çağrı önceki sonucu nasıl bulacak? İlk işlem başladı fakat sonucu kaydedilmeden süreç durduysa sistem bu durumu nasıl uzlaştıracak? Bu soruların yanıtı yoksa ajan yalnızca “yeniden deneme” özelliğine sahiptir; henüz güvenilir biçimde idempotent değildir.