Microsoft Agent Framework ile .NET’te Ajan Kurmanın İncelikleri
Bir agent, chatbot’tan neden farklı?
İşin aslı şu: çoğu ekip “AI yaptık” deyince hâlâ bir sohbet kutusu açıp modelden cevap bekliyor. Güzel, ama biraz ham kalıyor. Benim kafamda agent dediğimiz yapı işe sadece (belki yanılıyorum ama) konuşmuyor; iş yapıyor, karar veriyor, araç çağırıyor ve gerektiğinde geri dönüp yeniden deniyor. Yanı hani bir asistana not verirsiniz ya, “şunu araştır, bunu kontrol et, sonra bana dön” dersiniz — işte o çizgiye geçiyorsunuz.
Ben bu farkı ilk kez 2024 sonlarında bir finans müşterisinde çok net gördüm. Sadece soru-cevap yapan bir bot kullanıcıyı tatmin etmiyordu; çünkü sorunun yarısı cevapta değil, işlemdeydi. Müşteri temsilcisi hangi kaydı açacak, hangi API çağrılacak, hangi yetki kontrol edilecek… Bunları tek tek koda gömmek yerine agent mantığına yaklaşınca sistem bayağı toparlandı. Bu arada küçük bir not: agent her zaman daha iyi demek değil (bizzat test ettim). Bazı senaryolarda düz akış hâlâ daha güvenli ve ucuz.
Microsoft Agent Framework burada devreye giriyor..NET tarafında özellikle hoşuma giden şey şu: MEAI ile. Model katmanını sadeleştirmişsinizdir, VectorData ile bilgi erişimini oturtmuşsunuzdur; şimdi sıra “bu model ne yapacak?” sorusuna geliyor. Agent Framework tam bu boşluğu dolduruyor. Ben buna biraz da AI projesinin omurgası diyorum.
Bir dakika — bununla bitmedi.
Agent mantığını günlük hayattan düşünün
Mesela bir çalışana “hava durumuna bak” demek başka şeydir, “yarın İstanbul’daki toplantıya göre kıyafet önerisi çıkar” demek bambaşka şeydir. İkinci cümlede kişi sadece veri çekmiyor; bağlam kuruyor, dış kaynaktan bilgi alıyor ve sonuç üretiyor. Agent tam olarak bu ikinci seviyede dürüyor.
Garip gelecek ama, Burada hayatı nokta şu: ajanın eline sınırsız özgürlük vermek çoğu zaman kötü fikir oluyor. Bunu 2019’da kendi lab ortamımda denemiştim; araç sayısını abartınca model bazen en gereksiz aracı seçip dolaşıp duruyordu (kendi tecrübem). Sonra araçları daralttık, izinleri sıkılaştırdık, davranış belirginleşti (en azından benim deneyimim böyle). Yanı evet, özgürlük güzel ama kontrollü özgürlük daha iyi.
Çok konuştum, örnekle göstereyim.
Agent tasarlarken benim altın kuralım şu: modeli zeki yapmaya çalışırken sistemi savunmasız bırakmayın.
İlk ajanınızı kurarken neler dikkatimi çekti?
.NET’te ilk ajanı ayağa kaldırmak kağıt üstünde çok kolay görünüyor ve açık konuşayım, gerçekten de öyle başlıyor. Azure OpenAI istemcisi üzerinden chat client alıyorsunuz, sonra önü AsAIAgent ile ajana çeviriyorsunuz. Kulağa ufak bir köprü gibi geliyor ama etkisi büyük; çünkü artık yalnızca mesaj döndürmüyorsunuz, davranış tanımlıyorsunuz.
Benim hoşuma giden taraflardan biri bu yaklaşımın mevcut MEAI alışkanlıklarını bozmaması öldü (ki bu çoğu kişinin gözünden kaçıyor). Bir sürü platformda yeni framework gelince eski kodu çöpe atmanız gerekir ya — burada öyle kaba saba bir kopuş yoktu. Geçiş yumuşak hissediliyor.
Ama şunu da söyleyeyim: ilk denemede ben de klasik hata aldım — ortam değişkenini eksik set etmişim. Uygulama direkt patladı. Bilhassa AZURE_OPENAI_ENDPOINT veya deployment adı unutulunca uğraştırıyor… Neden önemli bu? Çözüm basit tabiî ama ilk anda insanın canını sıkıyor! Denemek isteyen biriyseniz önce kimlik doğrulama tarafını halledin; aksi hâlde framework değil sizin ortamınız ağlar.
Küçük örnekle başlayalım
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
? "gpt-5.4-mini";
AIAgent agent = new AzureOpenAIClient(
new Uri(endpoint),
new DefaultAzureCredential())
.GetChatClient(deploymentName)
.AsAIAgent(
instructions: "You are good at telling jokes.",
name: "Joker");
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));Burada en sevdiğim detay instructions kısmının açık olmasıdır aslında. Agent’a karakter veriyorsunuz ama bunu roman yazarmış gibi uzatmıyorsunuz (neyse uzatmayayım). Kısa talimatlar çoğu zaman daha iyi çalışıyor çünkü modelin kafası karışmıyor. Bu konuyla ilgili Microsoft Discovery ile Ar-Ge’de Yeni Oyun: Agentic Yapılar yazımıza da göz atmanızı tavsiye ederim.
Araç çağırma işi neden oyunu değiştiriyor?
Bir şey dikkatimi çekti: Ajanların asıl olayı tool calling tarafında ortaya çıkıyor diyebilirim (evet, doğru duydunuz). Çünkü model tek başına tahmin üretiyor; tool eklediğinizde işe gerçek dünyaya dokunmaya başlıyor — veri çekiyor, işlem başlatıyor, hesap yapıyor ya da başka servislere gidiyor.
Kendi deneyimimde en faydalı kullanım alanları hep aynı yerlere çıktı: CRM sorgusu, servis masası işlemleri, bulut kaynak kontrolü ve rapor üretimi… En çok da 2025 yazında Ankara’daki bir kurumsal müşteride destek ekibi için kurduğumuz prototipte ajan önce kayıtları taradı, sonra ilgili API’yi çağırdı. Sonunda operatöre kısa özet verdi. İnsan eli değmeden süreci bitirmedi ama ciddi hız kazandırdı (yanlış duymadınız)
İşte tam da bu noktada devreye giriyor. Entra Agent ID GA: Sponsor Grup Tipi Kuralları Değişti yazımızda bu konuya da değinmiştik.
| Kullanım tipi | Küçük ekip | Büyük kurum |
|---|---|---|
| Sade sohbet ajanı | Hızlı başlar | Sınırlı değer verir |
| Araç kullanan agent | Dikkatli kurulmalı | Bayağı iş görür |
| Çoklu agent orkestrasyonu | Zorlayıcı olabilir | Daha mantıklı hâle gelir |
| Sert politika + audit log | Tavsiye edilir | Zaten şarttır |
Neyse ki framework burada işleri toparlıyor ama eksik taraf yok mu? Var tabi… Tool sayısı büyüdükçe gözlemleme ihtiyacı artıyor ve debug süresi uzayabiliyor. Bir bakıma, en çok da üretimde “hangi adımda niye sapıtıldı?” sorusu önemli hâle geliyor.
Bence Türkiye’de en hayatı mesele güvenlikten çok disiplin meselesi…
Bunu Türkiye’deki şirketler açısından değerlendirecek olursam tablo biraz farklılaşıyor. Kurumsal müşterilerimde gördüğüm kadarıyla bizde ekipler çoğu zaman teknolojiyi hevesle dener ama operasyonel standardizasyon kısmını sonradan düşünürler… Sonuç? İlk PoC fena değildir ama ölçeklenince dağılır. Bu konuyla ilgili Azure Accelerate for Databases: AI İçin Veriyi Hızlandırmanın Yeni Yolu yazımıza da göz atmanızı tavsiye ederim. .NET ve PostgreSQL ile Azure’da Cache’i Ciddiye Almak yazımızda bu konuya da değinmiştik. Daha fazla bilgi için VSIX İçin SDK-Style Proje Desteği: Build Süresi %75 Azalıyor yazımıza bakabilirsiniz.
Açık konuşayım: Türkiye’de birçok şirket için asıl sorun teknoloji değil maliyet algısı oluyor. Azure OpenAI + agent mimarisi TL bazında bakınca bazı ekiplerde “bu pahalı mı?” sorusunu doğuruyor. Evet pahalı olabilir; özellikle gereksiz token tüketiyorsanız fatura hızlı şişer. Bu yüzden küçük startup iseniz tek ajanla başlayıp sadece kritik işlemlerde tool kullanmanızı öneririm. Enterprise tarafta işe ayrı roller tanımlayın; gözlemleme,onay mekanizması ve limitler koyun. Bütçe kısıtlıysa her şeyi LLM’e yaptırmayın — bazı işleri klasik kodla çözmek hâlâ daha ucuz ve sağlamdır.
Tek ajan mı çoklu ajan mı?
This part beni en çok düşündüren yerlerden biri öldü diyebilirim—evet İngilizce kaçtı biraz ama mevzu tam oraya bağlanıyor aslında (tek cümlede bile). Tek ajan yaklaşımı sade ve yönetilebilir olurken multi-agent yapı size esneklik veriyor fakat beraberinde koordinasyon yükü getiriyor.
Lafı gevelemeden söyleyeyim: Her projede multi-agent istemiyorum ben mesela… Çünkü sırf havalı dürüyor diye çoklu yapı kurmak bana pek doğru gelmiyor.Bir bankacılık çözümünde belge sınıflandırma için iki ayrı uzman ajan kurguladığımızda sonuç iyiydi; biri sınıflandırma yaptı biri kalite kontrol etti ama bunun karşılığında orchestration karmaşıklığı da geldi — dürüst olayım, biraz hayal kırıklığı —. yanı bedava değildi! Eğer süreç netse tek ajan daha temiz kalabilir.
Kullanım senaryosuna göre seçim yapın
Sihir burada değil…
- Eğer iş akışı basitse tek agent yeterli olur.Eğer aynı anda farklı uzmanlıklar gerekiyorsa multi-agent mantıklı hâle gelir.Eğer denetim önemliyse her adımı loglamak şarttır.Eğer bütçe hassassa tool sayısını azaltmak gerekir.Eğer büyüyen bir ürününüz varsa orkestrasyonu erken planlamak iyidir.
h3>Deneyimlerimin öğrettiği pratik adımlar
AZ-305 sınavına hazırlanırken dağıtık sistemlerdeki bağımlılık ilişkilerini ezberlemek yerine akışları çizerek öğrenmiştim. Aynısını agent mimarisinde de yaptığınızda kafanız rahatlıyor. İlk adım olarak neyin araç, neyin hafıza, neyin karar olduğunu ayırın; sonra güvenlik sınırlarını çizin; ardından loglama ekleyin. Bu üçlü olmadan production’a çıkmak bana göre erken davranmak olur.
Bir diğer konu da entegrasyon seçimleri. Mesela eğer elinizde zaten Service Bus, Cosmos DB ya da PostgreSQL varsa, ajanın gidip bunlarla kontrollü konuşması güzel iş çıkarır. Ama her şeyi doğrudan modele açarsanız hem maliyet hem güvenlik tarafı sert şekilde can yakar. Ben Logosoft’taki bazı projelerde önce ince yetkili servis katmanı koydum, sonra ajanı onun üstüne bindirdim; performans da düzen de bariz düzeldi.
Ha bu arada, küçük ekiplerle enterprise ekiplerin önceliği aynı olmuyor. Startup tarafında hızlı demo önemli; kurumsalda işe izlenebilirlik, onay akışı ve rollback planı önemli. Yanı teknik olarak aynı framework kullanılıyor olabilir ama tasarım dili değişiyor. Biri “hemen gösterelim” derken diğeri “yarın audit gelir mi？” diye bakıyor.
Geliştirirken takıldığım yerler:küçük sürprizler büyük etki yapıyor
Bu servisi ilk denediğimde benim tarafta tuhaf bir gecikme problemi yaşamıştık. Meğer sebep modelin kendisi değilmiş; tool response dönüyor ama bizim adapter katmanı sonucu düzgün sarmalamıyormuş. Çözümü bulunca yüzüm düştü biraz, çünkü sorun sandığım kadar büyük değildi. İşte böyle anlarda framework’ten ziyade kendi entegrasyon katmanınıza bakmanız gerekiyor.
Bir de şunu söyleyeyim:agent’lar için test yazmak klasik API testinden biraz farklı. Sadece çıktı doğru mu diye bakmak yetmiyor, aracın doğru sırada çağrılıp çağrılmadığını da doğrulamak gerekiyor. Geçen yıl İzmir’deki bir müşteriyle bunu yaşadık; unit test geçiyordu ama uçtan uca testte ajanın gereksiz yere ikinci tool’u tetiklediğini gördük: O noktada prompt’u kısaltınca problem çözüldü.
Bence Microsoft Agent Framework doğru yönde atılmış bir adım,ama henüz cilası tam bitmiş değil. Kağıt üstünde süper görünen bazı parçalar pratikte biraz daha pişmek istiyor. Hele bir de observability and policy management konusu büyüdükçe daha fazla önem kazanacak. Bugün çalışan şey yarın üretimde yeterli olmayabilir—burası net.
>
Sıkça Sorulan Sorular
Microsoft Agent Framework nedir?
Microsoft Agent Framework, aslında.NET içinde AI agents geliştirmek için kullanılan bir SDK yaklaşımı. Model çağrısını araç kullanımı, hafıza ve orkestrasyonla birleştiriyor. Yanı kısacası sadece cevap veren değil, gerçekten işlem yapan uygulamalar kurmanıza yardımcı oluyor.
Tek ajan mı yoksa çoklu ajan mı tercih edilmeli?
Karmaşıklığı düşük projelerde tek ajan genelde yeterli oluyor. Bence başlangıçta işi basit tutmak her zaman kazandırıyor. Ama birden fazla uzmanlık alanı veya ayrılmış görev zinciri varsa multi-agent yapı çok daha uygun. Bu ne anlama geliyor? Küçük ekiplerde sadelik öne çıkıyor, enterprise tarafta işe koordinasyon gücü fark yaratıyor.
Tool calling kullanırken en önemli risk nedir?
En büyük risk aşırı yetkilendirme ve kontrolsüz yan etkiler. Ajanların her araca erişmesi ciddi güvenlik sorunlarına yol açabiliyor. Tecrübeme göre izinleri dar tutmak, log almak ve gerekiyorsa insan onayı eklemek gerçekten iyi bir fikir.
Üretimde kullanmadan önce neyi muhtemelen test etmeliyim?
Araç sırası, hata yönetimi, timeout davranışı ve prompt stabilitesi mutlaka test edilmeli. Sadece çıktı testi yetmiyor; aracın yanlış yerde tetiklenmediğinden emin olmak çok önemli. Açıkçası maliyet takibini de ihmal etmemek gerekiyor, hani sonradan sürprizle karşılaşmak istemezsiniz (inanın bana)
Kaynaklar ve İleri Okuma
Orijinal Microsoft Blog Yazısı — Microsoft Agent Framework – Building Blocks for AI Part 3
Azure AI Foundry Resmî Dokümantasyonu (ciddiyim)
Microsoft GitHub Depoları / Başlangıç Kaynakları
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.
3 comments