Son olaylardaki ortak örüntü
Bir agent hiç yapmaması gereken bir şey yaptığında, postmortem genellikle modeli işaret eder. Olay raporları ise daha nettir. Bir agent, görevinin hiçbir parçası olmayan bir endpoint'i çağırır; yanıt ona başka bir şey söylemediği için bir mutasyonu yeniden dener; ya da API numaralandırmayı ucuz ve belgesiz kıldığı için bir koleksiyonu baştan sona tarar. Bunlar akıl yürütme hataları değil. Arayüz hataları.
Üç biçim tekrar ediyor. Birincisi, erişim: agent teknik olarak erişilebilir ama yetkisi dışında olan bir kaynağa dokunur. Araç yüzeyi geniş bir fiil sunmuştur ve agent onu kullanmıştır. İkincisi, yeniden deneme davranışı: hız semantiği olmayan arayüzlerde, belirsiz bir hata alan agent yeniden dener — çoğu zaman agresif biçimde — çünkü yanıttaki hiçbir şey ona yeniden denemenin yanlış ya da anlamsız olduğunu söylemez. Üçüncüsü, numaralandırma: sayfalama sözleşmesi ve kapsam sınırı olmayan izin verici bir list endpoint'i, bir agent için tüm koleksiyonu dolaşma daveti gibi okunur.
İnsan biçimli araçlar agent'larda neden başarısız olur
İnsana dönük API'ler belirsizliği tolere eder çünkü etraflarındaki niyeti ve ölçülülüğü bir insan sağlar. İzin verici bir endpoint'i okuyan kişi, bağlamdan ve teamülden, DELETE /items'ın her şeyi silme daveti olmadığını anlar. Hangi parametrelerin pratikte opsiyonel olduğunu, hangi hataların geçici olduğunu ve hangi fiillerin yalnızca eski nedenlerle var olduğunu bilir. Bu bilginin hiçbiri arayüzde değildir. İnsanın içindedir.
Bir agent yüzeyi harfiyen okur. Her fiil aday bir eylemdir. Her opsiyonel parametre bir karar noktasıdır. Belgesiz davranış bir makine için yumuşak bir kenar değil, keşfedilmemiş bir yoldur. Bir insanın pürüzlü bir köşe görüp etrafından dolaştığı yerde, agent bir dal görür ve o dala girebilir.
Asıl asimetri budur. İnsan arayüzleri affedicidir çünkü guardrail insanın kendisidir. Agent arayüzleri bunu varsayamaz. Yüzeyin kendisi, aksi halde bir insanın deneyimden sağlayacağı kısıtları taşımak zorundadır. Taşımadığında agent pervasız değildir; kendisine verilenle tutarlıdır.
Geniş bir yüzeyin etrafına yerleştirilen guardrail'ler bunu düzeltmez. Bazı çağrıları yakalar, bazılarını kaçırır ve agent'ın göremediği bir politika katmanı ekler. Agent hâlâ özgün yüzey üzerinde akıl yürütür. Düzeltme, karardan önce değil sonra gelir.
Agent'a dönük bir araç yüzeyi tasarlamak
Agent'lar için bir araç yüzeyi dar, açık ve kendini tanımlar olmalıdır. İşin çoğunu üç özellik yapar.
Niyet başına tek fiil, zorunlu parametrelerle
Geniş fiilleri niyete özgü fiillere indirgeyin. Rastgele alanları kabul eden genel bir update yerine, zorunlu bir adres ve zorunlu bir sipariş tanımlayıcısı alan set_delivery_address sunun. list yerine, zorunlu bir müşteri tanımlayıcısı ve zorunlu bir durum filtresi alan list_open_orders_for_customer sunun. Parametre kümesi bir öneri değildir; yazıya dökülmüş niyetin kendisidir.
Bu, agent'ın neyi ifade edebileceğini değiştirir. Opsiyonel alanları olan genel bir fiil, niyeti örtük bırakır ve opsiyonel alanları dolduran bir agent tahmin ediyordur. Zorunlu parametreleri olan dar bir fiil ise kapalı başarısız olur: agent müşteri tanımlayıcısını sağlayamıyorsa çağrıyı çalıştıramaz ve başarısızlık sessiz değil, okunabilirdir.
Arayüzde ifade edilen katı sınırlar
Hız ve kapsam sınırları, agent'ın hiç okumadığı bir politika belgesinde değil, araç tanımında yer alır. Bir araç bir pencere başına en fazla sınırlı sayıda çağrılabiliyorsa, bunu şemada söyleyin ve sınırda uygulayın. Bir koleksiyon en fazla bir sayfa okunabiliyorsa, sayfalamayı zorunlu kılın ve sayfa boyutunu sınırlı bir aralığa sahip zorunlu bir parametre yapın.
Mekanizma, ifadeden daha önemlidir. Araç sınırında uygulanan bir hız sınırı, agent'ın üzerine eyleyebileceği yapılandırılmış bir sinyal döndürür. Alt tarafta bir yerde uygulanan bir hız sınırı ise agent'ın yeniden deneyeceği opak bir hata döndürür. Aynı sınır, farklı yere konduğunda zıt davranış üretir.
Bir hata agent'a yalnızca neyin başarısız olduğunu değil, bundan sonra ne yapabileceğini de söylemelidir. Çıplak bir 403 yeniden denemeleri ve yoklamayı davet eder. Eylemin bu principal için izinli olmadığını söyleyen, izinli alternatifi adlandıran ve koşulun kalıcı olup olmadığını belirten yapılandırılmış bir hata, agent'a tahmin içermeyen bir yol verir.
{
"error": "scope_denied",
"message": "This principal may not modify billing details.",
"permitted": ["read_billing_summary"],
"retryable": false,
"next": "request_billing_change_approval"
}
Tek başına retryable alanı, agresif yeniden deneme döngülerinin geniş bir sınıfını ortadan kaldırır. permitted listesi, agent'ın sınırları başarısızlıklardan çıkarsamasını gerektirmeden bir sonraki adımını daraltır.
Bunun maliyeti
Bunun bedava bir versiyonu yok ve maliyetler gerçek.
İkinci bir yüzeyi sürdürmek ilki. Agent yüzeyi insan API'sinin üzerine ince bir sarmalayıcıysa, geniş fiiller sızar ve bütün çalışma kozmetik kalır. Gerçek bir agent yüzeyi, kendi fiilleri, kendi parametre gereksinimleri ve kendi hata sözcük dağarcığı olan ayrı bir sözleşmedir. Bu tek seferlik bir refactor değil, süregelen bir iştir.
Sürümleme ikincisi. Agent yüzeyi, insan yüzeyinden bağımsız olarak sürümlenmelidir çünkü ikisi farklı nedenlerle ve farklı hızlarda değişir. Aynı zamanda bir sözleşme olarak test edilmelidir: yalnızca çağrıların başarılı olduğu değil, yüzeyin reddetmesi gerekeni reddettiği ve reddetmelerin okunabilir olduğu da. Yalnızca mutlu yolu çalıştıran bir test paketi, fazla geniş bir fiili yakalayamaz.
Eski fiilleri reddetmek üçüncüsü ve en rahatsız edici olanı. Bazı fiiller, agent'ın yürütme bağlamından teknik olarak erişilebilir olsa da yüzeyinin parçası değildir. Uygun oldukları için onları açığa çıkarmak, baştaki sorunu geri getirir. Dürüst ödünleşim şudur: yüzeyi daraltmak, agent'ın teknik olarak gerçekleştirebileceği bazı görevlerin artık ona açık olmaması anlamına gelir ve bu görevlerin bazıları meşrudur. Bu maliyet, öngörülebilirlik satın almak için yetenekten ödenir. Bunu atlayan ekipler, örüntüyü sonradan daha geniş bir yüzey ve etrafında daha fazla guardrail ile yeniden keşfetme eğilimindedir.
Alternatif, harfiyen okunmak üzere hiç tasarlanmamış bir yüzeyin etrafına politika eklemeye devam etmektir. Bu yaklaşım, ters gidebilecek şeylerin sayısıyla ölçeklenir. Yüzeyi daraltmak ise agent'ın yapması gereken şeylerin sayısıyla ölçeklenir.