Desen
Büyük bir pazar yeri, satıcı araçlarını dış agent'lara açtı; tek bir model sağlayıcısıyla başladı. Rezervasyon, ticaret ve vergi platformları da kendi agent'a dönük yüzeyleriyle takip ediyor. Bu yeni bir arayüz sınıfı: birincil tüketici, tarayıcısı olan bir kişi değil, bir planner. Bu ayrım kozmetik değil. Bir insan, eksik ön koşulları bağlamdan çıkarabilir, belirsiz hataları tolere edebilir ve başarısız bir eylemi elle yeniden deneyebilir. Bir planner bunu yapamaz. Sözleşmenin açık, deterministik ve makine tarafından okunabilir olması gerekir.
Makine Çağırıcıların İhtiyaç Duyduğu, İnsan API'lerinin Atladığı Şeyler
Çoğu genel API, kendilerine karşı kod yazan geliştiriciler için tasarlandı, ancak çalışma zamanındaki tüketici hâlâ dokümantasyonu okuyan, yanıtları inceleyen ve savunmacı mantık yazan bir insandır. Agent çağırıcıları bu insanı döngüden çıkarır. Genellikle eksik olan üç şeye ihtiyaç duyarlar.
Makine Tarafından Okunabilir Ön Koşullar
Hangi alanların hangi durum geçişleri için gerekli olduğu düz metin olarak değil, bir şema olarak belirtilmelidir. Örneğin, bir rezervasyon uç noktası guest_count alanını yalnızca status değeri confirmed olduğunda veya tax_id alanını yalnızca kurumsal rezervasyonlar için gerektirebilir. Bu bir paragrafa gömülürse, bir planner tahmin yürütür. Geçiş başına gerekli alanları, izin verilen değerleri ve yan etkileri içeren bir durum makinesi yayımlayın. JSON Schema veya eşdeğer bir biçimsel tanım isteğe bağlı değildir; arayüzün kendisidir.
Deterministik Hata Taksonomisi
Hatalar mesaja göre değil, koda göre sınıflandırılmalıdır. Bir planner şunları ayırt edebilmelidir:
- Yeniden denenebilir: geçici ağ hatası, hız sınırı, kilit çekişmesi. Agent geri çekilip yeniden deneyebilir.
- Kalıcı: geçersiz girdi, eksik izin, desteklenmeyen durum geçişi. Yeniden denemek yardımcı olmaz.
- İnsan gerektirir: belirsiz iş kuralı, manuel inceleme gerekli, anlaşmazlık. Agent yukarıya iletmelidir.
Tek sinyal serbest metinli bir mesajsa, planner ya kırılgan dize eşleştirmeyi sabit kodlamalı ya da vazgeçmelidir. Her ikisi de başarısızlıktır. Bu üç sınıfa belgelenmiş bir eşlemeyle birlikte kararlı bir hata kodu kümesi yayımlayın ve sınıfı yanıt gövdesine ekleyin ki bir arama tablosu olmadan ayrıştırılabilsin.
Her Değiştirici Çağrıda Idempotency Anahtarları
Bir planner, bir zaman aşımı, çökme veya kısmi başarısızlıktan sonra bir adımı yeniden deneyebilir. Bir idempotency anahtarı olmadan, yeniden denenen bir POST /bookings çift rezervasyona veya çift ücretlendirmeye yol açabilir. Anahtar istemci tarafından üretilmeli, mantıksal işlem başına benzersiz olmalı ve sunucu tarafından tanımlı bir pencere boyunca dikkate alınmalıdır. Sunucu, tekrarlanan bir anahtar için yeni bir kaynak değil, aynı yanıtı döndürmelidir. Bu yeni bir fikir değil, ancak tutarsız uygulanıyor. Agent'a dönük yüzeyler için, iptaller ve iadeler dahil olmak üzere her değiştirici çağrıda zorunludur.
Sözleşmenin Bir Parçası Olarak Kotalar
Hız sınırları genellikle operasyonel bir sonradan akla gelir. Agent çağırıcıları için bunlar arayüzün bir parçasıdır. Planner'ların planlama yapabilmesi için hız sınırlarını ve ani artış izinlerini keşif dokümanında yayımlayın. Bir agent'ın başarısız olmadan önce geri çekilebilmesi için kalan kota başlıklarını döndürün. Etkileşimli ve toplu şeritleri ayırın; mutabakat yapan bir agent, bir ödeme işlemiyle rekabet etmemelidir.
Somut bir mekanizma: mevcut kotaları, ani artış pencerelerini ve sıfırlama zamanlarını makine tarafından okunabilir bir biçimde döndüren bir GET /limits uç noktası sunun. Her yanıta X-RateLimit-Remaining ve X-RateLimit-Reset ekleyin. Bir planner daha sonra yayımlanan sınırlara uyan bir token-bucket zamanla
Ödünleşim: ayrı şeritleri sürdürmek operasyonel karmaşıklık ekler ve yoğun etkileşimli dönemlerde toplu şeritte yetersiz kullanılan kapasiteye yol açabilir. Alternatif—öncelik ipuçlarıyla tek bir şerit—işletmesi daha basittir ancak bir planner'ın akıl yürütmesi için daha zordur, çünkü öncelik bir garanti değildir. Dürüst seçim, platformun toplu işlerin ara sıra aç kalmasını tolere edip edemeyeceğine bağlıdır.
Yönetişim Etkileri
Her agent'a dönük uç noktanın bir sahibi, bir kullanımdan kaldırma politikası ve sürümlenmiş bir değişiklik günlüğü olmalıdır. Bir agent arayüzüne yapılan kırıcı değişiklikleri, aşağı akış sistemleri için bir üretim olayı olarak değerlendirin. İnsana dönük bir kullanıcı arayüzü değişikliğinden farklı olarak, bir agent bir banner okuyarak uyum sağlayamaz. Sessizce başarısız olur ya da daha kötüsü, yanlış bir eylemde bulunur.
Bir agent'ın ne yaptığına dair anlaşmazlıkların kanıtlardan çözülebilmesi için yeniden oynatılabilir bir istek günlüğü tutun. Günlük idempotency anahtarını, tam isteği ve yanıtı, agent kimliğini ve zaman damgasını içermelidir. Bu yalnızca hata ayıklama için değil; güvenin temelidir. Bir satıcı bir agent'ın bir slotu çift rezerve ettiğini iddia ettiğinde, platform tam olarak neyin istendiğini ve neyin döndürüldüğünü gösterebilmelidir.
Keşif Üzerine Bir Not
Agent'a dönük yüzeyler insan müdahalesi olmadan keşfedilebilir olmalıdır. İyi bilinen bir yolda (ör. /.well-known/agent-api) uç noktaları, şemaları, hata kodlarını, hız sınırlarını ve kimlik doğrulama yöntemlerini listeleyen makine tarafından okunabilir bir manifest minimumdur. Bu, bir site haritasının agent eşdeğeridir. O olmadan, her entegrasyon özel yapımdır.
Sonuç
Önce makine çağırıcıları için tasarlamak, insan geliştiricileri görmezden gelmek anlamına gelmez. Sözleşmeyi, bir planner'ın tahmin yürütmeden akıl yürütebileceği kadar açık hale getirmek anlamına gelir. Idempotency, kotalar ve hata semantiği özellik değildir; arayüzün kendisidir. Bunları sonradan akla gelen şeyler olarak ele alan platformlar, agent'ların hata ayıklaması zor ve güvenilmesi daha da zor biçimlerde başarısız olduğunu görecektir. Bunları sözleşmenin bir parçası olarak yayımlayanlar ise güvenilir, denetlenebilir ve yeniden denenmesi güvenli yeni bir otomasyon sınıfını mümkün kılacaktır.