CrewAI Nasıl Kullanılır: Çoklu Ajan İş Akışlarına Pratik Bir Rehber
Cesur bir vaat: Eğer projenizi daha hızlı tamamlamak için en iyi takım arkadaşınızı klonlamayı dilediyseniz, size bu hissi yaşatır—planlama yapan, işbirliği yapan ve birlikte iş üreten birden fazla yapay zeka ajanını yöneterek.
Bu pratik, çözüm odaklı rehberde, 'yi tam olarak nasıl kullanacağınızı öğreneceksiniz: çerçeveyi kurmaktan ve ajanları tanımlamaktan, rolleri, araçları, görevleri ve gerçek sonuçlar sunan yapılandırılmış çoklu ajan iş akışlarını oluşturmaya kadar. Araştırma, içerik, veri analizi ve kod üretimi için kalıpları ve ajan çıkmazları, aşırı istem (prompt bloat) ve araç aşırı kullanımını gibi yaygın tuzaklardan nasıl kaçınacağınızı ele alacağız.
Odak noktamız: size kopyala-yapıştır kodları, savaşta test edilmiş en iyi uygulamalar ve uyarlayabileceğiniz birkaç iş akışı planıyla adım adım "bugün deneyin" yolu sunmak. İster pazar araştırmasını otomatikleştiriyor, ister biletlerden bir ürün spesifikasyonu oluşturuyor olun, bu 'yi etkili bir şekilde kullanmaya başlamanız için bir başlangıç noktasıdır.
Nedir (ve Neden Farklıdır)
- CrewAI, her ajanın bir rolü, hedefi, araçları ve kuralları olduğu çoklu ajan sistemleri oluşturmak için bir çerçevedir. Çerçeve daha sonra bu ajanları koordine eder—görevleri devretme, bağlamı paylaşma ve bir çıktıya doğru yineleme.
- Tek bir LLM isteminden farklı olarak, CrewAI yapıyı zorlar: ajanlar açık, görevler modüler, araçlar izinli ve sonuçlar denetlenebilir.
- Karşılığı: gerçek ekiplerin çalışma şeklini yansıtan ayrıştırılmış iş akışları (araştırma → sentez → yazma → kalite güvencesi)—yalnızca daha hızlı, ölçeklenebilir ve tekrarlanabilir.
Hızlı Başlangıç: 10 Dakikada Nasıl Kullanılır
Aşağıda, sizi sıfırdan çalışan çoklu ajan ekibine götürecek minimal bir model bulunmaktadır. Python kullandığınızı varsayacağız.
1) Kurulum ve Ayarlama
pip install crewai langchain-openai python-dotenv
LLM sağlayıcı anahtarlarınızla bir .env dosyası oluşturun:
OPENAI_API_KEY=sk-your-key
# veya yığınınız tarafından desteklenen diğer sağlayıcılar
2) Ajanlarınızı Tanımlayın (Roller + Hedefler + Araçlar)
from crewai import Agent
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)
researcher = Agent(
role="Pazar Araştırmacısı",
goal="Hedef pazar ve rakipler hakkında güvenilir, güncel bilgiler bulun.",
backstory=(
"İddiaları doğrulayan, kaynakları gösteren ve saygın yayınlardan gelen"
"sinyalleri özetleyen çalışkan bir analistsiniz."
),
tools=[], # daha sonra web/arama/kazıyıcı araçları ekleyin
llm=llm
)
strategist = Agent(
role="Ürün Stratejisti",
goal="Araştırmayı net bir konumlandırma ve yol haritası seçeneklerine sentezleyin.",
backstory="Açıklığa, fizibilitiye ve ölçülebilir sonuçlara öncelik veriyorsunuz.",
tools=[],
llm=llm
)
writer = Agent(
role="İçerik Yazarı",
goal="Örnekler ve sonraki adımlarla iyi yapılandırılmış bir özet oluşturun.",
backstory="Özlü, ikna edici İngilizce yazarsınız ve stil kılavuzlarını takip edersiniz.",
tools=[],
llm=llm
)
3) Görevler Oluşturun (Girdiler, Çıktılar ve Kabul Kriterleri)
from crewai import Task
research_task = Task(
description=(
"2025'te ABD KOBİ proje yönetimi yazılımı pazarını araştırın. "
"En iyi rakipleri, fiyatlandırma katmanlarını, ICP'leri ve karşılanmamış üç ihtiyacı belirleyin. "
"3–5 alıntıyla madde işaretleri döndürün."
),
expected_output=(
"Bölümler içeren bir markdown özeti: Pazar Büyüklüğü, Kilit Oyuncular, Fiyatlandırma, ICP'ler, "
"Karşılanmamış İhtiyaçlar, Kaynaklar (bağlantılarla birlikte)."
),
agent=researcher
)
synthesis_task = Task(
description=(
"Araştırma özetini kullanarak, bir konumlandırma ifadesi, 2–3 farklılaştırıcı "
"ve kilometre taşları olan 90 günlük bir yol haritası oluşturun."
),
expected_output="Özlü bir strateji notu (<= 400 kelime).",
agent=strategist
)
writing_task = Task(
description=(
"Strateji notunu halka açık tek sayfalık bir belgeye dönüştürün. Bir başlık, "
"değer önerisi, özellik madde işaretleri ve bir CTA ekleyin."
),
expected_output="Bir açılış sayfası için uygun bir markdown tek sayfalık belge.",
agent=writer
)
4) Ekibi Yönetin (Akış + Bellek)
from crewai import Crew
crew = Crew(
agents=[researcher, strategist, writer],
tasks=[research_task, synthesis_task, writing_task],
process="sequential", # çıktıları sırayla teslim et
verbose=True
)
result = crew.kickoff
print(result)
Bu, ilk çalışan hattınız. Ajanları tanımladınız, görevleri bağladınız ve sıralı bir akış çalıştırdınız. Bunu genişletmek için araçlar (arama, kazıma, kod yürütme), doğrulama adımları ve paralel aşamalar ekleyin.
Projeleri İçin Bir Zihinsel Model
Bir proje yöneticisi gibi düşünün:
- Roller: Kim ne yapar? Araştırmacı, Analist, Mühendis, İncelemeci.
- Kurallar: Hangi standartlar karşılanmalı? Stil kılavuzu, alıntılar, testler.
- Araçlar: Hangi yeteneklere izin verilir? Web araması, vektör DB, Python, API'ler.
- Görevler: Sorunu nasıl parçalara ayırırız? Girdiler, çıktılar, kabul kriterleri.
- Devirler: Ne aktarılır? Artefaktlar, meta veriler, kısıtlamalar.
- Geri Bildirim: Kim doğrular? Bir kalite güvencesi ajanı, döngüde bir insan veya testler.
ile kodunuz bu işletim modelini kodlar.
Gerçek İşler İçin Nasıl Kullanılır: Kanıtlanmış 5 Kalıp
1) Araştırma → Sentez → Taslak Hazırlama (İçerik ve Raporlar)
- Ajanlar: Araştırmacı, Editör, Yazar, Gerçek Denetleyicisi.
- Araçlar: Web araması, kaynak denetleyicisi, stil kılavuzu.
- İpucu: Halüsinasyonları önlemek için alıntıları ve bir "iddialar tablosunu" zorlayın.
fact_checker = Agent(
role="Gerçek Denetleyicisi",
goal="Tüm iddiaları birincil kaynaklara karşı doğrulayın; zayıf alıntıları işaretleyin.",
backstory="Şüpheci, titiz, tarafsız.",
llm=llm
)
qa_task = Task(
description="Tüm olgusal ifadeleri doğrulayın; [DÜZELTME] etiketleriyle satır içi düzeltmeler ekleyin.",
expected_output="Düzeltmelerin bir özetiyle düzeltilmiş bir taslak.",
agent=fact_checker
)
2) Biletlerden Ürün Spesifikasyonu (Mühendislik)
- Ajanlar: Bilet Gruplayıcı, Spesifikasyon Yazarı, İncelemeci, Test Yazarı.
- Araçlar: Sorun izleme API'si, gömme yoluyla kod tabanı bağlamı, birim testi oluşturucu.
- İpucu: Otomatik bir "Tamamlanma Tanımı" kontrol listesi ekleyin.
3) Veri → İçgörü → Anlatı (Analitik)
- Ajanlar: Veri Yöneticisi (Python), Analist, Hikaye Anlatıcısı.
- Araçlar: Pandas, SQL, grafik oluşturma, not defteri yürütme.
- İpucu: Doğrulanabilir analitik için
python yürütmesi olan araç özellikli bir ajan kullanın.
4) Koruma Raylı Kod Üretimi
- Ajanlar: Planlayıcı, Kodlayıcı, Linter, Test Edici, İncelemeci.
- Araçlar: Repo okuma, birim testi çalıştırıcısı, biçimlendirici, güvenlik tarayıcısı.
- İpucu: İncelemecinin doğruluğu kanıtlayan testlere başvurmasını isteyin.
5) Ölçekte Müşteri E-posta Dizileri
- Ajanlar: Segmentleyici, Metin Yazarı, Kişiselleştirici, Kalite Güvencesi.
- Araçlar: CRM API'si, şablonlar, marka tonu kılavuzu.
- İpucu: Bir geri dönme/spam kontrol aracı ekleyin ve A/B varyantlarını zorlayın.
Araç Ekleme: Ajanlara Gerçek Yetenekler Verin
, ajanlar araçları kullanabildiğinde parlar. Örnek: araştırmacıya web araması ve bir URL okuyucu verin.
from langchain_community.tools import DuckDuckGoSearchRun
from langchain_community.document_loaders import WebBaseLoader
search = DuckDuckGoSearchRun
def web_search_tool(query: str):
return search.run(query)
def read_url_tool(url: str):
loader = WebBaseLoader(url)
docs = loader.load
return "\n\n".join([d.page_content[:2000] for d in docs])
researcher.tools = [web_search_tool, read_url_tool]
En iyi uygulamalar:
- En az ayrıcalık: Yalnızca ajanın gerçekten ihtiyaç duyduğu araçları ekleyin.
- Şema disiplini: Araçlar deterministik ve türlenmiş olmalıdır; mümkün olduğunda özlü, yapılandırılmış metin (JSON/Markdown) döndürün.
- Maliyet kontrolü: Araç çıktılarını kısa tutun; devretmeden önce özetleyin.
Başarılı Görevler Tasarlama
İyi tasarlanmış görevler, çoklu ajan sistemlerini ya yapar ya da bozar.
- Açık olun: "X, Y, Z sütunlarına sahip bir markdown tablosu döndürün."
- Kabul kriterlerini tanımlayın: "Birincil kaynaklara bağlanan 3 alıntı içerir."
- Sınırlar belirleyin: Kelime sayıları, zaman sınırları veya adım sınırları kaymayı azaltır.
- Örnekler ekleyin: İstenen çıktı biçiminin mini bir spesifikasyonunu sağlayın.
- Bellek etiketleri ekleyin: Kolay devir için görevler arasında tutarlı başlıklar/anahtarlar kullanın.
Örnek görev şablonu:
Task(
description=(
"Metodoloji, örneklem büyüklüğü ve temel bulgularla birlikte uzaktan çalışma verimliliği üzerine 5 yeni çalışmayı (2023–2025) özetleyin."
"metodoloji, örneklem büyüklüğü ve temel bulgularla."
),
expected_output=(
"Çalışma başına H2 bölümleri, nihai bir karşılaştırma tablosu ve bağlantılar içeren Markdown."
),
agent=researcher
)
Yönetim Modları: Sıralı ve Paralel ve Hibrit
- Sıralı: Güvenilir devirler; daha yavaş ama akıl yürütmesi daha basit.
- Paralel: Birden fazla ajan aynı anda çalışır (örneğin, 3 araştırmacı); daha sonra birleştirin.
- Hibrit: Paralel olarak araştırma yapın → sentez ve kalite güvencesinde bir araya gelin.
Hibrit örnek:
r1 = Agent(role="A Araştırmacısı", goal="Fiyatlandırmaya odaklanın", backstory="", llm=llm)
r2 = Agent(role="B Araştırmacısı", goal="Özelliklere odaklanın", backstory="", llm=llm)
# r1, r2 için paralel görevler; bir takip sentezi görevi çıktılarını birleştirir.
İpucu: Birleştirirken, sentezleyiciden yinelenenleri kaldırmasını, çakışmaları çözmesini ve daha güçlü kaynağı belirtmesini isteyin.
Koruma Rayları ve Kalite Güvencesi: Ajanları Dürüst Tutun
- Hakemler: Açık veto yetkisi olan bir İncelemeci veya Gerçek Denetleyicisi ekleyin.
- Kontrol listeleri: Uyumluluğu (gizlilik, güvenlik, marka tonu) kalite güvencesi ajanının işaretlemesi gereken bir kontrol listesi olarak kodlayın.
- Öz eleştiri: Ajanlardan kısa bir "Neleri kaçırmış olabilirim" bölümü eklemelerini isteyin.
- Determinizm: Kalite güvencesi ajanları için daha düşük sıcaklık kullanın.
qa = Agent(
role="Kalite Güvencesi İncelemecisi",
goal="Çıktıların kabul kriterlerini ve stil kılavuzunu karşıladığından emin olun.",
backstory="Katı ve ukalasınız.",
llm=llm
)
Ajanları İçin İstek Mühendisliği
Ajan istekleriniz mini iş tanımlarıdır. Onları sıkı tutun.
- Rol isteği: Kimsiniz, ne için optimize ediyorsunuz.
- Hedef isteği: İstenen nihai durum.
- Kısıtlamalar: Kelime sayısı, biçim, ton, referanslar.
- Araçlar: Adlar, ne zaman kullanılacağı, ne döndürüleceği.
- Örnekler: 1–2 kısa, gerçekçi örnek.
Parça:
researcher = Agent(
role="Analitik Araştırmacı",
goal=(
"3–5 güvenilir alıntı ve bir risk notuyla kompakt, doğru özetler sunun."
),
backstory=(
"İddiaları doğruluyor, birincil kaynakları tercih ediyor ve belirsizliği işaretliyorsunuz."
),
llm=llm
)
Gözlemlenebilirlik: Ajanların Ne Yaptığını (ve Neden) Görün
Ayrıntılı günlükleri etkinleştirin ve artefaktları kalıcı hale getirin:
- Her görevin isteğini, çıktısını ve araç çağrılarını saklayın.
- Meta verilerle (model, sıcaklık, araçlar) bir çalıştırma manifestosu kaydedin.
- Ara notlar için bir karalama defteri tutun; hata ayıklamaya ve denetimlere yardımcı olur.
Model:
crew = Crew(..., verbose=True, output_log_file="runs/2025-crew.log")
Maliyet, Gecikme ve Güvenilirlik İpuçları
- Toplu işleme: Bağımsız görevleri paralelleştirin; oran sınırlarından kaçınmak için eşzamanlılığı sınırlayın.
- Özetleme: Belirteç çalkantısını azaltmak için ara artefaktları sıkıştırın.
- Önbelleğe alma: Vektör depolarıyla kararlı adımları (örneğin, pazar tanımları) not edin.
- Geri dönüşler: Hatalı aramalar için bir yedek model veya yeniden deneme ilkesi sağlayın.
- Döngüde insan: Yüksek riskli adımlarda isteğe bağlı onay kapıları ekleyin.
Yaygın Tuzaklar (ve Bunları Nasıl Düzeltirsiniz)
- Tuzak: Belirsiz görevler → dolambaçlı çıktılar.
- Düzeltme: Açık kabul kriterleri ve örnekler ekleyin.
- Tuzak: Çok fazla araç → dikkat dağıtma ve maliyet.
- Düzeltme: Yalnızca en az ayrıcalık, göreve özel araçlar.
- Tuzak: Sonsuz döngüler veya aşırı yineleme.
- Düzeltme: Adım/zaman sınırları ve "kriterler karşılanırsa durdur" ifadesi ekleyin.
- Tuzak: Ajanlar arasında bağlam kaybı.
- Düzeltme: Yapılandırılmış devir nesneleri (JSON) ve tutarlı başlıklar kullanın.
- Tuzak: Kalite güvencesi sonradan düşünülür.
- Düzeltme: Kalite güvencesini veto yetkisi olan birinci sınıf bir ajan olarak ele alın.
Uçtan Uca Örnek: Rekabetçi Özet Oluşturucu
Amaç: Hedef bir persona için üç aracı karşılaştıran rekabetçi bir özet oluşturun.
Ajanlar:
- Persona Analisti → acı noktalarını ve yapılması gereken işleri tanımlar.
- Araştırmacı → veri ve alıntılar toplar.
- Sentezleyici → karşılaştırma tablosu ve içgörüler oluşturur.
- Yazar → nihai özeti üretir.
- Kalite Güvencesi → kaynakları ve netliği doğrular.
Şablon:
persona = Agent(role="Persona Analisti", goal="ICP ve JTBD tanımlayın.", llm=llm)
researcher = Agent(role="Araştırmacı", goal="Güvenilir veri toplayın.", llm=llm)
synth = Agent(role="Sentezleyici", goal="Karşılaştırın ve yorumlayın.", llm=llm)
writer = Agent(role="Yazar", goal="Yöneticiye hazır bir özet oluşturun.", llm=llm)
qa = Agent(role="Kalite Güvencesi", goal="İddiaları ve netliği doğrulayın.", llm=llm)
persona_task = Task(description="SaaS'ta RevOps liderleri için ICP ve JTBD tanımlayın.", agent=persona,
expected_output="Madde işaretleri + acı noktaları + başarı ölçütleri.")
research_task = Task(description="3 araç için fiyatlandırma, özellikler ve incelemeler toplayın.", agent=researcher,
expected_output="Tablo + 5 alıntı.")
synth_task = Task(description="Bir karşılaştırma matrisi ve ilk 3 içgörüyü oluşturun.", agent=synth,
expected_output="Markdown tablosu + içgörüler.")
write_task = Task(description="Önerilerle 1 sayfalık bir özet hazırlayın.", agent=writer,
expected_output="Markdown'da yönetici özeti.")
qa_task = Task(description="Doğruluğu ve okunabilirliği kontrol edin; sorunları düzeltin.", agent=qa,
expected_output="Temiz, doğrulanmış özet.")
crew = Crew(agents=[persona, researcher, synth, writer, qa],
tasks=[persona_task, research_task, synth_task, write_task, qa_task],
process="sequential", verbose=True)
print(crew.kickoff)
'yi Ne Zaman Tek Bir İstem Yerine Kullanmalısınız
'yi şu durumlarda kullanın:
- Görev doğal olarak rollere veya aşamalara ayrılır.
- İzlenebilirliğe, kalite güvencesine veya araç kullanımına ihtiyacınız var.
- Tek seferlik değil, yeniden kullanılabilir bir hat oluşturuyorsunuz.
Şu durumlarda tek bir isteğe bağlı kalın:
- Harici araçlar olmadan kısa, öznel bir görevdir.
- Hız, yapıdan daha önemlidir.
Bu Arada: Bir Yapay Zeka Yan Paneliyle Daha Hızlı Taslak Hazırlayın
İçerik araştırmak, ana hatlarını çizmek ve taslaklarını hazırlamak için çoklu ajan iş akışları kullanıyorsanız, Sider.ai gibi bir yapay zeka yan panelinin, sayfaları özetlemek, ana hatlar oluşturmak ve taslakları gerçek zamanlı olarak iyileştirmek için tarayıcınızın ve belgelerinizin yanında bulunabileceğini belirtmekte fayda var. 'nin yönetiminin yerini almaz, ancak içeriği ekibinize geri bağlamadan önce pasajları toplama, bölümleri yeniden yazma veya tonu akla yatkın hale getirme gibi manuel bölümleri hızlandırabilir. Eyleme Geçirilebilir Sonraki Adımlar
- 'yi kurun ve hızlı başlangıç örneğini çalıştırın.
- Gerçek bir iş akışı (araştırma → taslak → kalite güvencesi) seçin ve kodlayın.
- Her seferinde bir araç ekleyin; çıktı kalitesi ve maliyeti üzerindeki etkiyi ölçün.
- Açık kabul kriterleri olan bir kalite güvencesi ajanı tanıtın.
- Hız için hibrit bir yönetim modeline geçin.
Temel Çıkarımlar
- , karmaşık projeleri modüler, çoklu ajan iş akışlarına dönüştürür.
- Başarı, net rollere, net görevlere ve disiplinli araç kullanımına bağlıdır.
- Koruma rayları (kalite güvencesi, kontrol listeleri, sınırlar) maliyetleri düşük ve kaliteyi yüksek tutar.
- Küçük başlayın, ardından paralel araştırma ve hibrit akışlarla ölçeklendirin.
Mini Kontrol Listesi: Nasıl Etkili Kullanılır
- Rolleri, hedefleri ve araçları açıkça tanımlayın.
- Kabul kriterleri ve örneklerle görevler yazın.
- Güvenilirlik için sıralı, hız için hibrit kullanın.
- Erken bir kalite güvencesi ajanı ekleyin; ona veto yetkisi verin.
- Her şeyi günlüğe kaydedin; denetimler için artefaktları saklayın.
- Özetler, önbelleğe alma ve toplu işlemeyle maliyeti optimize edin.
SSS
S1: nedir ve çoklu ajan iş akışları için nasıl kullanırım?
, rolleri, görevleri ve araçları olan birden fazla yapay zeka ajanını yönetmek için bir çerçevedir. Ajanları tanımlayarak, kabul kriterleri olan görevler oluşturarak ve nihai bir çıktı üretmek için devirleri koordine eden bir ekip çalıştırarak kullanırsınız.
S2: CrewAI ajanlarına web araması gibi araçlar nasıl ekleyebilirim?
Bir araca araç fonksiyonları ekleyin ve bunları ne zaman kullanacağını belirtin. Maliyeti kontrol etmek ve devirleri iyileştirmek için çıktıları yapılandırılmış ve kısa tutun (örneğin, JSON veya markdown).
S3: Ne zaman tek bir LLM istemi yerine CrewAI kullanmalıyım?
Bir görev aşamalara ayrıldığında, araç kullanımı veya KG gerektirdiğinde veya tekrarlanabilir işlem hatlarına ihtiyaç duyulduğunda CrewAI kullanın. Yapıya ihtiyaç duymayan hızlı, öznel görevler için tek bir istem kullanın.
S4: CrewAI çıktılarında halüsinasyonları nasıl önleyebilirim?
Vetolama yetkisine sahip bir Gerçek Kontrol veya KG aracısı ekleyin, birincil kaynaklara atıflar isteyin, KG için düşük sıcaklık ayarlayın ve iddia tablosu gibi kabul kriterleri belirtin.
S5: CrewAI, işleri hızlandırmak için görevleri paralel olarak çalıştırabilir mi?
Evet. Bağımsız görevler için paralel ajanlar (örneğin, birden fazla araştırmacı) ve ardından sonuçları birleştirmek için bir sentezleyici görevi kullanın. Hibrit orkestrasyon, hız ve güvenilirliği dengeler.