Graf mühendisliği: ölçekte kırılmayan ajan sistemleri nasıl kurulur

Düğüm sözleşmeleri, dört temel şekil, kenardaki doğrulama, kalıcı durum, yakınsayan döngüler ve topolojinin maliyet üzerindeki etkisi.

Hızlı not: Bu yazıyı okurken kendi akışını çiz. Çoğu kişi çizince görüyor: kurduğu şey aslında dört kutuluk bir zincir ve bekleyen düğümlerin çoğu diğerinin çıktısını hiç okumuyor.

Çoğu kişi ajan akışını hâlâ düz bir çizgi olarak tasarlıyor. Önce araştır, sonra yaz, sonra incele, en son gönder. Her adım bir öncekini bekliyor, yarısının o sonuca hiç ihtiyacı olmasa bile.

Sistem dallanmıyor. Paralelleşmiyor. Toparlanmayı bilmiyor. Tek bir bağlam penceresini beslemeye devam ediyor; ta ki ajan yavaşlayana, kafası karışana ya da pahalılaşana kadar.

Sorun artık istem değil. Sorun işin şekli. Graf mühendisliğinin düzelttiği şey de bu.

Graf mühendisliği tam olarak ne demek?

Graf mühendisliği, bir ajan akışını açık bir yürütme haritasına çevirme pratiği. Her kararı tek bir model döngüsünün içine saklamak yerine sistemi düğümler ve kenarlar olarak tanımlıyorsun.

DÜĞÜM        = sınırları belli tek bir iş birimi
KENAR        = iki düğüm arasındaki gerçek bağımlılık
DURUM        = düğümler arasında hayatta kalan veri
YÖNLENDİRİCİ = bir sonraki kenarı seçen kural
KAPI         = işin devam edip edemeyeceğine karar veren kontrol

Bir düğüm; ajan, araç çağrısı, deterministik bir fonksiyon, doğrulayıcı ya da insan onayı adımı olabilir. Kenar ise neyin sonra çalışabileceğini ve sınırdan hangi verinin geçtiğini söyler. Hangi döngülerin, hangi sırayla, hangi dallanma, birleşme ve toparlanma yollarıyla çalışacağına graf karar verir.

Döngü tek bir ajanın işini iyileştirir. Graf, birçok döngüyü tek bir sistemde koordine eder.

1. Her "sonra" bir bağımlılık değildir

Çoğu ajan akışı düz çizgi, çünkü talimatlar öyle yazılıyor: A yap, sonra B, sonra C. Ama sıra ile bağımlılık aynı şey değil. B, A'nın çıktısını tüketmiyorsa B'nin beklemesi için hiçbir sebep yok.

KÖTÜ

pazar verisi topla -> repoyu incele -> rakip fiyatlarını kontrol et

DAHA İYİ

                 -> pazar verisi topla ---------
KULLANICI İSTEĞİ -> repoyu incele --------------> SENTEZLE
                 -> rakip fiyatlarını kontrol et -

Graf mühendisliğinin ilk sorusu basit: bir sonraki adım, bir öncekinin çıktısını gerçekten okuyor mu? Cevap hayırsa kenarı kes. Tek başına bu değişiklik, yavaş bir zinciri genelde hızlı bir paralel grafa çeviriyor.

2. Her düğüme bir sözleşme ver

Kesin olarak tarif edemediğin düğümü yönlendiremez, test edemez ve değiştiremezsin. İşe yarayan her düğümün dört şeye ihtiyacı var: tek iş, açık girdi, yapılandırılmış çıktı ve net bir hata hali.

{
  "dugum": "kaynak_arastirmacisi",
  "girdi": {
    "konu": "metin",
    "kaynak_tipi": "birincil"
  },
  "cikti": {
    "iddia": "metin",
    "kaynak_url": "metin",
    "guven": "yüksek | orta | düşük"
  },
  "hata": "birincil_kaynak_bulunamadi"
}

Serbest metin, bir sonraki düğümü ne olduğunu tahmin etmeye zorlar. Yapılandırılmış çıktı ise model cevabını grafın güvenebileceği bir şeye çevirir. Bu aynı zamanda düğümleri değiştirilebilir yapar: sözleşme aynı kaldığı sürece modeli, istemi ya da aracı değiştirip sistemi baştan kurmak zorunda kalmazsın.

3. Kenarları ok değil, veri sözleşmesi olarak gör

Bir kenar "B, A'dan sonra gelir" demek olmamalı. "A bir veri üretti ve B onu tüketmeye yetkili" demeli.

Bu ayrım önemli, çünkü akış tesisatının çoğu için başka bir model çağrısı gerekmiyor. Dizileri düzleştirmek, tekrarları silmek, boşları elemek, durum kontrol etmek ve kayıtları birleştirmek deterministik işlerdir.

const kullanilabilir = sonuclar
  .filter(Boolean)
  .flatMap(sonuc => sonuc.items)

const tekil = [...new Map(
  kullanilabilir.map(x => [x.kaynak_url, x])
).values()]

Burada ajana gerek yok. Model çağrılarını karar gerektiren yere sakla, tesisat için kod kullan.

Her kenarı ayrı bir ajan olan graf, kendi kablolamasına token ödüyor demektir.

4. Neredeyse her ajan grafının arkasındaki dört şekli öğren

Elli desene ihtiyacın yok. Üretimdeki grafların çoğu dört şeklin birleşimi.

Zincir

A -> B -> C

Her adım gerçekten bir öncekinin çıktısını gerektiriyorsa kullan. Basit, tahmin edilebilir ve çoğu zaman gerekenden yavaş.

Elmas

        -> B1 -
A ->    -> B2 --> C
        -> B3 -

Tek işi bağımsız kollara böl, birlikte çalıştır, sonuçları birleştir. Araştırma, kod incelemesi, durum tespiti ve pazar taraması için asıl iş atı bu.

Yönlendirici

             -> HIZLI YOL
SINIFLANDIR ---
             -> TAM DENETİM

Duruma bak ve işin gerçekten ihtiyacı olan yolu seç. Küçük iş ucuz kalır, riskli iş daha derin bir grafa gider.

Kontrollü döngü

ÇALIŞ -> DOĞRULA -> GEÇTİ -> ÇIKIŞ
            |
            -> DÜŞTÜ -> GERİ BİLDİRİM -> ÇALIŞ

Sadece kanıt sonucun eksik olduğunu söylüyorsa tekrarla. Her döngünün sert bir durma noktası, bir bütçesi ve bir yakınsama kuralı olmalı.

5. Bağımsız işi dağıt, birleşmeyi bilerek koy

Paralellik, grafın anlaşılması en kolay ve suistimal edilmesi en kolay avantajı. Beş düğüm bağımsızsa birlikte çalıştır.

const sonuclar = await Promise.allSettled(
  kaynaklar.map(k => arastirmaDugumu(k))
)

const bulgular = sonuclar
  .filter(r => r.status === "fulfilled")
  .map(r => r.value)

Düşen bir kol diğer dördünü yok etmemeli. Ama her aşamadan sonra bariyer koyma. Birleşme, ancak bir sonraki düğümün tüm kümeye ihtiyacı varsa beklemeye değer: kaynaklar arası tekilleştirme, tüm adayları sıralama, alternatifleri karşılaştırma ya da kapsamın yeterli olup olmadığına karar verme.

Her parça bağımsız devam edebiliyorsa grafı akar halde tut.

Paralel olan otomatik olarak hızlı değildir. Sistemin nerede bekleyeceğine topoloji karar verir.

6. Yönlendirmeyi denetlenebilir yap

Kararı model verebilir. O kararın neyi tetikleyebileceğini ise graf zorunlu kılmalı.

const karar = await riskSiniflandir(degisiklik)

switch (karar.seviye) {
  case "dusuk":
    return hizliInceleme(degisiklik)

  case "yuksek":
    return tamParalelDenetim(degisiklik)

  default:
    return insanIncelemesi(degisiklik)
}

Sınıflandırıcı olasılıklıdır, izin verilen yollar ise deterministik. Böylece modelin esnekliğini alırken sistemin kontrolünü ona devretmemiş olursun.

7. Doğrulamayı kenara koy

Bir graftaki en yüksek kaldıraçlı düğüm, çoğu zaman hiçbir şey üretmeyen düğümdür. Görevi, zayıf işin aşağı akmasını durdurmak. Bir doğrulayıcı şunları kontrol edebilir:

• Her iddianın bir kaynağı var mı?
• Gösterilen kaynak, iddiayı gerçekten destekliyor mu?
• Kod testleri geçiyor mu?
• Sonuç istenen şemaya uyuyor mu?
• Bağımsız başka bir yol da aynı sonuca varıyor mu?

ÜRETİCİ -> DOĞRULAYICI -> GEÇTİ -> SENTEZLEYİCİ
                |
                -> DÜŞTÜ -> ONARIM

Aynı ajandan tek bağlamda hem üretmesini, hem onaylamasını, hem de yayınlamasını isteme. Rolleri ayır, istemleri ayır, hata sınırlarını ayır.

Anthropic'in üretimdeki araştırma sistemi de bu mantığı daha büyük ölçekte izliyor: bir lider ajan paralel alt ajanları koordine ediyor, bulgular sentezleniyor ve sonuç kullanıcıya ulaşmadan önce ayrı bir kaynak aşaması kanıtı ekliyor.

8. Diyagramların sakladığı kısım: durum

Kutular ve oklar, sistem çöktükten sonra devam etmesi gerekene kadar temiz görünür. Üretimdeki bir grafın kalıcı duruma ihtiyacı var:

gorev_id
mevcut_dugum
tamamlanan_dugumler
ciktilar
kararlar
kanitlar
butceler
tekrar_sayaclari
insan_onaylari

Düğümler arasında dev metinler taşıma, çıktının referansını taşı. Araştırma düğümü raporunu kaydedip geriye bir yol, kimlik ya da yapılandırılmış özet döndürsün. İnceleyen düğüm de üç ajandan geçip sıkışmış bir anlatı yerine çıktının kendisini okusun. Bu hem bağlam kaybını azaltır hem her geçişi denetlenebilir yapar.

Graf her an üç soruya cevap verebilmeli: şu ana kadar ne oldu, sistem bu yolu neden seçti, yürütme güvenle nereden devam edebilir? Cevap veremiyorsa o graf hâlâ bir demo.

9. Döngüyü ancak yakınsıyorsa ekle

Döngü, işin miktarının önceden bilinmediği yerlerde işe yarar: hata avı, derin araştırma, tekrarlı onarım. Ama "iyi olana kadar tekrarla" bir durma koşulu değildir. Ölçülebilir yakınsama kullan.

let bosTur = 0
let tur = 0
const gorulen = new Set()

while (bosTur < 2 && tur < 6) {
  const bulgular = await kesfet()
  const yeni = bulgular.filter(b => !gorulen.has(b.key))

  yeni.forEach(b => gorulen.add(b.key))
  bosTur = yeni.length === 0 ? bosTur + 1 : 0
  tur += 1
}

Sistemin neyi hatırladığına dikkat et: sadece doğrulamayı geçen bulgulara karşı değil, şimdiye kadar görülen her şeye karşı tekilleştiriyor. Yoksa reddedilen fikirler geri gelmeye devam eder ve graf aynı çıkmaz yolları tekrar tekrar keşfetmek için para öder.

Her kontrollü döngünün şunlara ihtiyacı var: bir tamamlanma testi, en fazla tur sayısı, token ya da maliyet bütçesi, önceki denemelerin kaydı ve yakınsama başarısız olursa bir yükseltme yolu.

10. Hatayı yerel bir olay olarak tasarla

Zincirde tek bir kırık adım bütün akışı dondurabilir. Grafta ise hata mümkün olan en küçük sınırın içinde kalmalı. Her düğümün bir politikası olmalı:

TEKRAR DENE  geçici araç ya da ağ hatası
YEDEĞE GEÇ   tercih edilen model veya kaynak yoksa
ATLA         isteğe bağlı bir kol düştüyse
ONAR         çıktı doğrulamadan geçemediyse
YÜKSELT      risk ya da belirsizlik eşiği aşıldıysa
DUR          bütçe, güvenlik veya yetki sınırına gelindiyse

Pahalı düğümlerden sonra kontrol noktası koy. Yazma işlemlerini tekrarlanabilir yap ki yeniden deneme yan etkileri ikiye katlamasın. Dosya değiştiren paralel işçilere izole çalışma alanı ver. Her yönlendirme kararını, onu üreten durumla birlikte kaydet.

Güvenilirlik her düğümün başarılı olmasını ummaktan gelmez. Bir düğüm başarısız olduğunda grafın ne yapacağına karar vermekten gelir.

11. Topoloji senin maliyet modelin

Graf, tek ajandan otomatik olarak ucuz değildir. Her göreve filo çıkarırsan çok daha fazla token yakabilir. Şekil hem gecikmeyi hem maliyeti belirler.

Sınırlı çıkarım, sınıflandırma ve biçimlendirme için ucuz modelleri kullan. Parçalama, sentez ve zor doğrulama için güçlü modelleri sakla. Basit işi kısa yoldan geçir, tam grafı hak eden işe ayır.

BASİT İSTEK  -> KÜÇÜK MODEL -> HIZLI KONTROL -> BİTTİ

KARMAŞIK İSTEK -> PLANLAYICI -> PARALEL UZMANLAR
                                -> DOĞRULAYICILAR
                                -> GÜÇLÜ SENTEZLEYİCİ
                                -> İNSAN KAPISI

Anthropic'in aktardığına göre çok ajanlı araştırma, genişlik gerektiren işlerde tek ajanı belirgin biçimde geçebiliyor; ama çok daha fazla token harcıyor. Denge bu.

Graf mühendisliği ajan sayısını büyütmek değil. Koordinasyonu yalnızca paralelliğin, uzmanlaşmanın ya da bağımsız doğrulamanın yeterli değer ürettiği yerde harcamak.

12. Araştırma ve yayın için üretim grafı

Tek bir fikri kaynaklı bir yazıya çeviren pratik bir graf:

                                  -> ŞİRKET KAYNAKLARI ----
KONU -> KAPSAM -> PARÇALA         -> AKADEMİK YAYINLAR -----> TEKİLLEŞTİR
                                  -> UZMAN PAYLAŞIMLARI ---
                                                             |
                                                             v
              YAYINLA <- İNSAN KAPISI <- SON KONTROL <- TASLAK
                                              |          ^
                                              -> DÜŞTÜ -> ONAR

1. Kapsam düğümü soruyu, hedef kitleyi ve tamamlanma ölçütünü tanımlar.
2. Parçalama düğümü bağımsız araştırma kulvarları oluşturur.
3. Araştırma düğümleri ayrı bağlamlarda paralel çalışır.
4. Deterministik kod tekrarları siler ve kaynakları normalleştirir.
5. Taslak düğümü yapılandırılmış kanıttan yazar.
6. Kontrolcü iddiaları, kaynakları, üslubu ve eksik bölümleri doğrular.
7. Düşen kontroller sadece ilgili bölümü onarıma geri yollar.
8. Yayından önce bir insan nihai çıktıyı onaylar.

Bu, takım taklidi yapan dev bir ajan değil. Sahipliği, durumu ve yetkisi açık bir sistem.

Graf ne zaman yanlış cevaptır?

Her istemi mimari diyagrama çevirme. Şu durumlarda tek ajanı tek döngüde tut: iş kısaysa, tek bağlam tüm bilgiyi tutabiliyorsa, bağımsız kol yoksa, hata ucuzsa ve bir insan sonucu hızla gözden geçirebiliyorsa.

Şu durumlarda grafa geç: iş paralel çalışabiliyorsa, farklı düğümlerin farklı araç ya da yetkilere ihtiyacı varsa, çıktılar bağımsız doğrulama gerektiriyorsa, iş kesintiden sonra devam edebilmeliyse, birden çok döngünün ortak duruma ihtiyacı varsa, maliyet ve yetki yola göre kontrol edilmeliyse.

Tek döngüyle başla. Grafı ancak bağımlılıklar seni zorladığında çiz.

Graf mühendisliği kontrol listesi

[ ] Her kenar gerçek veri ya da yetki taşıyor mu
[ ] Her düğümün sınırları belli tek bir işi var mı
[ ] Girdiler ve çıktılar yapılandırılmış mı
[ ] Bağımsız düğümler paralel çalışabiliyor mu
[ ] Birleşmeler sadece tam kümenin gerektiği yerde mi
[ ] Önemli sonuçlar aşağı akmadan doğrulanıyor mu
[ ] Hatalar yan etkileri ikiye katlamadan tekrar denenebiliyor mu
[ ] Graf bir kontrol noktasından devam edebiliyor mu
[ ] Her döngünün sert durma noktası ve bütçesi var mı
[ ] Bir insan yüksek riskli yolları kesebiliyor mu
[ ] Her yönlendirmenin neden seçildiğini açıklayabiliyor musun
[ ] Graf, çözdüğü problemden daha mı basit

Son sorunun cevabı hayırsa düğüm sil.

Asıl değişim

İstem mühendisliği talimatı iyileştirir. Bağlam mühendisliği modelin ne gördüğünü kontrol eder. Harness mühendisliği modelin etrafındaki ortamı kurar. Loop mühendisliği tek bir iş biriminin geri bildirimle gelişmesini sağlar. Graf mühendisliği ise işin tamamını koordine eder.

İSTEM -> BAĞLAM -> HARNESS -> DÖNGÜ -> GRAF
mesaj    hafıza     makine     koşu    koordinasyon

İstem yazan, ajandan daha fazlasını yapmasını ister. Mimar ise sistemin daha fazlasını güvenle yapabilmesi için grafı yeniden çizer.

Model sadece bir düğüm. Ürün, etrafındaki sistem.