AI ajanı ürününüzü buldu; API’de yetki sınırı yoksa satış yarıda kalır

AI ajanının SaaS ürününüzü ve API’nizi bulması, satın alma işlemini tamamlayabileceği anlamına gelmez. Operasyonun hangi müşteri adına çalışacağı, token’ın neye izin verdiği ve ödeme öncesinde nerede durulacağı açık değilse güvenli akış ilerleyemez; satış ödeme ya da abonelik adımından önce yarıda kalır.

Çözüm, her operasyonu makinenin okuyabileceği tek bir sözleşmeyle belgelemektir: amaç, zorunlu girdiler, kimlik doğrulama, yetki kapsamı, sonuç şeması, idempotency, oran sınırı, hata sonrası durum ve insan onayı gereken nokta birlikte tanımlanmalıdır. AgentReady’nin API kontrol listesi, bu alanların yayımlanan yüzeyde açık olmasını ve çalışan servisle uyuşmasını öneriyor.

Keşfedilebilirlikten sonra belirleyici sınır yetkidir

Bir ajanın uç noktayı seçebilmesi, o işlemi hangi hesapta ve hangi sonuç seviyesine kadar yürütebileceğini bildiği anlamına gelmez. “Sipariş oluşturur” açıklaması; işlemin yalnızca taslak mı hazırladığını, fiyatı değiştirebildiğini mi, yoksa satın almayı kesinleştirdiğini mi söylemiyorsa ajan güvenli bir karar veremez.

Temkinli bir akış belirsizlik karşısında ödeme öncesinde durmalıdır. İstemciye gereğinden geniş yetki vermek ise çözüm değildir: yanlış hesapta değişiklik veya yetkisiz finansal işlem riskini büyütür. Bu nedenle dokümanda açıklanan kapsamın sunucu tarafından da uygulanması gerekir.

• Her operasyonun gerektirdiği OAuth kapsamını veya rolü yazın.
• Hesap, çalışma alanı ve kaynak kimliğinin hangi kuralla eşleştirildiğini belirtin.
• Okuma, yazma, finansal sonuç doğurma ve geri döndürülemez işlemleri ayırın.
• Kullanıcı onayının hangi aşama için ve ne kadar süreyle geçerli olduğunu tanımlayın.

Geçerli OpenAPI dosyası, anlaşılır araç sözleşmesi demek değildir

Sözdizimsel geçerlilik yalnızca belgenin kurallara uygun biçimde yazıldığını gösterir; operasyonun anlamını veya güvenli kullanım sınırlarını garanti etmez. 16 üretim API’sindeki yaklaşık 600 uç noktayı inceleyen OpenAPI dokümantasyonu araştırması, 600 uç noktada 2.450 dokümantasyon ve REST kusuru saptadı; incelenen operasyonların tümünde en az bir kusur bulunduğunu ve ilk ajan denemelerinde görev planlama, araç seçme ve istek gövdesi oluşturma sorunları görüldüğünü aktarıyor.

Bu nedenle işlem tanımı yalnızca HTTP yöntemiyle yolu göstermemelidir. Kararlı ve ayırt edici bir operationId, iş sonucunu anlatan açıklama, parametrelerin türü ve birimi, gerekli yetki, başarı şeması ve bilinen hata durumları aynı operasyon etrafında birleşmelidir.

Kimlik doğrulama ile yetkilendirmeyi ayırın. Bearer token kullanıldığını belirtmek, çağrıyı yapan kimliğin nasıl doğrulandığını anlatır; bu kimliğin hangi kaynak üzerinde hangi eylemi gerçekleştirebileceğini açıklamaz. Operasyon tanımında gerekli kapsam, hedef kaynağın sahiplik kontrolü ve izin yetersizliğinde dönecek hata birlikte yer almalıdır.

OpenAPI Specification 3.0.0, operasyon düzeyindeki güvenlik gereksiniminin genel güvenlik tanımını geçersiz kılmasına ve başarı yanıtlarının yanında bilinen hata yanıtlarının belgelenmesine olanak verir. Ancak bu alanların varlığı sunucunun gerçekten yetki denetimi yaptığı anlamına gelmez; belge ile uygulamanın ayrıca eşleştirilmesi gerekir.

Tek operasyon için doldurulabilir sözleşme

Aşağıdaki koşullu örnek, ücret doğurmayan bir sipariş taslağı operasyonunu tanımlar. Alan adları ürüne göre değişebilir; önemli olan her alanın OpenAPI belgesinde, ajan aracında ve sunucu davranışında aynı anlama gelmesidir.

• Operasyon: createOrderDraft — müşteri hesabında henüz ücret doğurmayan, geri alınabilir bir sipariş taslağı oluşturur.
• Kullanım koşulu: Ürünler ve teslimat tercihi seçilmiş olmalıdır; operasyon ödeme onayı veya siparişi kesinleştirme amacıyla kullanılamaz.
• Girdi: account_id, line_items, currency ve delivery_option zorunludur; adet sınırları, para birimi biçimi ve boş değer davranışı şemada gösterilir.
• Kimlik doğrulama: OAuth 2.0 erişim belirteci gerekir; belirteç ile hedef account_id arasındaki ilişki sunucuda doğrulanır.
• Yetki: orders.draft.write kapsamı gerekir. Bu kapsam fiyat değiştirme, indirim tanımlama veya ödeme alma yetkisi vermez.
• Tekrar güvenliği: Her mantıksal denemede bir idempotency anahtarı gönderilir; aynı anahtar ve aynı gövde ikinci bir taslak oluşturmamalıdır.
• Oran sınırı: Kotanın hangi kimliğe uygulandığı, zaman penceresi, dönen başlıklar ve yeniden denemeden önce beklenecek süre belirtilir.
• Başarı sonucu: draft_id, hesaplanan toplam, para birimi, expires_at ve next_allowed_actions döner.
• Durdurma noktası: Toplam değişirse, ürün bulunamazsa veya ödeme gerektiren aşamaya geçilecekse ajan kullanıcıya dönmelidir.
• Sonuç seviyesi: Geri alınabilir taslak; finansal taahhüt oluşturmaz ve gönderim başlatmaz.

Bu sözleşme, operasyon adının taşıyamayacağı iş anlamını görünür kılar. Doküman “taslak” diyorsa uç nokta ödeme almamalı; kapsam yalnızca taslak yazmaya izin veriyorsa sunucu fiyat değiştirme isteğini reddetmelidir.

Hata yanıtı yeniden deneme kararını da taşımalı

“Bir hata oluştu” mesajı, ajana güvenli bir sonraki adım vermez. Her hata; kararlı bir uygulama kodu, kısa açıklama, ilgili alan, isteğin uygulanıp uygulanmadığı ve izin verilen kurtarma eylemini içermelidir. HTTP durumu taşıma katmanını, uygulama kodu ise iş nedenini ayırır.

• validation_failed: İstek uygulanmadı; belirtilen alan düzeltilerek yeniden gönderilebilir.
• insufficient_scope: İstek uygulanmadı; ajan daha geniş yetki edinmeye çalışmadan kullanıcıya veya yetkili onay akışına dönmelidir.
• rate_limited: İstek uygulanmadı; retry_after süresi dolmadan tekrar denenmemelidir.
• state_conflict: Kaynak değişti; ajan güncel durumu okumalı ve eski varsayımlarla yazma işlemini yinelememelidir.
• result_unknown: Sonuç kesin değil; mevcut işlem aynı idempotency anahtarıyla sorgulanmalı veya akış güvenli biçimde durmalıdır.

Yeniden deneme kuralını genel bir not olarak bırakmayın. Hangi yöntemlerin güvenle tekrarlanabildiğini, idempotency anahtarının kapsamını ve geçerlilik süresini, aynı anahtar farklı gövdeyle gönderildiğinde dönecek hatayı belirtin. Bağlantı koptuğunda ajan yeni bir yazma isteği oluşturmadan önce mevcut işlemin sonucunu sorgulayabilmelidir.

Belgeyi çalışan servisle eşleştirin

OpenAPI doğrulayıcısı iş sınırlarını sınamaz. Üretim benzeri, müşteri verisi içermeyen kontrollü bir ortamda zararsız bir operasyon seçin; doğru kapsamla başarıyı, eksik kapsamla reddi, aynı idempotency anahtarıyla tekrarı, oran sınırını ve kısmi hata sonrasındaki durumu ayrı ayrı doğrulayın.

1. Yayımlanan OpenAPI belgesinden istemci veya araç tanımını yeniden üretin.
2. Operasyonu belgelenen en düşük yetkiyle çalıştırın.
3. Başka hesaba ait kaynak kimliği göndererek sunucu tarafındaki sahiplik denetimini sınayın.
4. Aynı isteği aynı anahtarla yineleyip ikinci bir yan etki oluşmadığını kontrol edin.
5. Gerçek hata gövdesini belgelenen kod, alan, işlem durumu ve kurtarma talimatıyla karşılaştırın.
6. Geri döndürülemez aşamadan hemen önce ajanın durabildiğini ve kullanıcıya karar için yeterli bir özet sunduğunu doğrulayın.

Şema, kapsam, varsayılan değer veya hata anlamı değiştiğinde bu kontrolleri sürümleme sürecinde yeniden çalıştırın. Böylece ürünün keşfedilmesi satın alma yolculuğunu başlatabilir; açık yetki, tekrar ve kurtarma sınırları da ajanın işlemi güvenle tamamlayıp tamamlayamayacağını belirler.

Ayrıca okuyun:

• Bir AI ajanı sandbox’tan yine de çıkabilir: Güven sınırı nerede kırılır?
• OpenAI’nin ajanları sınırı aştı: Hugging Face ihlalinin tam zinciri
• Claude güvenlik araştırmacılarını geçti, ama ölçümün bir sınırı var