Çalışan bir agent içinde GPT-5'i Claude ile değiştirin ve çoğu zaman hemen hemen hiçbir şey değişmez. Yeniden deneme işlemlerini nasıl yönettiğini, bağlam penceresine ne beslediğinizi ya da ne zaman durmaya karar verdiğini değiştirin; tüm agent farklı davranır. Bu boşluk ipucudur: model, çalışan bir agent'ın en küçük ve en kolay değiştirilebilir parçasıdır. İlginç mühendislik, onu çevreleyen her şeyde yaşar.
Bu wrapper artık bir isme sahip. Uygulayıcılar, sabit bir komut dosyası çalıştırmak yerine zaman içinde eylemleri gerçekleştiren bir şeye metin oluşturucuyu dönüştüren katman için "harness" terimini benimsedi. Terim 2026 yılının başında Twitter ve mühendislik bloglarında hızla yayıldı; bu da aynı kelimenin her okuduğunuz yazıda biraz farklı anlam taşımasıyla gevşek biçimde kullanıldığı anlamına geliyor. Bu makale tam olarak tanımlar: harness nedir, neden oluşur, "framework" ve "scaffold"dan nasıl farklıdır ve agent'ınızın kalitesinin büyük kısmı neden modelde değil harness'ta gizlidir.
Kısa Versiyon
- Bir agent harness, LLM etrafındaki yürütme döngüsünü, araçları, belleği, bağlamı, durumu, hata işlemeyi ve güvenlik sınırlarını yöneten yazılımdır. Model metin üretir; harness modelin ne gördüğüne, ne yapabileceğine, ne zaman duracağına ve bir şeyler bozulduğunda ne olacağına karar verir.
- Prodüksiyonda, model çağrısı genellikle sistem yüzey alanının en küçük görünür parçasıdır. İyi kurulmuş bir harness içindeki daha zayıf bir model, dağınık bir harness içindeki daha güçlü bir modeli geçebilir, özellikle uzun süreli, araç yoğun görevlerde.
- Bir harness yaklaşık dokuz ila on bir yinelenen bileşene sahiptir. Bunların çoğu, modelin hiçbir zaman doğrudan temas etmediği şeylerdir.
- "Harness" ile "framework" aynı şey değildir. Bir framework (LangGraph, agents SDK) üzerine inşa ettiğiniz kütüphanedir; harness ise o kütüphanenin derlemenize yardımcı olduğu çalışan katmandır.
Agent Harness Nedir?
Bir agent harness, yürütme döngüsünü, araç erişimini, belleği, bağlamı, durum kalıcılığını, hata işlemeyi ve güvenlik sınırlarını yöneten dil modelinin etrafındaki yazılım altyapısıdır. Model metin üretir. Harness, her turda modelin ne gördüğüne, hangi eylemleri gerçekleştirebileceğine, ne zaman duracağına ve bir adım başarısız olduğunda ne olacağına karar verir.
En net ifade LangChain'den geliyor ve bunu bir denklem olarak özetliyor: Agent = Model + Harness. Model zekayı sağlar. Harness ise bu zekanın dünyada bir şeyler yapmasını sağlayan katmandır.
"Harness, modelin kendisi olmayan her türlü kod, yapılandırma ve yürütme mantığıdır."
— LangChain, Bir Agent Harness'ın Anatomisi
Sınırı anlamanın en kolay yolunu tek bir soru üzerinden buluyorum: ajanınız yanlış bir şey yaptığında, modelin kendi akıl yürütmesi mi yanlıştı, yoksa etrafındaki sistem modele yanlış bağlamı, yanlış araçları mı verdi ya da kurtarma yolu bırakmadı mı? Gerçek bir sistemde çoğu zaman ikincisi geçerlidir. Model, hatalı girdiler üzerinde doğru akıl yürüttü. Girdileri kontrol eden şey harness'tır.
Temel çıkarım: Model üretir; harness yönetir. Bu ayrım kavramın tamamıdır.
Bir Agent Harness'ın Bileşenleri Nelerdir?
Her production harness aynı tekrarlayan parçaları bir araya getirir: modeli tur tur sürüklüyen bir yürütme döngüsü, ona hareket etme imkanı veren araç erişimi, turlar arasında bellek, şu anda gördükleri için bağlam yönetimi, çalışmanın oturumlar boyunca hayatta kalması için durum kalıcılığı, başarısız adımlar için hata işleme ve yapabileceklerini kısıtlayan güvenlik bariyerleri. Production sistemleri doğrulama döngüleri ve alt ajan orkestrasyonu ekler.
Uygulayıcıların gerçek sistemleri nasıl tarif ettiğinden derlenen kullanışlı bir envanter:
- Yürütme / kontrol döngüsü: ajanı adım adım yönlendiren şey. Modeli çağır, çıktısını oku, istediği aracı çalıştır, sonucu geri gönder, durdurma koşuluna kadar tekrarla.
- Tool erişimi: modelin erişebildiği fonksiyonlar, API'ler, kod çalıştırma ortamı ve dosya sistemi.
- Bellek: agentin turnlar ve oturumlar arasında sakladığı şey.
- Bağlam yönetimi: her turda modelin penceresine ne yüklenir ve taşma durumunda ne sıkıştırılır.
- Durum kalıcılığı / checkpoint: agentin durumunu kaydederek çökmüş veya duraklatılmış bir çalışmanın devam edebilmesini sağlamak.
- Hata yönetimi: bir tool çağrısı veya model çağrısı başarısız olduğunda yeniden denemeler, geri dönüşler ve kurtarma.
- Güvenlik sınırları: aracın yapabileceklerine ilişkin sınırlamalar; izin verilen araçlar, adım sınırları ve çıktı doğrulaması gibi.
- Doğrulama döngüleri: aracın (veya harness'ın) işi tamamlandı saymadan önce kendi çalışmasını kontrol etmesi.
- Alt ajan orkestrasyonu: daha büyük görevlerde alt ajanları başlatma, görev devretme ve sonuçlarını toplama.
Bunların hepsi evrensel değil. Yürütme döngüsü, araçlar, bağlam yönetimi ve hata yönetimi bir hafta sonu prototipinde bile karşımıza çıkar. Durum kalıcılığı, doğrulama ve alt ajan orkestrasyonu, prototiplerin ve üretim sistemlerinin ayrıştığı noktalardır. Bir prototip bunları atlayabilir; uzun süreli çalışan bir üretim ajanı atlatamaz. Anthropic'in şu konudaki yazısı: uzun süreli çalışan ajanlar yalnızca üretim ortamına özgü kısımların bir turu: bağlam penceresi sıfırlandıktan sonra bir ajanın ilerleme dosyasından anlayışını nasıl yeniden kurduğu ve testlerin döngüye nasıl bağlandığı.
Akademik köprüyü arayanlar için yakın zamanda yayımlanan bir ajan mimarileri araştırması aynı makineyi daha küçük bir resmi temel bileşenler demetine sıkıştırır. Uygulayıcı listesi ve araştırmanın çerçevesi aynı yapıya ait iki yakınlaştırma düzeyidir: araştırma sıkıştırır, yukarıdaki envanter genişletir. Dokuz ila on bir sayısını çoğu üretim harness'ının paylaştığı bileşenler olarak değerlendirin, onaylanmış bir standart olarak değil; alan henüz hiçbir şeyi onaylamamıştır.
Temel çıkarım: Bir ajanın hareketli parçalarının çoğu harness'ta yaşar, modelde değil. Model, birçok bileşenden biridir.
Harness Neden Modelden Daha Önemlidir?
İyi tasarlanmış bir harness içindeki daha zayıf bir model, kötü tasarlanmış bir harness içindeki daha güçlü bir modeli sıklıkla geride bırakır. Sebep mekanik, sihirli değil: uçtan uca ajan güvenilirliği her adımın güvenilirliğinin çarpımıdır ve bu adımların çoğu (araç seçimi, bağlam derleme, hata kurtarma) modelin değil harness'ın işidir. Bunları geliştirin ve içinde hangi model olursa olsun tüm zincir daha güvenilir hale gelir.
Aritmetik bunu somutlaştırır. Bir on adımlı görevdeki her adımın %99 başarılı olduğunu varsayalım. Uçtan uca başarı %99 değildir. 0,99'un onuncu kuvvetidir, yaklaşık %90. Her adımı %99,9'a çıkarın, uçtan uca oran yaklaşık %99'a sıçrar. Adım başı güvenilirlik bileşik etki yapar ve adım başı güvenilirlik ezici biçimde bir harness özelliğidir. Bu yüzden hata işleme ve bağlam yönetimini sıkılaştırmak, bir kıyaslama testinde yarım puan daha iyi bir modelle değiştirmekten daha fazla karşılık verir.
Aynı yönü işaret eden bir üretim sinyali var. MongoDB, Vercel'in vaka çalışmasına atıfla, Vercel'in agent'larının araçlarının büyük bölümünü azalttığını ve aynı model üzerinde, daha küçük ve temiz bir harness ile başarı oranının keskin biçimde yükseldiğini bildiriyor. Bunu kanıt olarak değil, örtüşen kanıt olarak okuyun: bu bir üretim vakası, kontrollü bir deney değil; ancak yukarıdaki bileşik aritmetik ve anket çalışmasıyla aynı yönü işaret ediyor.
Bir platform mühendisi olarak sürekli geri döndüğüm sezgisel kural şu: bağlam darboğazdır, ham model kapasitesi değil; bugünkü model boşluklarını örtbas etmek için inşa edilen iskeletler modeller geliştikçe silinip gidecektir. Harness'ın dayanıklı parçalarını (döngü, durum, kurtarma) inşa edin ve alttaki modelin kendi takviminde ilerlemesine izin verin.
Temel çıkarım: Agent'ınız başarısız olduğunda, modelden önce harness'tan şüphe edin. Olasılıklar bunu destekliyor.
Harness, Scaffold ve Framework Arasındaki Fark Nedir?
Bu üçü birbirinin yerine kullanılıyor, ama olmamalı. A framework LangGraph veya bir agents SDK gibi üzerine inşa ettiğiniz kütüphane veya SDK'dır. A harness modelin etrafındaki çalışan yürütme ve yönetişim katmanıdır; bir framework bunu bir araya getirmenize yardımcı olur. A scaffold üçünün en gevşeğidir: bazen harness ile neredeyse eş anlamlı, bazen bunun prototip sürümü, bazen de özellikle prompt ve araç açıklama katmanı olarak kullanılır.
Terminoloji gerçekten yerleşmemiş durumda ve yapılabilecek en temiz şey, bir kullanım dayatmak yerine kullanımları haritalandırmaktır. HuggingFace'in Ajan Sözlüğü bunu doğrudan söylüyor:
"Bu terimlerin çoğunun henüz evrensel olarak kabul edilmiş tanımları yok ve farklı framework'ler aynı kelimeyi farklı şekillerde kullanıyor."
— HuggingFace, Ajan Sözlüğü
| Terim | Neyi ifade ettiği | İlişki |
|---|---|---|
| Framework | Geliştirme yaptığınız kütüphane veya SDK (LangGraph, bir ajan SDK'sı) | Bir harness oluşturmak için araç |
| Harness | Modelin etrafındaki çalışan katman: döngü, araçlar, bağlam, durum, koruyucular | Gönderdiğiniz ve çalıştırdığınız şey |
| Scaffold | Geniş anlamda kullanılır: harness ile neredeyse eş anlamlı, ya da prototip düzeyi / prompt katmanı versiyonu | Harness ile örtüşür; daha az kesin |
| Döngü | Harness içindeki yürütme döngüsü | Harness'in bir bileşeni |
Kendi sisteminiz hakkında akıl yürütmek için pratik sonuç: biri "framework" dediğinde, kütüphaneyi mi yoksa çalışan şeyi mi kastettiğini sorun. Biri "scaffold" dediğinde, tüm harness'i mi yoksa sadece prompt-ve-araç katmanını mı kastettiğini sorun. Buradaki değer, belirsizliği gidermektir; son sözü söyleme iddiası değil.
LangGraph Harness Desenini Nasıl Uygular?
LangGraph, harness deseninin popüler bir açık kaynak Python uygulamasıdır. Ajan yürütmesini, aralarında tiplenmiş durum akan ve her geçiş için checkpoint alınabilen yönlendirilmiş bir düğüm ve kenar grafiği olarak modeller. Yukarıdaki soyut bileşenler belirsiz geliyorsa, LangGraph bunların gerçek bir araçta somut şekil aldığını görmek için doğru yerdir.
Eşleşme neredeyse bire birdir. Düğümler ve kenarlar yürütme döngüsüdür: her düğüm iş yapar, her kenar kontrolün nereye gideceğine karar verir. Düğümler arasında geçirilen tiplenmiş durum nesnesi, bağlam-ve-durum bileşeninin açık hale getirilmiş halidir. Checkpointing (LangGraph durumu savers aracılığıyla kalıcı hale getirir Postgres destekli olanı gibi) durum kalıcılığı bileşenidir. Yapılandırılabilir bir adım limiti, hatalı davranan bir ajanın sonsuza kadar döngüye girmesini önleyen bir durdurma koşulu guardrail'idir. Aynı bileşenler, belirli bir kütüphane tarafından adlandırılmış ve bağlanmış.
Kendi sunucunuzda, günün her saatinde bir LangGraph ajanı çalıştırmak istiyorsanız, bu kavramsal değil, bir dağıtım sorusudur. Bkz. Linux VPS kılavuzumuzu bu yol için. Burada LangGraph sadece üzerinde çalışılmış örnektir: "yürütme döngüsü", "durum kalıcılığı" ve "guardrail"in soyutlamalar olmadığının, gerçek kodda işaret edebileceğiniz şeyler olduğunun kanıtı.
Sıkça Sorulan Sorular
Agent Harness Nedir?
Bir agent harness, bir dil modelini ajanına dönüştüren modelinin etrafındaki yazılımdır. Yürütme döngüsünü, araç erişimini, belleği, bağlamı, durum kalıcılığını, hata işlemeyi ve guardrail'leri yönetir. Model metin üretir; harness modelin ne gördüğüne, ne yapabileceğine, ne zaman duracağına ve bir şey başarısız olduğunda ne olacağına karar verir.
Agent Harness ile Agent Framework Aynı Şey midir?
Hayır. Framework, LangGraph veya bir agents SDK gibi üzerine inşa ettiğiniz kütüphane ya da SDK'dır. Harness ise bir framework'ün derlemenize yardımcı olduğu, modelin etrafındaki çalışan yürütme ve yönetim katmanıdır (döngü, araçlar, bağlam, durum ve kısıtlamalar). Bir harness oluşturmak için framework kullanırsınız.
Her Agent Harness'in Bileşenleri Nelerdir?
Çoğu harness ortak bir çekirdeği paylaşır: bir yürütme döngüsü, araç erişimi, bellek, bağlam yönetimi, durum kalıcılığı, hata yönetimi ve kısıtlamalar. Üretim harnessleri doğrulama döngüleri ve alt-ajan orkestrasyonu ekler. Prototipler yalnızca üretime özgü kısımları atlayabilir, ancak döngü, araçlar, bağlam işleme ve hata yönetimi neredeyse her yerde görünür.
"LLM, Ajan Sisteminizin En Küçük Parçasıdır" Ne Anlama Gelir?
Bu, bir ajanın davranışının ve güvenilirliğinin büyük bölümünün modelden değil harnessden geldiği anlamına gelir. Uçtan uca güvenilirlik, her adımın başarı oranının çarpımıdır ve adımların büyük çoğunluğu harness işidir. MongoDB, Vercel'in vaka çalışmasına atıfta bulunarak, aynı model üzerinde yalnızca harness değişikliklerinden kaynaklanan bir başarı oranı artışı bildirmektedir. Bu, harnessin düzeltilmesinin modelin düzeltilmesinden daha etkili olduğunun kanıtıdır.
Ajanınızın Kalitesi Nerede Yaşar
Harness, bir ajanın kalitesinin büyük bölümünün bulunduğu yerdir ve artık kendi sisteminizdeki sorunları tespit etmek için gereken terminolojiye sahipsiniz. Bir harness tanımlayabilir, bileşenlerini adlandırabilir, onu bir framework ve scaffold'tan ayırt edebilir ve belirli bir başarısızlığın model sorunu mu yoksa harness sorunu mu olduğu konusunda akıl yürütebilirsiniz.
Dolayısıyla, ajanınız bir dahaki sefere yanlış davrandığında, önce harness katmanını denetleyin: ona beslediğiniz bağlamı, açığa çıkardığınız araçları, belirlediğiniz durdurma koşullarını ve başarısız bir adımdan nasıl kurtulduğunu. O katman kontrol edilmeden daha büyük bir modele geçmeyin. Çoğu zaman geçmeniz gerekmeyecek.
