İlk ajanı kurmak: döngü, araç ve durma koşulu

Sorulacak soru "model bu işi yapabilir mi" değil, "adımların sırası girdiye göre değişiyor mu". Sıra sabitse her turda bir model çağrısı ödeyip aynı sırayı yeniden keşfetmek, pahalı ve kararsız bir yoldan aynı sonuca varmaktır. Ajanın karşılığını verdiği yer, bir aracın döndürdüğü sonucun bir sonraki adımı gerçekten değiştirdiği işlerdir.

"Kullanıcıya yardımcı ol" bir hedef değil bir temennidir: hiçbir turda karşılanmış sayılmaz, bu yüzden döngü tur sınırına kadar döner. Hedefi, dışarıdan bakan birinin doğru ya da yanlış diye işaretleyebileceği bir son durum olarak yazın. Aynı belgeye kapsam dışı bırakılanları da yazmak, ilk günde en çok işe yarayan tek satırdır.

hedef: "Gelen destek kaydını sınıflandır ve doğru kuyruğa taşı."
bitis_durumu:
  kayit_durumu: "siniflandirildi"
  kuyruk: "atandi"
  gerekce_notu: "yazildi"
kapsam_disi:
  - "Müşteriye mesaj göndermek"
  - "Kaydı kapatmak"
  - "İade veya ödeme işlemi başlatmak"

Doğrulama adımı: bitiş durumunu okuyan bir kontrol fonksiyonu yazın ve döngüyü onunla sonlandırın. Modelin "tamamladım" demesi bir sinyaldir, kanıt değil; kanıt ortamın son durumudur.

Araç sayısı arttıkça seçim hatası da artıyor; en zararlı durum ise iki aracın işlevinin örtüşmesi. Model "kayit_getir" ile "kayit_ara" arasında sallanmaya başladığında sorun modelin yeteneğinde değil, sizin sınır çizmenizde. Araç kümesi, ajanın karar uzayıdır: onu siz daraltırsınız.

• İlk sürümü yalnızca okuma yapan araçlarla kurun; döngü kararlı çalışmadan yazma eklemeyin.
• İki aracın açıklaması birbirine benziyorsa ikisini tek araca indirin veya birinin kapsamını daraltın.
• Ajanın hiç kullanmadığı aracı kümeden çıkarın; taşınan her şema bağlamdan pay alıyor.
• Yıkıcı işlemler (silme, gönderme, ödeme) ilk sürümde araç kümesinde hiç bulunmasın.
• Her aracı ajana bağlamadan önce elle çağırıp tek başına çalıştığını doğrulayın.

Döngü üç işten oluşur ve üçü de sizin kodunuzda durur: modele bağlamı ver, dönen araç çağrısını çalıştır, sonucu bağlama yaz. Model turlar arasında durum tutmaz; iki tur arasında taşınan her şey sizin yazdığınız şeydir. Bu yüzden "ajan çerçevesi" seçimi, bu üç işi sizin adınıza nasıl yaptığından başka bir şey değildir. Döngüden çıkış da bu kodun işi: modelin araç çağırmayı bırakması tek başına bir çıkış nedeni değil, bitiş durumu kontrol fonksiyonunu çalıştırmak için bir tetikleyicidir.

def dongu(hedef, araclar, ust_sinir_tur):
    baglam = baslangic_baglami(hedef, araclar)
    tur = 0
    while tur < ust_sinir_tur:
        tur += 1
        cevap = modeli_cagir(baglam, araclar)
        if cevap.arac_cagrisi is None:
            # Araç çağırmayı bırakmak çıkış nedeni değil, denetim tetikleyicisi.
            if bitis_durumu_saglandi():
                return tamamlandi(tur)
            baglam = baglama_yaz(baglam, "bitis_denetimi", eksik_kalanlar())
            continue
        sonuc = araci_calistir(cevap.arac_cagrisi)   # zaman aşımı burada
        baglam = baglama_yaz(baglam, cevap.arac_cagrisi, sonuc)
        if bitis_durumu_saglandi():
            return tamamlandi(tur)
    return sinira_gelindi(tur)

İlk sürümde her turda tek araç çağırın. Paralel çağrı gecikmeyi düşürür ama hata ayıklamayı zorlaştırır: iki araç aynı turda çalıştığında "hangisinin sonucu kararı bozdu" sorusunun cevabı izden okunamaz hâle gelir. Paralelliği, tek çağrılı döngü kararlı çalıştıktan sonra ekleyin.

Tek durma koşuluna bağlı bir döngü, o koşul hiç karşılanmadığında sınırsız döner. Dört koşulu ayrı ayrı kodlayın ve hangisiyle çıkıldığını ize yazın: koşu bittiğinde "neden bitti" sorusunun cevabı tek bir alanda okunabilmeli.

İsteme yazılan üst sınır bir kural değildir: model kendi turlarını saymaz ve uzun bağlamda bu cümlenin ağırlığı düşer. Sayaç döngü kodunda durmalı; sınır aşıldığında döngü modele sormadan çıkmalı.

1. 01Tur sayacı: model kaç kez çağrıldı.
2. 02Araç başına çağrı sayacı: aynı araç kaç kez çalıştırıldı.
3. 03Duvar saati: koşunun toplam süresi ve tek bir araç çağrısı için zaman aşımı.
4. 04Maliyet sayacı: koşu başına toplam belirteç ve çağrı sayısı, kayda yazılır.

Sınıra gelindiğinde ne olacağı da tasarımın parçası. Sessizce durmak en kötü seçenek: iş yarım kalır ve kimse haberdar olmaz. Kabul edilebilir üç çıkış var — kısmi sonucu bir insana devretmek, kaydı "tamamlanamadı" durumuyla kuyruğa geri koymak, ya da girdiyi daraltıp yeniden denemek.

Ajanların en pahalı davranışı, aynı aracı aynı parametrelerle tekrar tekrar çağırmak. Bunun kaynağı çoğunlukla modelin ısrarı değil, hata mesajının yön vermemesi: "İşlem başarısız" cümlesi hangi alanın değiştirileceğini söylemez, model de elindeki tek hamleyi tekrarlar.

• Geçici hata (zaman aşımı, oran sınırı): döngü kodunda sınırlı sayıda yeniden dene, modele hiç gösterme.
• Parametre hatası: hangi alanın neden reddedildiğini döndür ve tek bir düzeltme turuna izin ver.
• Yetki reddi: yeniden deneme yok; döngüyü durdur ve devret.
• Bulunamadı: sonucun boş olduğunu açıkça söyle — boş liste ile hata farklı şeylerdir.
• Ön koşul eksik: hangi adımın önce yapılması gerektiğini yaz, model o adıma dönebilsin.

Ajan hatası tek bir turun değil bir turlar dizisinin sonucudur; bu yüzden tek bir istem kaydı hiçbir şey anlatmaz. Her tur ayrı alanlarla kaydedilmeli ve bir koşu, izden okunarak baştan kurulabilmeli.

Doğrulama adımı: rastgele bir koşuyu seçip izden okuyarak aynı araç çağrılarını elle tekrarlayın. Aynı sonuca varamıyorsanız iz eksiktir; bu eksiklik ilk üretim hatasında pahalıya mal olur.