2026'da AI Ajanları Nasıl Oluşturulur (Tam Kurs)

işte kimsenin yapay zeka geliştiricilerine söylemediği gerçek.

çoğu demo yapıyor

tek ihtiyacın olan şey

üretim seviyesinde bir yapay zeka ajanı

TLDR; okumak istemiyorsan, bu bağlantıyı ajanına ver ve sorular sor: ➡️https://github.com/codejunkie99/agentic-harness

işte her şeyi başlatan tweet

sorun şu ki, çoğu yapay zeka mühendisi ajanlar konusunda ciddileşmeye karar verdiklerinde aslında ne inşa edeceklerine dair net bir fikre sahip değil.

bazıları LangChain'e yöneliyor çünkü YouTube'daki çoklu ajan demoları temiz görünüyor ve sonraki iki haftayı Python birlikte çalışabilirliği ve asenkron çalışma zamanı uyumsuzluklarıyla savaşarak geçirip her şeyi çöpe atıyor.

bazıları sıfırdan özel bir orkestrasyon katmanı inşa etmeye çalışıyor: bir döngü, bir oturum deposu, bir bağlam birleştirici ve asıl ajanı asla bitiremiyor çünkü altyapı zaman çizelgesini yemiş.

diğerleri merhaba-dünya webhook örneğini kopyalıyor, bir JSON yanıtı alıyor, sistemi anladıklarını varsayıyor ve bir oturum on dakikayı geçtiğinde, uzaktaki bir sanal alan görev sırasında çöktüğünde veya bağlam penceresi sıkıştırma yapılandırılmadan dolduğunda bozulan bir şey gönderiyor.

sonuç genellikle aynı: çok fazla tesisat, üretim ajanı yok ve üretim ajanı çalışma zamanının gerçekte neye benzediğine dair bir zihinsel model yok.

2026'da gerçek ajanlar inşa etmek ve göndermek istiyorsan, altı çerçeve öğrenmene gerek yok.

bir çalışma zamanını, bir üretim ajanına işleyiciden dağıtıma kadar sahip olacak kadar derinlemesine anlaman gerekiyor.

bu, şunları nasıl yapacağını öğrenmek anlamına geliyor:

• üç katmanlı mimariyi, işleyici mantığının sağlayıcı değişikliklerinden ve hedef değişikliklerinden ajan koduna dokunmadan kurtulacağı şekilde bağlamak
• oturumları ve görevleri doğru kullanmak, böylece uzun işler kendi bağlamlarını kirletmez
• model davranışını hiçbir şeyi yeniden derlemeden şekillendiren roller ve beceriler yazmak
• sıkıştırmayı yapılandırmak, böylece iki saat çalışan oturumlar birinci saatte halüsinasyon görmeye başlamaz
• HttpSessionEnv'yi uzaktaki sanal alanlara yönlendirmek, böylece ikili dosya yerel olarak çalışırken yürütme Linux'ta çalışır
• doğru derleme hedefini seçmek: native, node veya Cloudflare, aralarında herhangi bir ajan mantığını yeniden yazmadan
• bağdaştırıcıları elle yazmak yerine bağlayıcılar oluşturmak ve bu ayrımın gerçek yük altında neden önemli olduğunu anlamak

bu rehber, gerçek agentic-harness kod tabanından, onunla altı hafta boyunca gerçek ajanlar inşa edip kırmaktan ve hata ayıklaması en çok zaman alan başarısızlık modlarından oluşturulmuş tam bir teknik anlatımdır.

yazı 4.000+ KELİME ve depodan ve belgelerden doğrudan alıntılar içeriyor, ikinci el özetler veya demo seviyesindeki örnekler değil.

ancak asıl değeri, her bölümün çalışan bir kod parçacığı, kararın neden alındığına dair net bir açıklama ve atlarsan karşılaşacağın tam başarısızlık modunu içermesidir.

bu sayede okumayı bitirdiğinde, ilk işleyiciden sanal alana ve onu gözetimsiz çalıştıran CI işine kadar uçtan uca bir üretim ajanına sahip olabilirsin.

bu anlayışı inşa etmek, kod tabanıyla 6 HAFTADAN fazla günlük çalışma gerektirdi, çoğu gerçek koşullar altında bozulmadan önce doğru görünen şeylerin hatalarını ayıklamakla geçti.

şimdi başlayalım. ⬇️

Projenin Şekli

iki kutu. bir ikili dosya. her yürütme hedefi bir yapılandırma seçeneğidir, yeniden yazma değil.

• SDK, herhangi bir rust projesine çekebileceğin bir kütüphanedir. CLI onu sarar. Ajanın, use agentic_harness::prelude::*; ile başlayan bir rust ikili dosyasıdır.
• cargo build tüm boru hattıdır. Paketleyici yok. Derleme adımı yok. Hedef makinede dil çalışma zamanı yok. Kendi kendine yeten tek bir çalıştırılabilir artı bir manifest.json.

her şeyi yönlendiren tasarım kısıtlaması: aynı ajan ikili dosyası, dizüstü bilgisayarında etkileşimli modda, yeni bir depo klonlayan bir GitHub Actions işinde, HTTP üzerinden uzak bir E2B sanal alanına karşı ve bir Cloudflare Worker sınırında, aralarında tek bir ajan mantığı satırını değiştirmeden çalışmalıdır.

bu kod tabanındaki her karar, bu kısıtlamayı onurlandırmak için vardır.

3 katman ve her birinin neden var olduğu

zihinsel model üç eşmerkezli halkadır. Her bir sınırın nerede olduğunu bilmek, bu kılavuzdaki diğer her şeyden daha fazla hata ayıklama süresi kazandıracaktır.

rust kodun dış halkadır.

• işleyiciler yazarsın. İşleyiciler bir AgentContext alır. Oturumları çağırırlar. Oturumlar modeli çağırır, dosyaları okur, dosyaları yazar, kabuk komutlarını çalıştırır, görevler başlatır, MCP sunucularına bağlanır.
• asla doğrudan bir HTTP istemcisine dokunmazsın. Asla bir model yanıtını doğrudan ayrıştırmazsın. SDK her ikisini de halleder.

koşum (harness) orta halkadır.

• ajan kaydını yönetir, kimliği URL yoluyla yönlendirir, oturum kalıcılığını çağrılar arasında işler, oturumlar büyüdüğünde bağlam sıkıştırmasını, rol ve beceri keşfini, model seçim önceliğini ve sağlayıcıdan bağımsız ModelClient özelliğini yönetir.
• bu, işleyici koduna dokunmadan Anthropic'i OpenAI ile veya yerel bir Ollama örneğiyle değiştirmeni sağlar.
• koşum, ajan mantığını sağlayıcılar ve hedefler arasında yeniden kullanılabilir kılan şeydir.
• ayrıca üretimde bozulan tüm şeylerin ele alındığı yerdir: oturum durumu, bağlam taşması, sağlayıcı arızaları, eşzamanlı istek sıralaması.

yürütme hedefleri iç halkadır.

• yerel dosya sistemi. CI kontrolü. Daytona veya E2B'ye yönelik HttpSessionEnv. Cloudflare Worker sınırı.
• koşum hangisini kullandığını umursamaz. İşleyicilerin de umursamaz. session.shell() ve session.write() çağırırlar ve koşum bunları altta yatan hedefin ihtiyacına göre çevirir.
• bu ayrım asıl noktadır. E2B yeni bir API sürümü yayınladığında, bağlayıcıyı güncellersin, ajan mantığını değil.
• Anthropic claude-opus-4-7'yi yayınladığında, runtime.json'u güncellersin, işleyicilerini değil. Dış halka temiz kalır çünkü orta halka tüm değişiklikleri emer.

çalışma zamanı yapılandırması: model katmanını kontrol eden dosya

tek bir işleyici yazmadan önce, çalışma alanında runtime.json'a ihtiyacın var.

bunu .agentic-harness/config.json veya çalışma alanı kökünde agentic-harness.json olarak bırak. load_workspace_context() onu otomatik olarak alır.

çalışma zamanında model seçimi şu önceliği izler:

1. PromptOptions::model(...): çağrı başına geçersiz kılma
2. seçilen rolün model meta verileri: rol başına varsayılan
3. çalışma zamanı yapılandırmasından defaultModel: çalışma alanı varsayılanı

anlaşılması gereken şey: model kimliği, onu kullanmadan önce kaydedilmelidir. openaiCompatibleModels, koşumun yerleşik sohbet-tamamlamalar istemcisini bağlamak için kullandığı listedir. Modelin bu listede değilse, oturumun ortasında kafa karıştırıcı bir başarısızlık yerine başlangıçta temiz bir hata alırsın.

OpenAI uyumlu ağ geçitleri için yapılandırma aynı görünür. baseUrl'yi ağ geçidine yönlendir:

• asla runtime.json'a gerçek bir API anahtarı yazma. apiKeyEnv kullan ve gerçek anahtarı ortamında tut.
• koşum, env değişkenini başlangıçta değil, istek zamanında okur; bu, sunucuyu yeniden başlatmadan anahtarları döndürebileceğin anlamına gelir.

ajan kimliği bir URL yoludur, asla bir kayıt defteri araması değil

bu beni şaşırtan ilk tasarım kararıydı. Şimdi doğru olduğunu düşünüyorum.

Ajan kimlik sistemi yok. Kayıt defteri anahtarı yok. Kendin oluşturduğun UUID yok. Ajanının kimliği POST /agents/<name>/<id>'dir.

• koşum, bu URL'nin arkasındaki tüm oturum durumu muhasebesini halleder.
• bunun işe yarama nedeni: her sistemdeki her çağıran, bağlamdan anlamlı bir kimlik oluşturmayı zaten bilir. Bir PR numarası. Bir çalıştırma kimliği. Bir görev adıyla birleştirilmiş bir zaman damgası. Bir kullanıcı tanıtıcısı.
• bir oturum oluşturma uç noktasına ihtiyacın yok. Oturum kimliklerini ayrıca depolamana gerek yok. URL oturumun kendisidir.

rust tarafındaki ajan işleyicisi, çağıranın sağladığı kimliği almak için ctx.id()'yi çağırır:

oturumlar: durum bilgisi olan yürütme bağlamı

bir oturum, bir konuşma iş parçacığından daha fazlasıdır. Bir ajan çağrısı için tam yürütme bağlamıdır.

Şunları tutar:

• modelle mesaj geçmişi
• çalışma alanı dosya erişimi (okuma, yazma, düzenleme, grep, glob, stat, readdir)
• cwd ve env kontrolü ile kabuk yürütme
• araç kayıtları (MCP sunucuları, özel araçlar)
• atanan rol ve sistem istemi katmanı
• sıkıştırma bütçesi ve geçmiş su işareti

ctx.session_with_id()'yi anlamlı herhangi bir kimlikle çağırarak bir oturum alırsın:

• aynı kimliği kullandığında oturumlar HTTP çağrıları arasında kalıcı olur. Aynı ajan uç noktasını aynı oturum kimliğiyle üç kez çağır, model üç alışverişi de sürekli bir konuşma olarak görür.
• geçmiş otomatik olarak birikir. Onu yönetmezsin.
• bu, durumu kendin yönetmeden çok adımlı iş akışlarını mümkün kılan şeydir. session.prompt()'u çağırmaya devam edersin ve koşum geri kalan her şeyi halleder.

bir istemin yanında büyük miktarda bağlam iletmen gerektiğinde, dosyayı oku ve satır içinde biçimlendir:

oturum, konuşma ortasında yanlışlıkla bağlam penceresini taşırmaman için token sayımını yönetir. Bütçeye yaklaştığında sıkıştırma devreye girer. Bununla ilgili daha fazlası ilerleyen bir bölümde.

görevler: üst öğeyi temiz tutan odaklanmış alt oturumlar

• bu, ilk gün anlamış olmayı dilediğim ilkel yapıdır. Uzun işlerde tutarlı kalan ajanlar ile yarı yolda halüsinasyon görmeye başlayan ajanlar arasındaki farktır.
• bir görev, tek seferlik bir alt oturumdur. Temiz geçmiş. Paylaşılan çalışma alanı. Üst öğeye bir sonuç döndürür. Üst öğenin geçmişi, görevin ara muhakemesinin hiçbirini görmez.

• araştırma görevi izole bir şekilde çalışır. Tüm muhakeme zinciri.
• modelin kod hakkında yaptığı her ara gözlem, her "bekle, şu dosyayı da kontrol edeyim", görevin içinde kalır.
• üst oturum temiz bir özet alır. Gördüğü tek şey budur.Bunun pratikte neden önemli olduğu: uzun süreli bir oturumda doğrudan keşifsel analiz yaptığında, geçmiş ara araç çağrıları, kısmi yanıtlar ve artık geçerli olmayan şeyler hakkında model muhakemesiyle dolar.
• model, gerektiğinde bu gürültüye odaklanır. Sıkıştırma sonunda devreye girer ve aslında ihtiyacın olan bağlamı kaybeder. Görevler cerrahi düzeltmedir.

kural: alt problemin net bir teslimatı varsa ve tamamlanması için üst öğenin konuşma geçmişine ihtiyaç duymuyorsa, onu bir görev haline getir. "Görev yap" eşiği düşündüğünden daha düşüktür.

bir kod tabanında paralel analiz için: haritacı deseni, görevleri yay ve sonuçları topla:

her görev temizdir. Her görev tam olarak bir dizine odaklanmıştır. Üst oturum sonuçları toplar ve son belgeyi yazar.

12 modülün varsa, her biri diğerlerinden sıfır bagajla başlayan 12 odaklanmış görev çalıştırırsın.

roller ve beceriler: yeniden derlemeden davranışı şekillendirme

1. roller .agentic-harness/roles/ içinde yaşar. Beceriler .agents/skills/ içinde yaşar. Koşum başladığında her ikisi de otomatik olarak keşfedilir.
2. roller, bir çağrıya kapsamlı sistem istemi katmanlarıdır. Çağrı zamanında uygulanır ve sonrasında atılır. Mesaj geçmişinde kalıcı olmazlar. Çağrılar arasında birikmezler.

öncelik zinciri: çağrı rolü > oturum rolü > ajan rolü > rol yok.

• model ön yüzü isteğe bağlıdır ancak kullanışlıdır. Belirli rolleri belirli modellere yönlendirmeni sağlar.
• açıklayıcı rolün, hız ve maliyet için claude-sonnet-4-6 üzerinde çalışır. Güvenlik denetçin, derinlik için claude-opus-4-7 üzerinde çalışır. Bunu rol dosyasında bir kez yapılandırırsın ve bir daha düşünmezsin.
• beceriler, modelin bir oturumun başında okuduğu davranış tanımlayıcı dosyalardır.
• bunlar .agents/skills/ içindeki işaretleme dosyalarıdır. Koşum onları otomatik olarak bulur. Hiçbir yere kaydetmezsin.

pratik kullanım: kod tabanının yanında bir beceri kütüphanesi, nasıl çalıştığını açıklar. İşleme mesajı formatı, tercih edilen kütüphaneler, geçiş adlandırma kuralları, API tasarım desenleri, test gereksinimleri.

model bunu her oturumdan önce okur. İşaretlemeyi düzenlersin. Davranış bir sonraki çalıştırmada güncellenir. Yeniden derleme yok.

model bunu okur. Kuralına uyan işlemeler yazar. Her oturumda hatırlatmazsın. Tek bir dosyayı korursun.

kodlama ajanı döngüsü tüm ayrıntılarıyla

kodlama ajanı döngüsü, CLI'nin etrafında inşa edildiği birincil kullanım durumudur. Aynı zamanda yanlış yapılandırırsan en çok şeyin ters gidebileceği yerdir.

önemli olan tüm seçeneklerle birlikte tam komut:

her bayrağın ne yaptığı ve neden önemli olduğu:

1. --workspace . kökü ayarlar. Tüm dosya işlemleri burada sanal alana alınır. Ajan bu yolun dışında okuyamaz veya yazamaz, koşum seviyesinde zorunlu kılınır — modele kendini kısıtlaması için güvenerek değil.
2. --llm auto, çalışma zamanı yapılandırmandaki defaultModel'den modeli seçer. Derin muhakeme gerektiren karmaşık görevler için --llm anthropic/claude-opus-4-7 veya daha hızlı yineleme için --llm anthropic/claude-sonnet-4-6 kullan.
3. --deny-path sert bir engeldir. Önek stiliyle eşleşir, bu nedenle --deny-path config/ config/ altındaki her şeyi kapsar. İlk çalıştırmadan önce çalışma alanını denetle ve sırlar veya üretim yapılandırması tutan her yolu numaralandır — yalnızca .env değil.
4. --approve-dependencies, bir insan onay adımı olmadan Cargo.toml değişikliklerine izin verir. Eklenen her yeni kutu için inceleme yapmak istiyorsan bunu dışarıda bırak.
5. --commit, tüm değişiklikleri otomatik olarak aşamalandırır ve başarılı bir çalıştırmanın sonunda sağladığın mesajla işler. Bu bayrak olmadan, değişiklikler incelemen için aşamalandırılmamış değişiklikler olarak kalır.
6. --pr, işlemeden bir çekme isteği açar. Çalıştırmadan önce temiz bir git durumu ve ayrılmış bir HEAD değil, gerçek bir dal gerektirir.

döngünün kendisi: İncele → Özetle → LLM + Araçlar → Düzenle + Test → İşle · PR.

• incele: çalışma alanı yapısını okur, becerileri ve rolleri yükler, istemle en alakalı olması muhtemel dosyaları tanımlar.
• herhangi bir koda dokunmadan önce anlayışını coding-brief.md'ye yazar.
• özetle: model bir plana bağlanır. Çalışma ortasında .agentic-harness/runs/<id>/coding-brief.md'yi okuyarak ne karar verdiğini görebilirsin.
• özet yanlış görünüyorsa, çalıştırmayı öldür. Ajanın kötü bir planı uygulamasına izin vermektense daha net bir istemle yeniden başlamak daha ucuzdur.
• LLM + araçlar: düzenle-test döngüsü. Model değişiklikler yapar, test paketini çalıştırır, çıktıyı okur, daha fazla değişiklik yapar. Testler geçene, yineleme sınırına ulaşılana veya görevin tamamlandığına karar verene kadar yineler.

işle · PR: aşamalandırır, işler, gönderir, farkı ekleyerek PR'yi açar.

her çalıştırma, .agentic-harness/runs/<id>/ altına altı yapıt yazar:

1. coding-brief.md: ajanın herhangi bir kod yazmadan önce bağlandığı plan
2. summary.md: ne yapıldığı, ne denendiği ve neden yapıldığına dair insan tarafından okunabilir hesap
3. run.json: yapılandırılmış meta veriler: kullanılan model, toplam süre, giriş/çıkış token sayıları, yineleme sayısı, son çıkış durumu
4. events.jsonl: sırayla her araç çağrısı, tam girdiler ve çıktılarla birlikte, neyin yanlış gittiğini hata ayıklamak için
5. diff.patch: tüm dosya değişikliklerinin tam farkı
6. checks.json: başarıyı veya başarısızlığı belirleyen son test ve lint sonuçları

Hatırlanması Gereken İpuçları

• bunları geçici çıktı olarak değil, yapılandırılmış günlükler olarak ele al. Tekrarlayabilmem gereken herhangi bir görev için çalıştırma yapıtlarını depoya işlerim.
• yalnızca run.json (2KB), modeli, token maliyetlerini ve başarılı olup olmadığını söyler. events.jsonl, kötü bir çalıştırmayı hata ayıklaman gerektiğinde ajanın tam olarak neyi ve hangi sırayla yaptığını söyler.

CI için desen şudur:

HttpSessionEnv: ikili dosyayı yerel olarak çalıştırma, uzaktan yürütme

• bu, tam olarak anlamamın en uzun sürdüğü yetenektir. Şimdi altyapıya dokunan hemen her görevde kullanıyorum.
• ajan ikili dosyası makinenizde veya CI'da çalışır. Dosya sistemi ve kabuk işlemleri uzak bir sanal alan içinde yürütülür.
• ajan hangi ortamda olduğunu bilmez veya umursamaz.

use agentic_harness::HttpSessionEnv; kullan.

kablo protokolü HTTP üzerinden JSON'dur. Her işlem:

1. exec
2. read
3. write
4. edit
5. grep
6. glob
7. stat
8. readdir
9. mkdir
10. rm

tanımlı bir istek/yanıt şekline sahiptir.

Bu protokolü uygulayan herhangi bir sanal alan, bir HttpSessionEnv hedefi olarak çalışır.

Adlandırılmış bir sanal alanı bağlamak için:

yerleşik bağlayıcılar, Vercel Sandbox, Daytona ve E2B için kimlik doğrulama ve yaşam döngüsü ortak kodunu halleder:

• bunun için en çok kullandığım somut kullanım durumu: temiz bir Linux ortamında CI başarısızlıklarını yeniden üretmek.
• ajan, depoyu tam başarısız işleme karmasında klonlar, tam başarısız test komutunu çalıştırır, tam çıktıyı okur, başarısızlığı teşhis eder ve bir rapor yazar.
• raporu okurum. Yerel makineme asla dokunmadım. Oturum sona erdiğinde sanal alan atılır.

kimsenin uyarmadığı performans sorunu: HttpSessionEnv üzerinden her kabuk çağrısı bir ağ gidiş dönüşüdür. Sıkı döngüler: düzenle, test et, çıktıyı kontrol et, düzenle: hızla gecikme biriktirir.

Yerel olarak 5 saniye süren 40 yinelemeli bir döngü, her yineleme üç ayrı kabuk çağrısı yaparsa uzak bir sanal alana karşı birkaç dakika sürer.

Düzeltme: kabuk işini betiklere topla.

Yineleme başına üç yerine bir çağrı. Betiği bir kez yaz, tekrar tekrar çalıştır. 40 yinelemeli bir döngüde gecikme farkı gerçektir.

derleme hedefleri: aynı kod tabanı, üç dağıtım şekli

native varsayılandır. Tek bir ikili dosya. Tek bir manifest. Hedef makinede başka hiçbir şey. Yerel bir Linux ikili dosyasını çalıştırabilen her yerde çalışır.

node, bir Node giriş noktası gerektiren barındırma platformları içindir. Derleme, yerel rust ikili dosyasını bir alt işlem olarak başlatan ve HTTP'yi ona yönlendiren server.mjs oluşturur. Ajan mantığı hala rust olarak çalışır. Node katmanı 30 satırlık bir HTTP köprüsüdür.

Cloudflare, uç dağıtım içindir.

• derleme bir Worker sınır dosyası oluşturur ve Worker uyumlu bir uygulama bağdaştırıcısına bağlanır.
• işleyiciler WASM JSON ABI aracılığıyla WASM'ye derlenir.
• Durable Object bağlamaları, Cloudflare KV aracılığıyla oturum kalıcılığını yönetir.

Cloudflare ile ilgili önemli kısıtlama: Workers, uzun süreli kabuk komutlarını desteklemez. Gerçek bir dosya sistemleri yoktur.

cargo veya herhangi bir derleme aracını desteklemezler. --target cloudflare, webhook işleme, rota meta verileri, küçük kontrol uç noktaları ve Durable Object yönlendirme içindir, kodlama çalışması için değil.

cargo test çalıştırması gereken herhangi bir şey için, yerel bir işleme veya uzak sanal alana devredin.

pratik karar matrisi:

• bir ajana diğer hizmetlerin çağırdığı bir API olarak göndermek → nginx veya yönetilen bir platform arkasında native
• Railway, Render veya Node bekleyen bir platformda barındırmak → node
• webhook alımı, hafif yönlendirme, Durable Object durum yönetimi → cloudflare
• diğer her şey → native

şema güdümlü çıktı: model yanıtlarından yazılan rust yapıları

modelden JSON döndürmesini istemek ve yapmasını ummak çözümün yarısıdır.

Koşumun onu çıkarması, doğrulaması ve rust yapına dönüştürmesi tam çözümdür.

model, aynı yanıtta yazılan yükün yanında muhakeme düzyazısı da döndürebilir. Koşum, sonuç bloğunu

• --RESULT_START--- ve ---RESULT_END--- işaretçileri arasında çıkarır. Bir rust yapısı alırsın. Model çıktısından işleyici mantığına derleme zamanı tip güvenliği.
• şema iki şey yapar: modele hangi şekli üreteceğini söyler ve koşuma dönüştürme öncesinde doğrulama yapması için bir şey verir.
• model şemayla eşleşmeyen bir şey döndürürse, üç çağrı sonrasında eksik bir alana eriştiğinde paniklemek yerine PromptError::SchemaValidationFailed alırsın.

MCP araçları: sanal alanın dışına ulaşma

ajanın dosya ve kabuğun ötesinde yeteneklere ihtiyacı olduğunda, connect_mcp kaçış kapağıdır.

ajan, MCP sunucusunun tam araç setini alır. Yazılacak araç tanımı yok. Açıklamalar sunucudan gelir. Model, bu açıklamalara dayanarak hangi aracı ne zaman çağıracağına karar verir.

Bir oturuma birden çok MCP sunucusu bağlayabilirsin:

• model, araçları açıklamalarına göre çağırır. "sentry'de ara" gibi belirsiz bir açıklama tutarsız bir şekilde çağrılır.
• "hatalar, olaylar veya üretim sorunları hakkında herhangi bir soruyu yanıtlamadan önce bunu çağır" diyen bir açıklama güvenilir bir şekilde çağrılır.
• MCP sunucusunu kontrol ediyorsan, kuralcı açıklamalar yaz: modele ne zaman çağırması gerektiğini söyle, yalnızca ne döndürdüğünü değil.

bağlayıcılar: bağdaştırıcıları elle yazmak yerine oluşturma

alışılmadık bir API'ye karşı elle bağdaştırıcı kodu yazmak yerine, kodlama ajanına bir bağlayıcı tarifi ilet:

• bağlayıcı tarifi, sanal alan API'sinin ve karşılaması gereken SessionEnv sözleşmesinin yapılandırılmış bir açıklamasıdır.
• kodlama ajanı onu okur, rust bağdaştırıcı modülünü yazar, kimlik doğrulamayı halleder, sağlayıcı yaşam döngüsünü sarar ve onu bir HttpSessionEnv olarak sunar.
• farkı incelersin. Birleştirirsin. Bağdaştırıcı projende yaşar. Artık senin kodundur.

Daytona'yı bunu kullanarak tam inceleme döngüsü dahil yaklaşık 20 dakikada bağladım. Ajan, kimlik doğrulama başlığı formatını ilk geçişte doğru aldı.

Bağdaştırıcıyı sıfırdan Daytona belgelerine karşı yazmak, bir öğleden sonranın çoğunu ve yenileme token akışı hakkında en az iki yanlış varsayımı alırdı.

Bağlayıcı oluşturulduktan sonra:

otomatik sıkıştırma: bağlamı kaybetmeden uzun oturumları yönetme

uzun süreli oturumlar geçmiş biriktirir.

Sonunda modelin bağlam penceresini taşırırlar.

Koşum bunu otomatik olarak halleder, ancak doğru yapılandırman gerekir, aksi takdirde tam yanlış anda bağlamı kaybedersin.

context_window_tokens, oturum için toplam bütçedir.

• reserve_tokens, modelin yanıtı için ayırdığın şeydir. Geçmiş için etkili sınır context_window_tokens - reserve_tokens'dır.
• keep_recent_messages, sıkıştırmadan bağımsız olarak her zaman olduğu gibi korunan sondaki mesaj sayısıdır.

Geçmiş bütçeyi aştığında, koşum modelden sistem istemi ile tutulan kuyruk arasındaki her şeyi özetlemesini ister.

Bu özet, orta bölümün yerini alır. Kuyruk mesajları bozulmadan kalır. Sıkıştırılmış oturum daha küçüktür ve sonraki çağrı bütçeye sığar.

ödünleşim gerçektir: özetler kesinliği kaybeder. 50 mesaj önce alınan belirli bir karar: "authlib'i seçtik çünkü axum'un middleware modeliyle çalışan PKCE desteğine sahip tek kütüphane" özette "auth için authlib'i seçtik" olarak kalabilir.

Bu kesinlik, oturumun ilerleyen kısımlarındaki kararlar için önemliyse, onu açıkça depola:

• kararları dosyalara yaz. Dosyalar sıkıştırmadan kurtulur. Model onları talep üzerine geri okuyabilir. Çalışma alanı taşıyorsa geçmişin her şeyi taşıması gerekmez.
• modelinizin bildirilen gerçek bağlam penceresini görmek için agentic-harness doctor'ı çalıştır. context_window_tokens'ı bu değerin %80-90'ına ayarla.
• token sayacı model tarafında tam olarak doğru değildir ve %99'da oturuyorsan tek bir büyük dosya okuması seni sınıra itebilir.

Dikkat edilmesi gerekenler

1. oturum geçmişi kirlenmesi

• sorun: uzun bir oturum içinde keşifsel analiz, sonraki istemleri keşif aşamasındaki gürültüyle zehirler
• düzeltme: görevleri kullan. Görev geçmişi asla üst öğeye dokunmaz. "Görev yap" eşiği düşündüğünden daha düşüktür

1. rol önceliği sürprizleri

• sorun: çağrı düzeyindeki bir rol, oturum rolünü gölgeler. Model beklenenden farklı davranır ve nedenini bilmezsin
• düzeltme: oturum rolü kimliği belirler. Çağrı rolü odağı daraltır. Katmanlanırlar — çağrı rolü ekler, iptal etmemelidir

1. --deny-path boşlukları

• sorun: .env'yi reddedersin. Sırların ayrıca .env.local ve config/staging.yaml'de de yaşar. Ajan bunlardan birini okur
• düzeltme: dosya adlarını değil, önekleri reddet. --deny-path config/ altındaki her şeyi kapsar

1. CI'da ayrılmış HEAD

• sorun: ajan düzenler, testler geçer, işleme başarısız olur — çünkü işlenecek bir dal yoktur
• düzeltme: koşumu çağırmadan önce git checkout -b agent-run-$RUN_ID

1. Sıkı döngülerde HttpSessionEnv gecikmesi

• sorun: her biri üç kabuk çağrısı olan 40 yineleme, dakikalarca saf ağ gecikmesidir
• düzeltme: her şeyi tek bir çağrıda yapan agent-check.sh yaz. Yineleme başına bir çağrı

1. bağlam bütçesinin hafife alınması

• sorun: sıkıştırma görev ortasında devreye girer. Model planını kaybeder ve özetten doğaçlama yapmaya başlar
• düzeltme: gerçek pencereyi almak için agentic-harness doctor'ı çalıştır. Bütçeyi bunun %80-90'ına ayarla

1. çalışma zamanı yapılandırmasının işleyici kaydından sonra yüklenmesi

• sorun: Bir handler, load_workspace_context() çağrılmadan çalışıyor. Kayıtlı bir model yok. Hata, bir yapılandırma sorununa hiç benzemiyor.
• çözüm: Herhangi bir agent'ı bağlamadan önce app() içinde her zaman load_workspace_context()'i çağırın.

1. --llm'nin çalıştırmalar arasında otomatik değişmesi

• sorun: defaultModel güncelleniyor. Altı ay arayla yapılan iki çalıştırma karşılaştırılabilir olmuyor. İlkini tekrarlayamazsınız.
• çözüm: Tekrarlanabilirlik gerektiren her şey için modeli runtime.json içinde sabitleyin.

1. Çalıştırma yapıtlarının silinmesi

• sorun: runs/ klasörünü bir .gitignore kuralıyla temizliyorsunuz. Üç hafta sonra bir regresyonu tekrarlamanız gerekiyor ve her şey gitmiş oluyor.
• çözüm: Tekrarlamanız gereken her görev için çalıştırma yapıtlarını commit'leyin. run.json 2KB'dir. Saklayın.

farklı yapardım

1. Hiçbir şeye dokunmadan önce agentic-harness kılavuzunu okuyun.
2. Handler mantığını yazmadan önce oturum düzeyinde testler yazın.
3. Alt teslim edilebilir ürünü olan her şey için görevler kullanın.
4. İlk ciddi çalıştırmadan itibaren modeli sabitleyin.
5. Kararları dosyalarda saklayın, oturum geçmişinde değil.
6. Uzak sandbox'lar kullanırken en başından itibaren shell işlemlerini toplu olarak yapın.

sonuç olarak

Çoğu agent framework'ü bir API çağrısının etrafındaki sarmalayıcılardır. Bu bir runtime'dır.

Bir sarmalayıcı "modelin yanıt vermesini sağlama" sorununu çözer. Bir runtime ise "bir agent'ı üretime gönderme ve model değiştikten sonra, sandbox değiştikten sonra, kod tabanı değiştikten sonra, oturum iki saat sürüp bağlam penceresini taşırdıktan sonra bile çalışır durumda tutma" sorununu çözer.

3 katmanlı mimari

1. sizin kodunuz
2. harness (koşum takımı)
3. yürütme hedefi

bunu mümkün kılan şeydir. Siz handler'ları yazarsınız. Harness tüm operasyonel karmaşıklığı üstlenir. Yürütme hedefi bir yapılandırma seçeneğidir.

Değişmeyen şeyler: handler mantığı, oturum yapısı, görev kalıpları, rol tanımları, beceri dosyaları. Değişen şeyler: modeller, sağlayıcılar, sandbox satıcıları, dağıtım hedefleri.

Mimari, değişen şeylerin değişmeyenlere asla dokunmayacağı şekilde tasarlanmıştır.

İşte iddia bu. Doğru iddia.

Umarım bu makaleyi okumaktan ve agent'lar ve genel olarak nasıl geliştirdiğimi keşfetmekten keyif almışsınızdır ❣️

Sorumluluk Reddi

Bu makale yazar tarafından araştırılmış ve yazılmış, Minimax-M2.7 tarafından düzenlenmiştir. Küçük resim Pinterest'ten alınmıştır.

Harrison Chase "hafıza açık olmalı!" —

[https://x.com/hwchase17/status/2046308913939919232Harrison](https://x.com/hwchase17/status/2046308913939919232Harrison)

Chase :"Senin Koşum Takımın, Senin Hafızan" —

[https://www.langchain.com/blog/your-harness-your-memory](https://www.langchain.com/blog/your-harness-your-memory)

Vivek Trivedi :"Bir Agent Koşum Takımının Anatomisi" —

[https://www.langchain.com/blog/the-anatomy-of-an-agent-harness](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness)