AI ajanı hata yanıtını geçerli veri gibi kullanırsa.

JSON okunuyor; peki ne söylüyor?

Ajan bir araçtan miktar bilgisi bekliyor. Gelen JSON sorunsuz açılıyor; fakat içinde sonuç yerine hata var. Ajan hata metninden bir sayı çıkarıp sonraki adıma aktarırsa araç zinciri yanlış veriyle devam eder. Girdiyi doğru hazırlamış olmak, aracın her zaman beklenen başarı nesnesini döndüreceğini garanti etmez. Dönüş zarfını da ayrı bir sözleşmeyle okumak gerekir.

Bu uygulamada tek bir sentetik okuma aracının iki sonuç dalını tasarlayacağız. Başarı dalında ok alanı true, data.qty alanı en az bir olan tam sayıdır. Hata dalında ok false olur ve error.code bulunur. Sonraki hesap adımına yalnızca geçerli başarı miktarı aktarılabilir. Gerçek araç çalıştırılmayacak, stok ayrılmayacak ve kayıt değiştirilmeyecektir.

Başarı ve hata kelimelerini HTTP durum kodlarıyla eşitlemiyoruz. Örnekte yalnızca verilmiş sonuç gövdeleri inceleniyor. Ağ yanıtı alınamaması ayrıca ele alınması gereken bir durumdur. Burada bir gövde var; görev, bu gövdenin hangi izinli dalı karşıladığını ve ardından hangi davranışa izin verdiğini belirlemektir.

İki dalı açıkça tanımlayın

JSON Schema içinde oneOf, verinin tanımlanan alt şemalardan tam birine uymasını ister. Ancak bu sözcük tek başına başarı/hata anlamını kurmaz; her dalın gerekli alanları ve değerleri de tanımlanmalıdır. Aşağıdaki şema bu eğitim sözleşmesine aittir. Başka bir aracın mevcut yanıtına uygulanmadan önce o aracın gerçek sözleşmesi okunmalıdır.Kaynak: JSON Schema — Boolean schema combination

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    {
      "type": "object",
      "required": [
        "ok",
        "data"
      ],
      "additionalProperties": false,
      "properties": {
        "ok": {
          "const": true
        },
        "data": {
          "type": "object",
          "required": [
            "qty"
          ],
          "additionalProperties": false,
          "properties": {
            "qty": {
              "type": "integer",
              "minimum": 1
            }
          }
        }
      }
    },
    {
      "type": "object",
      "required": [
        "ok",
        "error"
      ],
      "additionalProperties": false,
      "properties": {
        "ok": {
          "const": false
        },
        "error": {
          "type": "object",
          "required": [
            "code"
          ],
          "additionalProperties": false,
          "properties": {
            "code": {
              "enum": [
                "NOT_FOUND",
                "TEMPORARY"
              ]
            }
          }
        }
      }
    }
  ]
}

properties alanı bir alanın bulunmasını zorunlu kılmaz; bu amaçla required kullanılır. Ek alanları dışlamak için de additionalProperties açıkça false yapılmıştır. Bu iki özellik JSON Schema nesne belgelerinde ayrı açıklanır. Örnekte başarı zarfına error veya hata zarfına data eklenmesi böylece geçerli sayılmaz. İç nesnelerde de aynı alan sınırı korunur.Kaynak: JSON Schema — Objects

Buradaki miktar alt sınırı ve iki hata kodu özgün örnek seçimidir. Bir gerçek araç sıfır miktarı geçerli kabul edebilir veya başka hata kodları kullanabilir. O durumda şema araç sözleşmesine göre değişir. Bu çalışmada ise koşulları sonuçları gördükten sonra esnetmeyeceğiz; testin anlamı sabit kurallara göre karar vermektir.

Altı yanıtı dönüştürmeden okuyun

Verilen iki dallı şemayı R1–R6 gövdelerine uygula. JSON okunabilirliğini dal geçerliliğinden ayır. Metin olan 4 değerini sayıya çevirme; eksik ok veya data alanını uydurma; hata dalındaki data fazlasını sessizce silme. Her sonuç için başarı dalı, hata dalı veya hiçbir geçerli dal kararı yaz. Sonraki hesap adımına yalnızca geçerli başarı miktarını öner. Gerçek araç çağrısı yapma ve geçerli hata yanıtını başarılı iş diye sunma.

Altı gövde de sözdizimi olarak geçerli JSON’dur. Bununla birlikte yalnızca R1 veri aktarımına uygundur. R2, sözleşmeye uygun bir hata bildirimidir; biçimsel olarak geçerli olması işi başarılı yapmaz. R3–R6 ise tanımlanmış iki sonuç biçiminin hiçbirine uymaz. Bu ayrımı tek bir “JSON geçerli” kutusuyla ifade edemezsiniz.

Geçerli hata ile bozuk sonucu karıştırmayın

Geçerli başarı: 1, R1. Aktarılabilecek veri: qty=4.
Geçerli hata bildirimi: 1, R2. Başarı verisi aktarılmaz.
Sözleşme ihlali: 4, R3–R6. Veri uydurulmaz veya sessizce düzeltilmez.
Toplam 1 + 1 + 4 = 6. Bu masa başı denemede gerçek sonraki araç çağrısı: 0.

R2 için hata yolunun ne yapacağı ayrı bir iş kararıdır. NOT_FOUND, olmayan kaydı yeniden üretme yetkisi vermez. TEMPORARY gibi bir kod da tek başına sınırsız tekrar gerekçesi olamaz; tekrar bütçesi ve işlemin etkisi kendi kurallarından alınır. Sonuç dalını doğru okumak bu kararların ön koşuludur, bütün iş akışının tamamı değildir.

R3’teki metin dört kolayca sayıya çevrilebilir görünebilir. Fakat sessiz dönüşüm, aracın sözleşmeye uymadığını gizler. İzinli bir uyarlama katmanı varsa bunun kuralları ayrıca yazılır ve ham yanıt korunur. Modelin o an uygun gördüğü düzeltme, veri sözleşmesinin yerine geçmemelidir. R4’te hangi alanı atacağını seçmek de benzer biçimde bir çelişkiyi görünmez kılar.

• Ham yanıtı ve hangi araç çağrısına ait olduğunu inceleme kaydında koruyun.
• Önce zarf ve dal koşullarını doğrulayın; sonra iş kuralı ve yetki kontrollerine geçin.
• Geçerli hata, sözleşme ihlali ve hiç yanıt alınamaması için ayrı yollar tanımlayın.
• Önceki başarılı cevabın miktarını yeni hatalı yanıtın yerine kullanmayın.

Şemaya uyan R1 de kaynağın güncelliğini, miktarın doğru kayıtla eşleştiğini veya sonraki işlemin yetkili olduğunu kanıtlamaz. Bu kontroller ayrı katmanlardır. Buradaki son karar yalnızca “bu sözleşme altında miktar alanı okunabilir” düzeyindedir. Başarı etiketini daha geniş bir iş onayına dönüştürmemek testin kapsamını korur.

Fazladan alan olmadan yeni hata kodu

Yeni R7 yanıtı {"ok":false,"error":{"code":"BUSY"}} olsun. Şemada yalnızca NOT_FOUND ve TEMPORARY kodları tanımlıdır. R7’nin JSON olarak okunabildiğini biliyorsunuz. Hangi dala uyduğunu ve BUSY kodunu TEMPORARY ile aynı sayıp sayamayacağınızı, şemayı değiştirmeden açıklayın.

R7 hiçbir geçerli dala uymaz: ok=false başarı dalını dışlar, BUSY ise hata dalının izinli kodlarında yoktur. Sözleşme incelemesine gider. BUSY kendiliğinden TEMPORARY yapılmaz. Araç sahibi bu kodu resmen tanımlarsa yeni şema ve yeni test sürümüyle ayrıca değerlendirilir.

Kendi ajanınızda bir başarılı, bir bilinen hata ve bir eksik dönüşü yan yana koyarak başlayın. İstek şemasının yanında sonuç şeması da görünür olsun. Sonraki araca hangi alanın hangi kanıtla geçtiğini izleyebildiğinizde, okunabilir bir hata metninin geçerli veri gibi kullanılmasını önleyebilirsiniz.