Yapay Zeka Ajanınız Neden Başarısız? Seviye 0'dan Seviye 7'ye Ajan Mimarisi

Gerçek Yapay Zeka Ajanları (Agents) Nasıl Tasarlanır?

"Persona"lardan Araç Kullanan (Tool-Using) Karar Mekanizmalarına Geçiş
Seviye 0'dan Seviye 7'ye adım adım senior düzeyde AI Engineer rehberi.

Yayınlanma: Haziran 2026  |  Okuma süresi: ~25 dk  |  Kategori: Yapay Zeka Mühendisliği

🎯 Giriş: Neden "Sen Dünyanın En İyi YZ Mühendisisin" Yetersizdir?

İnternetteki eğitimlerin %90'ı size bir ajan yaratmak için şunu yazmanızı söyler:

"Sen dünyanın en iyi yazılım mühendisisin..."

Eğer production'a, yani canlıya bir uygulama çıkacaksanız, sadece persona vererek yazdığınız promptlar sisteminizi bir halüsinasyon bombasına çevirir.

Agent'ların asıl gücü onlara verdiğiniz rollerdan değil; Tool Kullanımı (Araç Kullanımı), Grounding (Temellendirme) ve Açıklanabilirlik (Explainability)'dir.

💡 Bu Yazıda Ne Öğreneceksiniz?

Bu yazıda basit bir problem olan "iki metnin benzerliğini ölçme" görevini alacağız ve acemi bir yaklaşımdan, senior bir YZ mühendisinin tasarlayacağı otonom seviyeye kadar adım adım nasıl geliştireceğimizi göreceğiz. Her seviyede prompt, mimari ve maliyet karşılaştırması yapacağız.

🎬 Video ile Öğrenin: Murat Karakaya Akademi

Bu eğitimi Murat Karakaya Akademi YouTube kanalında da izleyebilirsiniz. Adım adım canlı demo, kod açıklaması ve mimari analiz ile Seviye 0'dan Seviye 7'ye aynı yolculuğu video olarak da takip edebilirsiniz.

▶ YouTube'da İzle — Murat Karakaya Akademi

📌 Seviye 0 — Acemi Yaklaşım: Kara Kutu & Halüsinasyon

Başlangıç

Senaryo: Uygulamamızda üretilen Metin 1 ile Metin 2'nin ne kadar benzer olduğunu 0–100 arasında bulmamız gerekiyor. (Örneğin bir RAG sisteminde, üretilen cevabın referans metne ne kadar sadık olduğunu ölçüyoruz).

Acemi Prompt:
"Sen bir metin analistisin. Sana verilen Metin 1 ve Metin 2'yi karşılaştırıp ne kadar benzer olduklarına karar ver. Benzerliği 0–100 arasında bir sayısal değer ile döndür. 0: Hiç benzemiyorlar, 100: Tamamen kelime kelime aynılar."

Neden Kötü?

1. Kara Kutu (Black Box): Model sadece "75" döndürdü. Neden 75? 74 veya 80 değil? Bilmiyoruz.
2. Subjektiflik: Aynı metinlere bir gün 60, ertesi gün 85 verebilir.
3. Halüsinasyon Riski: LLM'ler matematiksel ölçüm yapamaz; kelime tahmin eder. "75" uydurulmuş bir değerdir.

📌 Seviye 1 — Yapılandırılmış Çıktı & Düşünce Zinciri

İyileştirme

İstediğimiz ilk şey Açıklanabilirlik (Explainability). Modele "bana sadece sonuç verme, düşünme sürecini de ver" diyoruz.

"Sen bir metin analistisin. Amacın iki metnin anlamsal benzerliğini ölçmektir. Çıktını KESİNLİKLE geçerli bir JSON object olarak vermelisin. Markdown veya ek metin kullanma. Zorunlu JSON alanları: - reasoning: Bu iki metne özel benzerlik ve farklılık gerekçesi. - similarity_score: 0-100 arası bir tam sayı. Beklenen JSON şeması: { "type": "object", "required": ["reasoning", "similarity_score"], "properties": { "reasoning": {"type": "string"}, "similarity_score": {"type": "integer", "minimum": 0, "maximum": 100} } }"

Neden Daha İyi?

• Chain of Thought (Düşünce Zinciri): Modelden önce skoru istemedik. Önce reasoning alanını doldurmasını istedik. Model açıklamayı yazarken kendi çıkarımını temellendirir.
• Hata Ayıklama (Debugging): Skor 40 geldiğinde, "Model şu detayı kaçırmış, o yüzden düşük vermiş" diyebiliriz.
• Entegrasyon: JSON çıktısı uygulama kodu tarafından parse edilebilir.

⚠️ Eksik Kalan: Skor hâlâ subjektif. 0–100 arası skala bir LLM için çok geniştir ve kuralsızdır.

📌 Seviye 2 — Rubrik ve Objektivite (Divide & Conquer)

Özerklik Artışı

Agent'ın "benzerlik" gibi soyut bir kavramı kendi başına yorumlamasına izin vermiyoruz. Ona kurallar (rubrik) veriyoruz. Problemi parçalara bölüyoruz.

Rubrik:

• 1. Ana Fikir (0-20): İki metin aynı ana mesajı mı veriyor?
• 2. Ton ve Üslup (0-20): İki metnin resmiyeti ve duygusu aynı mı?
• 3. Varlıklar / Entities (0-20): Metinlerde geçen isimler, tarihler, sayılar eşleşiyor mu?
• 4. Eksik Bilgi (0-20): Metin 2, Metin 1'deki önemli bir detayı atlamış mı?
• 5. Akıcılık (0-20): Metin 2 yapısal olarak ne kadar tutarlı?

"Sen uzman bir değerlendiricisin. İki metni yukarıdaki 5 kritere göre değerlendir. Her kriter 0-20 puan arasındadır. Çıktını KESİNLİKLE geçerli bir JSON object olarak üret. Zorunlu JSON alanları: - evaluations: 5 öğeli liste [criterion, score, explanation] - total_score: Beş kriter skorunun toplamı. Beklenen JSON şeması: { "type": "object", "required": ["evaluations", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }"

Neden Daha İyi?

• Grounding (Temellendirme): Modeli soyut 100 üzerinden değerlendirmeden kurtardık.
• Objektiflik: Farklı zamanlarda çalıştırsanız bile skorlar çok daha tutarlı olur (varyans azalır).
• Karşılaştırılabilirlik: Farklı promptları aynı rubrik üzerinden değerlendirebiliriz.

📌 Seviye 3 — Örnekli Rubrik Kalibrasyonu (One-Shot / Few-Shot)

Kalibrasyon

Seviye 2'de rubrik verdik; fakat bu hâlâ sıfır-örnekli prompting (zero-shot prompting) idi. Model kriterleri okudu ama "20 puan ne zaman verilir?", "10 puan hangi sınır durumu?" gibi karar sınırlarını örneklerden görmedi.

Bu seviyede her kriter için küçük ve temsil gücü yüksek örnekler veriyoruz.

Puanlama Kalibrasyonu Örnekleri:

• Ana Fikir — 20 puan: "Veri temizliği model başarısı için kritiktir" ve "Model kalitesi büyük ölçüde temiz veriye bağlıdır" aynı ana fikri verir.
• Ana Fikir — 10 puan: İki metin de veri kalitesinden söz eder ama biri güvenlik risklerine, diğeri model performansına odaklanır.
• Ana Fikir — 0 puan: Biri veri temizliğini, diğeri spor müsabakası sonucunu anlatır.
• Ton ve Üslup — 20 puan: İki metin de akademik ve resmi bir dille yazılmıştır.
• Ton ve Üslup — 10 puan: Biri resmi, diğeri daha konuşma dilindedir ama anlam korunmuştur.

Neden Daha İyi?

• Tutarlılık: Model aynı puan aralıklarını daha kararlı kullanır.
• Öğretilebilirlik: Rubrik artık yalnızca soyut bir liste değil, davranış örnekleriyle desteklenmiştir.
• Maliyet: Few-shot örnekler giriş tokenını artırır — bu yüzden örnekler kısa ve net seçilir.

Beklenen JSON şeması:

{ "type": "object", "required": ["evaluations", "calibration_note", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Seviye 4 — Araç Kullanımı (Tool Calling) ve İş Akışı (Workflow)

Temellendirme Başlıyor

Seviye 3'te rubriği örneklerle kalibre ettik; fakat değerlendirme hâlâ yalnızca LLM yorumuna dayanıyor. Şimdi dış sistemlerden gelen deterministik metrikleri kanıt olarak ekliyoruz.

Kullanılan Metrikler:

• ROUGE-L F1: Kelime dizisi örtüşmesini ölçer.
• Hafif Benzerlik Skoru: Token cosine + Token Jaccard + Karakter 3-gram cosine + Sequence ratio birleşimi.

Metrik Yorumlama Kuralları:

• ROUGE-L F1 düşükse kelime örtüşmesinin düşük olduğunu gösterir; tek başına düşük anlamsal benzerlik kanıtı değildir.
• Hafif Benzerlik Skoru ROUGE-L'ye göre daha yüksekse, metinler farklı kelimelerle benzer mesaj veriyor olabilir.
• Hafif Benzerlik Skoru gerçek semantik embedding değildir; karar destek sinyali olarak kullanılmalı, tek karar verici yapılmamalıdır.

🌍 Gerçek Dünyada Neden Bu Kullanılır?

• Güvenilirlik: ROUGE ve hafif benzerlik skorları deterministiktir — aynı metin çiftine her zaman aynı skorları verir.
• İzlenebilirlik: LLM yorumu dış kanıta dayandığı için değerlendirme daha denetlenebilir olur.
• Maliyet Kontrolü: Hafif metrikler hızlıdır ve ağır model bağımlılığı gerektirmez.

🔬 Deney Hijyeni Notu

Seviye 4, Seviye 3 ile aynı rubrik metnini kullanır. Bu bilinçli bir karar: iki seviye arasındaki fark rubrik değişikliği değil, yalnızca dış metrik bağlamıdır.

Seviye 4'te eklenen Zorunlu JSON alanları:

• metric_interpretation: ROUGE-L F1 ve Hafif Benzerlik Skoru değerlerini nasıl yorumladığını açıkla.
• calibration_note: Rubrik kalibrasyon örneklerinin puanlamanı nasıl etkilediğini açıkla.

Beklenen JSON şeması (Seviye 4):

{ "type": "object", "required": ["evaluations", "metric_interpretation", "calibration_note", "total_score"], "properties": { "evaluations": { /* Seviye 3 ile aynı 5 öğeli liste */ }, "metric_interpretation": {"type": "string"}, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Seviye 5 — ReAct ve Ollama Tool Calling ile Gerçek Ajan Döngüsü

Gerçek Agentic Loop

Seviye 4'te güçlü bir iş akışı kurduk ama kurduğumuz sistem gerçek bir ajan mıydı? Tam olarak hayır. Çünkü metrikleri Python ile biz hesapladık. Gerçek ajan davranışında model hangi kanıta ihtiyaç duyduğunu belirler, yazılım katmanı aracı çalıştırır ve sonuç tekrar modele döner.

ReAct Döngüsü:

• Reasoning (Muhakeme): Model hangi dış kanıta ihtiyaç duyduğunu belirler.
• Action (Eylem): Model düz metin yazmak yerine Ollama'nın native tool_calls alanını üretir.
• Observation (Gözlem): Python ilgili fonksiyonu çalıştırır, sonucu role="tool" olarak modele geri verir.
• Final Answer (Nihai Cevap): Model tool sonuçlarını kullanarak rubrik temelli JSON değerlendirmesini üretir.

Ollama Native Tool Calling Akışı:

1. Fonksiyonlar `tools=[...]` listesiyle modele tanıtılır. 2. Model gerekiyorsa `response.message.tool_calls` üretir. 3. Python bu tool call'ları çalıştırır. 4. Sonuçlar `role="tool"` mesajları olarak konuşmaya eklenir. 5. Model tool sonuçlarına dayanarak nihai cevabı üretir.

Tool Tanımları (Python):

def calculate_rouge_tool(reference_text: str = "", candidate_text: str = "") -> str: """ROUGE skorlarını hesapla.""" return json.dumps(calculate_rouge(METIN_1, METIN_2), ensure_ascii=False) def calculate_lightweight_similarity_tool(reference_text: str = "", candidate_text: str = "") -> str: """Notebook'taki sabit Metin 1 ve Metin 2 için hafif benzerlik skorunu hesapla. Args: reference_text: Eğitim demosunda dikkate alınmaz; tool sabit METIN_1 kullanır. candidate_text: Eğitim demosunda dikkate alınmaz; tool sabit METIN_2 kullanır. Returns: Token cosine, token Jaccard, karakter 3-gram cosine, sequence ratio ve birleşik skoru içeren JSON string. """ return json.dumps(calculate_lightweight_similarity(METIN_1, METIN_2), ensure_ascii=False)

Tool Calling Loop (Pseudo-Python):

messages = [ {"role": "system", "content": TOOL_CALLING_SYSTEM_PROMPT}, {"role": "user", "content": "Metin 1: ..., Metin 2: ..."}, ] while True: response = client.chat( model=MODEL, messages=messages, tools=[calculate_rouge_tool, calculate_lightweight_similarity_tool], ) messages.append(response.message) if not response.message.tool_calls: print(response.message.content) # Final cevap break for tool_call in response.message.tool_calls: tool_name = tool_call.function.name result = available_tools[tool_name](**tool_call.function.arguments) messages.append({ "role": "tool", "tool_name": tool_name, "content": str(result), })

Neden Bu Ustalık Sınıfıdır?

• ReAct yalnızca Thought / Action / Observation yazdırmak değildir; düşünceyi gerçek araç yürütmeye bağlamaktır.
• Ajan; prompt, tool calling, execution loop, grounding ve hata kontrolü katmanlarının birlikte tasarlanmasıdır.
• Model araç ihtiyacını belirler, Python aracı gerçekten çalıştırır, nihai değerlendirme dış kanıtla desteklenir.

📊 Seviye 5 Token Maliyeti:

"Seviye 5 çok turlu (multi-turn) bir ajan loop'u olduğu için giriş tokenı (input token), yalnızca ilk kullanıcı promptunun uzunluğu değildir. Her client.chat çağrısında sistem mesajı, kullanıcı mesajı, önceki asistan mesajları ve tool sonuçları yeniden bağlama girer. Bu nedenle Seviye 5'teki input token toplamı, tekil token sayısı değil, kümülatif işlenen token / maliyet göstergesidir."

🛡️ Gerçek Dünyada: Üretim Ortamı Koruma Katmanları

Gerçek üretimde şu korumalar eklenir: şema doğrulama (schema validation), maksimum adım sayısı (max step limit), tool izin listesi (tool allowlist), yeniden deneme (retry) ve izleme/günlükleme (tracing/logging).

Seviye 5 Tool Calling JSON şeması:

{ "type": "object", "required": ["evaluations", "metric_interpretation", "calibration_note", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "metric_interpretation": {"type": "string"}, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Seviye 6 — Rubrik Bazlı Sub-Agentlar ve Python Aggregator

Modüler Mimarisi

Seviye 5'te tek bir ajan hem araç çağırdı hem de bütün rubriği tek başına yorumladı. Bu seviyede farklı bir mimari deniyoruz: tek büyük prompt yerine, her rubrik kriterini ayrı bir alt ajana (sub-agent) veriyoruz.

Mimari:

• 1 generic sub-agent fonksiyonu yazılır.
• Bu fonksiyon 5 farklı rubrik konfigürasyonu ile 5 kez çağrılır.
• Her sub-agent yalnızca kendi kriterini değerlendirir.
• Python aggregator sonuçları doğrular, sıraya koyar ve toplam skoru hesaplar.
• Aggregator LLM çağrısı yapmaz — deterministiktir.

Bu Seviyenin Pedagojik Mesajı:

✅ "Her şeyi agent yapmayın!"
LLM yorumsal değerlendirme içindir. Python doğrulama, toplama, formatlama ve deterministik hesaplama içindir.

Sınırları:

• 5 sub-agent = 5 LLM çağrısı = Seviye 5'ten daha pahalı.
• Her durumda gerekli değildir; rubrik büyüdüğünde veya denetlenebilirlik kritik olduğunda anlam kazanır.

Seviye 6 - Sub-Agent JSON Çıktısı (tek kriter için):

{ "criterion": "Ana Fikir", "score": 18, "explanation": "Bu kritere özel değerlendirme", "evidence": "Metinden veya metriklerden dayanak" }

Python Aggregator Toplam Çıktısı (tüm kriterler):

{ "evaluations": [ {"criterion": "Ana Fikir", "score": 18, "explanation": "...", "evidence": "..."}, {"criterion": "Ton ve Üslup", "score": 16, "explanation": "...", "evidence": "..."}, {"criterion": "Varlıklar", "score": 17, "explanation": "...", "evidence": "..."}, {"criterion": "Eksik Bilgi", "score": 15, "explanation": "...", "evidence": "..."}, {"criterion": "Akıcılık", "score": 14, "explanation": "...", "evidence": "..."} ], "metric_interpretation": "ROUGE ve hafif benzerlik metrikleri her sub-agent'a bağlam olarak verildi; her kriter kendi uzman alt ajanı tarafından yorumlandı.", "aggregation_note": "Toplam skor Python aggregator tarafından deterministik olarak hesaplandı; LLM orchestrator kullanılmadı.", "total_score": 80 }

Seviye 6 Python aggregator fonksiyon örneği:

def aggregate_sub_agent_results(sub_agent_results, metrics_context): expected_criteria = [config['criterion'] for config in RUBRIC_AGENT_CONFIGS] actual_criteria = [result['parsed'].get('criterion') for result in sub_agent_results] if actual_criteria != expected_criteria: raise ValueError(f"Sub-agent kriter sırası beklenenle aynı değil.") evaluations = [] for result in sub_agent_results: parsed = result['parsed'] score = parsed.get('score') if not isinstance(score, int) or not 0 <= score <= 20: raise ValueError(f"Geçersiz score: {parsed}") evaluations.append({ 'criterion': parsed['criterion'], 'score': score, 'explanation': parsed['explanation'], 'evidence': parsed['evidence'], }) total_score = sum(item['score'] for item in evaluations) return { 'evaluations': evaluations, 'metric_interpretation': '...', 'aggregation_note': 'Toplam skor Python ile deterministik olarak hesaplandı.', 'total_score': total_score, }

Seviye 6 — Token Maliyeti:

• 5 sub-agent = 5 bağımsız LLM çağrısı
• Her çağrı sistem promptu + kullanıcı promptu + metrik bağlamını içerir
• Toplam input token = 5 × (sistem + kullanıcı promptu uzunluğu)
• Aggregator token maliyeti = 0 (Python kodu çalışır)

Seviye 6 — Sub-Agent JSON Şeması (build_sub_agent_system_prompt içinde):

{ "type": "object", "required": ["criterion", "score", "explanation", "evidence"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"}, "evidence": {"type": ["string", "array", "object"]} } }

📌 Seviye 7 — Orkestratör Ajanlar ve Ne Zaman Gerekli Olmadıkları

Mimari Karar

Seviye 6'dan sonra doğal soru: "Bu alt ajanları bir de orkestratör ajan yönetse daha iyi olmaz mı?"

Orkestratör Ajan (Orchestrator Agent) gerçek hayatta güçlü bir mimaridir. Görevi parçalara ayırabilir, hangi sub-agent'ın çalışacağına karar verebilir, araç seçebilir, eksik veya çelişkili sonuçlarda yeniden deneme başlatabilir ve farklı ajanlardan gelen sonuçları nihai karara dönüştürebilir.

Ancak bu örnekte buna bilinçli olarak gerek duymuyoruz, çünkü:

• 5 rubrik kriteri önceden belli.
• Her kriterin mutlaka çalışması gerekiyor.
• Her sub-agent yalnızca kendi kriterini değerlendiriyor.
• Eksik kriter kontrolü, sıralama ve toplam skor Python ile güvenilir biçimde yapılabiliyor.

🏗️ Orkestratör Ajan Ne Zaman Anlamlıdır?

• Hangi sub-agent'ların çalışacağı görevden göreve değişiyorsa.
• Araç seçimi, veri kaynağı seçimi veya iş akışı dallanması gerekiyorsa.
• Alt ajan cevapları arasında çelişki varsa ve yorumlayıcı uzlaştırma gerekiyorsa.
• Kalite kontrol, yeniden deneme, eksik bilgi tamamlama veya insan onayı gibi dinamik adımlar varsa.

Seviye 7'nin Mesajı: Orkestratör + sub-agent mimarileri vardır ve önemlidir; fakat her problemde gerekli değildir. Bu örnekte Python aggregator doğru, sade ve öğretici tercihtir.

💡 Seviye 7 Notu: Bu seviye yeni bir LLM çağrısı çalıştırmaz. Mimari karar verme ve sınır çizme bölümüdür. Performans grafikleri Seviye 0-6 deneylerinin maliyetini gösterir.

📊 Tüm Seviyelerin Karşılaştırması

Seviye	Yaklaşım	Eklenen Katman	Kazanım	Sınır / Ders
Lvl 0	Persona / Kara Kutu	Basit sistem promptu	Hızlı başlangıç	Tutarsız, açıklanamaz, halüsinasyona açık
Lvl 1	JSON + Açıklama	Yapılandırılmış çıktı	Cevap parse edilebilir	Hâlâ subjektif
Lvl 2	Rubrik	Kriter bazlı değerlendirme	Daha objektif skor	Dış kanıt yok, hâlâ LLM yorumu
Lvl 3	One-Shot / Few-Shot Kalibrasyon	Kriter bazlı örnekler	Tutarlı skorlar	İşlem tokenı artar
Lvl 4	Workflow + Tools	ROUGE + hafif benzerlik metrikleri	Grounded, kanıta dayalı	Tool seçimini yazılımcı yapar
Lvl 5	ReAct + Tool Calling	Otomatik tool çağrısı + execution loop	Gerçek agent davranışı	Yüksek maliyet, loop yönetimi gerekli
Lvl 6	Sub-Agentlar + Python Aggregator	Generic sub-agent + deterministic toplama	Görev ayrıştırma, sorumluluk ayrımı	5× LLM çağrısı, daha pahalı
Lvl 7	Orkestratör Ajan Kararı	Mimari karar verme	İleri mimari anlayışı	Her yerde orkestratör gerekmez

🎓 Son Mesaj: Prompt Mühendisliği, Sistem Mühendisliğine Dönüşür

Bir ajana yalnızca güçlü görünen bir prompt verip doğru çalışmasını beklemek yeterli değildir.
Gerçek Yapay Zeka Ajanı, yalnızca cevap üreten bir model değil; düşünme biçimi, araç kullanımı, muhakeme adımları ve veriye dayalı kanıtları birlikte yönetilen bir yazılım sistemidir.

Seviye 0'dan Seviye 7'ye ilerlerken aslında aynı fikri katman katman inşa ettik. Önce çıktıyı yapılandırdık, sonra değerlendirmeyi rubrikle parçaladık, ardından örneklerle kalibre ettik. Daha sonra metriklerle temellendirme ekledik ve ReAct fikrini gerçek araç yürütmeye bağladık. Sonunda orkestratör ajan gibi daha ileri mimarilerin var olduğunu, fakat bu örnekte ek LLM orchestrator kullanmamanın daha doğru mühendislik kararı olduğunu gördük.

Bir YZ Mühendisi olarak değerimiz burada ortaya çıkar: Modelden mucize beklemek yerine, modelin güçlü ve zayıf yönlerini anlayıp etrafına doğru mimariyi kurmak. İyi ajan tasarımı; prompt yazmak kadar, veriyle kanıtlama, araçlarla destekleme, muhakemeyi görünür kılma ve çıktıyı ölçülebilir hale getirme işidir.

📝 Eğitimde Kullanılan Test Metinleri

Bu iki metin özellikle seçilmiştir: kelime örtüşmesi düşük (düşük ROUGE), ancak anlamsal olarak benzer mesaj vermektedirler.

Metin 1 (Referans):
"Yapay zeka modellerinin eğitilmesi sürecinde, yüksek kaliteli veri setlerinin kullanılması kritik bir öneme sahiptir. Eğer veri seti hatalı, yanlı veya eksik bilgiler içeriyorsa, modelin üreteceği sonuçlar da kaçınılmaz olarak kusurlu ve güvenilmez olacaktır. Bu nedenle veri temizliği, model mimarisinin karmaşıklığından bile daha öncelikli bir adımdır."

Metin 2 (Sistemden Gelen Çıktı):
"Makine öğrenmesi algoritmalarının başarısı, büyük ölçüde beslendikleri bilginin kalitesine bağlıdır. Kirli, önyargılı ya da noksan verilerle beslenen algoritmalar, doğal olarak yanlış ve itimat edilemez çıktılar verecektir. Dolayısıyla, verilerin filtrelenmesi ve düzenlenmesi, sistemin altyapısını kurmaktan çok daha elzem bir süreçtir."

🏷️ Etiketler & Hashtagler

#YapayZeka #AI #MachineLearning #DeepLearning #LLM #LargeLanguageModel #PromptMühendisliği #PromptEngineering #AgentDesign #ArtificialIntelligence #Ollama #ToolCalling #ReAct #SubAgent #Orchestrator #StructuredOutput #Rubric #FewShot #Grounding #Explainability #RAG #ROUGE #TokenMaliyeti #MuratKarakayaAkademi #YZMühendisliği #YZ #AIEngineering #AIAgents #TechEducation #YouTubeEğitim #Blogger

How to Design Real AI Agents (Agents)?

Transitioning from "Persona" to Tool-Using Decision Mechanisms
A step-by-step senior-level AI Engineer guide from Level 0 to Level 7.

Published: June 2026  |  Reading time: ~25 min  |  Category: AI Engineering

🎯 Introduction: Why "You Are the Best AI Engineer in the World" Is Not Enough

90% of online tutorials tell you to write this to create an agent:

"You are the best software engineer in the world..."

If you are deploying an application to production, prompts written with only persona will turn your system into a hallucination bomb.

The real power of agents does not come from the roles you assign them; it comes from Tool Calling, Grounding, and Explainability.

💡 What Will You Learn in This Post?

In this post we will take a simple problem — "measuring text similarity" — and show you step by step how to evolve it from a novice approach to an autonomous level designed by a senior AI Engineer. At each level we will compare prompts, architecture, and cost.

🎬 Learn with Video: Murat Karakaya Akademi

You can also watch this training on the Murat Karakaya Akademi YouTube channel. Follow the same journey from Level 0 to Level 7 with step-by-step live demos, code explanations, and architectural analysis.

▶ Watch on YouTube — Murat Karakaya Akademi

📌 Level 0 — Novice Approach: Black Box & Hallucination

Beginner

Scenario: We need to find how similar Text 1 and Text 2 are on a 0–100 scale. (For example, in a RAG system, we measure how faithfully a generated answer stays true to the reference text).

Novice Prompt:
"You are a text analyst. Compare the given Text 1 and Text 2 and decide how similar they are. Return the similarity as a numeric value between 0–100. 0: They do not match at all, 100: They are completely identical word for word."

Why Is This Bad?

1. Black Box: The model only returns "75". Why 75? Not 74 or 80? We don't know.
2. Subjectivity: The same texts might get 60 one day and 85 the next.
3. Hallucination Risk: LLMs cannot perform mathematical measurements; they predict words. "75" is a fabricated (hallucinated) value.

📌 Level 1 — Structured Output & Chain of Thought

Improvement

The first thing we want is Explainability. We tell the model: "Don't just give me the result, show me your thinking process."

"You are a text analyst. Your goal is to measure the semantic similarity between two texts. Your output MUST be a valid JSON object. Do not use Markdown or additional text. Required JSON fields: - reasoning: The specific justification for similarity and differences between these two texts. - similarity_score: An integer between 0-100. Expected JSON schema: { "type": "object", "required": ["reasoning", "similarity_score"], "properties": { "reasoning": {"type": "string"}, "similarity_score": {"type": "integer", "minimum": 0, "maximum": 100} } }"

Why Is This Better?

• Chain of Thought: We did not ask for the score first. We asked it to fill the reasoning field first. The model justifies its own inference while writing the explanation.
• Debugging: If the score is 40, we can look at the logs and say "The model missed this detail, that's why it gave a low score."
• Integration: The JSON output can be parsed by application code.

⚠️ What Is Missing: The score is still subjective. The 0–100 scale is too broad and unstructured for an LLM.

📌 Level 2 — Rubric and Objectivity (Divide & Conquer)

Increased Autonomy

We are not allowing the agent to interpret the abstract concept of "similarity" on its own. We give it rules (rubric). We break the problem into parts.

Rubric:

• 1. Main Idea (0-20): Do both texts convey the same core message?
• 2. Tone and Style (0-20): Do the texts have the same formality and emotion?
• 3. Entities (0-20): Do the names, dates, and numbers in the texts match?
• 4. Missing Information (0-20): Does Text 2 omit an important detail from Text 1?
• 5. Fluency (0-20): How structurally coherent is Text 2?

"You are an expert evaluator. Evaluate the two texts according to the 5 criteria below. Each criterion is scored 0-20. Your output MUST be a valid JSON object. Do not use Markdown or additional text. Required JSON fields: - evaluations: A list of 5 items [criterion, score, explanation] - total_score: The sum of the five criterion scores. Expected JSON schema: { "type": "object", "required": ["evaluations", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }"

Why Is This Better?

• Grounding: We removed the model from abstract evaluation on a scale of 100.
• Objectivity: Scores will be much more consistent even if you run them at different times (variance decreases).
• Comparability: We can evaluate different prompts against the same rubric.

📌 Level 3 — Example-Based Rubric Calibration (One-Shot / Few-Shot)

Calibration

In Level 2 we gave the rubric; however, this was still zero-shot prompting. The model read the criteria but never saw from examples what "When do I give 20 points?", "What is the boundary case for 10?", "When is 0 appropriate?"

At this level we provide small, representative-examples for each criterion.

Scoring Calibration Examples:

• Main Idea — 20 points: "Data cleaning is critical for model success" and "Model quality heavily depends on clean data" convey the same core message.
• Main Idea — 10 points: Both texts discuss data quality but one focuses on security risks while the other focuses on model performance.
• Main Idea — 0 points: One discusses data cleaning, the other discusses a sports match result.
• Tone and Style — 20 points: Both texts are written in an academic and formal tone.
• Tone and Style — 10 points: One is formal, the other more conversational, but the meaning is preserved.

Why Is This Better?

• Consistency: The model uses the same score ranges more reliably.
• Teachability: The rubric is now supported by behavioral examples, not just an abstract list.
• Cost: Few-shot examples increase input tokens — so examples must be short and clear.

Expected JSON Schema:

{ "type": "object", "required": ["evaluations", "calibration_note", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Level 4 — Tool Calling and Workflow

Grounding Begins

In Level 3 we calibrated the rubric with examples; however, the evaluation still relied solely on LLM interpretation. Now we add deterministic metrics from external systems as evidence.

Metrics Used:

• ROUGE-L F1: Measures word-sequence overlap.
• Lightweight Similarity Score: A combination of Token cosine + Token Jaccard + Character 3-gram cosine + Sequence ratio.

Metric Interpretation Rules:

• If ROUGE-L F1 is low, this indicates low word-sequence overlap; it is not alone evidence of low semantic similarity.
• If the Lightweight Similarity Score is higher than ROUGE-L, the texts may convey a similar message with different words.
• The Lightweight Similarity Score is not a real semantic embedding; it should be used as a decision-support signal, not as the sole decision-maker.

🌍 Why Is This Used in the Real World?

• Reliability: ROUGE and lightweight similarity scores are deterministic — they give the same scores to the same text pair every time.
• Traceability: Since the LLM's opinion is grounded in external evidence, evaluation becomes more auditable.
• Cost Control: Lightweight metrics are fast and do not require heavy model dependencies.

🔬 Experiment Hygiene Note

Level 4 uses the same rubric text as Level 3. This is a deliberate decision: the difference between the two levels is not a rubric change, but only external metric context.

Additional Required JSON Fields in Level 4:

• metric_interpretation: Explain how you interpreted the ROUGE-L F1 and Lightweight Similarity Score values.
• calibration_note: Explain how the rubric calibration examples affected your scoring.

Expected JSON Schema (Level 4):

{ "type": "object", "required": ["evaluations", "metric_interpretation", "calibration_note", "total_score"], "properties": { "evaluations": { /* Same 5-item list as Level 3 */ }, "metric_interpretation": {"type": "string"}, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Level 5 — ReAct and Ollama Tool Calling with Real Agent Loop

Real Agentic Loop

We built a strong workflow in Level 4, but was our system a real agent? Not exactly. Because we calculated the metrics with Python. In real agent behavior, the model determines what evidence it needs, the software layer executes the tool, and the result returns to the model.

ReAct Loop:

• Reasoning: The model determines what external evidence it needs to evaluate text similarity.
• Action: Instead of writing plain text, the model produces Ollama's native tool_calls field.
• Observation: Python executes the relevant function and returns the result to the model as role="tool".
• Final Answer: The model uses the tool results to produce the rubric-based JSON evaluation.

Ollama Native Tool Calling Flow:

1. Functions are presented to the model via the `tools=[...]` list. 2. If needed, the model produces `response.message.tool_calls`. 3. Python executes these tool calls. 4. Results are added to the conversation as `role="tool"` messages. 5. The model produces the final answer based on tool results.

Tool Definitions (Python):

def calculate_rouge_tool(reference_text: str = "", candidate_text: str = "") -> str: """Calculate ROUGE scores.""" return json.dumps(calculate_rouge(METIN_1, METIN_2), ensure_ascii=False) def calculate_lightweight_similarity_tool(reference_text: str = "", candidate_text: str = "") -> str: """Calculate lightweight similarity score for the fixed Text 1 and Text 2 in the notebook. Args: reference_text: Not considered in training demo; tool uses fixed METIN_1. candidate_text: Not considered in training demo; tool uses fixed METIN_2. Returns: JSON string containing Token cosine, Token Jaccard, character 3-gram cosine, sequence ratio, and combined score. """ return json.dumps(calculate_lightweight_similarity(METIN_1, METIN_2), ensure_ascii=False)

Tool Calling Loop (Pseudo-Python):

messages = [ {"role": "system", "content": TOOL_CALLING_SYSTEM_PROMPT}, {"role": "user", "content": "Text 1: ..., Text 2: ..."}, ] while True: response = client.chat( model=MODEL, messages=messages, tools=[calculate_rouge_tool, calculate_lightweight_similarity_tool], ) messages.append(response.message) if not response.message.tool_calls: print(response.message.content) # Final answer break for tool_call in response.message.tool_calls: tool_name = tool_call.function.name result = available_tools[tool_name](**tool_call.function.arguments) messages.append({ "role": "tool", "tool_name": tool_name, "content": str(result), })

Why Is This a Mastery-Level Skill?

• ReAct is not just writing Thought / Action / Observation; it is connecting thought to real tool execution.
• An agent is the joint design of prompt, tool calling, execution loop, grounding, and error control layers.
• The model determines tool needs, Python executes the tool, and the final evaluation is supported by external evidence.

📊 Level 5 Token Cost:

"Since Level 5 is a multi-turn agent loop, the input token is not just the length of the first user prompt. With each client.chat call, the system message, user message, previous assistant messages, and tool results are re-injected into context. Therefore, the input token total in Level 5 is not a unique token count, but a cumulative processed token / cost indicator."

🛡️ In the Real World: Production Guardrails

In real production, these protections are added: schema validation, maximum step limit, tool allowlist, retry, and tracing/logging.

Level 5 Tool Calling JSON Schema:

{ "type": "object", "required": ["evaluations", "metric_interpretation", "calibration_note", "total_score"], "properties": { "evaluations": { "type": "array", "minItems": 5, "maxItems": 5, "items": { "type": "object", "required": ["criterion", "score", "explanation"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"} } } }, "metric_interpretation": {"type": "string"}, "calibration_note": {"type": "string"}, "total_score": {"type": "integer", "minimum": 0, "maximum": 100} } }

📌 Level 6 — Rubric-Based Sub-Agents and Python Aggregator

Modular Architecture

In Level 5, a single agent both called tools and interpreted the entire rubric on its own. At this level we try a different architecture: instead of one large prompt, we give each rubric criterion to a separate sub-agent.

Architecture:

• 1 generic sub-agent function is written.
• This function is called 5 times with 5 different rubric configurations.
• Each sub-agent evaluates only its own criterion.
• Python aggregator validates, sorts, and calculates the total score.
• The aggregator makes no LLM calls — it is deterministic.

The Pedagogical Message of This Level:

✅ "Don't make everything an agent!"
LLM is for subjective evaluation. Python is for validation, aggregation, formatting, and deterministic computation.

Limitations:

• 5 sub-agents = 5 LLM calls = more expensive than Level 5.
• Not necessary in every case; it makes sense when the rubric grows or when audibility is critical.

Level 6 — Sub-Agent JSON Output (single criterion):

{ "criterion": "Main Idea", "score": 18, "explanation": "Specific evaluation for this criterion", "evidence": "Basis from text or metrics" }

Python Aggregator Total Output (all criteria):

{ "evaluations": [ {"criterion": "Main Idea", "score": 18, "explanation": "...", "evidence": "..."}, {"criterion": "Tone and Style", "score": 16, "explanation": "...", "evidence": "..."}, {"criterion": "Entities", "score": 17, "explanation": "...", "evidence": "..."}, {"criterion": "Missing Information", "score": 15, "explanation": "...", "evidence": "..."}, {"criterion": "Fluency", "score": 14, "explanation": "...", "evidence": "..."} ], "metric_interpretation": "ROUGE and lightweight similarity metrics were provided as context to each sub-agent; each criterion was interpreted by its own expert sub-agent.", "aggregation_note": "Total score was computed deterministically by the Python aggregator; no LLM orchestrator was used.", "total_score": 80 }

Level 6 Python Aggregator Function Example:

def aggregate_sub_agent_results(sub_agent_results, metrics_context): expected_criteria = [config['criterion'] for config in RUBRIC_AGENT_CONFIGS] actual_criteria = [result['parsed'].get('criterion') for result in sub_agent_results] if actual_criteria != expected_criteria: raise ValueError(f"Sub-agent criterion order does not match expected.") evaluations = [] for result in sub_agent_results: parsed = result['parsed'] score = parsed.get('score') if not isinstance(score, int) or not 0 <= score <= 20: raise ValueError(f"Invalid score: {parsed}") evaluations.append({ 'criterion': parsed['criterion'], 'score': score, 'explanation': parsed['explanation'], 'evidence': parsed['evidence'], }) total_score = sum(item['score'] for item in evaluations) return { 'evaluations': evaluations, 'metric_interpretation': '...', 'aggregation_note': 'Total score was computed deterministically by Python.', 'total_score': total_score, }

Level 6 — Token Cost:

• 5 sub-agents = 5 independent LLM calls
• Each call includes system prompt + user prompt + metric context
• Total input token = 5 × (system + user prompt length)
• Aggregator token cost = 0 (Python code runs)

Level 6 — Sub-Agent JSON Schema (inside build_sub_agent_system_prompt):

{ "type": "object", "required": ["criterion", "score", "explanation", "evidence"], "properties": { "criterion": {"type": "string"}, "score": {"type": "integer", "minimum": 0, "maximum": 20}, "explanation": {"type": "string"}, "evidence": {"type": ["string", "array", "object"]} } }

📌 Level 7 — Orchestrator Agents and When They Are Not Needed

Architectural Decision

After Level 6 the natural question is: "Wouldn't it be better if an orchestrator agent managed these sub-agents?"

Orchestrator Agent is a powerful architecture in the real world. An orchestrator can break down tasks, decide which sub-agent to run, select appropriate tools, initiate retries on missing or contradictory results, and convert results from different agents into a final decision.

However, in this example we deliberately do not need it, because:

• The 5 rubric criteria are predetermined.
• Every criterion must run.
• Each sub-agent evaluates only its own criterion.
• Missing criterion check, sorting, and total score can be reliably done with Python.

🏗️ When Does an Orchestrator Agent Make Sense?

• When which sub-agents to run changes from task to task.
• When tool selection, data source selection, or workflow branching is needed.
• When there are contradictions between sub-agent responses and an interpretive reconciliation is needed.
• When there are dynamic steps such as quality control, retry, missing information completion, or human approval.

Level 7's Message: Orchestrator + sub-agent architectures exist and are important; however, they are not necessary in every problem. In this example, the Python aggregator is the correct, simple, and instructive choice.

💡 Level 7 Note: This level does not make a new LLM call. It is an architectural decision-making and boundary-setting section. Performance graphs show the cost of Level 0-6 experiments.

📊 Comparison of All Levels

Level	Approach	Added Layer	Gain	Limitation / Lesson
Lvl 0	Persona / Black Box	Simple system prompt	Fast start	Inconsistent, unexplainable, hallucination-prone
Lvl 1	JSON + Explanation	Structured output	Answer becomes parseable	Still subjective
Lvl 2	Rubric	Criteria-based evaluation	More objective score	No external evidence, still LLM opinion
Lvl 3	One-Shot / Few-Shot Calibration	Criteria-based examples	More consistent scores	Input token cost increases
Lvl 4	Workflow + Tools	ROUGE + lightweight similarity metrics	Grounded, evidence-based	Developer selects the tools
Lvl 5	ReAct + Tool Calling	Automatic tool calling + execution loop	Real agent behavior	High cost, loop management needed
Lvl 6	Sub-Agents + Python Aggregator	Generic sub-agent + deterministic aggregation	Task decomposition, responsibility separation	5× LLM calls, more expensive
Lvl 7	Orchestrator Agent Decision	Architectural decision-making	Understanding of advanced architectures	Orchestrator not needed everywhere

🎓 Final Message: Prompt Engineering Becomes Systems Engineering

Simply giving an agent a powerful-sounding prompt and expecting it to work correctly is not enough.
A Real AI Agent is not just a model that produces answers; it is a software system that jointly manages thinking patterns, tool usage, reasoning steps, and data-driven evidence.

As we progressed from Level 0 to Level 7, we actually built the same idea layer by layer. First we structured the output, then we broke evaluation into rubric parts, then we calibrated with examples. Then we added grounding with metrics and connected the ReAct idea to real tool execution. Finally, we saw that more advanced architectures like orchestrator agents exist, but in this example, not adding an extra LLM orchestrator was the more correct engineering decision.

Our value as AI Engineers emerges here: instead of expecting miracles from the model, understand the model's strengths and weaknesses and build the right architecture around them. Good agent design is not just about writing prompts; it is about proving with data, supporting with tools, making reasoning visible, and making outputs measurable.

📝 Test Texts Used in the Training

These two texts were specifically selected: low word overlap (low ROUGE), yet they convey a semantically similar message.

Text 1 (Reference):
"In the process of training artificial intelligence models, the use of high-quality datasets is of critical importance. If the dataset contains incorrect, biased, or incomplete information, the results produced by the model will inevitably be flawed and unreliable. Therefore, data cleaning is a more prioritized step than the complexity of the model architecture."

Text 2 (System Output):
"The success of machine learning algorithms heavily depends on the quality of the information they are fed. Algorithms fed with dirty, biased, or incomplete data will naturally produce incorrect and untrustworthy outputs. Therefore, filtering and organizing data is a much more essential process than building the system's infrastructure."

🏷️ Tags & Hashtags

#ArtificialIntelligence #AI #MachineLearning #DeepLearning #LLM #LargeLanguageModel #PromptEngineering #AgentDesign #AI Agents #Ollama #ToolCalling #ReAct #SubAgent #Orchestrator #StructuredOutput #Rubric #FewShot #Grounding #Explainability #RAG #ROUGE #TokenCost #MuratKarakayaAkademi #AIEngineering #TechEducation #YouTubeEducation #Blogger

Yapay Zeka Ajanları ve Model Context Protocol (MCP)

Yapay Zeka Ajanları Çağı ve Model Context Protocol (MCP): LLM'leri Dış Dünyaya Bağlamak

Merhaba arkadaşlar, Murat Karakaya Akademi'ye hoş geldiniz.

Bugün sizlerle birlikte Yapay Zeka (AI) dünyasında oyunun kurallarını değiştiren, özellikle geliştiriciler ve sistem mimarları için hayati önem taşıyan bir konuyu; Model Context Protocol (MCP) kavramını derinlemesine inceleyeceğiz. Büyük Dil Modelleri (LLM) artık sadece metin üreten "chatbot"lar olmaktan çıkıp, iş yapan, düşünen ve dış dünya ile etkileşime giren "Ajanlara" (Agents) dönüşüyor. Peki, bu dönüşümü standart ve güvenli bir şekilde nasıl sağlarız? İşte cevabımız MCP.

Büyük Dil Modellerinin (LLM) Sınırları ve "Grounding" İhtiyacı

Öncelikle problemi net bir şekilde ortaya koyalım. Bir LLM, ne kadar büyük olursa olsun (Gemini, GPT-4, Claude vb.), aslında "statik" bir bilgi deposudur. Eğitim verisi ne zaman kesildiyse (cut-off date), bilgisi orada kalır. Örneğin, bugün dolar kurunu veya en son çıkan bilimsel makaleyi sorduğunuzda, model ya "bilmiyorum" der ya da istatistiksel tahminlere dayalı olarak halüsinasyon görür.

Bizim bu modellerin ayaklarını yere bastırmamız, yani teknik terimle "Grounding" yapmamız gerekiyor. Modeli statik bir ansiklopedi olmaktan çıkarıp, dinamik verilere ulaşabilen bir asistana dönüştürmeliyiz. Bunun geleneksel yöntemi Function Calling (Araç Kullanımı) idi. Ancak her modelin API yapısı farklı olduğunda ve entegre edilecek araç sayısı arttığında, bu durum geliştiriciler için bir "entegrasyon cehennemine" dönüşüyordu.

Çözüm: Model Context Protocol (MCP) Nedir?

Anthropic tarafından 2024 sonlarında önerilen ve hızla bir endüstri standardı haline gelen MCP, AI modelleri ile dış dünya (veritabanları, API'lar, dosya sistemleri) arasında ortak bir dil oluşturmayı hedefler.

Eskiden her LLM için ayrı ayrı "adapter" yazmak zorundaydık (N x M problemi). MCP sayesinde, bir kez MCP Sunucusu yazıyoruz ve bu sunucuyu Claude, Gemini veya VS Code gibi herhangi bir MCP İstemcisi (Client) hiçbir kod değişikliği yapmadan kullanabiliyor. Tıpkı USB standardı gibi; farenizi hangi bilgisayara takarsanız takın çalışır, değil mi? MCP de AI araçları için bunu sağlıyor.

MCP Mimarisi: Nasıl Çalışır?

Videoda detaylıca kodladığımız bu mimari üç ana bileşenden oluşur:

1. MCP Host (Ana Bilgisayar): Uygulamanızın (örneğin VS Code, Cursor veya kendi Python scriptiniz) çalıştığı yer.
2. MCP Client (İstemci): LLM ile MCP sunucusu arasındaki köprüyü kuran, sunucudaki fonksiyonları (araçları) LLM'e tanıtan katman.
3. MCP Server (Sunucu): Araçların (tools), kaynakların (resources) ve istemlerin (prompts) barındığı yer. Fonksiyonlarımızı burada tanımlıyoruz.

Uygulama Örneği: ArXiv Makale Ajanı

Eğitimimizde somut bir örnek üzerinden gittik. Amacımız şuydu: "Bana yapay zeka alanındaki son makaleleri bul, özetlerini çıkar ve bilgisayarıma bir rapor dosyası olarak kaydet."

Bunun için Python'da fastmcp kütüphanesini kullandık. Bu kütüphane işleri inanılmaz kolaylaştırıyor. Sadece fonksiyonunuzun başına bir dekoratör ekliyorsunuz:

from fastmcp import FastMCP

mcp = FastMCP("ArXiv Ajanı")

@mcp.tool()
def get_arxiv_papers(topic: str, max_results: int = 3):
    """Belirtilen konuda ArXiv'den makaleleri getirir."""
    # ... (ArXiv API çağrısı kodları) ...
    return paper_list
    

Bu kadar basit! Artık bu fonksiyon, Gemini veya başka bir model tarafından "görülebilir" ve "çağrılabilir" bir araç haline geldi. LLM, kullanıcının niyetini anlıyor, hangi aracın (tool) kullanılması gerektiğine karar veriyor, parametreleri dolduruyor ve sonucu alıp işliyor. İşte "Reasoning" (Muhakeme) yeteneği burada devreye giriyor.

Docker ile Dağıtım (Deployment)

Bir MCP sunucusu yazdınız ama bu sadece sizin bilgisayarınızda mı çalışacak? Hayır. Kurumsal bir yapıda, yazdığınız araçların tüm ekip tarafından kullanılmasını istersiniz. Videoda, hazırladığımız MCP sunucusunu nasıl Docker konteynerine çevireceğimizi ve bir web servisi (SSE - Server-Sent Events) olarak nasıl dışarıya açacağımızı da adım adım gösterdim.

Docker sayesinde, yazdığınız AI aracı, bağımlılık sorunları yaşamadan herhangi bir sunucuda veya bulut ortamında çalışabilir hale geliyor. Ekibinizdeki diğer geliştiriciler, sadece sunucunun IP adresini girerek sizin geliştirdiğiniz AI yeteneklerini kendi projelerine dahil edebilirler.

VS Code ve Cursor Entegrasyonu

MCP'nin en heyecan verici yanlarından biri de geliştirme ortamlarına (IDE) entegre olmasıdır. Videoda gösterdiğim gibi, VS Code veya Cursor kullanırken, arka planda çalışan bir MCP sunucusu sayesinde, yapay zeka asistanınız projenizin bağlamını, veritabanı şemanızı veya özel API dokümantasyonlarınızı anlayabilir. Bu, kod yazma verimliliğinizi katbekat artıracak bir gelişmedir.

Sonuç

Arkadaşlar, özetle; Büyük Dil Modellerini sadece sohbet etmek için kullanmak, süper bilgisayarı hesap makinesi olarak kullanmaya benzer. Onlara MCP ile el, kol ve göz (araçlar) verdiğimizde, gerçek dünyada iş yapan otonom ajanlara dönüşüyorlar. Bu standartlaşma, AI uygulamalarının geleceği için kritik bir adımdır.

Videoda tüm bu adımları; sunucu kurulumundan istemci kodlamasına, Docker deploy işleminden Gemini entegrasyonuna kadar satır satır kodladık. Mutlaka izlemenizi ve kendi bilgisayarınızda denemenizi öneririm. Kodlamadan korkmayın, hata yapa yapa en iyisini öğreneceğiz.

Murat Karakaya Akademi'ye Katılın!

Yapay Zeka, Derin Öğrenme ve Python dünyasındaki en güncel gelişmeleri, akademik derinlikten ödün vermeden ama herkesin anlayabileceği bir dille öğrenmek için kanala abone olmayı unutmayın. Sorularınızı videonun altına veya buraya yorum olarak yazabilirsiniz.

Birlikte öğrenmeye ve üretmeye devam edelim!

#MuratKarakayaAkademi #YapayZeka #MCP #ModelContextProtocol #Python #Docker #LLM #AIagents #SoftwareDevelopment

Modern yazılım geliştirme süreçlerinde GitHub Copilot ve VS Code etkileşimi.

VS Code + Copilot ile İleri Düzey Kod Geliştirme: Bağlam Mühendisliği ve Refactoring Rehberi

Murat Karakaya Akademi Özet Serisi • 21 Ocak 2026

Modern yazılım geliştirme süreçlerinde GitHub Copilot ve VS Code etkileşimi.

Merhaba değerli arkadaşlar, Murat Karakaya Akademi YouTube kanalına hoş geldiniz. Bugün sizlerle, canlı yayında gerçekleştirdiğimiz ve oldukça yoğun teknik tartışmalara sahne olan "Çalışma Odası" serimizin bir bölümünü daha yazılı bir rehber haline getiriyoruz.

Bu bölümde, yapay zekayı sadece bir "soru-cevap" aracı olarak değil, projenin tüm dinamiklerine hakim bir "kıdemli iş ortağı" olarak nasıl konumlandıracağımızı inceledik. Odak noktamız; Bağlam Mühendisliği (Context Engineering), talimat dosyaları (.md) ve Copilot'un gelişmiş modlarıydı.

Bu Eğitimi Canlı İzleyin!

Kodun nasıl bozulduğunu, yapay zekanın nerelerde yanıldığını ve bu hataları canlı yayında nasıl düzelttiğimizi görmek, öğrenme sürecinin en değerli parçasıdır. Aşağıdaki videodan eğitimin tamamına ulaşabilirsiniz:

1. Bağlam Mühendisliği (Context Engineering) Neden Kritik?

Yazılım geliştirirken GitHub Copilot gibi araçları kullanırken yapılan en büyük hata, AI'yı projenin geri kalanından bağımsız düşünmektir. Eğer ona sadece o anki dosyayı gösterirseniz, size getireceği öneriler projenin genel mimarisine aykırı olabilir.

Context Engineering, yapay zekaya projenin "anayasasını" öğretmektir. Biz bu yayında, Copilot'a hangi dosyaları okuması gerektiğini, hangi kodlama standartlarına (naming conventions) uyması gerektiğini ve hangi dosyalara kesinlikle dokunmaması gerektiğini nasıl öğreteceğimizi tartıştık.

2. .github/copilot-instructions.md: Projenin Hafızası

Canlı yayında gösterdiğim en önemli araçlardan biri .github/copilot-instructions.md dosyasıydı. Bu dosya, Copilot için bir "rehber" görevi görür. İçerisine projenin amacını, kullandığı teknolojileri (Python, ChromaDB vb.) ve özel kısıtlamaları yazdığımızda; yapay zeka artık her önerisinde bu dosyayı referans alır.

# Proje Kuralları
- Asla 'run.py' dosyasını güncelleme.
- Yeni fonksiyonlar her zaman tip ipucu (type hints) içermeli.
- Docstring formatı Google stili olmalı.

Bu yöntem sayesinde, yapay zekaya her seferinde "Şu kütüphaneyi kullanıyorum, şu kurala uy" demekten kurtuluyoruz.

3. Refactoring Süreci: build_knowledge_base'i Parçalamak

Elimizdeki RekMK kütüphanesinde bir tasarım sorunu vardı: build_knowledge_base fonksiyonu hem yeni koleksiyon oluşturuyor hem de mevcut olanı yüklüyordu. Bu, "Single Responsibility" (Tek Sorumluluk) prensibine aykırıydı.

Yayında, bir prompt_file.md hazırlayarak Copilot'a bu fonksiyonu nasıl ikiye ayıracağını (Refactor) adım adım anlattık. İşte burada Edit Mode'un gücünü gördük. Edit Mode, AI'nın yaptığı değişiklikleri satır satır görmemize ve onaylamamıza olanak tanıyarak kontrolün bizde kalmasını sağlıyor.

4. Agent Mode: Büyük Güç, Büyük Sorumluluk

Eğitimin en heyecanlı ama bir o kadar da riskli kısmı Agent Mode kullanımıydı. Agent, terminale erişebilir, testleri çalıştırabilir ve hataları kendi kendine giderebilir. Ancak yayında gördüğümüz üzere; Agent bazen bir hatayı düzeltmeye çalışırken 2700 satır gereksiz kod yazabiliyor veya ana dosyalarınızı mahvedebiliyor.

"Agent Mode'u kullanmadan önce mutlaka Git commit'i yapın. Agent kontrolü kaybederse tek tuşla geri dönebilmelisiniz." - Murat Karakaya

5. Test Stratejisi: Manuel vs Otomatik

Değişiklikleri yaptıktan sonra iki tür test uyguladık. Önce Manuel (Smoke) Test ile sistemin temel işlevlerini (koleksiyon oluşturma, veri gömme) gözümüzle kontrol ettik. Ardından Otomatik Testler (pytest) ile Agent'ın yazdığı kodların diğer parçaları bozup bozmadığını denetledik. Yapay zekanın "Testler geçti" demesine güvenmeyip, terminal çıktılarını bizzat analiz etmenin önemini yayında açıkça gördük.

Sonuç

Yapay zeka araçları bizi tembelleştirmek için değil, daha karmaşık mimarileri daha hızlı inşa etmemiz için varlar. Ancak bu araçları yönetmek bir "orkestra şefliği" gerektiriyor. Doğru bağlamı sağlamazsanız, orkestra (AI) yanlış notalar çalmaya başlar.

Bu ve benzeri teknik içerikler için kanalımı takip etmeyi, sorularınızı muratkarakaya.net üzerinden veya YouTube yorumlarından sormayı unutmayın. Bir sonraki "Çalışma Odası" yayınında görüşmek üzere!

#MuratKarakayaAkademi #VSCode #GitHubCopilot #BağlamMühendisliği #ContextEngineering #Refactoring #Python #YazılımGeliştirme #CodingAgents #YapayZeka

Yapay Zeka İş Görenlerinde Yeni Dönem: Agent Skills ve VS Code Entegrasyonu

Yapay Zeka İş Görenlerinde Modüler Yetenek Devrimi: Agent Skills ve VS Code Entegrasyonu

Murat Karakaya | 30 Aralık 2025 Çalışma Odası Özeti

Merhaba değerli okurlar ve Murat Karakaya Akademi takipçileri. 2025 yılının bu son "Çalışma Odası" yayınında, yapay zeka dünyasında çığır açan bir mimariyi, Anthropic tarafından önerilen ve artık standart VS Code sürümlerinde de tam destekle yerini alan Agent Skills (İş Gören Yetenekleri) protokolünü derinlemesine inceledik. Bu yazı, YouTube kanalımızda gerçekleştirdiğimiz modüler ajan mimarisi eğitiminin en güncel ve teknik detaylarını içeren kapsamlı bir özetidir.

Gelişme Notu: Agent Skills özelliği artık VS Code'un kararlı (stable) sürümünde kullanılabilir durumdadır. Bu yazıda, bu teknolojinin sadece nasıl kurulduğunu değil, arka plandaki çalışma mantığını ve neden geleceğin yazılım geliştirme standartı olacağını detaylandıracağız. Canlı uygulama adımlarını görmek için aşağıdaki videomuzu mutlaka izlemenizi öneririm.

Neden Agent Skills? "Spagetti Prompt" ve Bağlam Kayması Sorunu

Yapay zeka modelleriyle (LLM) çalışan geliştiricilerin en büyük kabusu, projenin büyümesiyle birlikte kontrol edilemez hale gelen talimat listeleridir. Model her yeni sohbette tüm proje kurallarını, kod standartlarını ve araç tanımlarını okumaya zorlandığında şu teknik darboğazlar oluşur:

• Bağlam Kayması (Context Drift): Model, çok fazla talimat arasında asıl görevinden sapabilir.
• Token İsrafı: Her istekte binlerce satırlık sistem talimatı göndermek maliyeti artırır ve hızı düşürür.
• Statik Yapı: Geleneksel "Prompt"lar statiktir; modelin o anki ihtiyacına göre şekillenmezler.

Agent Skills, bu problemleri modülerlik ve dinamik keşif ile çözerek, yapay zekayı "her şeyi bilen ama kafası karışık" bir asistandan, "ihtiyacı olduğunda doğru araca ulaşan" kıdemli bir iş gören (agent) seviyesine taşır.

Görsel: Yapay Zeka İş Görenlerinin Dinamik Yetenek Seçimini Temsil Eden Teknik Şema

Teknik Derinlik: Agent Skills Nasıl Çalışır?

Agent Skills protokolü, Aşamalı İfşa (Progressive Disclosure) prensibi üzerine kuruludur. Bu, modelin bilişsel yükünü optimize eden üç katmanlı bir süreçtir:

1. Dinamik Keşif (Metadata Layer)

Model, projenizdeki .github/skills dizinini tarar. Sadece skill.md dosyalarının en başındaki YAML metadata kısmını okur. Burada tanımlanan name ve description, ajanın hangi yeteneği ne zaman kullanacağına karar verdiği "etiket"lerdir.

2. Bağlamsal Yükleme (Activation Layer)

Kullanıcı "API'yi refactor et" dediğinde, ajan sadece bu işle ilgili yeteneğin talimatlarını hafızasına çeker. Diğer tüm yetenekler (UI tasarımı, veri analizi vb.) pasif kalır, böylece bağlam penceresi tertemiz kalır.

3. Kod Yürütme ve Araç Kullanımı (Execution Layer)

Bir yetenek sadece metin değildir. İçerisinde Python scriptleri veya komut satırı araçları (FFmpeg, Docker vb.) barındırabilir. Ajan, yetenek klasörü içindeki bu araçları yerel makinede güvenli bir şekilde çalıştırarak gerçek eylemler gerçekleştirir.

Bir Yeteneğin Anatomisi

Etkili bir skill.md dosyası oluşturmak için şu teknik yapı takip edilmelidir:

---
name: api_refactor_expert
description: "Express.js kodlarını Fastify mimarisine dönüştürmek ve performans optimizasyonu yapmak için kullanılır."
---

# Talimatlar
- Dönüşüm sırasında 'fastify-autoload' yapısını tercih et.
- Şema doğrulama için Joi yerine TypeBox kullan.

# Örnekler
[Girdi ve çıktı kod örnekleri buraya gelir]

Buradaki description alanı hayati önem taşır. Yapay zeka iş göreninin bu yeteneği seçmesi için bu açıklamanın çok net ve işlevsel olması gerekir.

VS Code Entegrasyonu ve Kurulum

Artık Insider sürümüne ihtiyaç duymadan, standart VS Code üzerinde Agent Skills yapısını kurabilirsiniz. Bunun için ana dizininizde şu yapıyı kurgulamanız yeterlidir:

• .github/skills/
• ├── pdf_manager/ (Yetenek Klasörü)
• │   ├── skill.md (Talimatlar ve Metadata)
• │   └── merge_pdf.py (Çalıştırılabilir Betik)
• └── code_reviewer/
•     └── skill.md

VS Code Settings (Ayarlar) kısmından "Chat: Use Agent Skills" aramasını yaparak özelliğin aktif olduğunu doğrulayabilirsiniz. Bu ayar aktif olduğunda, Copilot veya Claude tabanlı ajanlar otomatik olarak bu dizini taramaya başlar.

Neden Gelecek Bu Protokolde?

Agent Skills'i MCP (Model Context Protocol) ile kıyasladığımızda, en büyük avantajının "Sıfır Altyapı Maliyeti" olduğunu görüyoruz. MCP için bir sunucu yönetmeniz gerekirken, Agent Skills için sadece bir klasör yönetirsiniz.

Ayrıca, bu yetenekler projenizin bir parçası olduğu için Git (Versiyon Kontrol Sistemi) ile takip edilebilir. Takımınıza yeni katılan birine proje kurallarını anlatmak yerine, ona Agent Skills içeren bir depo (repository) teslim edersiniz ve yapay zeka asistanı o kuralları saniyeler içinde öğrenir.

Son Söz: Akıllı Asistandan Akıllı İş Görene

Agent Skills, yapay zeka ile etkileşimimizi kökten değiştiriyor. Artık modelleri sadece metinlerle beslemiyoruz; onlara gerçek dünyada iş yapabilecekleri birer "yetkinlik seti" kazandırıyoruz. VS Code'un bu protokolü standart hale getirmesi, bireysel geliştiriciler ve büyük yazılım ekipleri için verimlilikte devasa bir sıçrama anlamına geliyor.

Eğitimin tüm teknik detayları ve canlı uygulama demosu için YouTube videomuzu izlemeyi unutmayın!

Canlı Yayını İzle & Yeteneklerini Geliştir

Daha fazla teknik derinlik ve yapay zeka eğitimi için takipte kalın.

#MuratKarakayaAkademi #AgentSkills #VSCode #AIProgramming #YapayZekaİşGörenleri #AnthropicClaude #ModülerYazılım #KodlamaEğitimi