Microsoft Agent Framework: Katmanlı SDK Tasarımının İç Yüzü
Geçen hafta Microsoft’un yeni Command Line bloğunda Shawn Henry imzalı bir yazı çıktı. Konu basit gibi dürüyor ama değil: Microsoft Agent Framework (MAF) nasıl tasarlanmış, neden katmanlı bir SDK mimarisi seçilmiş, işte bunlar anlatılıyor. Yazıyı okurken birkaç yerde başımı salladım. Son iki yılda kurumsal müşterilerle yürüttüğümüz ajan projelerinin acı taraflarına baya dokunuyor. Ama bazı kısımlarda da “hmm, teoride tamam da pratikte ne olacak?” dedim.
Bu yazıda MAF’ın arkasındaki fikri kendi kelimelerimle açacağım (evet, doğru duydunuz). Sonra da Türkiye’deki kurumsal gerçeklikle nerede örtüşüyor, nerede biraz havada kalıyor, ona bakacağım. Açık konuşayım: ajan dünyası şu ara deli gibi dönüyor ve doğru framework seçimi insanın kafasını karıştırıyor. Umarım bu yazı size az biraz yön verir.
Evet, doğru duydunuz.
Chat’ten Ajana Geçiş: Aslında Ne Değişti?
Şöyle ki, İlk AI dalgası vardı ya, hani çoğumuzun hâlâ orada kaldığı dönem, o iş aslında basit bir döngüye dayanıyordu: kullanıcı bir şey yazıyor, model cevap veriyor, konu kapanıyor. Sonra üstüne RAG geldi, tool calling geldi, biraz daha akıllandı; ama dürüst olayım, mantık hâlâ “soru-cevap” çizgisinden pek çıkmıyordu.
Ajan tarafı işe başka bir oyun. Burada modelin kendi başına karar vermesi, araçları sırayla çağırması, ara sonuçlardan yeni planlar çıkarması, hatta gerektiğinde başka ajanlarla konuşması bekleniyor. Yanı sohbet eden bir bot değil, iş yapan yazılım‘dan bahsediyoruz. İşte, peki neden önemli? Çünkü fark tam da burada başlıyor (eh, fena değil)
Bir dakika — bununla bitmedi.
Bu geçiş kulağa kolay geliyor ama altyapıda işler biraz karışıyor, hatta bazen düpedüz can sıkıyor; çünkü artık state’i nerede tutacağınızı, 14 adım sonra patlayan bir ajanı nasıl toparlayacağınızı ve üretimde sessizce maliyet şişiren senaryoları nasıl yakalayacağınızı tek tek düşünmeniz gerekiyor.
- Ajan 14 adım sonra crash olursa ne yapacağız? State nerede tutuluyor?
- Üretimde bir ajan saatte 40 dolar OpenAI faturası kesiyor — bunu kim fark edecek?
- Compliance ekibi “bu ajan hangi veriyi gördü, ne karar verdi” diye sorduğunda elimizde ne var?
- Bir ajan başarısız olunca, hata model’de mi, prompt’ta mı, tool’da mı, orchestration’da mı?
İşte MAF tam burada devreye giriyor. “Bir LLM’e prompt atın, cevap alın” kısmı kolay zaten; asıl mesele o LLM’in etrafına üretim kalitesinde bir kabuk geçirmek. Microsoft’un yaklaşımı da bu noktada ortaya çıkıyor: katmanlı bir SDK ile işi sadece demo seviyesinde bırakmamak.
Katmanlı SDK Felsefesi: Lego Gibi Düşünün
MAF’ın tasarımında üç ana parça var. Bunları her gördüğümde aklıma aynı şey geliyor: son 3-4 yılda ekiplerin kendi kendine kurup durduğu örüntüler, şimdi biraz daha düzgün bir isimle karşımıza çıkıyor. Yanı yeni bir fikirden çok, dağınık olanı toparlama hali gibi.
1. Agent Loops (Ajan Döngüleri)
Bu kısım işin tam göbeği. Model, konuşma geçmişi, tool çağrısı, çıkan sonuç, sonra yeniden model… Kısır gibi dönüyor — ki bu tartışılır — ama iyi anlamda dönüyor; ajanın nefes alıp verdiği yer burası. MAF bunu sizin elle yazmanızı istemiyor, hazır veriyor, ama isterseniz kapağı açıp içeri giriyorsunuz. Güzel tarafı da bu zaten.
Peki neden önemli? Çünkü çoğu senaryoda döngünün iskeleti aynı kalıyor, sadece detaylar değişiyor (en azından benim deneyimim böyle). Bir yerde tool sayısı artıyor, başka yerde memory davranışı farklılaşıyor, bazen de akışın ortasında küçük bir yön değişikliği gerekiyor; işte o zaman “default ile başla, lazım olunca aç” yaklaşımı baya iş görüyor.
2. Workflows (İş Akışları)
Tek bir ajan loop’u bazen yetmiyor. Mesela bir fatura işleme senaryosu düşünün: OCR ajanı belgeyi okuyor, doğrulama ajanı tutarları kontrol ediyor, onay ajanı da belirli bir limitin üstündeyse insan onayı istiyor. Burada artık tek ajan yok; daha çok birbirine pas atan ajanlar var, yanı küçük bir orkestra gibi çalışıyorlar.
Bak şimdi, ilk bakışta bu yapı basit görünüyor ama asıl mesele sıra yönetimi ve geçişler. Bir adım gecikirse tüm süreç kayabiliyor (özellikle hata yakalama. Geri dönüş noktaları varsa), o yüzden workflow katmanı işi toparlıyor; neyin önce geldiğini, neyin bekleyeceğini ve nerede insan müdahalesi gerekeceğini daha net hâle getiriyor (en azından benim deneyimim böyle)
Bir dakika — bununla bitmedi.
3. Harnesses (Koşum Takımları)
İsim biraz tuhaf dürüyor, açık konuşayım. Ama mantık gayet anlaşılır: ajanın etrafındaki tüm ekipmanlar tek tek paketlenmiş hâlde geliyor; memory burada mı olacak, tool registry nasıl davranacak, planlama modülü eklenecek mi, middleware devrede mi, gözlemlenebilirlik nereye akacak… Hepsi ayrı ayrı seçilebiliyor.
Bence, Evet.
Böyle olunca istediğinizi takıyorsunuz, istemediğinizi bırakıyorsunuz. Şey gibi düşünün: her projede aynı çantayı taşıyorsunuz. Içindeki aletleri duruma göre değiştiriyorsunuz; bazen sade kurulum yetiyor, bazen de birkaç parça daha ekleyince sistem daha rahat oturuyor.
Bence MAF’ın en doğru tarafı şu: “her şeyin defaultu olsun ama gerektiğinde override edilebilsin” fikri. Semantic Kernel’de bunu tam istediğimiz gibi kuramamıştık, AutoGen işe başka bir yöne kaymıştı. Şimdi ikisinin de işe yarayan taraflarını alıp tek çatı altında toplamaya çalışıyorlar.
Peki Bu Katmanlar Pratikte Nasıl Gözüküyor?
Tuhaf ama, Şöyle düşünün. En altta sade bir chat client var; Azure OpenAI’a, Foundry’e, hatta Ollama’ya konuşan bir abstraction. Onun üstünde tool calling ve conversation state geliyor. Bir katman daha yukarıda memory ve context yönetimi var. En tepede de workflow ile multi-agent koordinasyonu dürüyor.
İtiraf edeyim, Burada can alıcı nokta şu: bu katmanların hepsini kullanmak zorunda değilsiniz. 50 satırlık bir prototipte sadece en alt katman yeterli olabilir. Ama prod’a yaklaşınca üst katmanları açıyorsunuz, sonra da aynı kodu baştan yazmıyorsunuz. Kağıt üstünde basit gibi duran şey, pratikte biraz ince ayar istiyor.
Bunu biraz açayım. Bu konuyla ilgili Photoshop’ta MSVC ve SPGO ile %20 Hız Artışı: Nasıl Oldu? yazımıza da göz atmanızı tavsiye ederim.
Tipik Bir Karar Tablosu
Müşterilerle “MAF mı, kendimiz mi yazalım, başka framework mu?” diye konuşurken genelde masaya şöyle bir tablo koyuyorum:
| Senaryo | Önerim | Neden |
|---|---|---|
| Tek ajan, basit tool calling, POC | MAF’ın sadece agent loop katmanı | Hızlı başlarsın, bağımlılık sayısı da düşük kalır |
| 3-5 ajan, sıralı iş akışı | MAF Workflows | State machine’i elle kurma derdinden kurtulursun |
| Long-running, durable süreçler | MAF + Durable Functions/Foundry | Process restart toleransı lazım olur, yoksa iş uzar da uzar |
| Ultra hassas, deterministik akış | Klasik kod + nokta atışı LLM çağrıları | Tam ajan paradigmasına neredeyse her zaman gerek olmuyor aslında |
Bu tabloyu beton gibi görmeyin. Sadece başlangıç için iyi bir pusula bu. Her projenin ayrı bir huyu var; biri sakın gidiyor, öbürü ilk günden sürpriz çıkarıyor.
Evet.
Neyse uzatmayalım.
Türkiye Penceresinden: Bu İş Bizde Nasıl Yürüyecek?
Şimdi asıl can alıcı yere gelelim. Türkiye’deki kurumsal müşteriler, ajan işine biraz temkinli bakıyor, açık konuşayım. Global tarafta herkes “agent-first architecture” diye konuşurken, bizde hâlâ “chatbot mu yapsak, copilot mu kursak” sorusu dönüp dürüyor çoğu yerde. Garip ama gerçek.
Birkaç gözlem var, lafı gevelemeden söyleyeyim: Azure Cosmos DB’ye Immutable Backup Geldi: Ne Değişiyor? yazımızda bu konuya da değinmiştik.
Veri ikametgâhı sorunu. Bankacılık ve kamuya yakın işlerde veri Türkiye dışına çıkamıyor. Bu da Azure OpenAI’ı doğrudan kullanırken sadece bölge seçimini değil, log toplama tarafını da etkiliyor (hatta bazen en çok orası can sıkıyor). MAF güzel, evet. Altındaki model endpoint’i nerede koşuyor, observability verisi nereye akıyor, bunları en başta netleştirmek lazım (buna dikkat edin). Yoksa proje yürürken bir anda hukuk ekibi geliyor ve “durun” diyor; sonra iki ay bekliyorsunuz. Evet, tam olarak böyle.
Maliyet hesabı TL bazında acı veriyor. Bir GPT-4 sınıfı modeli ciddi token ile çağırınca aylık fatura kolayca beş haneli dolar rakamlarına çıkabiliyor. Kur işi de üstüne binince, TL tarafında bu tablo çoğu orta ölçekli şirketin yıllık AI bütçesini tek kalemde yiyebiliyor (ben de ilk duyduğumda şaşırmıştım). O yüzden MAF’ın harness katmanındaki routing ve fallback yetenekleri baya işe yarıyor: küçük modele git, kararsız kalırsa büyüğüne yükselt. Bunu sıfırdan yazmak istemezsiniz, inanıyorum. Hem uğraştırır hem de gereksiz risk çıkarır.
Peki neden?
İnsan kaynağı problemi. Türkiye’de “AI engineer” ilanı açan şirketlerin önemli kısmı aslında “Python bilen biri” arıyor gibi dürüyor. Şey yanı, gerçek anlamda agent mimarisi tasarlayacak, state management ve observability tarafına gömülmüş insan sayısı çok az. Bu yüzden framework’ün öğrenme eğrisi ciddi fark yaratıyor. MAF’ın katmanlı yapısı burada iyi çalışıyor; kıdemsiz geliştirici üst katmanı kullanıyor, kıdemli olan dibe inip ince ayar yapabiliyor. Fena değil.
Neyse, peki neden?
Startup vs Kurumsal: İki Farklı Reçete
Eğer 5-10 kişilik bir startup’sanız, bence doğrudan MAF’ın en üst katmanından başlayın. Workflow ve harness’ları olduğu gibi alın; önce hız kazanın, sonra MVP’yi çıkarın, darboğaz nerede patlıyorsa orayı özelleştirin. Erken optimizasyon çoğu zaman ayağa dolanıyor. Hani biraz sert söyledim ama doğruya yakın bu.
Açık konuşayım, Ama büyük bir kurumsal yapıdaysanız — diyelim banka ya da telekom — iş değişiyor. Önce platform team kurun. Bu ekip MAF üzerine sizin standartlarınızı, log formatlarınızı ve compliance kontrollerinizi giydirsin; sonra ürün ekipleri o iç platformu kullansın. Yoksa herkes kendi kafasına göre ajan yazmaya başlıyor. Ortaya çorba çıkıyor (gerçek çorba değil tabiî, teknik borç yığını). 18 ay sonra da hiçbir şeyi toparlayamıyorsunuz. Yukarıda bahsettiğim microservices dönemindeki hata var ya, işte aynı şeyin başka versiyonu bu.
Şimdi gelelim işin can alıcı noktasına.
Kod Tarafından Küçük Bir Bakış
Tam syntax değişebilir, o ayrı; ama mantığı göstermek için kabaca böyle düşünün:
// Basit ajan loop — en alt katman
var agent = new ChatAgent(chatClient)
.WithInstructions("Sen bir fatura analiz uzmanısın.")
.WithTools(invoiceTools);
var response = await agent.RunAsync("Bu PDF'i analiz et.");
// Workflow katmanı — orkestrasyon
var workflow = new Workflow()
.AddAgent("ocr", ocrAgent)
.AddAgent("validator", validationAgent)
.AddAgent("approver", approvalAgent)
.Connect("ocr", "validator")
.Connect("validator", "approver", when: amount => amount > 10000);
await workflow.ExecuteAsync(inputDocument);Ne yalan söyleyeyim, İşin özü şu: aynı temel parçaları farklı seviyelerde bir araya getiriyorsunuz (evet, doğru duydunuz). Basit gibi dürüyor, ama bazen en temiz fikirler zaten böyle çıkıyor. Bu yapı, Discovery to Execution: Foundry’de Ajanları Toolbox ile Ölçeklemek yazısında anlattığım Foundry tool ecosystem’iyle de gayet doğal şekilde oturuyor. .NET Haziran 2026 Servis Güncellemesi: 3 CVE ve Bilmeniz Gerekenler yazımızda bu konuya da değinmiştik.
Gözlemlenebilirlik: Aslında En Çok Konuşmamız Gereken Konu
Garip gelecek ama, Bence MAF’ın en kıymetli tarafı, baştan beri “observability first” diye kurgulanmış olması. Çünkü bir ajan 12 tool çağırıp, üç — ki bu tartışılır — alt-ajana işi paylaştırıp, iki dakika sonra da “üzgünüm yapamadım” diyorsa, orada ne olduğunu göremiyorsanız işin tadı kaçıyor; üretime çıkarmak da açık konuşayım, pek mantıklı olmuyor (şaşırtıcı ama gerçek). Çıkamaz. SIG Storage’ı Tanımak: Kubernetes’te Veri Kalıcılığının Mutfağı yazımızda bu konuya da değinmiştik. Bu konuyla ilgili Microsoft Build 2026: Liderlerin Bilmesi Gereken 3 Kritik Çıkarım yazımıza da göz atmanızı tavsiye ederim.
OpenTelemetry entegrasyonu var ya, işte o yüzden önemli. Trace ID’lerin ajan adımları boyunca taşınması, token kullanımının her seviyede ölçülebilmesi — bunlar ekstra süs değil, bildiğin temel ihtiyaç. Copilot Autofix Azure DevOps’ta: Alert Yığını Bitiyor mu? yazısında benzer bir yere değinmiştim aslında: AI sistemlerinin çıktısını görebilmek, bazen üretmesinden bile daha can alıcı oluyor. Evet.
Neyse uzatmayalım, mesele tam burada düğümleniyor. Bir sistemi çalıştırmak başka şey, önü sonradan anlayabilmek bambaşka şey; hatta bazen ikinci kısım daha zor oluyor çünkü olayın içinde küçük gibi duran bir trace kaybı, sonra bütün kök neden analizini çorba ediyor. Şimdi, peki neden? Çünkü ajanlar klasik uygulama gibi davranmıyor.
Şey, bir de şu var: sadece hata loglamak yetmiyor. Bazen sistem hata vermiyor ama saçma karar veriyor; işte asıl sınır bozucu kısım orası (bu konuda ikircikliyim). O yüzden ben trace, metrik ve prompt geçmişini birlikte görmeyi seviyorum (evet biraz uğraştırıyor), ama sonradan “burada ne olmuş?” sorusuna cevap verebilmek için buna değer.
Neyi Beğenmedim? Açık Konuşayım
Her yazıyı övgüyle bitirmem, çünkü o zaman işin tadı kaçıyor. MAF tarafında da, açık konuşayım, benim gözüme batan birkaç nokta var.
Birincisi dokümantasyon. Microsoft ne kadar uğraşsa da bu alan deli gibi hızlı aktığı için doc’lar hep biraz geriden geliyor, bazı senaryolarda örnek bulamayıp doğrudan kaynak koda inmek zorunda kalıyorsunuz (evet, bazen başka çare kalmıyor), “1 saat içinde POC çıkaralım” diye yola çıktıysanız da tempo bir anda düşebiliyor.
İkincisi, multi-provider meselesi. Şimdilik yapı biraz Azure merkezli gidiyor; OpenAI. Foundry tarafı rahat, ama Anthropic, Gemini ya da açık kaynak modellerle çalışmak isteyince abstraction katmanında ufak tefek boşluklar çıkabiliyor. Claude Fable 5 Microsoft Foundry’de: Otonom Ajan Devri Başlıyor ile Foundry üzerinden Anthropic erişimi baya kolaylaştı, fakat native multi-provider bir kurgu arıyorsanız LangGraph hâlâ daha esnek dürüyor. Peki neden? Çünkü orada kontrol biraz daha sizin elinizde kalıyor.
Üçüncüsü, bence en kritik yer: ajan paradigmasının kendisi henüz tam oturmuş değil. MAF iyi bir framework, bunda sıkıntı yok. Alt taraftaki modeller bazen aynı soruya iki farklı ruh hâliyle cevap veriyor (şey yanı, bugün dediğine yarın tersini de diyebiliyor). “Reliable agent” lafı şu an kulağa biraz iddialı geliyor (şaşırtıcı ama gerçek). Emin değilim ama sanırım 2026 boyunca bu iş daha toparlanacak; yine de bugünden “ajan her şeyi yapar” beklentisine girerseniz, sonu biraz hayal kırıklığı olabiliyor (buna dikkat edin). Sahada gördüğüm tablo bu. Tam da öyle.
Nereden Başlamalı? Pratik Yol Haritası
Eğer MAF’a bugün dokunmak istiyorsanız, bence sırayı fazla kurcalamayın. İlk adım basit olsun, çünkü işin asıl ayarı orada çıkıyor.
- Bir hafta: Tek ajan, 2-3 tool, lokal ortamda. Yanı önce bir “merhaba dünya” seviyesinde ne oluyor önü anlayın; şaşırtıcı biçimde, çoğu kişi burada bile takılıyor.
- İkinci hafta: Memory ekleyin. Konuşmaları kalıcı yapın. Cosmos DB veya Redis backend’i deneyin; hangisi elinizde daha rahat duruyorsa oradan yürüyün, çünkü teoriden çok pratik kurtarıyor.
- Üçüncü hafta: İki ajanı bir workflow içinde konuşturmaya başlayın. Burada durum aktarımının neden can sıktığını net görürsünüz; küçük gibi duran şeyler, bazen bütün akışı yamultur.
- Bir ay sonra: Observability, evaluation ve guard-rail katmanlarını ciddiye almaya başlayın. Production hazırlığı tam olarak burada başlıyor, öncesi biraz deneme yanılma gibi gidiyor açık konuşayım. (bu kritik)
Bir şey dikkatimi çekti: Bu sırayı atlayıp doğrudan “multi-agent enterprise workflow” yazmaya kalkışmak — gördüm, denedim, hep ağladık. Evet. Adım adım gidin; yoksa sistem değil, sız yoruluyorsunuz.
Sıkça Sorulan Sorular
Microsoft Agent Framework, Semantic Kernel’in yerine mi geçiyor?
Tam olarak öyle değil. MAF, hani Semantic Kernel ve AutoGen’den öğrenilen dersleri birleştiren yeni nesil bir çatı. Semantic Kernel hâlâ destekleniyor, ama uzun vadede Microsoft’un ajan stratejisinin merkezî MAF olacak gibi görünüyor. Bence yeni projelere doğrudan MAF ile başlamak en mantıklısı.
MAF’ı Azure dışında, on-premises ortamda kullanabilir mıyım?
SDK’in kendisi aslında sadece bir kütüphane, istediğiniz yerde koşuyor. Ama model çağrıları için bir endpoint’e ihtiyacınız var. Bunu Azure OpenAI, OpenAI, lokal Ollama veya mesela self-hosted bir vLLM olarak çözebilirsiniz. Kurumsal güvenlik ve compliance gereksinimleriniz varsa açıkçası Azure private endpoint en güvenli yol.
Tek ajan yetmiyorsa kaç ajan kullanmalıyım?
“Mümkün olan en az sayıda” diyebilirim. Yanı her ajan, kendi prompt’u, kendi token maliyeti, kendi failure mode’u demek. Bir görevi 5 ajana bölmek “modüler” gibi görünüyor ama gerçekte hata yüzeyini 5’le çarpıyorsunuz. Tecrübeme göre ideal başlangıç: 1 ajan + iyi tasarlanmış tool’lar (ki bu çoğu kişinin gözünden kaçıyor). Karmaşıklaştıkça böl.
MAF üretim için yeterince olgun mu?
Eh, SDK olarak evet, ancak ajan paradigmasının kendisi henüz tüm senaryolar için olgun değil. Belirli ve sınırlı bir düşüneyim… görevler için, mesela doküman işleme, müşteri destek triage veya kod review yardımcısı gibi şeyler için bugün üretimde rahatlıkla kullanılabiliyor. Ama “her şeyi yapan otonom asistan” hâlâ pişme aşamasında, açıkçası.
Mevcut.NET veya Python projeme entegre etmek zor mu?
Genelde değil. Hem.NET hem Python SDK’leri mevcut. Eğer projeniz. Azure ekosistemindeyse, hani Functions, App Service, Container Apps gibi şeyler kullanıyorsanız, entegrasyon oldukça doğal gidiyor. Aslında ana zorluk teknik değil, mimarı: ajanın koşacağı bağlamı, secret yönetimini. Gözlemlenebilirliği baştan doğru kurgulamak.
Kaynaklar ve İleri Okuma
Shawn Henry — Inside the Microsoft Agent Framework: How we designed a layered SDK
Şunu fark ettim: Microsoft Agent Framework Resmî Dokümantasyonu
Microsoft Agent Framework GitHub Deposu
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
Yorum gönder