Geçen hafta Microsoft tarafında Command Line diye yeni bir blog açıldı. Shawn Henry’nın orada yazdığı “Inside the Microsoft Agent Framework” başlıklı yazıyı okuyunca, açık konuşayım, bir süredir kafamda dönen birkaç soruya cevap bulmuş öldüm. Hani şu klasik soru var ya: “Tamam, prompt yazdım, RAG kurdum, tool calling de çalışıyor — peki bunu nasıl üretime taşıyacağım?” İşte MAF tam da bu boşluğu hedefliyor. Evet.
Ben burada kaynak makaleyi birebir çevirmeyeceğim. Zaten öyle yapınca tadı kaçıyor biraz. Onun yerine, kendi sahadan baktığımda — yanı Logosoft’ta kurumsal müşterilerle agent projeleri konuşurken, güvenlikten kimlik yönetimine, maliyet takibinden operasyon tarafına kadar uzayan o uzun masayı düşünün — bu katmanlı SDK yaklaşımı ne anlama geliyor, önü anlatmaya çalışacağım. Türkiye’deki kurumsal gerçeklerle de bağdaştıracağım. Hazırsanız başlayalım.
Önce şunu netleştirelim: Niye “katmanlı” bir SDK?
İlk dalga AI uygulamaları, açık konuşayım, biraz naifti. Bir chat penceresi vardı, arkada bir GPT modeli dönüyordu, üstüne de biraz prompt engineering serpiştiriliyordu; hepsi bu. Sonra RAG geldi. Ardından tool calling çıktı. Şimdi işe durum epey değişti: model artık tek başına bir şey değil, agent dediğin şey de sadece “konuşan model” değil; hafıza, planlama, araç çağırma, gözlemlenebilirlik. Birden fazla agent’ın birbirine ayak uydurması da işin içine giriyor.
Bunu biraz açayım.
İşin garibi, İşin aslı burada şu: SDK’yı tek bir abstraction seviyesinde kurarsan, ya fazla aşağıda kalıyorsun (developer her şeyi sıfırdan yazıyor, sonra ufak tefek hatalar birikiyor), ya da fazla yukarı çıkıyorsun (her şey kapalı kutu gıbı oluyor, debug ederken insanın canı sıkılıyor). Microsoft’un bu kez seçtiği yol — bence de mantıklı olan yol — katmanlı bir mimarı. Yanı altta daha ham primitiveler var, üstteyse daha opinionated, hazır pattern’ler duruyor. Daha açık söyleyeyim, tam da öyle.
Bir benzetme yapayım ama çok uzatmadan. Azure SDK’larını düşünün; Azure.Identity size DefaultAzureCredential veriyor ve çoğu senaryoda bu gayet yetiyor. Ama özel bir ihtiyaç çıkarsa (mesela farklı kimlik doğrulama akışı kullanacaksanız), alta inip ClientSecretCredential ya da ManagedIdentityCredential‘ı doğrudan çağırabiliyorsunuz. MAF de aşağı yukarı aynı kafa ile tasarlanmış; yanı dışarıdan bakınca sade görünüyor,. Içeride elinizi sokabileceğiniz katmanlar var. Evet.
Üç temel kavram: Agent Loops, Workflows, Harnesses
Shawn’ın yazısında üç kavramın altı çiziliyor. Açık konuşayım, bunları tek tek açmak lazım; çünkü dokümantasyonda ilk bakışta biraz havada kalıyor, sonra bir bakıyorsunuz işin omurgası aslında bunlar.
Agent Loop — kalbi burası
Agent loop dediğimiz şey, kabaca “model -> düşün -> araç çağır -> sonucu değerlendir -> tekrar düşün -> cevap ver” döngüsünün soyutlanmış hâli. Kulağa basit geliyor, evet; ama bunu güvenli, gözlemlenebilir ve kontrol edilebilir şekilde yapmak hiç kolay değil, hele ki gerçek dünyada tool sayısı artınca iş iyice dallanıp budaklanıyor.
Geçen ay bir sigortacılık müşterisinde tam olarak şu sorunla boğuştuk: agent sonsuz döngüye giriyor. Aynı tool’u 14 kere çağırıyor, her seferinde aynı sonucu alıyor, ama “yeterli bilgim yok” deyip dönüp duruyor; MAF’taki agent loop tasarımı bu tür şeyleri built-in olarak ele alıyor — iterasyon limitleri, timeout’lar, state takibi falan var. Yanı siz while true yazıp her şeyi elle kontrol etmek zorunda kalmıyorsunuz. İyi tarafı bu. Kötü tarafı? Biraz disiplin istiyor.
Neyse, peki neden önemli? Çünkü agent işi romantik görünse de arkada baya mekanik bir kontrol ihtiyacı var. Şey gıbı düşünün: model akıllı olabilir ama sınır koymazsanız bir noktada kendi etrafında dönmeye başlıyor.
Workflows — birden fazla agent koordinasyonu
İşin asıl ilginç tarafı burası. Tek agent senaryosu (single-agent) bayağı çözüldü artık; ama gerçek dünyada bir tane “müşteri talebi” geldiğinde arka planda 5-6 farklı agent koşması gerekebiliyor, biri belgeleri okuyor, biri compliance kontrolü yapıyor, biri fiyatlandırma çıkarıyor, biri de kararı insana yönlendiriyor — yanı olay düz mantık değil.
İşte workflow’lar bunun için var. Yapısal olarak orchestration pattern’leri sunuyorlar; sequential, parallel, conditional, human-in-the-loop… Bu kısım bence MAF’ın en işe yarar taraflarından biri. Daha önce Microsoft Agent Framework BUILD 2026: Saha Notlarım ve yazısında biraz değinmiştim. Orada Build duyuruları açısından bakmıştım; bugün SDK katmanlı tasarımına odaklanalım. Neyse uzatmayayım, burada mesele “agent var” demek değil, “agent’lar nasıl sıraya giriyor” sorusunu çözmek (ciddiyim)
Bir dakika — bununla bitmedi.
E sonra? Eğer bu koordinasyonu elle kurmaya kalkarsanız kod kısa sürede çorba oluyor. Workflow tam da o çorbayı biraz toparlıyor diyeyim.
Harnesses — yeniden kullanılabilir runtime yetenekleri
Eh, Harness kavramı biraz daha az tanıdık geliyor olabilir. Şöyle düşünün: agent’ınızın ihtiyaç duyduğu ortak hizmetler var; bellek, planlama, middleware, telemetry, güvenlik kontrolleri… Bunları her agent için sıfırdan yazmıyorsunuz, harness’lar olarak takıp çıkarıyorsunuz. Bak şimdi kilit nokta şu: burada tekrar eden altyapıyı ayırınca hem test kolaylaşıyor hem de aynı davranışı farklı senaryolarda kullanabiliyorsunuz.
Bence harness yaklaşımı MAF’ı sadece bir “framework” olmaktan çıkarıp gerçek bir platform’a dönüştüren tasarım kararı. Çünkü kurumsal müşteri ne ister? Audit log ister, RBAC ister, observability ister; harness’lar bunları standartlaştırıyor ve ekiplerin her projede aynı tekeri yeniden icat etmesini engelliyor.
Daha açık söyleyeyim, tam da öyle.
Katmanları somutlaştıralım: tipik bir kurumsal senaryo
İşin garibi, Lafı dolandırmadan örneğe gireyim. Diyelim ki bir telekom müşterisi için “abonelik iptal” sürecini agent’a devretmek istiyorsunuz; müşteri arıyor, agent dinliyor, gerekli kontrolleri yapıyor, sonra da bazı durumlarda işi insana eskaliasyon ediyor. Mantıklı değil mi? Basit gıbı duruyor, ama işin içine CRM, billing, güvenlik ve kayıt tarafı girince tablo bir anda değişiyor.
Bir dakika — bununla bitmedi.
Bu senaryoyu MAF katmanlarına ben şöyle ayırırım:
| Katman | Sorumluluk | Örnek |
|---|---|---|
| Agent Loop | Model + tool çağrıları + state | “Müşteri ID’sını al, CRM’den çek, iptal sebebini sor” |
| Harness | Bellek, telemetry, güvenlik | Konuşma geçmişini sakla, PII’yı maskele, App Insights’a logla |
| Workflow | Çok adımlı orkestrasyon | İptal → Compliance kontrolü → Onay → CRM güncelleme |
| Entegrasyon | Dış sistem bağlantıları | CRM API, billing sistemi, Teams bildirimi |
Burada asıl kilit nokta şu: herkes her şeyi yapmaya çalışmıyor. İyi de oluyor bu. Workflow tarafına bakan ekip akışı toparlıyor, agent loop’u yazan ekip modelin davranışını kurcalıyor, harness tarafındaki ekip işe güvenlik. Izleme işlerini sıkı tutuyor (özellikle PII maskeleme kısmını hafife almayın). Kısacası roller ayrılınca kafa da biraz rahatlıyor. Bu konuyla ilgili Cosmos DB Güvenliği: Yeni Projede İlk Gün Kararları yazımıza da göz atmanızı tavsiye ederim.
Peki neden önemli? Çünkü yarın öbür gün iptal sürecine yeni bir compliance adımı eklemek istediğinizde bütün sistemi yeniden yamalamıyorsunuz. Sadece ilgili katmanı oynuyorsunuz. Evet, bazen entegrasyon tarafında minik sürprizler çıkıyor; ama en azından nerede patladığını daha çabuk görüyorsunuz.
Pratik bir kod örneği — basit bir agent
Dokümantasyondan birebir kopya değil, kendi denediğim minimal örnekten esinlenerek yazıyorum, çünkü bazen en iyi fikirler uzun uzun anlatılan şemalardan değil, iki satır kurcalayıp “ha tamam” dediğiniz yerden çıkıyor, hani şu küçük ama iş gören örnekler var ya, işte onlardan biri.
// C# tarafından basit bir agent tanımı
var agent = new ChatClientAgent(
chatClient: azureOpenAIClient.AsChatClient("gpt-4o"),
instructions: "Sen bir IT destek asistanısın. Kısa cevap ver.",
tools: new[] {
AIFunctionFactory.Create(GetTicketStatus),
AIFunctionFactory.Create(CreateIncident)
});
// Middleware ekleyelim — harness mantığı
agent.Use(new TelemetryMiddleware(appInsights));
agent.Use(new ContentSafetyMiddleware(contentSafetyClient));
var response = await agent.RunAsync("PRINT-552 sorununu çöz");
Şunu söyleyeyim, Burada gözümün takıldığı şey middleware pattern’i öldü. ASP.NET Core’dan tanıdık geliyor, evet; aynı damar. Ama dür bir saniye — bu benzerlik sadece “alışık hissettiriyor” seviyesinde kalmıyor,.NET tarafından gelen developer’lar için öğrenme eğrisini baya aşağı çekiyor, üstelik Python tarafında da benzer bir yaklaşım görüyorsunuz, yanı iş bayağı yabancı gelmiyor (ciddiyim) Bu konuyla ilgili Visual Studio 2026: Tema Renklerini Artık Siz Yönetiyorsunuz yazımıza da göz atmanızı tavsiye ederim.
Kısa bir not düşeyim buraya. Daha fazla bilgi için PostgreSQL’in Geleceği: Microsoft’tan Commit’ten Bulut’a yazımıza bakabilirsiniz.
Türkiye’deki kurumsal yapılar için ne anlama geliyor?
Açık konuşayım, Türkiye’deki kurumsal müşterilerin çoğunda hâlâ “AI agent” denince gözün önüne bir chatbot geliyor. Ama işin rengi değişiyor, baya da hızlı değişiyor; özellikle bankacılıkta, telekomda ve sigortacılıkta son 6 ayda gördüğüm şey şu: insanlar artık “agent” derken arka ofiste dönen bir süreci otomatikleştiren yapıyı kastediyor, yanı RPA’nın LLM’li hâli gıbı düşünün.
İşte tam burada MAF’ın katmanlı yaklaşımı bence fena değil, hatta kurumsal tarafta ciddi rahatlık sağlıyor. Çünkü kurumsal müşteri ne istiyor, peki? Bir yandan kararın izini sürmek istiyor, bir yandan KVKK tarafında kafası rahat olsun istiyor, üstüne insan onayı gerektiğinde bunu workflow içinde düzgünce görmek istiyor (ve tabii maliyetin de uçup gitmemesini bekliyor), (bu konuda ikircikliyim). Olay sadece model çağırmak değil. Daha fazla bilgi için Opus 4.6 (fast) Copilot’ta Emekli Oluyor: Geçiş Notları yazımıza bakabilirsiniz.
- Auditability: “Bu agent niye bu kararı verdi?” sorusuna cevap verebilmek. Harness katmanındaki telemetry burada devreye giriyor. — ciddi fark yaratıyor
- KVKK/Compliance: PII’nın nereye gittiği, log’larda ne tutulduğu. Middleware ile maskeleme, segregation.
- Insan kontrolü: Belli eşiklerde mutlaka human-in-the-loop. Workflow katmanında native destek var.
- Maliyet kontrolü: Token kullanımı, kaç defa hangı model çağrıldı. Observability ile bağlantılı. (bu kritik)
Ne yalan söyleyeyim, Bir banka projesinde geçen aralarda — adını veremiyorum tabi — şöyle bir durumla karşılaştık: regulatory ekip “agent’ın aldığı her karar için 7 yıl saklanabilir log istiyoruz” dedi. Eski mimaride bu iş gerçekten uğraştırıyordu; ama MAF tarzı bir yapıda harness seviyesinde standart bir telemetry sink ayarlayıp Azure Monitör’a yazdırınca mesele baya toparlanıyor (sıfırdan custom kod yazmadan ilerliyorsunuz). Evet, kritik nokta da bu zaten.
İşte tam da bu noktada devreye giriyor.
Enterprise vs Startup: hangı katmandan başlamalısınız?
Burada işi ikiye ayırmak lazım, çünkü sahada gördüğüm senaryolar gerçekten aynı değil. Kısa cevap şu: her ekip aynı yerden başlamıyor, hatta bazen aynı problemi bile farklı çözüyor.
Startup veya küçük ekipseniz: Agent loop seviyesinde kalın. Tek bir agent, birkaç tool, basit bir UI yeterli oluyor; workflow’a baştan abanmanıza gerek yok. Harness’lardan işe sadece telemetry’yi açın, çünkü prod’a çıkınca hangı tool’un ne kadar maliyet yediğini görmek istiyorsunuz, yoksa sonra “bu niye bu kadar pahalı öldü?” diye kafayı duvara vurursunuz.
İnanın, Evet. Daha fazla bilgi için Agents League Hackathon 2026: Enterprise Agents Sahnede yazımıza bakabilirsiniz.
Enterprise yapıdaysanız: İlk günden workflow ve harness katmanını planlayın. Peki neden? Çünkü 6 ay sonra dönüp “bunu yeniden mimarlayalım” demek istemezsiniz; açık konuşayım, o cümle genelde kimsenin hoşuna gitmez. Mesela compliance harness’ı, content safety middleware. Insan onayı checkpoint’leri tasarımın içine baştan koyun (sonradan eklemeye çalışınca iş büyüyor), ayrıca Foundry Observability Build 2026: Agent’tan ROI’ye Tam tarafındaki gözlemlenebilirlik araçlarını da dahil edin — agent ROI’sını ölçmek için bunlar baya iş görüyor.
Neyse, çok dağıtmadan söyleyeyim: küçük ekipte hız kazanmak için sade kalmak daha mantıklı, enterprise tarafta işe ilk gün biraz ağır davranmak sonradan sızı rahatlatıyor. E peki, sonuç ne öldü? İkisi de doğru; sadece başlangıç noktası farklı.
Maliyet tarafı: TL bazında bir hesap
FinOps şapkamı takayım. MAF kendi başına para yutmuyor, framework açık kaynak; asıl fatura altyapıdan geliyor, işte olay burada biraz ters köşe yapıyor:
- Model çağrıları (Azure OpenAI veya Foundry) — bunlar token bazlı
- Hosting (App Service, Container Apps veya AKS) — ciddi fark yaratıyor
- Observability (App Insights, Log Analytics) — ciddi fark yaratıyor
- Vector store (Azure AI Search veya alternatifi)
Tipik bir kurumsal POC için aylık baseline 8.000-15.000 TL civarı tutar — model kullanımına göre çok değişiyor tabi. Üretime çıkınca işler hafif şişiyor; (belki yanılıyorum ama) agent başına ayda 3-5 bin çağrı varsayımıyla, GPT-4o seçerseniz model maliyeti ayda 25.000-40.000 TL’ye kadar çıkabiliyor, hani ilk bakışta “bu kadar mı?” dedirtiyor ama yük gerçekten orada birikiyor. Eğer maliyet kritikse, harness katmanında bir model routing middleware yazıp basit sorguları küçük modele yönlendirin — gerçekten karmaşık olanları GPT-4o’ya bırakın, yanı işi akıllıca bölmek lazım. Foundry Agent Optimizer: Prompt’u Makine Yazsın Devri tarafındaki optimizasyon teknikleri de prompt token’larını ciddi düşürebiliyor.
İlk başlangıç için pratik adımlar
Bu yazıyı okuyup “tamam, deneyeceğim” diyorsanız, ben olsam şöyle giderim: önce ufak başlarım, sonra yavaş yavaş genişletirim, çünkü ilk günden her şeyi aynı sepete koyunca insanın kafası çorba oluyor.
- Azure OpenAI veya Foundry’de bir model deploy edin. Boş bir resource group’ta gpt-4o-mini ile başlayın — ucuz ve hızlı. Açık konuşayım, burada amaç gösteriş değil; sadece ayağa kalksın yeter. İlk denemede pahalı modele abanmak gereksiz yere can sıkıyor.
- NuGet’ten Microsoft.Agents.AI paketini yükleyin. Python tarafı için
pip install agent-framework. Şey, küçük gıbı duruyor ama bu adım olmadan sonraki işlerin çoğu zaten yürümüyor. Paket kuruldu mu? Tamamdır, artık elinizde oynayacak bir zemin var. - İlk agent’ı tek tool ile çalıştırın. Mesela hava durumu sorgusu gıbı basit bir şey. Sadece akışı anlayın. Burada kasmaya hiç gerek yok; tek tool ile başlayınca prompt mu gidiyor, tool mu dönüyor, response nasıl şekilleniyor, bunları net görüyorsunuz. — ciddi fark yaratıyor
- Telemetry middleware ekleyin. App Insights connection string’i koyun, hangı tool ne kadar sürede çağrılıyor görün. Hani çoğu kişi bunu sonra ekler ya, bence tam tersi daha iyi; çünkü sorun çıkınca “nerede takıldı?” sorusunun cevabı elinizin altında oluyor. Evet, biraz ekstra uğraş veriyor. — bunu es geçmeyin
- İkinci agent ekleyip workflow deneyin. Sequential bir akış kurun, birinin çıktısı diğerinin girdisi olsun. Bak şimdi iş değişiyor; ilk agent veri hazırlıyor, ikinci agent önü işliyor ve aradaki geçişi görünce sistemin nerede dağıldığını da daha rahat yakalıyorsunuz. — ciddi fark yaratıyor
- Sonra harness’larla zenginleştirin: bellek, content safety, RBAC. Az önce “önce basit başla” dedim ama burası da boş geçilmiyor; özellikle güvenlik ve erişim tarafı devreye girince iş biraz ciddileşiyor. Siz ne dersiniz?
Bu sırayla giderseniz her adımda bir şey öğreniyorsunuz ve sıkışırsanız nereye bakacağınızı da biliyorsunuz. Doğrudan workflow + multi-agent ile başlarsanız debugger içinde kaybolursunuz. Lafı gevelemeden söyleyeyim, o yol biraz yoruyor. Neyse uzatmayalım: önce küçük kazanım alın, sonra büyütün.
Tam da öyle.
Eleştirim ve hayal kırıklıkları
Bi saniye — Tabi her şey güllük gülistanlık değil. İlk denediğimde, Python ile.NET sürümleri arasında API isimlendirmesi biraz can sıkıyor; bir tarafta run_async, öbür tarafta RunAsync var, tamam dil farkı dersin ama parametre adları da yer yer değişiyor, işte orada insanın kafası hafif karışıyor — valla güzel iş çıkarmışlar —. Dokümantasyon tarafında da Python şu an daha zayıf duruyor, açık konuşayım.NET örnekleri işe daha toparlanmış, daha az dağılıyor.
Bir de workflow’ların görsel tasarımcısı yok — yanı Logic Apps’teki gıbı sürükle-bırak bir ekran beklemeyin. Her şey kod üzerinden gidiyor. Bu bazı kurumsal müşteriler için eksi yazabilir, hatta baya yazabilir; business analyst’lerin agent tasarlamasını istiyorsanız Copilot Studio tarafı daha mantıklı ölür (en azından ilk bakışta öyle) (evet, doğru duydunuz). MAF işe net biçimde developer-first bir araç. Evet.
Sıkça Sorulan Sorular
Microsoft Agent Framework, Semantic Kernel’ın yerini mi alıyor?
Kısaca evet. MAF, aslında Semantic Kernel ve AutoGen’in birleşiminden doğan yeni nesil bir framework. Mevcut SK projelerinizi hemen migrate etmeniz gerekmiyor — geriye dönük uyumluluk var, merak etmeyin. Ama yeni bir şeye başlıyorsanız, bence doğrudan MAF ile gitmeniz çok daha mantıklı.
MAF sadece Azure OpenAI ile mi çalışıyor?
İtiraf edeyim, Hayır, yanı bu konuda oldukça esnek aslında. OpenAI, Azure OpenAI, Anthropıc, Ollama gıbı farklı sağlayıcılarla rahatça çalışabiliyor. Her şey IChatClient arayüzü üzerinden soyutlanmış — modelinizi değiştirmek tek satırlık iş. On-prem model çalıştırıyorsanız da Foundry Local entegrasyonu mevcut.
Workflow ve agent loop arasındaki fark nedir, ne zaman hangisini kullanmalıyım?
Agent loop, tek bir agent’ın “düşün-araç çağır-cevap ver” döngüsü (buna dikkat edin). Workflow işe birden fazla adımı veya agent’ı koordine eden üst katman, yanı biraz daha büyük resme bakıyor. Mesela tek agent + birkaç tool işinizi görüyorsa agent loop gayet yeterli. Ama birden fazla agent’ın sırayla ya da paralel çalışması gerekiyorsa, o zaman workflow devreye giriyor.
Production’da MAF kullanmak için hangı sertifikalar veya bilgiler gerekli?
Açıkçası zorunlu bir sertifika yok. Ama AZ-104 (Azure temelleri), AI-102 (Azure AI Services) ve AZ-204 (developer) kombinasyonu gerçekten çok işe yarıyor. Bu ne anlama geliyor? Tecrübeme göre mesela AI-102 hazırlığında öğrendiğiniz observability ve content safety pattern’lerini MAF projelerinde direkt uygulayabiliyorsunuz — o bilgiler boşa gitmiyor.
MAF’i lokal geliştirme ortamında deneyebilir mıyım?
Net bir şekilde evet. Ollama veya Foundry Local kullanarak büyük çoğunluk framework’ü internet bağlantısı olmadan deneyebilirsiniz. Bu özellikle prototip aşamasında hani çok rahat bir şey — token harcamadan, hiçbir yere bağlanmadan istediğiniz kadar deneme yapabiliyorsunuz.
Kaynaklar ve İleri Okuma
Inside the Microsoft Agent Framework: How we designed a layered SDK (Shawn Henry, orijinal yazı)
Şahsen, Microsoft Agent Framework Resmî Dokümantasyonu
Microsoft Agent Framework GitHub Reposu
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.
