Agent Harness Engineering

Bir kodlama ajanı, modelin kendisi ve etrafına inşa edilen her şeydir. Koşum mühendisliği, bu iskeleti yaşayan bir yapıt olarak ele alır ve ajan her hata yaptığında onu sıkılaştırır.

Basitçe söylemek gerekirse: bir ajan başarısız olduğunda, aynı hatayı bir daha asla yapmaması için kalıcı bir çözüm üretirsiniz.

Son iki yıldır sektör modelleri tartışıyor: hangisi daha zeki, hangisi daha temiz React kodu yazıyor veya hangisi daha az halüsinasyon görüyor. Bu tartışma önemli olmakla birlikte, sistemin diğer yarısını göz ardı ediyor.

Model, çalışan bir ajan için yalnızca bir girdidir. Geri kalanı koşumdur: modelin etrafına sarılı, görevleri tamamlayabilmesi için gerekli olan prompt'lar, araçlar, bağlam politikaları, kancalar, sanal alanlar, alt ajanlar, geri bildirim döngüleri ve kurtarma yolları.

İyi bir koşuma sahip vasat bir model, kötü bir koşuma sahip harika bir modeli sürekli olarak yener. Giderek artan bir şekilde, en ilginç mühendislik çalışması modeli seçmekte değil, etrafındaki iskeleti tasarlamakta yatıyor.

Bu disiplinin artık bir adı var. @Vtrivedy10, koşum mühendisliği terimini ortaya atarak bir koşumun gerçekte ne olduğunu ve her bir parçasının neden var olduğunu net bir şekilde açıkladı. @dexhorthy gibi sektördeki diğer sesler ortaya çıkan kalıpları takip ederken, HumanLayer ajan başarısızlıklarını bir yapılandırma "beceri sorunu" olarak çerçeveliyor, Anthropic'in mühendislik ekibi uzun süreli uygulama tasarımı üzerine kılavuzlar yayınlıyor ve Birgitta Böckeler kullanıcı tarafı deneyimini araştırıyor - hepsi kabaca aynı fikirde birleşiyor.

Bu yazı, tüm bu iplikleri bir araya getiriyor.

Koşum Gerçekte Nedir?

Trivedy'nin temel tanımı işin büyük kısmını üstleniyor:

Ajan = Model + Koşum. Eğer model değilseniz, koşumsunuz.

Bir koşum, modelin kendisi olmayan her kod parçasını, yapılandırmayı ve yürütme mantığını kapsar. Ham bir model bir ajan değildir. Ancak bir koşum ona durum, araç yürütme, geri bildirim döngüleri ve uygulanabilir kısıtlamalar sağladığında bir ajan haline gelir.

Somut olarak, bir koşum şunları içerir:

• Sistem prompt'ları, CLAUDE.md, AGENTS.md, beceri dosyaları ve alt ajan talimatları.
• Araçlar, beceriler, MCP sunucuları ve bunların teknik açıklamaları.
• Dosya sistemi, sanal alanlar ve başsız tarayıcılar gibi paketlenmiş altyapı.
• Alt ajanları başlatma, devir teslimleri yönetme ve modelleri yönlendirme için orkestrasyon mantığı.
• Lint kontrolleri veya bağlam sıkıştırması gibi deterministik yürütme için kancalar ve ara katman yazılımları.
• Günlükler, izlemeler, maliyet ve gecikme ölçümü için gözlemlenebilirlik araçları.

Özünde, bir ajan bir hedefe ulaşmak için bir döngü içinde araçları çalıştıran bir sistemdir. Gerçek beceri, hem araçları hem de bu döngüyü tasarlamakta yatar.

Bu geniş bir yüzey alanını temsil etse de, bu sizin yüzey alanınızdır, model sağlayıcısının değil. Claude Code, Cursor, Codex, Aider ve Cline'in hepsi birer koşumdur. Temeldeki model platformlar arasında aynı olabilir, ancak deneyimlediğiniz davranışa koşum hakimdir.

"Beceri Sorununu" Yeniden Çerçeveleyelim

Mühendislerin, bir ajan anlamsız bir şey yaptığında modeli suçlaması ve sorunu "bir sonraki sürümü beklemek" üzere rafa kaldırması yaygındır.

Koşum mühendisliği zihniyeti bu varsayılanı reddeder. Başarısızlıklar genellikle bir şekilde anlaşılabilirdir. Ajan bir kuralı görmezden geldiyse, AGENTS.md dosyasına ekleyin. Yıkıcı bir komut çalıştırdıysa, onu engellemek için bir kanca yazın. 40 adımlı bir görevde kaybolduysa, mimariyi bir planlayıcı ve bir yürütücü olarak bölün. Sürekli olarak bozuk kodla bitiriyorsa, döngüye bir tür denetimi geri basınç sinyali ekleyin.

HumanLayer'ın dediği gibi: "Bu bir model sorunu değil. Bir yapılandırma sorunudur." Performans kıyaslamalarını düşünün: hazır bir çerçeve içinde çalışan lider bir model, aynı modelin özel, yüksek düzeyde ayarlanmış bir koşumda çalıştırılmasından genellikle çok daha düşük puan alır. Bir modeli daha iyi kod tabanı araçlarına, daha sıkı prompt'lara ve daha keskin geri basınca sahip bir ortama taşımak, orijinal kurulumun geride bıraktığı yeteneklerin kilidini açabilir.

Bugünkü modellerin teorik olarak yapabilecekleri ile gerçekte yaptıklarını gördükleriniz arasındaki boşluk, büyük ölçüde bir koşum boşluğudur.

Mandal: Her Hata Bir Kural Haline Gelir

Koşum mühendisliğindeki en hayati alışkanlık, ajan hatalarını kalıcı sinyaller olarak ele almaktır - yeniden deneyip unutulacak tek seferlik tesadüfler olarak değil.

Bir ajan, yanlışlıkla birleştirilen yorumlanmış bir testle bir PR gönderirse, bu bir girdidir. AGENTS.md'nin bir sonraki yinelemesi şunu belirtmelidir: "Testleri asla yorumlama; sil veya düzelt." Bir sonraki ön işleme kancası, diff içinde .skip( ifadesini otomatik olarak işaretlemelidir. İncelemeci alt ajanı, yorumlanmış testleri engelleyecek şekilde güncellenmelidir.

Kısıtlamalar yalnızca gerçek bir başarısızlık gözlemlediğinizde eklenmeli ve yetenekli bir model onları gereksiz kıldığında kaldırılmalıdır. İyi bir sistem prompt'undaki her satır, belirli, tarihsel bir başarısızlığa kadar izlenebilmelidir.

Bu nedenle, koşum mühendisliği herkese uyan tek bir çerçeve değil, bir disiplindir. Belirli bir kod tabanı için doğru koşum, tamamen onun benzersiz başarısızlık geçmişi tarafından şekillendirilir.

Davranıştan Geriye Doğru Çalışmak

Bir koşum tasarlamanın en etkili yolu, istenen davranışla başlamak ve onu sağlayan bileşeni oluşturmaktır: İstediğimiz davranış → Bunu başarmak için koşum tasarımı.

Koşumun her parçasının belirgin bir işi olmalıdır. Bir bileşenin sağlamak için var olduğu belirli davranışı adlandıramıyorsanız, kaldırılmalıdır.

Dosya Sistemi ve Git - Kalıcı Durum

Dosya sistemi temeldir. Modeller yalnızca bağlam pencerelerine sığan şeyler üzerinde çalışabilir. Bir dosya sistemi, veri okumak için bir çalışma alanı, ara işleri boşaltmak için bir yer ve birden çok ajanın koordinasyonu için bir yüzey sağlar.

Git eklemek, ajanın ilerlemeyi izlemesine, deneylerde dallanmasına ve hataları geri almasına olanak tanıyan ücretsiz sürüm oluşturma sağlar.

Bash ve Kod Yürütme: Genel Amaçlı Araçlar

Çoğu ajan bir ReAct döngüsü üzerinde çalışır: akıl yürüt, bir araç çağrısı aracılığıyla hareket et, gözlemle, tekrarla. Ajana akla gelebilecek her eylem için önceden bir araç oluşturmak yerine bash erişimi vermek, ihtiyaç duyduğu şeyi anında oluşturmasına olanak tanır.

Ajanlar genellikle kabuk komutlarında başarılıdır, bu da bash ve kod yürütmeyi otonom sorun çözme için varsayılan strateji haline getirir.

Sanal Alanlar ve Varsayılan Araçlar

Bash yalnızca güvenli bir şekilde çalışıyorsa kullanışlıdır. Sanal alanlar, ajanlara ana makineyi riske atmadan kod çalıştırmak, dosyaları incelemek ve çalışmayı doğrulamak için izole bir ortam sağlar.

İyi bir sanal alan, güçlü varsayılanlarla birlikte gelir: önceden yüklenmiş dil çalışma zamanları, test CLI'ları ve başsız tarayıcılar; ajanın kendi çalışmasını gözlemlemesine ve kendi kendini doğrulama döngüsünü kapatmasına olanak tanır.

Bellek ve Arama: Sürekli Öğrenme

Modellerin, eğitim ağırlıkları ve mevcut bağlamlarının ötesinde hiçbir bilgisi yoktur. Koşumlar, her oturuma bilgi enjekte eden bellek dosyaları (AGENTS.md gibi) kullanarak bu boşluğu kapatır.

Yeni kütüphane sürümleri veya canlı veriler gibi gerçek zamanlı bilgiler için web arama ve MCP araçları doğrudan koşuma entegre edilir.

Bağlam Çürümesiyle Mücadele

Modellerin muhakeme yeteneği, bağlam pencereleri doldukça düşer. Koşumlar bu kıtlığı üç ana teknik kullanarak yönetir:

• Sıkıştırma: API hatalarını önlemek için eski bağlamı akıllıca özetleme ve boşaltma.
• Araç çağrısı boşaltma: Büyük araç çıktılarını (2.000 satırlık günlükler gibi) dosya sisteminde saklarken, bağlamda yalnızca temel başlıkları ve altbilgileri tutma.
• Aşamalı açıklama: Talimatları ve araçları, bir görev açıkça gerektirdiğinde ortaya çıkarma; başlangıçta her şeyi yüklemek yerine.

Uzun Vadeli Yürütme

Otonom, uzun süreli çalışma, erken durma ve zayıf problem ayrıştırmasından muzdariptir. Koşumlar buna yapısal tasarım yoluyla karşı koyar:

• Döngüler: Bir modelin çıkma girişimini engelleme ve onu yeni bir bağlam penceresinde bir tamamlama hedefine karşı devam etmeye zorlama.
• Planlama: Modeli, hedefleri adım adım bir plan dosyasına ayrıştırmaya zorlama ve her adımdan sonra kendi kendini doğrulama kancaları aracılığıyla çalışmasını kontrol etme.
• Bölmeler: Oluşturma ve değerlendirmeyi ayrı ajanlara ayırma; modellerin kendi çalışmalarını değerlendirirken sahip oldukları içsel olumlu önyargıyı önleme.

Kancalar Sizin Uygulama Katmanınızdır

Kancalar, bir eylemi talep etme ile onu uygulama arasındaki boşluğu doldurur. Belirli yaşam döngülerinde çalışırlar: bir araç çağrısından önce, bir dosya düzenlemesinden sonra veya bir işlemeden önce. Kancalar, yıkıcı komutları engeller, token tasarrufu için otomatik biçimlendirmeyi zorunlu kılar ve test paketlerini çalıştırır.

İdeal olarak, başarı sessizdir ve başarısızlıklar ayrıntılıdır. Bir tür denetimi geçerse, ajan hiçbir şey duymaz; başarısız olursa, hata kendi kendini düzeltme için doğrudan döngüye enjekte edilir.

İşte Kural Kitabı ve Araç Seçimi

Bir deponun kökünde düz bir işaretleme dosyası hala en yüksek kaldıraçlı yapılandırma noktasıdır. Ancak, bir stil rehberi değil, bir pilot kontrol listesi gibi ele alınmalıdır. Kısa tutun ve her kuralın geçmiş bir başarısızlık yoluyla kazanıldığından emin olun.

Aynı disiplin araçlar için de geçerlidir. On adet yüksek odaklı araç, elli adet örtüşen araçtan her zaman daha iyi performans gösterir.

Ayrıca, araç açıklamaları prompt'u doldurduğundan, kötü niyetli veya özensiz harici entegrasyonlar (doğrulanmamış MCP sunucuları gibi), ajan daha çalışmaya başlamadan önce ona kötü prompt'lar enjekte edebilir.

Üretimde Böyle Görünüyor

Olgun bir koşumun gördüğüm en net kamusal resmi, Fareed Khan'ın (tahmini) Claude Code'un mimarisi dökümüdür.

Önceki bölümdeki hemen hemen her kavram, bu diyagramda adlandırılmış bir bileşen olarak karşımıza çıkıyor. Bağlam enjeksiyonu bilgi katmanıdır. Döngü durumu, bellek deposunda ve çalışma ağacı izolatöründe yaşar. Yıkıcı eylem kancaları, izin geçidinin arkasında oturur. Alt ajan bağlam güvenlik duvarları, tüm çoklu ajan katmanıdır. Araç dağıtım kaydı, MCP sunucularının ve bash'in takıldığı yerdir. Claude Code'un yörüngesi, en az altındaki model kadar koşumla ilgilidir.

Koşumlar Küçülmez, Yer Değiştirir

Modeller geliştikçe, bir koşuma olan ihtiyaç ortadan kalkmaz - kayar.

Daha iyi modellerin iskeleti gereksiz kılacağını varsaymak caziptir. Örneğin, son model yükseltmeleri "bağlam kaygısı" azaltımlarına olan ihtiyacı büyük ölçüde azalttı. Ancak taban yükseldikçe, tavan da yükselir. Daha önce ulaşılamayan görevler artık oyundadır ve tamamen yeni başarısızlık modlarını beraberinde getirir.

Bir koşumdaki her bileşen, modelin kendi başına neyi yapamayacağına dair bir varsayımı kodlar. Model geliştiğinde, eskiyen iskelet kaldırılmalı ve bir sonraki ufka ulaşmak için yeni iskelet inşa edilmelidir.

Peki Ya Eğitim Döngüsü?

Koşum tasarımı ve model eğitimi arasında aktif bir geri bildirim döngüsü vardır.

Günümüz modelleri genellikle döngüde belirli koşumlarla sonradan eğitilir ve bir dereceye kadar aşırı uyum yaratır. Model, koşum tasarımcılarının önceliklendirdiği belirli eylemlerde (ör. dosya sistemi işlemleri, bash, alt ajan dağıtımı) son derece iyi hale gelir.

Bu, koşumu statik bir yapılandırma dosyası değil, yaşayan bir sistem haline getirir ve "en iyi" koşumun, sizin belirli görevleriniz ve iş akışlarınız için özel olarak optimize edilmiş olan olduğunu kanıtlar.

Hizmet Olarak Koşum (HaaS)

Sektör, LLM API'leri (tamamlamalar sağlayan) üzerine inşa etmekten, Koşum API'leri (bir çalışma zamanı sağlayan) üzerine inşa etmeye doğru kayıyor. SDK'lar artık döngüyü, araçları, bağlam yönetimini, kancaları ve sanal alanları kutudan çıkar çıkmaz sunuyor.

Modern varsayılan, orkestrasyonu sıfırdan oluşturmak yerine, bir koşum çerçevesi seçmek, temel direklerini yapılandırmak ve yalnızca alana özgü prompt ve araç tasarımına odaklanmaktır.

Sorun gidermeyi ölçeklenebilir kılan şey budur: tüm ajan mimarisini yeniden icat etmek yerine, iyi yapılandırılmış bir yapılandırma yüzeyini ince ayarlamaktır.

Bu Nereye Gidiyor

Bugünün en iyi kodlama ajanlarına bakarsanız, altlarındaki modellerden çok birbirlerine benzerler. Modeller farklıdır, ancak koşum kalıpları yakınsamaktadır. Sektör, üretken metni gönderilebilir yazılıma dönüştürmek için gereken yük taşıyıcı iskeleti hızla belirlemektedir.

En heyecan verici açık problemler, tek ajanların ötesine geçiyor: birden çok ajanı paralel olarak orkestre etmek, ajanların koşum düzeyindeki başarısızlıkları düzeltmek için kendi izlemelerini analiz etmelerini sağlamak ve araçları tam zamanında dinamik olarak bir araya getiren ortamlar oluşturmak.

Nihayetinde bu, koşumların statik yapılandırma dosyaları olmaktan çıkıp derleyiciler gibi davranmaya başladıkları aşamadır.

Harika bir ajan koşum çerçevesi arıyorsanız, @FredKSchott Flue'yu yazdı. Sağlam ve görünüşe göre bu yazının daha önceki bir sürümünden ilham almış!