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.
📋 İçindekiler
-
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ı,
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.
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.
💡 Bilgi: Ajan sistemlerinde en sık gördüğüm hata şu: geliştirme ortamında her şey tıkır tıkır giderken üretimde “neden bu ajan bu kararı verdi?” sorusunun havada kalması. İlk gün observability planlamayan ekipler ikinci ayda ciddi can sıkıntısı yaşıyor; trace’lerinizi, prompt versiyonlarınızı ve tool çağrı sonuçlarınızı en başından kayıt altına alın.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
Bu yazı yapay zeka (büyük dil modelleri) ile hazırlanmış, insan editör tarafından incelenmiştir. İçerik üretim sürecimiz.Aşkın KILIÇYazar20+ 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.
AZ-305AZ-104AZ-500AZ-400DP-203AI-102İlgili Yazılar
İlginizi Çekebilir
Aslı S.
Katmanlı mimari kısmı çok yerinde bir yaklaşım, özellikle state yönetimi production’da gerçekten baş belası olabiliyor. Peki denetlenebilirlik için özel bir tool mu sunuyor yoksa mevcut observability stack’leriyle mi entegre oluyor?
Ebru G.
State yönetimi ve denetlenebilirlik konularında production’da gerçekten çok sorun yaşıyoruz. MAF’ın bu katmanlı yaklaşımı teoride güzel duruyor ama merak ettiğim şu: mevcut LangChain veya AutoGen tabanlı projelere entegrasyon ne kadar ağrısız oluyor?
2 comments