Araç şeması nasıl tasarlanır?

Araç şeması, bir ajanın hangi aracı hangi girdilerle çağırabileceğini ve araçtan nasıl bir çıktı beklemesi gerektiğini açıkça tanımlayan sözleşmedir. İyi tasarlanmış bir şema; gerekli alanları zorunlu tutar, belirsiz değerleri sınırlar, güvenlik açısından riskli işlemleri ayırır ve hatalı çağrıları daha işlem başlamadan engeller. En uygulanabilir yaklaşım, önce aracın tek bir işini belirlemek, ardından girdileri JSON Schema mantığıyla tanımlamak ve gerçekçi örneklerle doğrulamaktır.

Araç şeması hangi soruları yanıtlamalıdır?​

Bir araç şeması en az şu bilgileri netleştirmelidir:

• Araç hangi işi yapar?
• Hangi girdileri kabul eder?
• Hangi girdiler zorunludur?
• Her girdinin veri türü nedir?
• Hangi değerler geçerlidir?
• İşlem başarılı olduğunda hangi çıktı döner?
• İşlem geri döndürülemezse veya dış sisteme veri yazıyorsa ek onay gerekir mi?

Örneğin bir ajanın takvim etkinliği oluşturması için create_calendar_event adlı araç; başlık, başlangıç zamanı, bitiş zamanı ve katılımcılar gibi alanları kabul edebilir. Kullanıcının niyeti yalnızca bilgi istemekse bu araç çağrılmamalı; çünkü araç dış sistemde kalıcı değişiklik yapar.

Şema tasarlarken izlenecek sıra​

Önce aracın kapsamını tek bir cümleyle sınırlandırın: “Bu araç, onaylanmış bir takvim etkinliğini oluşturur.” “Takvimle ilgili her şeyi yapar” gibi geniş tanımlar, ajanın yanlış işlemi seçme ihtimalini artırır.

Daha sonra girdileri belirleyin. Her alanın türünü, zorunluluk durumunu ve kabul edilebilir değerlerini yazın. Tarih ve saat için serbest metin yerine ISO 8601 biçimi, durum alanı için sınırlı seçenekler kullanmak doğrulamayı kolaylaştırır.

Örnek olarak aşağıdaki şema, varsayımsal bir takvim aracı için en küçük uygulanabilir tasarımdır:


Bu örnekte title, start_time, end_time ve user_confirmation zorunludur. additionalProperties: false kullanılması, ajanın şemada bulunmayan alanları göndermesini önlemeye yardımcı olur. Ancak bu ayar tek başına yetkilendirme veya kullanıcı onayı sağlamaz; uygulama tarafında da kontrol yapılmalıdır.

Alanları belirsiz bırakmayın​

“Uygun tarih”, “kısa açıklama” veya “gerekirse e-posta” gibi ifadeler ajanın yorum alanını genişletir. Bunun yerine biçimi ve sınırı belirtin. Örneğin priority alanı serbest metin olmak yerine low, normal ve high değerleriyle sınırlandırılabilir.

Okuma ve yazma araçlarını ayırın​

Veri getiren bir araç ile dış sistemde değişiklik yapan araç aynı risk düzeyinde değildir. search_orders yalnızca kayıt okuyabilirken cancel_order siparişi değiştirebilir. Bu araçları ayrı tanımlayın; yazma, silme, para transferi, mesaj gönderme veya erişim değiştirme gibi işlemlerde açık onay ve sunucu tarafı yetkilendirme arayın.

Seçim yaparken aşağıdaki ayrım, şemanın güvenlik ve bakım kararlarını netleştirir.
Tablo, şemanın yalnızca veri biçimi olmadığını gösterir: araç tanımı, işlemin etkisini ve uygulamanın hangi ek kontrolleri yapacağını da açıkça ortaya koymalıdır.

Örnek çağrıyı nasıl değerlendirmelisiniz?​

Varsayımsal şemaya uygun bir çağrı şöyle olabilir:


Bu girdide zorunlu alanlar vardır, saatlerin zaman dilimi bellidir ve onay değeri true olarak verilmiştir. Beklenen sonuç, aracın başarılı bir işlem kimliği ve oluşturulan etkinliğin temel bilgilerini döndürmesidir. Bu sonuç etkinliğin gerçekten takvimde oluşturulduğunu varsayım olarak kanıtlamaz; uygulama, dış servisten gelen başarı yanıtını ve mümkünse etkinlik kimliğini ayrıca doğrulamalıdır.

Başlangıç zamanı bitiş zamanından sonraysa çağrı reddedilmelidir. Katılımcı adresi geçersizse araç bunu hata olarak döndürmeli, ajanın adresi sessizce değiştirmesine izin verilmemelidir. user_confirmation değeri false ise uygulama aracı hiç çağırmamalı veya güvenli bir önizleme döndürmelidir.

Şemayı tamamlamadan önce kontrol listesi​

1. Aracın tek görevini yazın. Tanım, ajanın başka bir işi bu araçla yapabileceği kadar geniş olmamalıdır.
2. Her alan için tür ve sınır belirleyin. Metin, sayı, doğru/yanlış, dizi ve nesne ayrımını açıkça yapın.
3. Zorunlu alanları ayırın. İşlem için gerçekten gerekli olmayan alanları zorunlu yapmayın; kritik alanları da isteğe bağlı bırakmayın.
4. Geçerli seçenekleri sınırlayın. Durum, işlem türü veya öncelik gibi alanlarda serbest metin yerine izin verilen değerleri kullanın.
5. Ek alanları değerlendirin. Şema desteklemiyorsa beklenmeyen alanları reddedin; destekliyorsa bunların güvenlik etkisini ayrıca kontrol edin.
6. Başarılı ve hatalı sonuçları tanımlayın. Uygulama, doğrulama hatası ile yetki hatasını ve dış servisin başarısızlığını birbirinden ayırmalıdır.
7. Yazma işlemlerini onay ve yetki kontrolleriyle bağlayın. Şemadaki bir doğru/yanlış alanı, sunucu tarafındaki kimlik ve yetki kontrolünün yerine geçmez.
8. Gerçekçi örneklerle deneyin. Eksik alan, yanlış tür, geçersiz seçenek, sınır değeri ve tekrarlanan çağrı durumlarını test edin.

İyi bir araç şeması, ajanın her durumda doğru karar vereceğini garanti etmez. Şema yalnızca izin verilen girdileri ve beklenen sözleşmeyi sınırlar; kimlik doğrulama, yetkilendirme, işlem tekrarı, günlükleme, oran sınırlama ve dış servisten dönen sonucun doğrulanması uygulama katmanında ayrıca yapılmalıdır. Bu ayrım korunursa araçlar daha öngörülebilir çalışır ve hatalı ya da riskli çağrılar gerçek işleme dönüşmeden durdurulabilir.