Agent Harness ile Ajana Veri Vermek: Onay ve Hafıza Dahil
Araya gireyim: Geçen yazıda bir Agent Framework ile Kendi Claw’ünü Kurmak: Saha Notları başlıklı bölümde harness’ı ayağa kaldırmış, kişisel finans asistanımıza custom tool, web arama ve planlama yeteneklerini vermiştik. Konuşuyordu, piyasa hakkında sohbet ediyordu. Güzel. Ama işin can sıkıcı tarafı şuydu: bizim veriye dokunamıyordu, bir de anlık bir kararla hassas bir aksiyon almasını durduracak düzgün bir fren de yoktu.
Yanı teoride hoş dürüyor. Pratikte işe biraz ürkütücü.
Dürüst olmak gerekirse, Bu yazıda o iki eksiği kapatıyoruz. Harness’ın kutudan çıkan üç yeteneğiyle: dosya erişimi, onay mekanizması ve kalıcı hafıza. Ajanı üretime yaklaştıran şey aslında bu üçlü; modelin ne kadar akıllı olduğu bir yere kadar gidiyor, asıl fark ajanın “işini yapabilecek kadar özgür ama ortalığı dağıtamayacak kadar sınırlı” olmasında.
Neden Bu Uç Yetenėk Bir Arada?
Bakın şimdi, sahada en sık gördüğüm hata şu: insanlar bir LLM alıyor, üstüne tool calling ekliyor, sonra da gidip doğrudan üretim veritabanına yazma yetkisi veriyor. Kulağa pratik geliyor, evet; ama iş ters gidince ortaya çıkan şey genelde “AI saçmaladı” hikâyesi değil, bildiğiniz mimarı açığı oluyor.
Şimdi gelelim işin can alıcı noktasına.
Asıl mesele halüsinasyon falan değil. Mesela ajan hangi veriyi okuyacak, hangi aksiyonu insan onayı olmadan alamayacak, hangi bilgiyi de oturumlar arasında hatırlayacak; bunları net ayırmanız lazım. Harness bu üç parçanın temelini hazır getiriyor, gerisi size kalıyor — yanı ne yapacağını doğru tarif etmekte iş bitiyor.
“Bir ajanı üretime almanın kuralı basit: kendi başına asla geri alınamaz bir işlem yapmamalı. Bu, güvenlik değil, mühendislik disiplini.”
Dosya Erişimi: Ajana Gerçek Veriyi Vermek
Uydurma sayilarla oynayan bir finans asistaninin ne kıymeti var, değil mi? Kullanıcı portföyünü gerçekten okuması gerek. Harness’in file_access_* tool ailesi bunu belirli bir klasör altında çözüyor. Yanı ajan tüm diski karistiramiyor, sadece işaret ettiğiniz sandbox klasorde dolasabiliyor. Kısa olan bu. Ama kritik kısım da tam burası.
C# tarafında kurulum bir satır aslında: basit görünüyor, hatta biraz fazla sakın bile dürüyor; ama arka planda ajana dosya sistemi yetkisi verirken nerede gezecegini de kilitliyorsunuz (AppContext.BaseDirectory içindeki working klasörü), yanı hem kontrollü hem de kullanışlı bir düzen kurmuş oluyorsunuz.
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
FileAccessStore = new FileSystemAgentFileStore(
Path.Combine(AppContext.BaseDirectory, "working")),
ChatOptions = new ChatOptions
{
Instructions = instructions,
Tools = [/*... */]
},
});Python tarafı da benzer bir sadelikte: burada da mesele uzun uzun konuşmak değil, doğru store’u verip geçmek. Hani bazen kodu gördüğünüzde “bu kadar mi?” dersiniz ya, aynen o his var; ama is görüyor.
from agent_framework import FileSystemAgentFileStore
agent = create_harness_agent(
client=client,
agent_instructions=FINANCE_INSTRUCTIONS,
tools=[get_stock_price, place_trade],
file_access_store=FileSystemAgentFileStore("working"),
)Bu tek satırla ajan altı yeni tool kazanıyor: read_file, save_file, list_files, list_subdirectories, search_files, delete_file. Ama tool’ları vermek yetmiyor; ajana nasıl kullanacağını da anlatmak lazım. Yoksa eline anahtar verirsiniz de hangi kapinin acildigini kendi kafasına göre anlamaya çalışır. Tahmin eder mısınız? Instructions kısmına su notu ekliyoruz:
Çok konuştum, örnekle göstereyim.
Sandbox Klasorunun Önemi
Doğrusu, Şunu özellikle vurgulayayım: FileSystemAgentFileStore bir kisitleme mekanizması. Ajan bu klasorun dışına cikamiyor. Prompt injection saldirilarinda bile “yukarıdaki klasorden şu dosyayı sil” gibi bir yönlendirme çalışmıyor, çünkü tool’un kendisi o yolu göremiyor. Peki bunu neden söylüyorum? Bu çok rahatlatan bir detay; ama dur bir saniye — esas olay rahatlık değil, mimarı sınırın kendisi.
Bunu yaşayan biri olarak söyleyeyim, Neyse uzatmayalım, konu net: bu koruma prompt katmanında değil, mimarı düzeyde çalışıyor. Yanı model ne kadar hevesli davranirsa davransın, dosya sistemi ona sadece sizin verdiğiniz sandbox’i gösteriyor (buna dikkat edin). Tam da bu yüzden güven hissi biraz daha sağlam oluyor.
Hmm, bunu nasıl anlatsamdı…
Onay Mekanizması: Ateşle Oynanan Yerde Fren
Veri okumak? Pek sorun değil. Ama trade açmak? Orada iş değişiyor,. Aksiyonun bir sonucu var, bazen de geri dönüşü hiç keyifli olmuyor; ajan bunu insan onayı olmadan yapmamalı, nokta.
Harness’ın built-in approval mekanizması tam bu yüzden var: bir tool’u “approval-required” diye işaretliyorsun, ajan çağırmadan önce dürüyor ve soruyor. Basit görünüyor, ama sahada baya iş görüyor.
.NET tarafında ApprovalRequiredAIFunction ile sarıyoruz:
public static AIFunction CreatePlaceTradeTool() =>
new ApprovalRequiredAIFunction(
AIFunctionFactory.Create(PlaceTrade));
private static string PlaceTrade(string symbol, int quantity, string side)
{
// Simülasyon
return $"Order simulated: {side} {quantity} {symbol}";
}Python tarafında da benzer bir dekoratör mantığı var. Ajan tool’u çağırmaya karar verdiğinde harness akışı duraklatıyor, kullanıcıya “şunu yapmak istiyorum, onaylıyor musun?” diye soruyor; kullanıcı evet derse tool çalışıyor, hayır derse iptal oluyor. Evet, bu kadar.
Hangi Tool’lar Onay Gerektirmeli?
Küçük bir detay: Genel kural şu: geri alınamaz olanlar ve dış dünyaya etki eden her şey. Sahada bunu ayırırken bazen kafa karışıyor gibi geliyor, ama açık konuşayım, aşağıdaki sınıflandırma çoğu ekipte işi toparlıyor:
| Tool Tipi | Onay Gerekli mi? | Örnek |
|---|---|---|
| Salt okuma | Hayır | portfolio.csv okumak, fiyat sorgulamak |
| Sandbox içi yazma | Genelde hayır | Rapor markdown’ı üretmek |
| Sandbox içi silme | Evet (tercihen) | Eski raporu silmek |
| Dış API çağrısı (idempotent) | Duruma göre | Piyasa verisi çekmek |
| Finansal işlem | Kesin evet | Trade açmak, transfer yapmak |
| E-posta / mesaj gönderme | Kesin evet | Müşteriye rapor yollamak |
Bunu bir kere yerine oturttun mu, ekibin geri kalanıyla “hangi tool approval alsın?” tartışması epey kısalıyor. Hatta bazen gereksiz toplantı bile kurtarıyor; küçük detay gibi dürüyor ama etkisi fena değil.
Açıkçası, Neyse uzatmayalım.
Peki neden? Çünkü kontrolsüz otomasyon ilk başta rahat hissettirir, sonra bir bakmışsın yanlış trade ya da yanlış mesaj yüzünden ortalık karışmış; işte approval burada frene basıyor ve seni o son dakika telaşından biraz olsun uzak tutuyor.
Kalıcı Hafıza: İki Farklı Türü Var
Şimdi işin can alıcı yerine geldik. Ajanın, oturum bittiğinde de bir şeyleri hatırlaması lazım; ama neyi hatırlayacak, asıl mesele bu. Harness burada iki ayrı hafıza tipi sunuyor, ve açık konuşayım, bu ayrımı kaçırırsanız sonra her şey biraz çorba oluyor.
Kısa Vadeli: Konuşma Bağlamı
Aynı oturum içinde ajanın “az önce ne konuşmuştuk?” sorusunu yakalaması gereken bilgiler bunlar. Genelde thread state içinde otomatik tutuluyor, yanı kullanıcı “AAPL fiyatı ne?” deyip ardından “kaç adet almalıyım?” dediğinde, ajanın hâlâ AAPL’den söz edildiğini anlaması gerekiyor; yoksa cevap havada kalıyor, baya sınır bozucu olur.
Uzun Vadeli: Kalıcı Tercihler ve Bilgiler
İşin asıl işe yarayan tarafı burada. Kullanıcının risk toleransı, yatırım hedefleri, sevmediği sektörler… Bunlar oturumlar arasında taşınmalı ki ajan her seferinde sıfırdan başlamasın. Harness bunu bir memory store üzerinden yönetiyor; ajan öğrendiği bilgiyi bir tool ile kaydediyor, sonra gelecek oturumda geri okuyor — valla güzel iş çıkarmışlar —
Fena değil ama şu kısmı atlayan çok oluyor: hafıza her şeyi kaydetmemeli (inanın bana). Yoksa ortalık doluyor da doluyor, ajan alakasız detaylarla şişmiş bağlamın içinde debelenmeye başlıyor (evet, doğru duydunuz). O yüzden instructions tarafında “sadece kullanıcının açıkça söylediği tercihleri kaydet” gibi net bir kural koymak gerekiyor; başka türlü küçük notlar büyüyor, sonra başa bela oluyor (evet, doğru duydunuz)
Peki neden?
Türkiye’deki Kurumsal Perspektif
Sahada gördüğüm kadarıyla, Türkiye’deki şirketler bu ajan işine biraz farklı bakıyor. Batı tarafında genelde “önce hızlı — en azından ben öyle düşünüyorum — prototip çıkar, güvenliği sonra toparlarız” kafası var; bizdeyse regülasyon baskısı — özellikle BDDK, KVKK, EPDK gibi kurumların denetimindeki alanlarda — işi ters çeviriyor, yanı önce onay akışı kuruluyor, sonra fonksiyonlar konuşuluyor. Garip geliyor ama aslında kötü de değil.
Hatta burada küçük bir avantaj çıkıyor ortaya. Çünkü Agent Framework’teki approval mekanizması tam da bu uyum ihtiyacına oturuyor; bir bankada ajan trade önerisi yapabiliyor. Işlemi kendi başına açamıyor, approval log’u da denetime hazır hâlde kalıyor. KVKK tarafında da FileSystemAgentFileStore‘un sandbox yaklaşımı işe yarıyor, çünkü veri sınırlarını mimarı olarak çizmek daha kolay oluyor. Evet, mesele bu kadar net değil tabiî; yine de pratikte baya iş görüyor.
Bir de maliyet kısmı var ki, orası biraz can sıkıyor. Azure OpenAI’da token maliyetlerini (belki yanılıyorum ama) TL bazında düşününce insan ister istemez frene basıyor; her oturumun başına 5000 token’lık bir “geçmiş” koyarsanız, ay sonunda gelen faturaya bakıp kısa bir sessizlik yaşayabilirsiniz. Uzun vadeli hafızayı özet halinde tutmak, ham log saklamaktan hem daha ucuz hem de çoğu zaman daha mantıklı dürüyor. Şey, açık konuşayım, burada disiplin yoksa bütçe hızlı dağılıyor.
Küçük Ekip mi, Enterprise mı?
İki farklı dünya var burada. İkisine de aynı reçeteyi sürmek pek akıllıca değil.
İki farklı senaryo için iki ayrı yol öneriyorum, çünkü küçük bir startup ile kurumsal yapı aynı ritimde yaşamıyor (hatta çoğu zaman birbirine bakıp “bu ne böyle?” diyorlar), biri hızlıca ayağa kalkmak istiyor, diğeri işe iz, onay ve kontrol peşinde koşuyor.
- Küçük ekip / startup:
FileSystemAgentFileStoreyeterli. Yerel diskte çalışın, hafıza için basit bir SQLite da iş görür; her tool’a approval koymayın, sadece geri alınamaz olanlara koyun. Overengineering bu aşamada en büyük düşmanınız, açık konuşayım. - Enterprise: File store’u Azure Blob Storage tabanlı bir hayata geçirmea taşıyın. Hafıza katmanı için Cosmos DB ya da Cosmos DB Rolleri: Uygulamam İçin Hangisi Doğru Seçim? yazısında değindiğim rol yapısıyla RBAC uygulayın; approval akışlarını da Teams veya ServiceNow gibi kurumsal onay sistemlerine bağlayın — ki bu taraf, Agentic Cloud Operations: İçgörüden Eyleme Geçen Bulut Devri yazımda anlattığım “insan-döngüde” mimarisiyle baya örtüşüyor.
Evet. Kısa cevap bu kadar.
Aslında mesele teknoloji seçmekten çok, riskin nerede durduğunu görmek (ciddiyim). Küçük tarafta hız kazanıyorsunuz, enterprise tarafında işe denetlenebilirlik ve kontrollü ilerleme daha ağır basıyor; yanı biri “çalışsın yeter” diyor, öteki “kim neyi neden yaptı?” diye soruyor.
Pratik Uygulama: İlk Adımlar
Denemek istiyorsanız, bence işi fazla büyütmeden şu sırayla gidin; yoksa ortalık çabuk karışıyor:
- Boş bir
working/klasörü açın, içine örnek birportfolio.csvkoyun. - Sadece dosya erişimini açın, sonra ajanla konuşun. “Portföyümde ne var?” sorusuna düzgün cevap veriyor mu, önce ona bakın.
- Ardından bir
place_tradetool ekleyin — ama approval olmadan. Ajanın nasıl doğrudan aksiyon aldığını görün. Açık konuşayım, bu biraz ürkütüyor; tam da burada approval’ın neden gerektiği netleşiyor. - Şimdi bunu
ApprovalRequiredAIFunctionile sarın. Farkı hemen hissediyorsunuz, şey, aynı iş ama kontrol bambaşka oluyor. - En sona hafızayı bırakın. Küçük başlayın: mesela sadece “kullanıcının risk toleransı” gibi tek bir alan yeter.
Şöyle ki, Bu sırayı atlayıp hepsini aynı anda kurmaya kalkarsanız, bir şey bozulduğunda nereye bakacağınızı şaşırırsınız; ben olsam hiç acele etmem, katman katman ilerlerim.
Eksik Yönler ve Dikkat Edilecekler
Açık konuşayım, her şey güllük gülistanlık değil. Harness’ın approval akışı şu an baya basit: yes/no (buna dikkat edin). Ama gerçek hayatta iş biraz dallanıp budaklanıyor; mesela “sadece 100 lot’a kadar onaylıyorum, üstünü bana sorma” gibi yarım yamalak değil, gayet net ara kararlar lazım oluyor, bunu da şimdilik kendi tool wrapper’ınızda çözmeniz gerekiyor (yanlış duymadınız)
Hani bir de hafıza tarafında minik ama can sıkıcı bir durum var. Hani ne farkı var diyorsunuz, değil mi? Model bazen “önemli” ile “önemsiz” ayrımını kaçırabiliyor, yanı kullanıcının bir kere laf arasında söylediği şeyi kalıcı tercih sanıp kaydedebiliyor; bu yüzden hafızaya yazma tool’ünü da approval-required yapabilirsiniz, biraz sert bir yöntem ama hassas domainlerde açıkçası fena durmuyor.
Bence bu üçlü, doğru yöne atılmış sağlam bir adım. Ama hâlâ eksik kalan parça şu: cross-agent memory sharing. Yanı aynı kullanıcıya bakan birden fazla ajan varsa, bunlar hafızayı nasıl ortak kullanacak? Şey… framework tarafı burada henüz tam oturmuş değil, muhtemelen önümüzdeki sürümlerde daha net bir tablo göreceğiz.
Sıkça Sorulan Sorular
FileSystemAgentFileStore güvenli mi, üretim ortamında kullanabilir mıyım?
Tek sunuculu senaryolarda kesinlikle kullanılabilir. Ama Kubernetes gibi distributed bir ortamdaysanız, pod’lar arası tutarlılık için Azure Blob ya da S3 tabanlı bir implementasyona geçmeniz gerekiyor. Aslında framework’ün interface’i açık tutulmuş, yanı kendi store’unuzu yazmanız da mümkün.
Approval mekanizması senkron mu çalışıyor? Uzun süren onaylar için ne yapmalıyım?
Varsayılan akış senkron çalışıyor. Ama mesela onayın Slack veya Teams üzerinden saatler sonra geleceği bir senaryonuz varsa, tool içinde bir “pending approval” state’i oluşturup dışarıdan callback ile devam eden bir akış kurmanız gerekiyor. Framework buna izin veriyor, ama açıkçası bu özellik out-of-the-box gelmiyor.
Kalıcı hafıza LLM’in context penceresini şişirmez mi?
Bi saniye — Şişirir, dikkat etmezseniz. Bu yüzden bence hafızayı ham log olarak tutmak yerine özetlenmiş bir “kullanıcı profili” şeklinde saklamak çok daha mantıklı. Ajanın instructions’ına “hafızayı sadece ilgili konu geldiğinde çağır” gibi bir kural eklemek de işe yarıyor. Tahmin eder mısınız? Tecrübeme göre otomatik retrieval yerine tool call ile getirtmek genelde hem daha ekonomik hem daha kontrollü oluyor.
Onay isteyen tool’lar kullanıcı deneyimini mahveder mi?
Bir şey dikkatimi çekti: Doğru dozajda kullanılırsa tam tersine güven veriyor. Her tool’a onay koyarsanız evet, kullanıcı bıkar. Ama sadece geri alınamaz aksiyonlara koyarsanız kullanıcı “iyi ki soruyor” der. Yanı aslında her şey dengede.
Aynı yapıyı.NET yerine Python ile de kurabilir mıyım?
Evet, Microsoft Agent Framework hem.NET hem Python tarafında paritede ilerliyor. File access, approval ve memory üçlüsü her iki dilde de mevcut (yanlış duymadınız). Sadece API isimleri biraz farklılaşıyor — hani.NET tarafı biraz daha “type-safe” hissettiriyor, Python tarafı işe daha çevik.
Peki neden?
Kaynaklar ve İleri Okuma
Microsoft DevBlogs: Agent Harness Working with your data safely
Microsoft Agent Framework Resmî Dokümantasyonu
Microsoft Agent Framework GitHub Deposu
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.
4 comments