AI ajanının araç girdisi geçerli görünüyor; işlem de geçerli mi?

Düzgün biçimlenmiş veri işleme izin vermez

Ajan bir stok rezervasyonu aracı için depo, ürün ve miktar alanlarını doldurdu. JSON okunabiliyor, bütün alanlar yerinde ve miktar bir tam sayı. Yine de depoda yeterli ürün olmayabilir. Araç girdisini denetlemek yalnızca metni düzgün bir nesneye çevirmek değildir. Bu yazıda biçim, şema ve güncel iş kuralı kontrollerini ayrı kararlar olarak tasarlayacağız; herhangi bir gerçek rezervasyon çalıştırmayacağız.

Örnek katalog sentetiktir. A ve B depo kodları geçerlidir. A deposunda P-17 ürünü için 5, P-18 için 0 kullanılabilir adet vardır. Test kullanıcısının yalnızca A deposunda işlem yapma yetkisi olduğunu varsayıyoruz. P-99 katalogda yoktur. Bu bilgiler modelin tahmini değil, örnekte güvenilir iş kaydı olarak verilen girdilerdir. Gerçek sistemde güncel stok ve izinler yetkili uygulama katmanından okunmalıdır.

JSON Schema belgelerinde required, bulunması zorunlu alanları; additionalProperties ise tanımlananların dışındaki alanların kabulünü düzenler. Bir alanı properties içinde tanımlamak onu kendiliğinden zorunlu yapmaz. Bu nedenle örnek şemamız üç alanı ayrıca required listesine alır ve fazladan alanları reddeder. Bu kurallar bir kullanıcının kim olduğunu veya hangi depoya yetkili olduğunu doğrulamaz.Kaynak: JSON Schema — Object ve zorunlu özellikler

Alan sözleşmesini kısa ve açık yazın

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["depo", "urun", "miktar"],
  "additionalProperties": false,
  "properties": {
    "depo": {"enum": ["A", "B"]},
    "urun": {"type": "string", "pattern": "^P-[0-9]{2}$"},
    "miktar": {"type": "integer", "minimum": 1, "maximum": 10}
  }
}

Sayısal tür ve sınır belgeleri integer ile tam sayı koşulunu, minimum ve maximum ile dahil sınırları tanımlar. Burada miktar 1 ile 10 arasında tam sayı olmalıdır. 0 ve 11 reddedilir; 1 ve 10 sınır bakımından uygundur. Ancak 10’un şemaya uyması depoda 10 adet bulunduğu anlamına gelmez. Bu makaledeki şema, kontrol sırasını öğretmek için hazırlanmış küçük bir sözleşmedir.Kaynak: JSON Schema — Sayısal türler ve sınırlar

Ürün deseninin P-17 ile P-99’u kabul etmesi beklenir; ikisi de biçime uyar. Katalogda var olma kontrolü ayrı yapılır. Benzer biçimde depo kodu B şemada geçerli olsa da bu test kullanıcısının yetkisi dışındadır. Geçerli kod kümesi ile kişiye tanınan izin kümesi aynı şey değildir. Şema bütün iş mantığını içine alan tek bir izin belgesi olarak kullanılmamalıdır.

Biçim ve iş kuralını farklı sütunlarda tutun

Tabloda 1,5 Türkçe gösterimdir; JSON içinde kesir yazılırsa 1.5 kullanılır. Son satırda miktar sayı 3 değil, tırnak içindeki metindir. Bu örneğin sözleşmesi sessiz tür dönüşümü yapmaz. Model veya uygulama ‘zaten aynı anlamda’ diyerek metni sayıya çevirecekse bunun ayrı, açık ve test edilmiş bir normalleştirme kuralı olması gerekir. Buradaki beklenen sonuç doğrudan rettir.

T1 yalnızca o andaki örnek verilerle ön koşullara uygun bulunur; rezervasyon yapılmış sayılmaz. İki kullanıcı aynı stoku eşzamanlı isteyebilir. Gerçek araç, işlem anında yetkiyi ve güncel stoku güvenilir sunucu tarafında tekrar kontrol ederek stok değişimini tutarlı biçimde uygulamalıdır. Ekranda daha önce görülen 5 adet, daha sonraki işlem için garanti değildir.

Düzeltme diye kullanıcının isteğini değiştirmeyin

Sentetik şema, katalog, stok ve kullanıcı yetkisini kullan. T1–T6 için şema kontrolünü ve iş kuralını ayrı değerlendir. Reddedilen girdiyi çalıştırma. Stok yetmiyorsa miktarı 5’e indirme; bilinmeyen ürünü benzer bir kodla değiştirme. Sonucu uygun taslak veya ret gerekçesi olarak yaz. Geçerli taslağı tamamlanmış rezervasyon diye bildirme. Güncel sunucu kontrolü ve gerekiyorsa insan onayı için sonraki adımı göster.

T1: Ön koşullara uygun taslak; işlem yapılmadı.
T2: Stok yetersiz; istenen 8 adet korunur, değişiklik için kullanıcı kararı gerekir.
T3: Şema reddi; depo kodu Z geçersiz.
T4: Şema reddi; miktar tam sayı değil.
T5: Katalog reddi; P-99 bulunmuyor.
T6: Şema reddi; miktar metin türünde.
B deposu kod olarak geçerli olsa da bu test kullanıcısına yetkili değildir.

Ret cevabını kısa ve düzeltilebilir hazırlayın. Hangi alanın hangi kurala uymadığını söyleyin; iç sistem ayrıntılarını veya kullanıcının görmemesi gereken katalog bilgisini dökmeyin. İş kuralı reddinden sonra aynı isteği tekrar tekrar göndermek stok yaratmaz. İzinli yeniden deneme, insan onayı ve aynı işlemin iki kez oluşmasını önleme konuları ilgili ajan yazılarındaki ayrı kontrollerle tamamlanır.

Bir ek alan ve bir eksik alan deneyin

1. JSON okunabilir mi ve beklenen nesne türünde mi?
2. Zorunlu alanlar, türler ve sınırlar sağlanıyor mu?
3. Kimlikten gelen izin, katalog ve güncel stok uygun mu?
4. Retten sonra yan etki oluşmadığı doğrulanabiliyor mu?
5. Uygun taslak ile tamamlanan işlem ayrı raporlanıyor mu?

Küçük alıştırma: T1 girdisine force: true alanı ekleyin. additionalProperties false olduğu için şema bunu reddeder; force bir yetki sağlamaz. İkinci denemede miktar alanını tamamen çıkarın. required listesinde olduğu için bu girdi de reddedilir. Varsayılan olarak 1 adet eklemek bu sözleşmenin parçası değildir. Kullanıcı yeni ve açık bir girdi sağlamadan işlem taslağı tamamlanmış kabul edilmez.

Çalışmanın sonunda yalnızca örnek JSON’u saklamayın. Hangi girdinin nerede reddedileceğini gösteren tabloyu, geçerli taslağın işlem anındaki kontrollerini ve kullanıcıya dönecek sonucu birlikte tutun. Böylece araç bağlantısı kurulduğunda akıcı model çıktısının hangi sınırda durması gerektiği önceden belirlenmiş olur. Bu eğitim tasarımı gerçek entegrasyonun güvenilirliğini tek başına kanıtlamaz; uygulanacak kontrolleri somutlaştırır.