Microsoft Agent Framework Harness ile C# Ajan Kurmak

⏱️ 7 dk okuma📅 17 Eylül 2026

Bir dil modelini “ajan” hâline getiren şey modelin kendisi değil, etrafındaki çalışma zamanıdır: araç çağırma döngüsü, plan takibi, bellek, onay akışı ve bağlam yönetimi. Microsoft Agent Framework bu katmanı agent harness adıyla hazır sunuyor. Bruno Capuano’nun.NET Blog’da duyurduğu From Model to Agent: The Agent Framework Harness, Live in C# serisi, tek bir C# ajanını dört oturumda adım adım yetenek ekleyerek inşa ediyor. Bu yazıda serinin kapsamını, harness’ın ne sağladığını ve her oturumda hangi kararların masaya yatırıldığını özetliyorum.

Seri nasıl işliyor?

Yayınlar,.NET YouTube kanalı ve Microsoft Reactor üzerinde eş zamanlı olarak, Eylül ayında dört ardışık perşembe gerçekleşiyor; her oturum sonrasında iki platformda da talep üzerine izlenebilir kalıyor. Yazının yayımlandığı sırada ilk iki oturum erişilebilir durumda, kalan ikisi ise programda.

Serinin çıkış noktası, yazarın daha önce yayımladığı “üç satır C# ile Foundry Hosted Agent” içeriği. O yazı dağıtım tarafını anlatıyordu; bu seri ise ondan önceki soruyu yanıtlıyor: Dağıtmadan önce ajanın içine ne koymalıyım?

Agent harness tam olarak ne yapıyor?

Model metin üretir. Ajan ise araç çağırabilen, sonuçları inceleyen, planını güncelleyen, işe yarar bilgiyi hatırlayan, riskli işlemler için onay isteyen ve büyüyen bağlam penceresini yöneten bir döngüye ihtiyaç duyar. Bu çevreleyen çalışma zamanı harness’tır.

Kavram, Agent Framework ekibinin “Build your own claw and agent harness” serisinden geliyor. Oradaki tanım basit: claw, bir harness üzerine kurulmuş CLI tarzı ajandır. Siz modeli, talimatları ve alana özgü araçları getirirsiniz; harness aradaki ajanik mekanizmayı sağlar.

.NET tarafında kritik satır şu:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
ChatOptions = new ChatOptions
{
Instructions = "You are a personal finance education assistant.",
Tools = [StockTools.GetStockPrice]
}
});

Bu tek çağrı, ajana şu yetenekleri içeren bir hat kazandırıyor:

otomatik fonksiyon çağırma
model çağrılarından sonra geçmişin kalıcılaştırılması
todo ve agent-mode sağlayıcılarıyla planlama
bağlam sıkıştırma (context compaction)
dosya belleği
model servisi destekliyorsa web araması
araç onayları
skills
OpenTelemetry enstrümantasyonu

Her yetenek yapılandırılabilir: değiştirebilir, kapatabilir veya kendi sağlayıcınızı ekleyebilirsiniz.

Örnek senaryo: kişisel finans eğitim asistanı

Dört oturum boyunca tek bir örnek üzerinden ilerleniyor: bir kişisel finans eğitim asistanı. Finans seçilmesinin nedeni, risk seviyeleri birbirinden farklı araçları aynı ajanda toplamaya elverişli olması:

Hisse fiyatı sorgulamak salt okunur bir araç çağrısı.
Portföy okumak kullanıcı verisine erişim demek.
Rapor yazmak bir dosyayı değiştiriyor.
Simüle edilmiş bir işlem yan etki üretiyor ve onay gerektiriyor.
Risk profilini hatırlamak kullanıcı kapsamlı, kalıcı bellek istiyor.
Portföy değeri hesaplamak, modelin prosa içinde aritmetik yapmasından çok kod çalıştırmakla daha doğru.
Shell komutları çalıştırmak sınırlandırma ve politika gerektiriyor.
Üretime çıkan bir finans ajanı iz kaydı, yönetişim ve değerlendirme istiyor.

Yazar açıkça belirtiyor: örneklerdeki tüm fiyat ve işlemler sahte ve yalnızca örnekleme amaçlı; bu bir yatırım tavsiyesi değil, ajan sistemlerinin farklı risk seviyelerindeki araçlarla nasıl davrandığını öğrenmek için bir senaryo. Kodun tamamı MafClaw örnek deposunda bulunuyor.

Oturum 1: modelden ajana

İlk oturumda Microsoft Foundry’deki bir model üzerinden IChatClient oluşturuluyor:

IChatClient chatClient =
new AIProjectClient(new Uri(endpoint), new AzureCliCredential())
.GetProjectOpenAIClient()
.GetResponsesClient()
.AsIChatClient(model);

Ardından harness ile sarmalanıp tek bir özel araç veriliyor. Araç sıradan bir C# fonksiyonu; Agent Framework şemayı imza ve açıklamalardan üretiyor:

[Description("Gets the illustrative stock price for a ticker symbol.")]
public static string GetStockPriceBySymbol(
[Description("Stock ticker symbol, e.g. MSFT")] string symbol)
{
var upper = symbol.Trim().ToUpperInvariant();
return upper switch
{
"MSFT" => "MSFT: 512.34 USD (mock)",
"NVDA" => "NVDA: 184.72 USD (mock)",
"AMZN" => "AMZN: 241.18 USD (mock)",
_ => $"{upper}: not available"
};
}
public static AIFunction GetStockPrice { get; } =
AIFunctionFactory.Create(
GetStockPriceBySymbol,
"get_stock_price");

Basit bir soruda model aracı seçiyor, harness çağırıyor, sonuç modele dönüyor ve nihai yanıt üretiliyor. Daha geniş bir istekte ise harness plan oluşturup todo listesini işleyebiliyor. Demoda özel bir planlama motoru yazılmıyor; yalnızca bu ajana özgü davranış yapılandırılıyor, planlama çalışma zamanını harness sağlıyor.

Oturum 2: kullanıcı verisiyle güvenli çalışmak

İkinci oturumda asistana bir portföy CSV dosyasına erişim veriliyor, ancak yalnızca onaylanmış bir çalışma dizini içinde:

var workingDirectory =
Path.Combine(AppContext.BaseDirectory, "working");
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
FileAccessStore =
new FileSystemAgentFileStore(workingDirectory),
ChatOptions = new ChatOptions
{
Instructions = """
The user's portfolio is in portfolio.csv.
Read it before answering portfolio questions.
Write generated reports under the approved working folder.
""",
}
});

Model keyfî dosya sistemi erişimi almıyor; uygulama tek bir klasöre köklenmiş bir dosya deposu veriyor, harness da dosya araçlarını bu sınır üzerinden açıyor. Sonuç: portföy sorusu çalışıyor, sınır dışındaki bir yolu okuma denemesi engelleniyor.

İkinci sınır insan onayı. Simüle işlem ApprovalRequiredAIFunction ile sarmalanıyor:

public static AIFunction RequestSimulatedTrade { get; } =
new ApprovalRequiredAIFunction(
AIFunctionFactory.Create(
RequestSimulatedTradeOrder,
"request_simulated_trade"));

Model eylemi talep edebiliyor ama doğrudan çalıştıramıyor. Harness önce bir onay isteği yayınlıyor; host uygulama hangi aracın hangi argümanlarla onay beklediğini gösterip insan kararını aynı ajan oturumuna geri dönduruyor.

Sürtünmeyi azaltmak için salt okunur dosya işlemlerine otomatik onay tanımlanıyor:

ToolApprovalAgentOptions = new ToolApprovalAgentOptions
{
AutoApprovalRules =
[
FileAccessProvider.ReadOnlyToolsAutoApprovalRule
],
},

Yazma, yıkıcı işlemler ve simüle işlem hâlâ onay sınırından geçiyor. Buradaki mantık net: her zararsız okuma kullanıcıyı böldüğünde onay gürültüye dönüşür; amaç daha çok onay penceresi göstermek değil, sonuç doğuran eylemleri görünür kılmaktır.

Canlı soru bir örneğe dönüştü

Yayındaki soru–cevap bölümünde bir izleyici “Kullanıcı onay isteğine hiç yanıt vermezse ne olur?” diye sormuş. Yazarın yanıtı: sonsuza kadar bekleyen bir onay akışı tamamlanmış sayılmaz. Oturumdan sonra sınırlı bir onay politikasıyla yeni bir örnek hazırlanmış: deneme başına beş saniyelik süre, en fazla beş deneme, eksik veya geçersiz girdide yeniden deneme, y için anında onay, n için anında ret, son denemeden sonra otomatik ret, kullanıcı isteminin kalanı için kalıcı ret ve modelden gelen tekrarlı onay turlarına sınır.

const int maxApprovalAttempts = 5;
var approvalTimeout = TimeSpan.FromSeconds(5);
var approvalPolicy = new TimedApprovalPolicy(
maxApprovalAttempts,
approvalTimeout);

Oturumun son bölümü bellekti: uygulamanın sahibi olduğu yerel JSON belleği ile yönetilen Foundry Memory karşılaştırıldı. Vurgulanan nokta şu: modelin “kaydettim” demesi, gerçekten bir şeyin kalıcılaştığının kanıtı değildir. Uygulamanın gerçek bir depolama sonucuna, bir kapsama ve hataları yüzeye çıkarma yoluna ihtiyacı var.

Oturum 3: skills, shell, CodeAct ve arka plan ajanları

Üçüncü oturum, sistem istemini yüzlerce sayfalık bir talimat kılavuzuna çevirmeden ajanı genişletmenin dört yolunu ele alıyor:

Skills: Alan bilgisini keşfedilebilir dosyalarda paketler. Ajan kısa açıklamayı görür, tam talimatları yalnızca ihtiyaç duyulduğunda yükler.
Shell: Dosya düzenleme veya dizin inceleme gibi doğal olarak komutla ifade edilen işleri, komut politikası, yürütme zaman aşımı ve açık onayla sınırlandırılmış bir çalışma dizininde çalıştırır.
CodeAct: Kontrollü bir yürütme ortamında kod yazıp çalıştırır; modelden metin içinde aritmetik istemekten daha güvenilir ve denetlenebilirdir.
Background agents: Ana ajan bağımsız araştırma görevlerini eşzamanlı çalışan ayrı ajanlara devreder ve sonuçları toplar.

Yazıda altı çizilen uyarı önemli: shell ve kod yürütme güçlü yeteneklerdir. Sınırlandırma, politika ve onay deneyimi iyileştirir ama izolasyonun yerini tutmaz.

Oturum 4: üretime hazır hâle getirmek

Son oturum dört başlıkla döngüyü kapatıyor:

Observability: OpenTelemetry izleri, araç çağrıları, model çağrıları ve token kullanımı ile ajanın gerçekte ne yaptığını görmek.
Governance: Microsoft Purview politika entegrasyonuyla kurumsal politikanın yalnızca insan davranışına değil ajan davranışına da uygulanması.
Evaluations: Tekrarlanabilir kalite kontrolleriyle “demoda iyi hissettirdi” ifadesini ölçülebilir bir sinyale çevirmek.
Deployment: Tek bir ajan tanımını konsol uygulaması, barındırılan uç nokta ve değerlendirme koşumu arasında paylaşarak Foundry Hosted Agent olarak dağıtmak; her host yalnızca kendisine uygun yetenekleri etkinleştiriyor.

Buradaki tasarım kararı da açıkça belirtiliyor: paylaşımlı bir barındırılan konteyner, geliştirme sırasında işe yaradı diye keyfî yerel dosya sistemi veya shell erişimini devralmamalı. Harness’ın yerelde verdiği her yeteneğin üretime uygun bir karşılığı var ve bu tercih framework’ün değil, sizin kararınız. Dağıtım yaklaşımı Agent Framework örneğindeki konteyner barındırma kurulumunu izliyor.

Neden harness ile başlamalı?

Bu parçaların hepsini kendiniz yazabilirsiniz: araç döngüsü, her servis çağrısından sonra geçmiş serileştirme, plan yönetimi, bağlam sıkıştırma, bellek katmanı, onay protokolü, skills yükleme, arka plan işçileri ve tüm hattın enstrümantasyonu. Bazı durumlarda bu düzeyde kontrol gerçekten gerekir.

Ancak çoğu ekip zamanını ajanı değerli kılan alan davranışına ayırmak ister: Hangi araçlar olmalı? Hangi veriye erişebilir? Hangi eylemler onay gerektirir? Ne hatırlamalı? Hangi skills yüklenmeli? Hangi görevler eşzamanlı çalışabilir? Hangi politikalar geçerli? Çalışıp çalışmadığını nasıl değerlendireceğiz?

Harness bu kararlara birleştirilebilir bir yuva sağlıyor. Sınırların sahibi hâlâ sizsiniz; araçları siz seçiyor, neyin onaylanacağına, hatırlanacağına, çalıştırılacağına, izleneceğine ve dağıtılacağına siz karar veriyorsunuz. Yalnızca bu soruları yanıtlamadan önce ajan çalışma zamanını sıfırdan yeniden inşa etmek zorunda kalmıyorsunuz.

Kaynaklar ve İleri Okuma

Bu yazı yapay zeka (büyük dil modelleri) ile hazırlanmış, insan editör tarafından incelenmiştir. İçerik üretim sürecimiz.

Aşkın KILIÇYazar

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.

AZ-305AZ-104AZ-500AZ-400DP-203AI-102