Agent Framework ile Kendi Claw’unu Kurmak: Saha Notları
Geçen hafta bir arkadaşım sordu: “Şu Claude Code, Cursor, Codex falan — bunlar nasıl çalışıyor ya? Sihir gibi geliyor.” Açık konuşayım, sihir değil. Aslında ortada sadece iyi paketlenmiş bir agent harness var; yanı bir dil modelinin etrafına araç çağrısı, planlama, hafıza, onay mekanizması. Gözlemlenebilirlik ekleyip döngü halinde çalıştırıyorsunuz, hepsi bu. Basit dürüyor ama işin püf noktası da zaten burada.
Microsoft, geçtiğimiz günlerde Agent Framework ile bu harness’ı hazır kutuda sunmaya başladı. Hem.NET hem Python tarafında. Ben de hafta sonu oturup baştan sona kurcaladım; şimdi size kendi “claw”unuzu (yanı CLI tarzı bir kodlama/iş ajanını) nasıl ayağa kaldıracağınızı, nerede tökezleyebileceğinizi ve özellikle Türkiye’deki ekipler için hangi detayların biraz daha can sıkıcı olabileceğini anlatacağım. Hmm, bazı yerleri ilk bakışta basit sanıyorsunuz ama öyle çıkmıyor.
Durun, bir saniye.
İnanın, Konu uzun. Ama uzatmadan söyleyeyim: sonunda kafanızda net bir resim oluşacak. Bir bakıma, peki neden? Çünkü bu işte teori güzel dürüyor, asıl farkı kurulumda ve günlük kullanımda görüyorsunuz; hele ekip içinde birkaç kişi aynı ajanla uğraşınca küçük ayrıntılar büyüyüp karşınıza çıkıyor.
Önce şunu anlayalım: “Claw” dediğimiz şey aslında ne?
Ortalıkta dönen terimler biraz karışıyor, değil mi? Agent, copilot, claw, assistant (kendi tecrübem). İlk bakışta hepsi aynı sepete gidiyor gibi dürüyor ama işin aslı öyle değil.
Vallahi, Bir “claw” — Microsoft ekibinin kullandığı ifadeyle — komut satırında çalışan, sizin yerinize plan çıkaran. Sonra da o plana göre (söylemesi ayıp) hareket eden bir ajan. Tipik örnek olarak Claude Code ya da OpenAI Codex CLI düşünebilirsiniz; arayüzü bir kenara ittiğinizde geriye kalan şey şaşırtıcı derecede sade kalıyor:
- Çağırabileceği araçlar (dosya okuma, web araması, shell komutu, API çağrısı…)
- Takip edip uyarlayabileceği bir plan
- Oturumlar arasında yaşamaya devam eden bir hafıza
- Riskli işlerde insan onayı isteyen bir approval mekanizması
- Ne yaptığını görebildiğiniz bir observability katmanı
- Bunu gerçek bir servis olarak deploy edebilme yolu
Dürüst olmak gerekirse, Lafı gevelemeden söyleyeyim: bu altı parçayı tek tek elle kurmak, yanı sıfırdan harness yazmak, insanı fena yoruyor. Ben ilk denediğimde sadece “tool calling” döngüsünü stabil hâle getirmek üç günümü aldı; küçük gibi dürüyor ama orada ufak bir hata çıkınca zincirin tamamı tökezliyor (ciddiyim). Agent Framework tam burada devreye giriyor ve bu parçaları kompoze edilebilir bloklar halinde önünüze koyuyor.
Evet, doğru duydunuz.
Kısaca: claw = model + harness. Model motor, harness işe şasi. Şasiyi her seferinde yeniden dökmek zorunda değilsiniz artık.
Neden tam da şimdi mümkün öldü?
Bu soruyu gerçekten çok duyuyorum. “GPT-3 zamanında niye yapılmadı?” diye soran da var, “o zamanlar eksik olan neydi?” diyen de. Cevap kısa gibi dürüyor ama işin içinde ince bir fark var: modelin talimat takip etme yeteneği.
Harness tarafında modele her turda iki katman talimat gidiyor, biri sizin yazdığınız prompt, öteki de harness’in kendi sistem talimatları; yanı “şu aracı çağır”, “bu adımı bekle”, “önce onay işte” gibi parçalar üst üste biniyor. Eski nesil modeller bunu ya yarım anlıyordu ya da dümdüz kaçıyordu, tool calling gerekiyorken düz metin cevap verip döngüyü kırıyordu, işte sorun tam oradaydı.
Son 12-18 ayda tablo değişti, baya değişti aslında. Instruction-following tarafı toparlandı, function calling daha güvenilir hâle geldi, context window da genişledi; böyle olunca claw’lar “şimdi” pratik hâle geldi. Eski veya küçük bir modelle de çalıştırırsınız tabiî, ama sonra sürekli hata kovalamaya başlarsınız, insanın canı sıkılır. Açık konuşayım: GPT-4.1, Claude Sonnet 4 ya da o seviyede bir şey kullanın, aşağı inerseniz uğraşırsınız.
Bir uyarı — abartılan kısım
Araya gireyim: Ha bu arada, “agent” kelimesi piyasada öyle bir şişti ki, bazen sadece bir prompt template’i bile AI agent diye satılıyor. Sahada bunu çok görüyorum; ekipler bir — en azından ben öyle düşünüyorum — LangChain script’i yazıyor, sonra adına ajan mimarisi diyorlar. Hayır, değil. Gerçek bir harness’te en az üç şey olmalı: araçlar arasında geçiş yapabilen bir döngü, durum tutan bir hafıza. Hata çıkınca kendini toparlayabilme; gerisi biraz pazarlama kokuyor.
Hmm, bunu nasıl anlatsamdı…
Agent Framework ne sunuyor, ne sunmuyor?
Şöyle ki, Resmî seriye bakınca, işin omurgası dört parçaya ayrılıyor (bizzat test ettim). Kâğıt üstünde düzenli dürüyor, hatta biraz fazla düzenli bile; (kendi tecrübem). Sız ne dersiniz? Pratikte bu şema fena değil, çünkü ilk günden her şeyi yüklemeye çalışmıyorsunuz, adım adım gidiyorsunuz.
| Bölüm | Eklenen Yetenek |
|---|---|
| 1 — Harness & Claw tanışması | Minimum harness, özel get_stock_price tool’u, web araması, plan/execute modu |
| 2 — Veriyle güvenli çalışma | Dosya erişimi, riskli aksiyonlar için onay, kalıcı hafıza (dosya + Foundry) |
| 3 — Yetenekleri ölçekleme | Foundry-managed skills, arka plan ajanları, shell erişimi, CodeAct |
| 4 — Production-ready | OpenTelemetry, Purview governance, Foundry Hosted Agents, evaluation |
Bu tabloyu görünce insanın aklına hemen şu geliyor: “Tamam da bunlar gerçekten ne yapıyor?” İşin aslı, birinci bölümde verilen harness, REPL benzeri bir iskelet gibi çalışıyor; sız soruyu atıyorsunuz, model “burada tool çağırmam lazım” diye düşünüyor (ya da öyle davranıyor), harness da tool’u çalıştırıp sonucu geri veriyor. Klasik ReAct döngüsü yanı. Ama açık konuşayım, paketlemesi temiz olunca aynı şey daha az yorucu hissettiriyor.
Bir dakika — bununla bitmedi.
Serinin örneği olarak seçilen kişisel finans asistanı da yerinde olmuş. Hisse fiyatı çekiyor, portföy CSV’sını okuyor, rapor yazıyor, üstüne analiz yapıyor; yanı tek başına “bakın agent var” demek yerine birkaç farklı kası aynı anda yokluyor. Bir yandan araç çağrısı var, bir yandan dosya erişimi var, bir yandan da yanlışlıkla işlem yaparsa ortalığı karıştıracak onay senaryosu var. Hmm, bence eğitim açısından baya iş görüyor (inanın bana)
Pratikte ilk üç adım
Bir şey dikkatimi çekti: Kafadan başlayacak olsam sırayı şöyle kurarım. İlk adım basit gibi görünüyor ama bazen en çok orada tökezleniyor insan; çünkü tool’u doğru tanımlamazsanız geri kalan her şey biraz makyaj gibi kalıyor.
- Tool tanımıyla başlayın. Tek bir Python fonksiyonu yazın, decorator ile işaretleyin, harness’a verin. Modele “şu fonksiyonu çağır” dedirtebiliyorsanız temel oturuyor demektir; fazlasına hemen atlamayın derim.
- Plan modunu ekleyin. Modele todo listesi tutmasını söyleyin. Tek adımlık görevlerden çok adımlık görevlere geçince fark anında ortaya çıkıyor; bazen küçük bir liste bile işi toparlıyor.
- Onay mekanizmasını test edin. Yazma ya da silme yapan herhangi bir tool’a approval gate koyun. Burası üretime çıkarken ayağınızı en çok kaydıran yer oluyor; hani “bir şey olmaz” dediğiniz anda olur ya, tam o nokta.
Eğer bu üç adımı geçtiyseniz, Agent Framework ile Claw Mimarisi: İlk Ajanı Üç Adımda Kurmak yazımda daha somut bir başlangıç şablonu var. Bakabilirsiniz. E sonra? Oradan devam etmek daha kolay oluyor zaten.
Tam da öyle.
Kod örneği: minimum harness nasıl görünüyor?
Lafı uzatmadan, Python tarafında bir iskelet bırakayım. Kafada hemen otursun diye, çünkü bazen iki satır kod bile insanın gözüne uzun geliyor,. Burada mantık aslında çok düz; agent’ı tanımlıyorsun, tool’ları veriyorsun, sonra da harness ile akışı ayağa kaldırıyorsun.
from agent_framework import Agent, tool
from agent_framework.harness import Harness
@tool
def get_stock_price(symbol: str) -> dict:
"""Verilen hisse sembolü için anlık fiyat döndürür."""
# Burada gerçek bir API çağrısı olur
return {"symbol": symbol, "price": 142.35, "currency": "USD"}
@tool(requires_approval=True)
def write_report(path: str, content: str) -> str:
"""Diske rapor yazar. Onay gerektirir."""
with open(path, "w") as f:
f.write(content)
return f"Yazıldı: {path}"
agent = Agent(
model="gpt-4.1",
tools=[get_stock_price, write_report],
instructions="Sen bir kişisel finans asistanısın. Önce plan yap, sonra uygula."
)
harness = Harness(agent, memory="file://./memory.json")
harness.run_interactive()
Bu kadar. Gerçekten. 20 satırın altında çalışan bir claw’unuz var; küçük görünüyor ama iş görüyor, hatta ilk denemede şaşırtıcı derecede rahat hissettiriyor. Tabiî üretime çıkacaksa daha çok iş var (loglama, hata yönetimi, güvenlik onayı, belki biraz da yetkilendirme), ama “hello world” seviyesinde hikâye tam olarak burada başlıyor.
Peki neden?
İlginç olan şu ki,.NET tarafı da çok benzer, sadece attribute syntax’ı ve DI container kurulumu var ekstra. Sız ne dersiniz? Aynı mantık orada da oldukça temiz dürüyor.
Türkiye’deki ekipler açısından durum ne?
Şimdi asıl yere gelelim. Bu teknolojiyi Türkiye’deki bir şirkette ayağa kaldırmak, San Francisco’daki bir startup’ta denemekten biraz farklı ilerliyor, hatta bazen aynı şeyden konuşuyor gibi yapıp bambaşka dertlere çarpıyorsunuz; birkaç gözlemim var, bazıları da açıkçası ilk bakışta insanın aklına gelmiyor.
Aslında, Birincisi maliyet. Agent harness’ları sandığınızdan daha fazla token yiyor. Çünkü her turda harness kendi sistem prompt’ünü, plan listesini, tool tanımlarını ve geçmiş mesajları modele yeniden gönderiyor; yanı tek bir kullanıcı isteği arkada 6-10 model çağrısına dönüşebiliyor, sonra sız de “bu kadar mı?” diye faturaya bakıyorsunuz. Dolarla ödediğiniz bir API’yi TL bütçesiyle çevirmeye çalışıyorsanız, ilk ay faturayı görünce irkilmeniz normal. Önerim şu: prototip aşamasında küçük bir modelle (mini/flash sınıfı gibi) başlayın, sonra gerçekten gerekli kısımlarda büyük modele geçen bir routing mantığı kurun; yoksa FinOps tarafında işler çabuk karışıyor. Bu konuyu ayrıca Copilot Usage Metrics API’ye ai_credits_used Geldi: FinOps İçin Ne Anlama Geliyor? yazımda biraz açmıştım, AI bütçesi tutuyorsanız bakmaya değer.
İkincisi veri yerleşimi. Bankacılık, sigorta, kamu — bu sektörlerde “veri yurt içinde kalacak” şartı var. Agent Framework ile modeli Azure OpenAI üzerinden Türkiye’ye yakın bölgelerden çağırabiliyorsunuz (West Europe gibi), bu kısmı fena değil;. Dur bir saniye — bazı yönetilen özellikler, özellikle Foundry Hosted Agents, henüz her bölgede yok. Production’a çıkmadan önce hangi bileşenin nerede koştuğunu tek tek çizip hukuk ekibine onaylatın, çünkü sonradan migration yapmak tatlı tatlı gitmiyor, baya uğraştırıyor. Evet.
Şahsen, Üçüncüsü kültürel direnç. Bu taraf teknik değil. “Ajanı portföyüme eriştirip kendi başına işlem yapsın” cümlesi, Türkiye’deki birçok kurumsal yöneticide alarm zillerini çaldırıyor; haklılar da aslında, çünkü mesele sadece otomasyon değil, kontrol hissi de var (bu konuda ikircikliyim). Approval gate’leri ve audit log’ları en başından sıkı kurun (ciddiyim). “Önce çalıştıralım, sonra güvenlik ekleriz” yaklaşımı burada pek yürümüyor, açık konuşayım.
Startup vs Enterprise: hangi yolu seçmeli?
Bana en çok gelen soru bu. “Küçük ekibim var, hemen mi başlayayım, yoksa biraz bekleyeyim mi?” Cevap, açık konuşayım, tek satırlık değil.
Küçük ekip / startup iseniz
Hemen girin işe. Python SDK ile bir tool, bir agent, bir harness kurmak yarım gün sürüyor; sonra hafızayı dosyaya yazarsınız, hosting tarafını da şimdilik büyütmezsiniz (çünkü çoğu zaman gerek de kalmıyor), modeli Azure OpenAI’dan ya da direkt OpenAI’dan çekersiniz, hangisi o an daha mantıklıysa. Observability için OpenTelemetry’yi en baştan bağlayın; yoksa ileride debugging yaparken insanın içi daralıyor. Toplam yatırım? Kabaca 1 hafta. Dönen değer? Fena değil, hatta bazen beklediğinizden fazla.
Evet.
Kurumsal yapıdaysanız
Acele etmeyin. Önce şu üç soruya net cevap verin; çünkü işin aslı burada başlıyor ve cevaplar havada kalırsa, teknik tarafta her şey çalışsa bile kurum içinde kimse elini taşın altına koymuyor: bu ajan hangi verilere erişecek, o veriler hangi sınıflandırmada dürüyor, yanlış aksiyon aldığında sorumluluk kullanıcıda mı sistem sahibinde mi AI ekibinde mi olacak? Audit trail nasıl tutulacak ve ne kadar süre saklanacak? Bunları netleştirmeden koda dalmak bana pek sağlıklı gelmiyor.
Açıkçası, Bu soruların cevabı yoksa, harness ayağa kalksa bile kabul görmez. Önce governance iskeletini kurun, sonra koda geçin. Sıralamayı ters çevirdiğinizi gördüğüm projelerde sonuç hep aynı öldü; pilot güzel başlıyor, sonra bir yerde takılıyor ve rafta kalıyor. Hani “birazdan toparlarız” deniyor ya, çoğu zaman toparlanmıyor. Bu konuda Agentic Cloud Operations: İçgörüden Eyleme Geçen Bulut Devri yazımda kurumsal benimseme tarafına daha çok değinmiştim.
Peki neden?
Eksik bulduğum şeyler — açık konuşayım
Agent Framework genel olarak fena değil. Hatta bayağı düzgün dürüyor. Ama işin aslı, beklediğim kadar olgun da değil; birkaç yerde insanın kaşı kalkıyor, çünkü ilk bakışta iyi görünen şeyler biraz kurcalayınca hafif tökezliyor.
Hafıza tarafı henüz biraz ham. Dosya tabanlı hafıza prototip için yeterli, tamam, ama çok kullanıcılı bir senaryoya geçince tablo değişiyor ve işler bir anda karışabiliyor; Foundry tarafına bağlandığınızda kalıcılık geliyor, evet, fakat bunun da ayrı bir maliyeti var. Bence orta katmanda (Cosmos DB ya da Redis üzerinden) kendi memory provider’ınızı yazmak şu an için daha sağlıklı bir yol gibi dürüyor. Deep Agents + Cosmos DB: Operasyonel Veride Plan-Eylem-Doğrulama yazımda bu konuya değinmiştim, ilgisi var; hatta oradaki yaklaşım burada birebir akla geliyor.
Küçük bir detay: Bir de evaluation tarafı var. Serinin 4. bölümünde geleceği söyleniyor ama şu an elinizde çalışan bir ajan varsa, onun kalitesini ölçmek için kendi test harness’ınızı kurmanız gerekiyor; yanı işi biraz sız toparlıyorsunuz, framework henüz o yükü tamamen almıyor. Bu da ayrı bir emek. “Bu ajan dün %85 başarılıydı, bugün %82; ne değişti?” sorusuna net cevap verecek bir araç set’i hazır gelse keşke. Olacak gibi dürüyor, sadece henüz ortada yok.
Son olarak dokümantasyon hâlâ Python ağırlıklı..NET tarafı da var, önü inkâr etmeyeyim, ama örneklerin çoğu Python olunca.NET stack ile ilerleyen biri ara ara çeviri yapmak zorunda kalıyor; çok dramatik değil ama küçük küçük sürtüyor. Sıkıntı mı? Değil aslında. Yine de beklemediğiniz yerde ufak bir fren hissi yaratabiliyor.
Pratik bir başlangıç planı
Hani, Bu uzun yazının özetini, denemek isteyenler için bir checklist’e çevirmek istiyorum:
- İlk hafta: Tek bir tool, tek bir agent, tek bir kullanıcı senaryosu. Lokal çalıştırın. Token sayacını da gözünüzün ucuyla takip edin; çünkü orada işler bazen sandığınızdan hızlı şişiyor.
- İkinci hafta: 2-3 tool ekleyin. Plan modunu açın. Bir yazma işlemine approval gate koyun, sonra hata durumlarına bakın; asıl sürpriz genelde orada çıkıyor.
- Üçüncü hafta: Hafızayı kalıcı hâle getirin. OpenTelemetry ile trace toplayın. Bir Grafana dashboard’a bağlayın; yoksa ne öldü bitti anlamak zorlaşıyor.
- Dördüncü hafta: Gerçek kullanıcılarla bir pilot yapın. 10 kişi yeter. Geri bildirimleri sistematik olarak toplayın, ama şey, her yorumu da aynı ağırlıkta okumayın.
- Sonra: Foundry’ye taşımak isteyip istemediğinize bakın. Çoğu senaryoda kendi altyapınızda çalıştırmak daha esnek olabiliyor, hatta bazen beklediğinizden daha rahat ilerliyorsunuz.
Bu sıralamayı takip edenlerin canı daha az yanıyor. Atlamaya çalışanlar — özellikle “direkt prod’a çıkalım” diyenler — çoğu zaman geri dönüp baştan yapıyor; açık konuşayım, bu işte acele eden biraz duvara tosluyor.
Sıkça Sorulan Sorular
Agent Framework, LangChain veya Semantic Kernel’in yerini mi alıyor?
Bence tam olarak almıyor. Semantic Kernel zaten Microsoft’un kurumsal odaklı agent kütüphanesiydi, Agent Framework işe üst katmanda — hani harness. — paketleme yapıyor. LangChain hâlâ çevre genişliği açısından önde. Hangisini seçeceğiniz aslında ekosisteminize bağlı: Azure ağırlıklıysanız Agent Framework mantıklı, çok provider’lı bir yapıdaysanız LangChain hâlâ rakipsiz.
Claude Code veya Cursor varken neden kendi claw’umu yapayım ki?
Genel amaçlı bir kodlama asistanı istiyorsanız hazır olanları kullanın, daha pratik. Ama mesela “şirketimin SAP modüllerine erişip rapor üreten bir ajan” gibi domain’e özel bir şey istiyorsanız, hazır araçlarla bunu yapamazsınız. Açıkçası kendi harness’ınız tam da o noktada devreye giriyor.
Hangi modelle başlamalıyım?
Prototipte gpt-4o-mini veya benzeri ucuz bir modelle başlayın. Çalıştığını gördükten sonra gpt-4.1 veya Claude Sonnet 4.5 seviyesine geçin. Tecrübeme göre düşük model, harness’ın sınırlarını test etmek için de iyi — daha çabuk kırılıyor, eksiklikleri daha çabuk görüyorsunuz (ben de ilk duyduğumda şaşırmıştım)
Production’a çıkmadan önce kritik adım nedir?
Approval gate’ler ve audit log. Bu ikisi olmadan kurumsal bir ortamda hiçbir agent uzun ömürlü olmuyor. Tool tanımlarını “yazma yapan / okuma yapan” diye iki sınıfa bölün; yazma yapanların hepsi başlangıçta onay istesin. Güven inşa edildikçe gevşetebilirsiniz.
Türkiye’den Azure OpenAI çağrısı yaparken hangi bölgeyi seçmeliyim?
Genelde West Europe veya Sweden Central düşük gecikme veriyor. Veri yerleşim şartınız varsa hukuk ekibinizle doğrulayın — çünkü “Avrupa içinde kalsın” ile “Türkiye’de kalsın” aslında çok farklı şeyler. Bir de bazı modeller her bölgede deploy edilmiş olmuyor, başlamadan önce model availability tablosuna bakın.
Kaynaklar ve İleri Okuma
Microsoft DevBlog — Build your own claw and agent harness
Neyse, bir şey dikkatimi çekti: Azure AI Foundry Resmî Dokümantasyonu (inanın bana)
Microsoft Agent Framework GitHub Repository
OpenTelemetry GenAI Semantic Conventions (en azından benim deneyimim böyle)
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.
0 comments