CrewAI Nasıl Kullanılır? Adım Adım Çok Ajanlı AI Rehberi

Tek bir yapay zeka modeli çoğu göreve yetmez. Araştırma yapmak, içerik üretmek, kod yazmak ve rapor hazırlamak için ayrı ayrı prompt’lar yazmak yerine bunları otomatik bir ekip olarak koordine etmek mümkün. CrewAI tam bunu yapıyor: her birinin rolü, araçları ve hedefi olan birden fazla agent’ı birlikte çalıştırıyor.

Bu rehberde kurulumdan çalışan bir projeye kadar her adımı geçeceğiz.

CrewAI Nedir, Neden Öne Çıkıyor?

CrewAI, çok ajanlı sistemler kurmak için geliştirilmiş açık kaynaklı bir Python framework’ü. Her agent belirli bir rol üstleniyor, araç seti ve hedefiyle donatılıyor; bir orkestrasyon katmanı da bu agent’ların hangi sırada ve nasıl çalışacağını yönetiyor.

Çoklu ajan mimarisinin fikri basit: karmaşık bir görevi parçalara ayır, her parçayı o işe odaklanmış bir agent’a ver. Bir agent araştırma yapıyor, bir diğeri analiz ediyor, üçüncüsü rapor yazıyor. Sorumlulukları böldüğünüzde hata oranı düşüyor ve sonuçlar daha tutarlı çıkıyor.

CrewAI, diğer agent framework’leriyle karşılaştırdığınızda en düşük kurulum eşiğine sahip seçeneklerden biri. Birkaç Python sınıfıyla çalışan bir ekip oluşturabilirsiniz; graph tanımı ya da özel orkestrasyon kodu gerekmez.

Framework 2023’te yayınlandı ve GitHub’da 25 binden fazla yıldız topladı. API tasarımının sade olması ve LangChain araçlarıyla uyumlu çalışması bu ilgiyi açıklıyor.

Kurulum: Python Ortamı Hazırlama

Python 3.10 veya üstü gerekiyor. Sanal ortam kullanın; yoksa bağımlılıklar global ortama dağılır ve sürüm çakışmaları sorun çıkarır.

python -m venv crewai-env
source crewai-env/bin/activate
# Windows için: crewai-env\Scripts\activate

CrewAI ve araç paketini yükleyin:

pip install crewai crewai-tools

Varsayılan LLM olarak OpenAI API kullanıyor. Anthropic Claude veya başka bir sağlayıcıya geçmek isterseniz litellm entegrasyonu mevcut. Başlangıç için OpenAI API anahtarınızı ortama ekleyin:

export OPENAI_API_KEY="sk-..."

Değişkenleri .env dosyasından okumak daha temiz:

OPENAI_API_KEY=sk-...
SERPER_API_KEY=...

from dotenv import load_dotenv
load_dotenv()

Kurulumu doğrulamak için basit bir import testi:

from crewai import Agent, Task, Crew
print("CrewAI kurulu ve hazır")

Hata yoksa bir sonraki adıma geçebilirsiniz. Bağımlılık sorunlarıyla karşılaşırsanız pip install --upgrade crewai ile güncel sürüme geçin; kütüphanenin major sürüm geçişlerinde API değişiklikleri olabiliyor.

İlk Agent ve Task Tanımlama

CrewAI’da iki temel nesne var: Agent ve Task.

Agent, kim olduğunu, ne bildiğini ve nasıl davranacağını tanımlıyor:

from crewai import Agent

researcher = Agent(
    role="Araştırmacı",
    goal="Verilen konu hakkında doğru ve güncel bilgi topla",
    backstory=(
        "Teknoloji ve yapay zeka alanında uzmanlaşmış bir araştırmacısın. "
        "Kaynaklara eleştirel yaklaşır, karşılaştırmalı analiz yaparsın."
    ),
    verbose=True,
    allow_delegation=False,
)

role, goal ve backstory parametreleri agent’ın sistem prompt’unu oluşturuyor. Bu üç alanı ne kadar net yazarsanız o kadar tutarlı davranış alırsınız. backstory kısmını atlayabilirsiniz ama agent davranışı belirgin biçimde daha genel kalıyor.

Task, ne yapılacağını ve kimin yapacağını belirliyor:

from crewai import Task

research_task = Task(
    description=(
        "CrewAI framework'ünün 2026'daki güncel özellikleri hakkında "
        "kapsamlı bir araştırma yap. Öne çıkan özellikler, kullanım alanları "
        "ve bilinen kısıtlamaları listele."
    ),
    expected_output="Madde madde araştırma özeti, en az 5 önemli nokta",
    agent=researcher,
)

expected_output parametresinin önemi büyük. Agent bu çıktı formatını hedef alıyor; belirsiz bırakırsanız sonuçlar tahmin edilemez hale geliyor. “Özet” yerine “5 maddelik özet, her madde 1-2 cümle, Markdown liste formatında” gibi spesifik formatlar çok daha güvenilir sonuç veriyor.

Crew Oluşturma ve Çalıştırma

Agent ve task’larınız hazır olduğunda bunları bir Crew içinde birleştiriyorsunuz:

from crewai import Crew, Process

crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()
print(result)

Process.sequential task’ları sırayla çalıştırıyor; her task tamamlandığında çıktısı bir sonrakine aktarılıyor. Process.hierarchical ise bir yönetici agent yaratarak diğerlerini o koordine ediyor. Çoğu kullanım senaryosunda sequential başlangıç için yeterli.

crew.kickoff() tüm akışı başlatıyor ve son task’ın çıktısını döndürüyor. Verbose modda her agent adımını terminalde canlı takip edebilirsiniz.

Birden fazla agent ve task’ı birleştiren örnek:

writer = Agent(
    role="İçerik Yazarı",
    goal="Araştırma bulgularını okunabilir bir blog yazısına dönüştür",
    backstory="SEO ve teknik içerik konusunda deneyimli bir yazarsın.",
    verbose=True,
)

write_task = Task(
    description="Araştırmacının bulduklarını temel alarak 500 kelimelik bir blog yazısı yaz.",
    expected_output="Başlık, giriş, 3 bölüm ve sonuç içeren blog metni",
    agent=writer,
    context=[research_task],  # önceki task çıktısını bağla
)

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()

context parametresiyle hangi task’ın çıktısının hangi task’a girdi olacağını açıkça belirtebilirsiniz. Belirtmezseniz CrewAI sequential sırada bir öncekinin çıktısını otomatik geçirir; karmaşık ekiplerde açık context bağlaması okunabilirliği artırıyor.

Araç Entegrasyonu: Arama ve Dosya Okuma

Agent’ları gerçek anlamda güçlü kılan araçlar. crewai-tools paketi en yaygın kullanım senaryoları için hazır araçlar içeriyor.

Web araması için SerperDevTool:

from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

researcher = Agent(
    role="Araştırmacı",
    goal="Güncel web kaynaklarından bilgi topla",
    backstory="Çevrimiçi araştırma uzmanısın.",
    tools=[search_tool],
    verbose=True,
)

SerperDevTool için Serper API anahtarı gerekiyor ve .env dosyasına SERPER_API_KEY olarak eklemeniz gerekiyor. Ücretsiz planda aylık 2.500 sorgu var.

Dosya okuma:

from crewai_tools import FileReadTool

file_tool = FileReadTool(file_path="data/rapor.txt")

analyst = Agent(
    role="Veri Analisti",
    goal="Rapordaki verileri analiz et",
    backstory="Veri analizi konusunda uzman bir analistsn.",
    tools=[file_tool],
    verbose=True,
)

Özel araç yazmak da mümkün. BaseTool sınıfından türeterek kendi iş mantığınızı bir agent aracına dönüştürebilirsiniz:

from crewai.tools import BaseTool

class VeritabaniSorgulaTool(BaseTool):
    name: str = "veritabani_sorgula"
    description: str = "Şirket veritabanından müşteri bilgisi çeker"

    def _run(self, musteri_id: str) -> str:
        # gerçek uygulamada DB sorgusu
        return f"Müşteri {musteri_id}: Ad Soyad, durum: aktif"

CrewAI, LangChain araçlarını da doğrudan kabul ediyor. LangChain ekosisteminde mevcut araçlarınız varsa bunları tools listesine geçmek yeterli.

Gerçek Proje: İçerik Araştırma Ekibi

Buraya kadar öğrendiklerimizi bir araya getirelim. Hedef: konu girişi verildiğinde araştıran, analiz eden ve özet çıkaran üç ajanlı bir ekip.

import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool

load_dotenv()

search_tool = SerperDevTool()

# --- Agent'lar ---

researcher = Agent(
    role="Kıdemli Araştırmacı",
    goal="Verilen konu hakkında kapsamlı ve doğru bilgi topla",
    backstory=(
        "Teknoloji alanında uzman bir araştırmacısın. "
        "Birden fazla kaynağı karşılaştırır, tutarsızlıkları fark edersin."
    ),
    tools=[search_tool],
    verbose=True,
    allow_delegation=False,
    max_iter=10,
)

analyst = Agent(
    role="İçerik Analisti",
    goal="Araştırma bulgularını değerlendir ve önemli trendleri çıkar",
    backstory=(
        "Teknik içeriği hedef kitleye göre analiz etme konusunda uzman "
        "bir analistsn. Bilgileri önem sırasına göre düzenlersin."
    ),
    verbose=True,
    allow_delegation=False,
)

writer = Agent(
    role="Teknik Yazar",
    goal="Analiz bulgularını açık ve anlaşılır bir özete dönüştür",
    backstory=(
        "Karmaşık teknik konuları geniş bir kitleye aktaran deneyimli "
        "bir yazarsın. Kod örnekleri ve pratik tavsiyeler öne çıkarırsın."
    ),
    verbose=True,
    allow_delegation=False,
)

# --- Task'lar ---

research_task = Task(
    description=(
        "'{topic}' konusunda kapsamlı araştırma yap. "
        "Son 6 aydaki gelişmeleri dahil et. "
        "Her bulgu için kaynağı belirt."
    ),
    expected_output="5-7 maddelik araştırma özeti, her madde en az 2 cümle",
    agent=researcher,
)

analysis_task = Task(
    description=(
        "Araştırmacının bulgularını değerlendir. "
        "En önemli 3 trendi ve pratik uygulamalarını belirle."
    ),
    expected_output=(
        "Trend analizi: her trend için başlık, açıklama, "
        "kullanım senaryosu ve dikkat edilmesi gereken bir nokta"
    ),
    agent=analyst,
    context=[research_task],
)

writing_task = Task(
    description=(
        "Araştırma ve analiz bulgularını 600-800 kelimelik bir özete dönüştür. "
        "Teknik detayları korurken anlaşılır bir dil kullan. "
        "Sonunda 3 maddelik pratik öneri ekle."
    ),
    expected_output=(
        "Yapılandırılmış özet: giriş paragrafı, 3 ana bölüm, "
        "sonuç ve öneriler listesi"
    ),
    agent=writer,
    context=[research_task, analysis_task],
)

# --- Crew ---

crew = Crew(
    agents=[researcher, analyst, writer],
    tasks=[research_task, analysis_task, writing_task],
    process=Process.sequential,
    verbose=True,
)

# Çalıştır
result = crew.kickoff(inputs={"topic": "CrewAI 2026 güncel özellikler"})
print(result)

inputs parametresiyle task açıklamalarındaki {topic} gibi değişkenlere çalışma zamanında veri geçirebilirsiniz. Aynı crew yapısını farklı konular için defalarca çalıştırmanızı sağlıyor.

Ekibi genişletmek için yeni agent ve task ekleyip agents ve tasks listelerini güncellemek yeterli. CrewAI task sırasını listede belirttiğiniz gibi koruyor.

CrewAI vs LangGraph: Hangisini Seç?

LangGraph ile CrewAI çoğu zaman aynı kategoride değerlendiriliyor; ama farklı problemleri çözüyorlar ve farklı ekipler için uygunlar. Daha kapsamlı bir karşılaştırma için agent framework karşılaştırma yazımıza bakabilirsiniz.

Pratik karar için iki soru sorun:

CrewAI tercih edin:

• Görevi net rollere bölebiliyorsanız
• Sequential veya basit hiyerarşik akış yeterliyse
• Hızlı prototip gereken bir durumda
• Ekipte LangGraph deneyimi yoksa

LangGraph tercih edin:

• İş akışında döngü veya koşullu geri bildirim varsa
• Her adımda durum takibi gerekiyorsa
• Üretim sisteminde tam kontrol öncelikli

Karar sürecinde sıfırdan agent yapmak yazısı da yol gösterici olabilir; orada temel agent bileşenlerinin framework bağımsız nasıl çalıştığını görebilirsiniz.

Yaygın Hatalar ve Çözümleri

Agent sonsuz döngüye giriyor

Araç çağrısı başarısız olduğunda bazı modeller aynı çağrıyı tekrarlıyor. max_iter ile iterasyon sınırı koyun:

agent = Agent(
    role="...",
    goal="...",
    backstory="...",
    max_iter=8,  # varsayılan 25
)

Task çıktısı her seferinde farklı geliyor

expected_output belirsiz yazılmış olabilir. Beklenen formatı detaylı tanımlayın:

# Kötü
expected_output="Özet"

# İyi
expected_output=(
    "5 maddelik özet. Her madde: başlık (3-5 kelime) + "
    "açıklama (2-3 cümle). Markdown liste formatı."
)

Token limiti çok hızlı dolup taşıyor

Araştırma task’larında context hızla büyüyebiliyor. Uzun task zincirlerinde aralara özet task’lar ekleyin:

summarize_task = Task(
    description="Araştırma çıktısını 300 kelimeyle özetle, anahtar bulguları koru",
    expected_output="Kısa özet, 300 kelime altı",
    agent=researcher,
    context=[research_task],
)

Araç izin veya API hataları

SerperDevTool ve benzeri araçlar API anahtarlarını ortam değişkenlerinden okuyor. .env dosyasının proje kök dizininde olduğunu ve load_dotenv() çağrısının import’lardan sonra geldiğini kontrol edin.

Verbose çıktı üretimde gereksiz

Geliştirme bittikten sonra verbose=False yapın. Gerekirse özel bir logger kurabilirsiniz:

import logging
logging.basicConfig(level=logging.WARNING)
# crewai loglarını susturmak için
logging.getLogger("crewai").setLevel(logging.ERROR)

CrewAI kurulumu hızlı ama tutarlı sonuç almak için agent rolleri ile expected_output parametrelerini iterasyonla geliştirmeniz gerekiyor. İlk çalıştırmada beklediğiniz çıktıyı alamazsanız backstory ve beklenen çıktı tanımlarını düzenlemek en hızlı iyileştirme yolu. LangChain ekosisteminiz zaten kuruluysa mevcut araçlarınızı CrewAI’a taşımak birkaç satır değişiklik istiyor.