CrewAI: Hazır Ekip Değil, Ödünç Alınan Varsayımlar

Model: dört kavram, bir sözleşme

CrewAI’ın modeli sade. Agent bir rol, bir hedef ve bir arka plan hikâyesiyle tanımlanıyor. Task bir açıklama, beklenen çıktı ve onu yapacak agent. Crew agent’ları ve görevleri bir araya getiriyor. Process görevlerin nasıl ilerleyeceğini söylüyor: sıralı ya da bir yönetici agent’ın dağıttığı hiyerarşik düzen.

İşimiz basitti: haftalık müşteri şikâyetlerini oku, kategorilere ayır, regülasyon riski taşıyanları işaretle, yöneticiye bir sayfalık rapor yaz. Üç rol kendiliğinden çıktı:

from crewai import Agent, Task, Crew, Process

analist = Agent(
    role="Sikayet analisti",
    goal="Haftalik sikayetleri kategorilere ayirmak",
    backstory="Araci kurumun musteri deneyimi ekibinde calisiyorsun.",
    allow_delegation=False,   # varsayilana birakma, acikca yaz
)
uyum = Agent(
    role="Uyum uzmani",
    goal="Regulasyon riski tasiyan sikayetleri isaretlemek",
    backstory="Sermaye piyasasi mevzuatini iyi biliyorsun.",
    allow_delegation=False,
)
yazar = Agent(
    role="Rapor yazari",
    goal="Yoneticiye bir sayfalik ozet yazmak",
    backstory="Kisa ve net yazarsin.",
    allow_delegation=False,
)

siniflama = Task(
    description="Su sikayetleri kategorilere ayir: {sikayetler}",
    expected_output="Kategori basina sayi ve kisa aciklama",
    agent=analist,
)
risk = Task(
    description="Regulasyon riski tasiyan sikayetleri bul",
    expected_output="Risk tasiyan sikayetlerin listesi ve gerekcesi",
    agent=uyum,
    context=[siniflama],      # DIKKAT: ham sikayet degil, analistin CIKTISI gelir
)
rapor = Task(
    description="Haftalik raporu yaz",
    expected_output="Bir sayfalik rapor",
    agent=yazar,
)

ekip = Crew(
    agents=[analist, uyum, yazar],
    tasks=[siniflama, risk, rapor],
    process=Process.sequential,
)
sonuc = ekip.kickoff(inputs={"sikayetler": sikayet_metni})

Kodu okuyan biri hatayı hemen görüyor: {sikayetler} yalnızca ilk görevin açıklamasında var. Uyum agent’ı şikâyetleri değil, analistin yazdığı özeti görüyor. Ben bunu yazarken görmedim, çünkü kafamda bir ekip vardı ve ekipte herkes aynı klasöre bakar.

Hızlı prototip: gerçekten hızlı

Önce hakkını vereyim. 14 Temmuz Salı sabah başladım, akşam ilk rapor uyum ekibinin önündeydi. Rolleri yazmak işi düşünmeme de yardım etti: “uyum uzmanı ne arar?” sorusunu agent tanımlarken sorduk ve cevabı uyum ekibinden aldık. Düz kodla aynı gün bu noktaya gelemezdim; hangi adıma kaç çağrı gerektiğini, çıktıyı nasıl parse edeceğimi düşünmem gerekirdi.

İki hafta boyunca, 16 ve 23 Temmuz’da, rapor düzgün geldi. Yöneticiler memnundu. 30 Temmuz raporu da düzgün görünüyordu.

Sahadan: kaybolan cümle

3 Ağustos Pazartesi uyum ekibi aradıktan sonra şikâyeti bulduk. Müşteri, para çekme talebinin üç gün beklemesinden şikâyet ediyordu ve son cümlesi “bu hafta içinde çözülmezse SPK’ya şikâyet edeceğim” idi. Analist agent onu doğru sınıflamıştı: “para çekme gecikmesi, müşteri memnuniyetsiz”. Doğru, ama eksik. Özetin içinde SPK kelimesi yoktu.

Uyum agent’ı elindeki metne göre doğru karar verdi: gecikme şikâyetleri risk değildir. Hatayı yapan agent yoktu. Hata veri akışındaydı ve veri akışını ben değil, sıralı process’in varsayılanı belirlemişti. Bulmamız bir buçuk gün sürdü, çünkü önce prompt’ta sorun aradık: uyum agent’ının hikâyesini uzattık, “dikkatli ol” ekledik. Hiçbiri işe yaramadı; agent’ın görmediği bir cümleyi dikkatle okumasını istiyorduk.

Nerede önüne geçiyor?

1. Bağlam taşıma

Sıralı process’te bir görev bir öncekinin çıktısını bağlam olarak alıyor. Bu, her adımda bilginin bir kez sıkıştırılması demek. Üç adımlık zincirde ham veri ilk agent’ta kalıyor; sonrakiler özetin özetini görüyor. Ham veriyi her göreve açıkça koymak mümkün, ama o zaman token iki katına çıkıyor ve “ekip” modelinin sunduğu kolaylık kalmıyor.

2. Gizli yeniden deneme

Bir agent bir görevde tek çağrı yapmıyor: düşünüyor, gerekirse tool çağırıyor, sonucu okuyor, tekrar düşünüyor. Çıktı beklenen biçime uymazsa yeniden deniyor. Bunun bir iterasyon sınırı (max_iter) var; değerini sen yazmadıysan varsayılanı seçmişsin demektir. Bir koşumuzda uyum agent’ı biçimi tutturamadı, koşu 38 yerine 52 çağrı ve 241 bin token’a çıktı. Bunu yalnızca koşunun sonundaki toplamdan fark ettik.

Bizim tool’larımız salt okumaydı. Yazan bir tool olsaydı — bilet açan, müşteriye mesaj atan — gizli yeniden deneme çift bilet demekti. Bu, at-least-once yazısındaki problemin aynısı; yeniden deneyen bir sistemin yan etkisi olan her adımı idempotent olmak zorunda.

3. Agent’lar arası konuşmada kaybolan token

Her LLM çağrısında agent’ın rolü, hedefi, hikâyesi, format talimatları ve önceki görevin çıktısı yeniden gönderiliyor. Tek çağrıda küçük; 38 çağrıda büyük. Ortalama bir koşunun 186 bin token’ının 108 bini, yani %58’i, işin kendisi değil bu tekrar eden metindi. Şikâyet metinlerinin kendisi toplamda 30 bin token civarı.

4. Hata ayıklama

verbose açıkken ekrana akan metin okunabilir ama sorgulanamaz. “Uyum agent’ı üçüncü çağrısında hangi metni gördü?” sorusunun cevabı o akışın içinde bir yerde, ama bulmak için kaydırarak okuman gerekiyor. Bir buçuk günün büyük kısmı buraya gitti.

CrewAI’ı izlemek: kim ne harcadı?

Koşu bittiğinde crew bir kullanım özeti veriyor: toplam token, toplam istek. Bu, token panosu yazısında anlattığım görev başı maliyet için yetiyor, ama “neden bu kadar” sorusuna cevap vermiyor. Kırılımı almak için izlemeyi framework’ün altına, LLM çağrısı seviyesine indirdik:

# LLM istemcisini sar: framework ne yaparsa yapsin, her cagri buradan gecer
def izlenen_cagri(mesajlar, **ayar):
    bas = simdi()
    cevap = llm_istemcisi.cagir(mesajlar, **ayar)
    kaydet({
        "kosu_id"   : aktif_kosu(),         # tek haftalik rapor = tek kosu
        "agent"     : aktif_agent_rolu(),   # gorev baslarken set edilir
        "gorev"     : aktif_gorev(),
        "iterasyon" : iterasyon_sayaci(),   # ayni gorevde kacinci cagri
        "girdi_tok" : cevap.kullanim.girdi,
        "cikti_tok" : cevap.kullanim.cikti,
        "sure_ms"   : simdi() - bas,
        "girdi"     : mesajlar,             # asil kazanc: agent NE GORDU
    })
    return cevap

CrewAI görev ve adım sonlarında callback kabul ediyor; biz onları sadece aktif agent ve görevi işaretlemek için kullandık. Asıl bilgi, çağrının girdisini kaydetmekten geldi. SPK hatasını bu kayıtla yeniden oynattığımızda, uyum agent’ının gördüğü metinde “SPK” kelimesinin geçmediğini tek sorguyla gördük. Bir buçuk gün yerine iki dakika.

Aynı iş, iki kez: CrewAI ve düz kod

Hatayı bulduktan sonra aynı işi düz kodla yazdım. Agent yok, rol yok; üç adım ve adımlar arasında açık bir veri sözleşmesi:

# 1) siniflama: 20'lik partiler, JSON cikti, sema dogrulamasi
kategoriler = [siniflandir(parti) for parti in partile(sikayetler, 20)]   # 6 cagri

# 2) risk: HAM sikayet metni gider, ozet degil
#    once ucuz on filtre (SPK, avukat, dava, mahkeme...), sonra model
adaylar = on_filtre(sikayetler) + riskli_kategoriler(kategoriler)
riskler = [risk_degerlendir(parti) for parti in partile(adaylar, 10)]    # ~6 cagri

# 3) rapor: tek cagri, girdisi yapisal veri
rapor = rapor_yaz(kategoriler, riskler)                                   # 1 cagri

Sonra iki sürümü uyum ekibinin elle etiketlediği dört haftalık şikâyet setinde koşturduk. Dört haftada 11 riskli şikâyet vardı:

Tabloya dürüst bir çekince: düz kod sürümünü, problemi bildikten sonra yazdım. Üç günün içinde CrewAI’dan öğrendiklerim de var. Sıfırdan başlasaydım düz kod muhtemelen daha uzun sürerdi. Hata ayıklama satırı da adil değil: iki hata farklı zorlukta ve CrewAI’ın 1,5 günü izleme kurulmadan önceydi. Tabloyu “CrewAI kötü” diye değil, “neyin bedelini nerede ödüyorsun” diye oku.

Bende işe yaramayanlar

• Hikâyeyi uzatarak düzeltmek. Uyum agent’ının backstory’sine üç paragraf mevzuat ekledim. Her çağrıda tekrar gönderildiği için koşu 186 binden 214 bin token’a çıktı; SPK cümlesi yine gelmedi, çünkü sorun agent’ın bilgisinde değil, önündeki metindeydi.
• Hiyerarşik process’e geçmek. “Bir yönetici agent dağıtsın, belki ham veriyi doğru kişiye verir” dedik. Çağrı sayısı 38’den 61’e çıktı, sonuç değişmedi. Veri akışı problemini bir agent daha ekleyerek çözemezsin.
• Ekran çıktısını log sanmak. İki hafta boyunca “verbose açık, görüyoruz” dedik. Görüyorduk, ama saklamıyorduk ve sorgulayamıyorduk.

Ne izlemeli?

Kontrol listesi

Sonuç

O Perşembe raporu yanlış değildi; eksikti. Her agent kendi önündeki metne göre doğru karar verdi. Eksik olan, benim yazmadığım ama framework’ün benim yerime verdiği bir karardı: uyum uzmanı neyi okuyacak?

CrewAI’ı bırakmadık. Yeni bir iş geldiğinde ilk gün hâlâ onunla başlıyoruz, çünkü adımları bulmanın en hızlı yolu bu. Ama adımlar belli olunca düz koda geçiyoruz ve o geçişi bir iyileştirme değil, işin olgunlaşması olarak görüyoruz.

Test şu: crew’undaki her agent’ın bir çağrıda tam olarak hangi metni gördüğünü söyleyebiliyor musun? Söyleyemiyorsan bir ekibin yok; varsayımlarını tanımadığın biriyle çalışıyorsun.