Agent Framework ile Claw Mimarisi: İlk Ajanı Üç Adımda Kurmak
Bir şey dikkatimi çekti: Bir model çağrısının etrafına döngü kurup ona “ajan” demek… Kulağa basit geliyor, değil mi? Aslında evet, baya basit. Ama işin içine planlama, hafıza, araç çağırma ve hata yönetimi girince tablo bir anda değişiyor; Microsoft’un yeni Agent Framework’ü de tam burada devreye giriyor — döngüyü hazır veriyor, sen sadece ajanını “senin yapan” parçaları ekliyorsun.
Bu yazıda Wes Steyn’in “agent harness and claw” konseptini kendi bakış açımla anlatmaya çalışacağım. Kafamda netleştirmek için aylardır farklı framework’lerle uğraşıyorum (Semantic Kernel, LangGraph, AutoGen derken liste uzayıp gidiyor), yanı konuya dışarıdan bakmıyorum; Agent Framework biraz farklı bir noktada dürüyor ve ben de önü farklı kılan şeyleri, bir de Türkiye’deki kurumsal projelerde nasıl konumlanır önü yoklayacağım.
Bir dakika — bununla bitmedi.
“Claw” Nedir, “Harness” Nedir, Niye Önemli?
Önce terimleri oturtalım çünkü Microsoft tarafı bu konuda biraz şairane konuşuyor. Harness dedikleri şey, modelin etrafındaki tüm “sistem” — yanı fonksiyon çağırma, geçmişi tutma, planlama, web araması, akış yönetimi; claw işe bu harness’a takılan ajanın kendisi: talimatları, özel araçları, kişiliği.
Yanı harness pantolon, claw da senin. Pantolon herkes için aynı, ama nasıl giydiğin sana özel. Lafı gevelemeden söyleyeyim: bu ayrım göründüğünden daha kıymetli. Çünkü daha önce her ajan framework’ünde aynı şeyi yaşadık — döngüyü, retry’ı, tool dispatch’i, history persistence’ı kendin kuruyordun. Saatler gidiyordu. Hatta bazen gün gidiyordu.
Agent Framework’ün vaadi şu: bu plumbing kısmını tek satıra indirelim, sen sadece domain mantığına odaklan. Kulağa hoş geliyor. Bakalım pratikte ne kadar tutuyor (şaşırtıcı ama gerçek). Peki neden önemli? Çünkü çoğu ekip aslında ajan yazmıyor; tekrar eden altyapıyı yeniden yazıyor.
Üç Adımda Kişisel Finans Asistanı
Orijinal makaledeki örnek bir kişisel finans asistanı: watchlist’i gözden geçirip yeni hisse öneren bir ajan. Üç yeteneği var:
- Özel bir araç: get_stock_price — hisse fiyatı çeken fonksiyon
- Web search — piyasa haberlerini taramak için
- Planning — “watchlist’ımı gözden geçir ve yeni hisse öner” gibi muğlak istekleri adım adım plana çevirmek
Yapı basit gibi dürüyor. Önce bir chat client kuruyorsun, sonra önü harness’a sarıyorsun, sonra konsol döngüsüne bağlıyorsun; kağıt üstünde iş bitmiş gibi görünüyor ama pratikte küçük ayrıntılar hemen ortaya çıkıyor (özellikle auth ve telemetry tarafında), o yüzden “bitti” demek biraz iddialı olur.
1. Adım: Chat Client’i Kur
Her şey chat client ile başlıyor — modele konuşan parça. Endpoint, credential, deployment adı..NET tarafında şöyle görünüyor: (yanlış duymadınız)
// Ortam degiskenlerinden okuyoruz
var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT tanimli değil.");
var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ? "gpt-5.4";
// Foundry projesi üzerinden IChatClient olusturuyoruz
IChatClient chatClient =
new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
.GetProjectOpenAIClient()
.GetResponsesClient()
.AsIChatClient(deploymentName);Python tarafı daha kısa:
client = FoundryChatClient(credential=AzureCliCredential())Dürüst olmak gerekirse, Burada dikkat edilmesi gereken bir nokta var: DefaultAzureCredential lokalde az login session’ını kullanır, ama production’a çıkarken ManagedIdentityCredential’a geçmek lazım. Bunu söylemekten dilimde tüy bitti diyebilirim; saha gözlemim şu ki ekiplerin yarısı bu adımı atlıyor ve sonra “neden prod’da auth patladı” diye şaşırıyorlar. Cevap çok romantik değil: çünkü container’da az login session’ı yok.
2. Adım: Chat Client’i Harness’a Çevir
Sıra geldi sihirli kısma..NET’te AsHarnessAgent, Python’da create_harness_agent çağrısı yapıyorsun. İki şey veriyorsun: instructions (ajanın ne yapacağı) ve araçlar. Gerisi harness’ın sorumluluğu.
Ve işler burada ilginçleşiyor.
Beni şahsen en çok şaşırtan şey planning’in built-in gelmesi öldü. Daha önce LangGraph’ta bunu yapmak için ayrı planner node yazmak gerekiyordu; state machine kuruyordun, akışı sen yönetiyordun (yanlış duymadınız). Açık konuşayım bazen ufak bir değişiklik bile zincirleme kırılıyordu. Agent Framework planning’i bir bayrak gibi açıyor; gerisini kendi hallediyor gibi dürüyor. Fena değil.
Ama dürüst olayım: bu kadar “kara kutu” olması beni biraz da huzursuz ediyor. Planner ne zaman devreye girer, ne zaman atlanır, nasıl debug ederim? Microsoft’un dokümantasyonu henüz bu soruların hepsine net cevap vermiyor (evet, doğru duydunuz). Olgunlaşma süreci içindeler diyelim; yanı iş görüyor ama tam cilalı değil.
Bir dakika — bununla bitmedi.
3. Adım: Konsol Döngüsüne Bağla
Son adım klasik bir interactive loop. Kullanıcıdan input alıyorsun, harness’a yolluyorsun, cevabı yazdırıyorsun ve tekrar dönüyorsun. Burada anlatacak çok bir şey yok aslında —. Framework’ün RunStreamingAsync gibi metodlarla token-by-token streaming sağlaması güzel detay; özellikle terminalde ya da basit admin ekranlarında baya işe yarıyor.
Built-in Olarak Ne Alıyorsun, Ne Almıyorsun?
Burası önemli çünkü beklentiyi doğru ayarlamazsan hayal kırıklığı geliyor. Aşağıda harness’ın size verdiği parçalarla hâlâ sizin çözmeniz gereken işleri yan yana koydum:
| Harness Veriyor | Sen Hâlâ Yapıyorsun |
|---|---|
| Function invocation döngüsü | Tool’ların kendisini yazmak |
| Conversation history yönetimi | Hangi history’nın nereye yazılacağı (Redis, Cosmos, vs.) |
| Planning yetisi | Plan adımlarının iş kurallarına uyup uymadığı |
| Web search entegrasyonu | Sonuçların filtrelenmesi, kaynak doğrulama |
| Streaming response | UI tarafında render |
| Error handling iskeleti | Meseleye göre retry politikaları belirlemek |
Küçük bir detay: Kısacası harness sana iskeleti veriyor. Eti hâlâ sen koyuyorsun; başka türlü de olmaz zaten çünkü tersine mühendislik gibi davranan bir framework’e dönüşmesini kimse istemezdi.
Türkiye’deki Kurumsal Bağlamda Bu Ne İfade Ediyor?
İnanın, Neyse uzatmayayım ama bence asıl kritik yer burası. Bu teknolojiler Silikon Vadisi’nde konuşulduğunda her şey biraz peri masalı gibi geliyor; Türkiye’deki kurumsal müşteriye gittiğinde işe soru seti aniden değişiyor. Sohbet doğrudan zemine iniyor.
Konu 1: regülasyon ve veri ikametgâhı.
Bi saniye — Büyük finans ya da sağlık müşterisi şunu soruyor: “Ajanın çağırdığı LLM hangi region’da?” Foundry’nın North Europe ve West Europe deployment’ları bu soruya teknik cevap olabiliyor ama gerçek dünyada KVKK uyumluluğu için hukuk ekibiyle aylarca yazışmak gerekiyor; framework burada sihir yapmıyor çünkü mesele teknikten çok süreç ve hukuk işi.
Doğrusu, Konu 2: maliyet.
Ajan dediğin şey tek çağrıda tek cevap vermiyor çoğu zaman; planner var, executor var, tool decision var derken bir konuşmada 5-10 LLM çağrısı görmek hiç sürpriz değil (özellikle kullanıcı isteği bulanıksa). Eğer GPT-5 sınıfı model kullanıyorsan ve günde 1000 kullanıcın varsa aylık fatura kolayca altı haneli TL seviyesine çıkabiliyor; o yüzden ilk PoC’de muhtemelen tag budget alarmı değil token bütçe alarmı ? Hayır dur — düzgün söyleyeyim: Azure Cost Management üzerinden budget alert kurmak gerekiyor.
“Bir framework’ü değerlendirirken şuna bakın: en kolay senaryosu ne kadar kolay, en zor senaryosu ne kadar mümkün? Agent Framework birinciside parlıyor, ikincide henüz olgunlaşıyor.”
Konu 3: yetkinlik açığı.
<>
<>
Sıkça Sorulan Sorular
Agent Framework, Semantic Kernel’in yerini mi alıyor?
Tam olarak değil aslında, ama yönelim o tarafa doğru gidiyor. Yanı Microsoft Semantic Kernel’i daha alt seviyede bırakıyor, Agent Framework işe onun üzerine inşa edilmiş ajan-odaklı bir katman. Yeni bir projeye başlıyorsanız bence doğrudan Agent Framework’ten gidin. Mevcut Semantic Kernel projeleriniz zaten çalışmaya devam edecek — panik yapmaya gerek yok.
Hangi modellerle çalışıyor, sadece OpenAI mi?
Hayır, model-agnostic bir yapısı var (evet, doğru duydunuz). Azure OpenAI, OpenAI, Anthropic Claude, Google Gemini, hatta Ollama gibi lokal modeller de destekleniyor. Chat client’i hangi provider’a yöneltirseniz harness onun üzerinde çalışıyor. Açıkçası bu, vendor lock-in açısından bence framework’ün en güçlü yanı.
Production’a almadan önce ne yapmalıyım?
En az üç şey yapın. Managed identity’ye geçin — hani DefaultAzureCredential prod’da gerçekten riskli olabiliyor. Bir de token bütçe alarmı kurun, telemetry ve logging ekleyin. Bunlar olmadan prod’a alırsanız, tecrübeme göre ilk fatura veya ilk incident’ta çok üzülürsünüz.
Web search built-in mi geliyor, ekstra ücret var mı?
İnanın, Web search aslında Foundry’nın sağladığı bir özellik ve ekstra çağrı bedeli oluşturuyor. Bing Search backend’i kullanılıyor. Fiyatlandırması ayrı bir SKU üzerinden yürüyor, yanı mutlaka Azure Pricing Calculator’dan bir bakın. Yoğun kullanımda gözden kaçabilen bir maliyet kalemi bu — mesela başta küçük görünüyor ama birikiyor.
Planning her zaman devreye giriyor mu?
Hayır, harness model çağrısının context’ine bakarak planner’a ihtiyaç var mı yok mu ona karar veriyor. Mesela “saati söyle” gibi basit sorularda planner hiç devreye girmiyor, doğrudan cevap geliyor. Ama “watchlist’ımı analiz et ve öner” gibi multi-step bir ihtiyaç varsa planner devreye giriyor. İstemezseniz bu davranışı konfigürasyonla kapatabiliyorsunuz zaten.
Kaynaklar ve İleri Okuma
Meet your agent harness and claw — Microsoft DevBlogs (Wes Steyn)
Şimdi, dürüst olmak gerekirse, Microsoft Foundry Resmî Dokümantasyonu
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.
2 comments