AI ajanı ilk sayfayı bütün sonuçlar sanıyorsa.

Üç kayıt gelmesi, yalnızca üç kayıt olduğu anlamına gelmez

Ajanınızdan açık kayıtları listelemesini istediniz. Araç üç satır döndürdü; ajan da “Bütün açık kayıtlar bunlar” dedi. Yanıtın içinde sonraki sayfayı istemek için bir işaretçi varsa bu sonuç erken verilmiştir. Sayfalı bir araçta içerik listesi kadar tamamlanma bilgisi de okunmalıdır. Bu yazıda küçük bir sorgunun bütün sayfalarını izleyip hangi anda tam sonuç denebileceğini belirleyeceğiz.

Sayfalamada sonuç tek pakete sığdırılmak yerine parçalara ayrılır. Sonraki parçayı istemek için çoğu sözleşmede bir anahtar veya işaretçi taşınır; alan adı ve bitiş kuralı kullanılan araca bağlıdır. Ajanın doğal dilde “devam et” demesi, uygulamanın doğru anahtarla yeni istek kurduğunu göstermez. Çağrı günlüğünde hangi isteğin hangi yanıtın devamı olduğu izlenebilmelidir.

AWS’nin DynamoDB sorgu sayfalama açıklaması, devam anahtarının sonraki isteğe taşınmasını ve bitişin anahtar durumundan anlaşılmasını anlatır. Filtreleme nedeniyle boş kayıt listesiyle birlikte devam anahtarı da gelebilir. Bu davranış, aşağıdaki özgün eğitim örneğinin çıkış noktasıdır. Burada kullanılan next ve snapshot alanları bir DynamoDB API sözleşmesi olarak sunulmaz; tanımladığımız küçük araç zarfına aittir.Kaynak: AWS — Paginating table query results in DynamoDB

Araç sözleşmesini sonuç listesinden önce okuyun

Görev: Demo grubundaki açık kayıtların kimliklerini listele.
Sorgu: grup=Demo, durum=Açık.
Örnek koşulu: S9 sabit veri görünümü; bütün sayfalarda aynı içerik kümesi.
Yanıt alanları: items, next, snapshot.
Bitiş: next=null ve başarılı yanıt.
Devam: next doluysa aynı sorgu ve S9 ile sonraki sayfayı iste.
Toplam çağrı sınırı: 3. Gerçek API çağrısı yapılmaz.

İlk yanıt üç kayıt getirir, fakat C1 işaretçisi sorgunun tamamlanmadığını gösterir. İkinci yanıt yeni kayıt getirmese de C2 taşır. Bu nedenle “liste boş, iş bitti” kuralı burada yanlış olur. Üçüncü yanıt R4 ve R5’i getirir; başarılı yanıtla birlikte next alanı null olduğunda tanımlı sorgu bu örneğin sözleşmesine göre tamamlanır.

S9 sabit görünümü bu öğretim senaryosunun açık varsayımıdır. Gerçek bir API’nin çok sayfalı sorgusunda aynı anda eklenen veya kaldırılan kayıtların nasıl ele alındığını ayrıca öğrenmelisiniz. Bir ürünün tek okuma için verdiği tutarlılık açıklamasından bütün sayfaların tek anı temsil ettiği sonucu çıkarılamaz. Araç sabit görünüm sağlamıyorsa sonuç notu tarama zamanını ve bu kapsam sınırını taşımalıdır.

İçeriği, çağrıyı ve bitiş kanıtını ayrı sayın

Üç çağrı yapılmış olması beş kayıt bulunduğu anlamına gelmez; sayılar farklı şeyleri ölçer. Aynı şekilde ikinci çağrının boş olması başarısız HTTP yanıtı değildir. Günlükte çağrı durumu, devam işaretçisi ve gelen kayıtlar ayrı alanlarda durmalıdır. Böylece sorun çıktığında veri yokluğu ile iletişim hatası veya yanlış sayfa isteği birbirine karışmaz.

Kimliklerin benzersizliğini de kontrol edin. Bir sonraki sayfada R3 tekrar gelseydi satır toplamı altı olabilir, ama benzersiz kayıt sayısı beş kalabilirdi. Bu tekrarın nedenini görünür tutmak gerekir; yalnızca tekrarı kaldırıp tamlık garantisi vermeyin. Kaydın iki sürümü farklıysa hangi içeriğin geçerli olduğunu belirleyen ayrı bir sözleşme gereklidir. Bu örnekte R1–R5’in her biri tek kez görünür.

Çağrı bütçesiyle bitiş kanıtı da ayrı koşullardır. Bütçenin dolması, veri kaynağının bittiği anlamına gelmez. İki çağrıyla sınırlı bir görevde üç kayıtla durabilirsiniz, ancak sonucu kısmi diye işaretlemelisiniz. Tersine sözleşmeye göre bitişe ulaşıldıysa bütçeyi doldurmak için gereksiz çağrı yapılmaz. Burada üçüncü çağrı hem kalan kayıtları hem de tamamlanma işaretini sağlar.

Sonuç cümlesine kapsamı taşıyın

Bağlam: Demo grubunun açık kayıtlarını S9 sabit görünümünde listeleyeceğim. Girdi: üç sentetik yanıt ve next sözleşmesi. Yanıtları devam anahtarlarıyla eşleştir; boş items listesini tek başına bitiş sayma. Her çağrıda yeni kimlikleri, birikimli benzersiz sayıyı ve next değerini yaz. Üç çağrı sınırını aşma. Çıktı: sonuç listesi, tam/kısmi durumu ve bitiş kanıtı. Kontrol: C1 ve C2 doğru sırayla taşınmalı; veri görünümü veya filtre değişirse sonucu birleştirme.

Sorgu: Demo / Açık, görünüm S9.
Kayıtlar: R1, R2, R3, R4, R5.
Benzersiz kayıt sayısı: 5. Başarılı çağrı sayısı: 3.
Durum: Bu sözleşme ve sabit görünüm altında tamamlandı.
Bitiş kanıtı: C2 ile istenen üçüncü sayfa başarılı döndü ve next=null.
İkinci sayfanın boş olması sorguyu sonlandırmadı.

Bu teslim “kurumdaki bütün kayıtlar beştir” demez. Yalnızca Demo grubu, Açık durumu ve S9 görünümüyle sınırlıdır. Yetki filtreleri veya başka gruplar sonucu etkileyebilir. Ajanın kısa yanıtında bile sorgu kapsamını korumak, eksik veriyle geniş bir iş kararı verilmesini önler. Okuyucu, listeye hangi şartlarla ulaşıldığını yeniden kurabilmelidir.

Sürekli dönen işaretçiyi de durdurun

1. next boş değilken listeyi tamamlandı diye sunma.
2. Aynı işaretçi tekrar dönüyorsa döngüyü kaydet ve incelemeye ayır.
3. Filtre veya görünüm değişirse farklı sonuçları sessizce birleştirme.
4. Hata ya da bütçe sınırında eldeki kayıtları kısmi olarak teslim et.
5. Benzersiz kayıt sayısını çağrı ve ham satır sayısından ayrı göster.

Küçük alıştırma: Çağrı bütçesini ikiye indirin. Sonuç R1, R2 ve R3 ile sınırlı kalır; ikinci yanıtın C2 işaretçisi açık iştir. Beklenen teslim “üç kayıt bulundu, sorgu kısmi kaldı” biçimindedir. Henüz alınmayan üçüncü sayfanın kimliklerini ajan kendi kendine yazmamalıdır. Bu sayfayı okuyucu olarak biliyor olmanız, iki çağrılık araç izinin o veriyi taşıdığı anlamına gelmez.

Kendi iş akışınızda bitiş kuralını araç sahibinden öğrenip birkaç küçük yanıtla sınayın. Normal sayfa, boş ara sayfa, tekrar eden işaretçi ve bütçe kesintisi aynı test paketinde bulunabilir. Tamamlanmış bir liste, yalnızca çok sayıda satır içeren liste değil, tanımlı sorgunun bittiğini gösteren kaydı da taşıyan listedir.