CrewAI ve AutoGen ile Çoklu Ajan Sistemleri

Tek bir dil modeline verilen uzun ve karmaşık istemler, çoğu zaman tutarsız sonuçlar üretir. Çoklu ajan sistemleri bu soruna iş birliği çözümü getirir: görev, uzmanlaşmış rollere sahip birden fazla ajana bölünür ve ajanlar birbirlerinin çıktıları üzerinde çalışır. CrewAI ve AutoGen, bu yaklaşımı uygulayan iki önde gelen açık kaynak Python çerçevesidir. Bu rehber, iki çerçevenin kurulumunu, temel yapı taşlarını ve tasarım desenlerini ele alır.

İki Çerçevenin Yaklaşımı

CrewAI, ekip (crew) metaforu üzerine kuruludur. Her ajan bir role, hedefe ve arka plan hikâyesine sahip olur; görevler önceden tanımlanır ve ajanlar arasında zincir hâlinde akar. Süreç kavramı, görevlerin sırayla mı yoksa paralel mi yürütüleceğini belirler. Bu yapı, net iş akışları olan senaryolarda içerik üretimi, rapor hazırlama, veri analizi gibi güçlüdür ve öngörülebilir sonuç verir.

AutoGen, Microsoft Research kökenli bir çerçevedir ve ajanlar arası konuşmayı temel birim olarak alır. Güncel AgentChat arayüzünde takım (team) sınıfları, RoundRobinGroupChat ve SelectorGroupChat gibi önceden tanımlı sohbet desenleri sunar: sıradan tur sistemiyle ajanlar konuşur veya bir yönetici ajan, sıradaki konuşmacıyı seçer. Bu esneklik, doğrulama gerektiren, müzakereli akışlarda avantaj sağlar.

Ön Koşullar

Her iki çerçeve de Python 3.10 veya üzeri bir ortam ister ve pip ile kurulur. Model bağlantısı için bir API anahtarı veya yerel sunucu gerekir. Sanal ortam kullanımı şiddetle önerilir; çerçevelerin bağımlılık ağaçları geniştir ve sistem Python’unu kirletmemek akıllıca olur. Kod editörü olarak sıradan bir geliştirme ortamı yeterlidir; çerçeveler kendi arayüzlerini getirmez, çıktılar terminalde veya Jupyter defterlerinde alınır.

CrewAI Kurulumu ve Temel Yapı

1. Sanal ortam oluşturulur ve CrewAI kurulur; kurulum, komut satırı aracını da beraberinde getirir.

python -m venv .venv
source .venv/bin/activate
pip install crewai

2. Proje iskeleti CLI ile oluşturulur.

crewai create crew ilk-ekip

3. Model sağlayıcı bilgileri ortam değişkenleriyle tanımlanır.
4. Ajanlar ve görevler tanımlanıp ekip çalıştırılır.

CrewAI’de üç yapı taşı vardır. Agent sınıfı rolü, hedefi ve arka planı tanımlar; ayrıca hangi araçları kullanacağı belirtilir. Task sınıfı yapılacak işi, beklenen çıktıyı ve hangi ajana atandığını tanımlar. Crew sınıfı ajanları ve görevleri birleştirip yürütür. Rol tanımının kalitesi sonucun kalitesini doğrudan belirler; “deneyimli bir teknik editör” gibi betimlemeli roller, soyut etiketlerden çok daha iyi çalışır. Görev zincirinde bir görevin çıktısı, bağlam olarak sonraki göreve aktarılabilir; araştır-geliştir-denetle düzeni bu zincirle kurulur.

AutoGen Kurulumu ve Temel Yapı

1. Sanal ortamda AgentChat paketi kurulur.

pip install autogen-agentchat

2. Model istemcisi için sağlayıcı paketi eklenir; OpenAI uyumlu uç noktalar için ilgili ek paket kurulur.
3. Ajanlar tanımlanıp bir takım deseniyle çalıştırılır.

AutoGen’in güncel API’sinde AssistantAgent sınıfı, bir model ve sistem istemiyle ajan üretir. RoundRobinGroupChat, ajanları sırayla konuşturur; SelectorGroupChat ise her turda uygun ajani bir yönetici model seçer. Ajanlardan biri, konuşmayı bitirme koşuluyla görevlendirilebilir; böylece diyalog, önceden belirlenen bir hedefe kilitlenir. Örnek desen: bir kod yazar ajan, bir kod inceleyen ajan ve yalnızca “ONAY” diyebilen bir sonlandırıcı ajan; bu üçlü, kendini düzelten bir geliştirme döngüsü kurar.

Model Bağlantısı ve Yerel Modeller

Her iki çerçeve de OpenAI uyumlu API’leri destekler; bu, yerel model sunucularının doğrudan kullanılabilmesini sağlar. Ollama çalışıyorsa taban adres olarak localhost:11434’teki OpenAI uyumlu uç nokta verilir ve model adı belirtilir. vLLM ile daha yüksek verimli sunumlar da aynı yolla bağlanır. Küçük modellerin çoklu ajan düzeninde zorlandığı unutulmamalıdır; ajanlar arası protokolü izleme becerisi, modelin takip yeteneğiyle doğru orantılıdır ve en az 7B-8B sınıfı modeller önerilir.

Rol Tanımlama ve Görev Zinciri Tasarımı

Başarılı bir çoklu ajan sisteminin tasarım ilkeleri iki çerçevede de ortaktır. Rollere belirgin uzmanlık ve sorumluluk verilir; iki ajanın görevi örtüşüyorsa sonuçlar çelişir. Görev zinciri tek yönlü ve net olmalıdır; her görevin beklenen çıktı biçimi tanımlanır. Denetleyici bir rol eklemek kaliteyi belirgin artırır; üreten ajandan bağımsız bir eleştirmen, hata yakalama oranını yükseltir. Ajan sayısı minimumda tutulmalıdır; her ek ajan, koordinasyon maliyeti ve API çağrısı demektir. Karmaşık problemlerde genişleyen desenler kullanılabilir: önce bir planlayıcı ajan alt görevleri listeler, sonra uzman ajanlar bu listeyi işler.

Araçlar ve Yeteneklendirme

Rol tanımları ajanın kimliğini, araçlar ise yeteneklerini belirler. Ajanlara web arama, dosya okuma-yazma, kod çalıştırma gibi araçlar verildiğinde, görevler yalnızca metin üretmenin ötesine geçer: araştırma ajanı gerçek kaynaklardan güncel bilgi toplar, rapor ajanı çıktıyı dosyaya yazar, veri ajanı betik çalıştırıp sayısal sonuç üretir. CrewAI’de araçlar, ajan tanımına araç listesi olarak eklenir; AutoGen’de araç kaydı ve istemci tanımı benzer biçimde ajan yapılandırmasına bağlanır.

Yeteneklendirme, ajan düzeninin gücünü büyütürken hata yüzeyini de büyütür. Her ek araç, ajanın hangi araçla hangi sırada çağrı yapacağına dair karar uzayını genişletir; küçük modeller bu kararlarda sıkıntı yaşar. Bu yüzden araç seti, görev için gerçekten gereken ölçüde tutulmalıdır. Araç çıktılarının biçimi de önemlidir: uzun ve dağınık çıktılar, sonraki ajanın bağlamını doldurur; araç düzeyinde özetleme veya filtreleme, zincirin tümünü verimli kılar. Ayrıca dış kaynaklara bağımlı araçların (web araması gibi) hata durumlarında ne döndüreceği tanımlanmalıdır; başarısız bir araç çağrısının zinciri sessizce bozması, en zor teşhis edilen sorunlardandır.

İzleme, Maliyet ve Değerlendirme

Çoklu ajan sistemleri, tek istekli uygulamalardan katbekat fazla model çağrısı yapar; bir ekip çalıştırması kolayca onlarca istek üretebilir. İzleme bu yüzden tasarımın parçasıdır: CrewAI, görev bazında çıktı ve kullanım bilgisi sunar; AutoGen’de mesaj akışı doğrudan yazdırılabilir. Çalıştırma günlüklerinin kaydedilmesi, hem maliyet denetimi hem hata teşhisi için temel veri kaynağıdır. Token tüketimi ajan bazında ayrıştırıldığında, en pahalı aşama görünür hâle gelir ve optimizasyon hedefi somutlaşır.

Değerlendirme, tek seferlik değil sürekli bir işlemdir. Sistemin çıktıları, sabit bir test görevleri kümesi üzerinde düzenli ölçülmelidir; rol tanımlarında veya akışta yapılan her değişiklik bu ölçümlerle doğrulanır. Ölçütler göreve göre değişir: içerik üretiminde biçim uyumu ve doğruluk, kod görevlerinde test geçişi, araştırma görevlerinde kaynak doğrulaması en temel göstergelerdir. Bir de koordinasyon ölçütü vardır: ajanların birbirini gereksiz yere düzelttiği, aynı noktada döndüğü döngüler, kaliteyi değil maliyeti büyütür; tur sayısı istatistikleri bu tür yapısal bozuklukları erken ele verir. Ölçüm kültürü kurulmuş bir ekipte, çoklu ajan sistemini canlı bir ürüne taşımak, deneme yanılmadan veriye dayalı gelişime dönüşür.

Sürdürülebilir Yapılandırma

Büyüyen sistemlerde ajan ve görev tanımlarının koda gömülü olması bakım yükü yaratır. CrewAI, ajanlar ve görevler için YAML tabanlı yapılandırma sunar; roller, hedefler ve görev tanımları yapılandırma dosyalarına taşınır, kod yalnızca akışı yönetir. Bu ayrım, iş uzmanlarının rol tanımlarını geliştirme sürecine girmeden düzenlemesine imkân verir. AutoGen tarafında yapılandırma, kod içinde biraz daha doğal olsa da model istemcileri ve takım desenleri parametrik tanımlanabilir.

Ortak ilkeler üç başlıkta toplanabilir. Birincisi sürüm kontrolü: yapılandırma dosyaları koda tabi tutulur, değişiklikler geçmişle izlenir. İkincisi ortam ayrımı: geliştirme ortamında ekonomik modeller, üretimde güçlü modeller; model adları yapılandırmadan okunur. Üçüncüsü gizli bilgi yönetimi: API anahtarları asla yapılandırma dosyasına yazılmaz, ortam değişkenlerinden okunur ve dosyalar depoya girilmez. Bu ilkeler uygulandığında çoklu ajan sistemi, tek seferlik bir prototipten sürdürülebilir bir bileşene dönüşür; ekip büyüdükçe ve görev çeşitlendikçe yapı, yeniden yazım yerine genişlemeyle büyür.

Yaygın Hatalar ve İpuçları

En yaygın hata, fazla sayıda ajanla başlamaktır; iki ajanla çalışan bir sistemi önce kurup sonra genişletmek, hata ayıklamayı kolaylaştırır. İkincisi, belirsiz rol tanımlarıdır; ajanlar birbirinin işine karışırsa döngü kurulur ve görev bitmez. AutoGen’de konuşma döngülerinin bitirme koşulu olmadan sonsuza uzaması tipik bir sorundur; sonlandırıcı ajan veya tur sınırı mutlaka tanımlanmalıdır. CrewAI’de görev çıktılarının sonraki göreve doğru aktarılmaması, zincirin kopmasına yol açar.

Maliyet kontrolü için ajan başına token tüketimi izlenmeli, gereksiz tur sayısı sınırlandırılmalıdır. Hata ayıklamada ajanların ara çıktılarının günlüklenmesi, zincirin nerede bozulduğunu gösterir. Jupyter defterlerinde hızlı prototipleme, yapıyı kurmadan önce desenin çalıştığını doğrulamanın en hızlı yoludur. Son olarak, iki çerçevenin de hızla geliştiği dikkate alınarak güncel dokümantasyon takip edilmeli ve sürüm güncellemeleri sanal ortam içinde test edilerek uygulanmalıdır.