AI Agent Geliştirme: Sıfırdan Otonom Ajan Tasarlamak

Yapay zeka dünyasında son iki yılın en çok konuşulan kavramı kuşkusuz AI agent'lar. Bir LLM'e soru sorup yanıt almaktan ibaret olan klasik kullanımın ötesine geçerek, modelin kendi kararlarını verdiği, araçları çağırdığı ve uzun vadeli hedeflere doğru ilerlediği sistemler inşa etmek artık mümkün.

Bu yazıda sıfırdan bir AI agent'ın nasıl tasarlanacağını, nelere dikkat edilmesi gerektiğini ve üretim ortamındaki zorluklarla nasıl başa çıkılacağını ele alacağız.

Agent Nedir?

En basit tanımıyla bir AI agent, bir hedefe ulaşmak için araçları kullanabilen, hafızaya sahip ve döngüsel çalışan bir sistemdir.

Kullanıcı hedefi
      ↓
  [ LLM Düşünür ]
      ↓
  Araç çağrısı?
   ↙        ↘
 Evet        Hayır → Yanıt üret
  ↓
Aracı çalıştır
  ↓
Sonucu LLM'e geri ver
  ↓
  (döngü)

Bu döngüye ReAct (Reasoning + Acting) denir ve modern agent framework'lerinin büyük çoğunluğu bu örüntü üzerine kuruludur.

Temel Bileşenler

1. Beyin — LLM

Agent'ın tüm kararları bir dil modeli tarafından verilir. Model seçimi kritiktir:

Model	Güçlü Yönü	Zayıf Yönü
GPT-4o	Genel yetenek, araç çağrısı	Maliyet
Claude 3.5 Sonnet	Uzun bağlam, kod	API limitleri
Gemini 2.0 Flash	Hız, multimodal	Tutarsızlık
Llama 3.3 70B	Açık kaynak, özelleştirme	Altyapı maliyeti

2. Araçlar (Tools)

Araçlar, LLM'in dış dünyayla etkileşime girebildiği kapılardır. Her araç bir JSON şemasıyla tanımlanır:

tools = [
    {
        "name": "web_search",
        "description": "İnternette arama yapar ve sonuçları döndürür.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Arama sorgusu"
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maksimum sonuç sayısı",
                    "default": 5
                }
            },
            "required": ["query"]
        }
    }
]

3. Hafıza (Memory)

Agent'lar üç tür hafıza kullanır:

• Kısa vadeli (In-context): Mevcut konuşma geçmişi. Bağlam penceresine sığar, oturum bitince silinir.
• Uzun vadeli (Vector store): Geçmiş deneyimler embedding olarak saklanır. Semantic search ile geri çağrılır.
• Prosedürel: Agent'ın öğrendiği örüntüler ve tercihler. Fine-tuning veya system prompt ile kodlanır.

4. Orkestrasyon Katmanı

Döngüyü yöneten, araç çağrılarını tetikleyen ve hataları ele alan kod:

import anthropic

client = anthropic.Anthropic()

def run_agent(user_message: str, max_iterations: int = 10) -> str:
    messages = [{"role": "user", "content": user_message}]
    
    for iteration in range(max_iterations):
        response = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=4096,
            tools=tools,
            messages=messages,
        )
        
        # Model yanıt ürettiyse döngüyü bitir
        if response.stop_reason == "end_turn":
            return extract_text(response)
        
        # Araç çağrısı varsa işle
        if response.stop_reason == "tool_use":
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": str(result),
                    })
            
            # Konuşma geçmişini güncelle
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
    
    return "Maksimum iterasyon sayısına ulaşıldı."

Üretim Ortamının Zorlukları

Güvenilirlik

LLM'ler deterministik değildir. Aynı girdi farklı çıktılar üretebilir. Bu nedenle:

import tenacity

@tenacity.retry(
    stop=tenacity.stop_after_attempt(3),
    wait=tenacity.wait_exponential(multiplier=1, min=2, max=10),
    retry=tenacity.retry_if_exception_type(anthropic.APIError),
)
def safe_llm_call(messages):
    return client.messages.create(...)

Maliyet Kontrolü

Her iterasyon token tüketir. Uzun döngüler pahalıya patlar. Önlemler:

• max_iterations sınırı koy
• Araç çıktılarını özetle, ham veriyi direkt LLM'e verme
• Küçük görevler için ucuz modele yönlendir (routing)

Gözlemlenebilirlik

Agent ne yapıyor? Nerede takıldı? Neden yanlış karar verdi? Bunları görmek için:

import langsmith  # veya Langfuse, Helicone, ...

with langsmith.trace("agent_run", metadata={"user_id": user_id}):
    result = run_agent(user_message)

Her araç çağrısını, LLM düşüncesini ve geçen süreyi kayıt altına alın.

Mimari Örüntüler

Tek Agent

Basit görevler için yeterli. Bir LLM, birkaç araç, düz döngü.

Multi-Agent (Çok Ajanlı)

Karmaşık görevleri paralel veya hiyerarşik olarak çözer:

Orchestrator Agent
    ├── Research Agent  → web arama, kaynak özetleme
    ├── Code Agent      → kod yazma, test çalıştırma
    └── Writer Agent    → taslak oluşturma, düzenleme

Bu yaklaşımda her alt agent kendi araç setine ve sistem promptuna sahiptir. Orchestrator görevi parçalar, delegasyonu yapar ve sonuçları birleştirir.

Human-in-the-Loop

Kritik adımlarda insan onayı:

def execute_tool(name: str, params: dict):
    if name in HIGH_RISK_TOOLS:
        confirmed = ask_human_approval(name, params)
        if not confirmed:
            return "İşlem kullanıcı tarafından iptal edildi."
    return TOOL_MAP[name](**params)

Framework Seçimi

Kendi orkestrasyon katmanınızı yazmak yerine hazır araçlar kullanabilirsiniz:

• LangChain / LangGraph — En yaygın, zengin ekosistem, bazen aşırı soyutlama
• CrewAI — Multi-agent için optimize, role-based tasarım
• AutoGen — Microsoft'tan, konuşmacı agent'lar
• Smolagents — HuggingFace'ten, minimal ve anlaşılır kod

Ancak üretim sistemleri için çoğu zaman minimal custom implementasyon en iyi seçimdir. Framework bağımlılığı, debugging'i zorlaştırır ve versiyon kırılmalarına açık kapı bırakır.

Başlangıç İçin Tavsiyeler

1. Küçük başla: Tek araçlı, tek döngülü bir agent yaz. Çalıştır, gözlemle.
2. Sistem promptuna yatırım yap: Agent'ın davranışının %70'i burada şekillenir.
3. Eval pipeline kur: Otomatik testler olmadan agent kalitesini ölçemezsin.
4. Araç hatalarını iyi ele al: LLM yanlış parametrelerle araç çağırabilir. Sağlam error handling şart.
5. Bağlamı yönet: Konuşma uzadıkça maliyet ve hata oranı artar. Özetleme veya sliding window uygula.

AI agent geliştirme hâlâ hızla evrilen bir alan. Bugün "en iyi pratik" sayılan yaklaşım yarın değişebilir — ama temel döngüyü ve bileşenleri anladıktan sonra yeni araçlara adapte olmak çok daha kolay.

İyi kodlamalar.