Tanımadığınız Ajan: İlkeler, Mimari ve Mühendislik Uygulamaları

0. TL;DR

"The Claude Code You Don't Know: Architecture, Governance, and Engineering Practices" makalesini yazdıktan sonra, Agent'ların alt katmanlarına dair anlayışımın yeterince derin olmadığını fark ettim. Ekibimizin Agent tabanlı iş çözümleri geliştirme konusundaki önemli deneyimiyle birleşince, sistematik bir inceleme yapma ihtiyacı hissettim. Bu nedenle, materyalleri, açık kaynak uygulamaları ve kendi kodlarımı tarayarak bu makaleyi derledim.

Bu makale, kontrol akışı, bağlam mühendisliği, araç tasarımı, bellek, çoklu-agent organizasyonu, değerlendirme, izleme ve güvenlik dahil olmak üzere, Agent mimarisinin mühendislik çıktılarını en çok etkileyen kısımlarına odaklanmaktadır. Son olarak, bu tasarım prensiplerini bir araya getirmek için OpenClaw uygulamasını kullanacağız.

Bu derlemeyi yaparken, birkaç sonuç başlangıçtaki varsayımlarımdan farklı çıktı: daha pahalı modellerin getirdiği iyileştirmeler genellikle beklenenden daha küçüktür; bunun yerine, Harness ve doğrulama testlerinin kalitesi başarı oranları üzerinde daha büyük bir etkiye sahiptir. Agent davranışını hata ayıklarken, öncelikle araç tanımlarını kontrol edin, çünkü çoğu araç seçim hatası yanlış açıklamalardan kaynaklanır. Ayrıca, değerlendirme sisteminin kendisindeki sorunları tespit etmek genellikle Agent hatalarından daha zordur. Agent kodunu sürekli değiştirip sonuç alamıyorsanız, cevap bu alanlarda olabilir.

1. Agent Döngüsünün Temel Çalışması

Bir Agent Döngüsünün temel uygulama mantığı, soyutlandığında 20 satırdan az kod içerir:

1const messages: MessageParam[] = [{ role: "user", content: userInput }];
2
3while (true) {
4  const response = await client.messages.create({
5    model: "claude-opus-4-6",
6    max_tokens: 8096,
7    tools: toolDefinitions,
8    messages,
9  });
10
11  if (response.stop_reason === "tool_use") {
12    const toolResults = await Promise.all(
13      response.content
14        .filter((b) => b.type === "tool_use")
15        .map(async (b) => ({
16          type: "tool_result" as const,
17          tool_use_id: b.id,
18          content: await executeTool(b.name, b.input),
19        }))
20    );
21    messages.push({ role: "assistant", content: response.content });
22    messages.push({ role: "user", content: toolResults });
23  } else {
24    return response.content.find((b) => b.type === "text")?.text ?? "";
25  }
26}

İlgili kontrol akışı şu şekildedir: Model düz metin döndürene kadar Algı -> Karar -> Eylem -> Geri Bildirim döngüsü devam eder:

Birçok Agent uygulaması ve resmi SDK gördükten sonra, yapıların benzer olduğunu söyleyebilirim. Döngünün kendisi oldukça kararlıdır. Minimal bir uygulamadan alt-agent'ları, bağlam sıkıştırmasını ve beceri yüklemeyi desteklemeye kadar, ana döngü nadiren değişir. Yeni yetenekler genellikle döngünün içini değiştirmek yerine dışına eklenir.

Yeni yetenekler temel olarak üç şekilde entegre edilir: araç setlerini ve işleyicileri genişletmek, sistem prompt yapılarını ayarlamak ve durumu dosyalara veya veritabanlarına dışsallaştırmak. Döngü gövdesi devasa bir durum makinesi haline gelmemelidir. Model muhakemeyi yönetirken, dış sistemler durumu ve sınırları yönetir. Bu iş bölümü bir kez kurulduğunda, temel döngü mantığının sık sık ayarlanmasına gerek kalmaz.

Workflow ve Agent Arasındaki Fark Nedir?

Anthropic doğrudan bir ayrım yapar: yürütme yolunun kodda önceden yazıldığı sistem Workflow'tur; LLM'nin bir sonraki adımı dinamik olarak belirlediği sistem ise Agent'tır. Temel fark, kontrolün kimde olduğudur. Gerçekte, Agent olarak etiketlenen birçok ürün Workflow'a daha yakındır, ancak hiçbiri doğası gereği üstün değildir. Önemli olan, görev için doğru çözümü bulmaktır.

Bir diyagramda bakmak daha sezgisel hale getiriyor:

Beş Yaygın Kontrol Deseni

Çoğu AI sistemi, parçalarına ayrıldığında bu beş desenin kombinasyonlarıdır. Birçok senaryo tam Agent özerkliği gerektirmez; bu desenlerden birkaçını birleştirmek yeterlidir. Anahtar, hangi tasarımın göreve uygun olduğudur.

1. Prompt Zincirleme (Prompt Chaining): Görevler, her LLM adımının bir önceki çıktıyı işlediği sıralı adımlara bölünür. Kod kontrol noktaları eklenebilir. Çeviri sonrası oluşturma veya taslak sonrası gövde metni yazma gibi doğrusal süreçler için uygundur.
2. Yönlendirme (Routing): Girdiyi sınıflandırır ve uzmanlaşmış bir sürece yönlendirir. Basit sorular hafif modellere, karmaşık olanlar güçlü modellere gider; teknik destek ve fatura sorgulamaları farklı mantık izler.
3. Paralelleştirme (Parallelization): İki varyant: Bölümleme (görevleri bağımsız alt görevlere ayırma) ve Oylama (aynı görevi fikir birliği için birden çok kez çalıştırma). Yüksek riskli kararlar veya çoklu perspektif gerektiren durumlar için uygundur.
4. Orkestratör-İşçiler (Orchestrator-Workers): Merkezi bir LLM, görevleri dinamik olarak parçalar ve işçi LLM'lere devreder, ardından sonuçları sentezler. Bu, nanobot'un spawn aracı ve learn-claude-code'un alt-agent modunun prototipidir.
5. Değerlendirici-Optimize Edici (Evaluator-Optimizer): Bir üretici çıktı üretir ve bir değerlendirici, standartlar karşılanana kadar bir döngü içinde geri bildirim sağlar. Çeviri veya yaratıcı yazarlık gibi kalite standartlarının kodda tam olarak tanımlanmasının zor olduğu görevler için uygundur.

Bu desenler, kontrol akışının nasıl oluşturulacağını çözer. Şimdi daha mühendislik odaklı bir soruya bakalım: bir sistem neden kararlı bir şekilde çalışır?

2. Harness Neden Modelden Daha Kritiktir?

Harness, bir Agent etrafında oluşturulan test, doğrulama ve kısıtlama altyapısını ifade eder. Bir Harness en az dört parçayı içerir: kabul temelleri, yürütme sınırları, geri bildirim sinyalleri ve geri dönüş yöntemleri.

Model önemli olmakla birlikte, bu çevresel mühendislik koşulları genellikle bir sistemin kararlı bir şekilde çalışıp çalışmadığını belirler. Bu yargı, kodlama gibi yüksek düzeyde doğrulanabilir görevler için en doğrudur, ancak açık araştırma veya çok turlu müzakere gibi zayıf doğrulama görevlerinde modelin üst sınırı daha kritik olmaya devam etmektedir.

OpenAI'ın Agent-Öncelikli Geliştirme Pratiği

Üç mühendis, yaklaşık 1.500 PR ile beş ayda bir milyon satır kod yazdı; bu, geleneksel geliştirmenin 10 katı hızındadır. Bu hız sadece model gücüyle ilgili değildi; doğru mühendislik kararlarıyla ilgiliydi:

1. Agent'ın göremediği içerik yoktur: Bilgi, kod tabanının kendisinde bulunmalıdır. Harici dokümanlar, çalışan bir Agent için görünmezdir. AGENTS.md, yaklaşık 100 satırlık bir dizin olarak tutulur ve ayrıntılar, isteğe bağlı referans için docs dizinlerine bölünür.
2. Kodla kısıtlayın, belgelemeyin: Belgelerdeki normlar kolayca göz ardı edilir. Linter'lara, tip sistemlerine veya CI kurallarına kodlanmış kısıtlamalar yürütülebilirdir. Mimari katmanlama, manuel inceleme ile değil, özel Linter'lar tarafından mekanik olarak zorlanır.
3. Uçtan uca otonom görev tamamlama: Durumu doğrulamaktan ve hataları yeniden üretmekten, düzeltmeleri uygulamaya ve uygulama doğrulamasını yönlendirmeye, PR açmaya, incelemeleri yönetmeye ve birleştirmeye kadar tüm zincir insan müdahalesi gerektirmez. Agent'lar, günlükleri, metrikleri ve izleri aktif olarak kontrol eder.
4. Birleştirme sürtünmesini en aza indirin: Geçici test başarısızlıklarını ilerlemeyi engellemek yerine yeniden denemelerle ele alın. Yüksek verimli ortamlarda, manuel inceleme için bekleme maliyeti genellikle küçük hataları düzeltmekten daha yüksektir. Kodlama disiplini ortadan kalkmadı; manuel incelemeden makine tarafından yürütülen kısıtlamalara kaydı.

Uygulama, günlükleri, metrikleri ve izleri Vector aracılığıyla Victoria depolama katmanına dağıtır; bu, LogQL, PromQL ve TraceQL arayüzlerine karşılık gelir. Codex, bu arayüzler aracılığıyla sorgular, ilişkilendirir ve muhakeme yapar. Değişikliklerden sonra uygulamayı yeniden başlatır, iş yüklerini yeniden çalıştırır ve sonuçları Codex'e geri besler. UI Journeys de girdilerdir. Bu gözlemlenebilirlik yığını her görev için oluşturulur ve tamamlandığında yok edilir. Agent, hataların kendisine söylenmesini beklemez; düzeltmeleri doğrulamak için sistem durumunu sorgular.

Harness için Ana Sonuç Nedir?

Diyagram, görev netliği ve doğrulama otomasyonunu kullanarak görevleri dört duruma ayırır. Sağ üst (net hedefler, otomatik doğrulama) Agent'lar için ideal bölgedir. Sol üst (net görev ancak manuel inceleme) insan inceleme hızıyla sınırlıdır. Sağ alt (otomatik geri bildirim ancak belirsiz hedefler) yanlış yönde verimli harekete yol açar. Sol alt (her ikisinden de yoksun) Agent'ları işe yaramaz hale getirir.

Harness'in işi, görevleri sağ üst köşeye itmek, doğru ve yanlışın insan gözüyle değil, makine tarafından yürütülebilir standartlarla yargılanmasını sağlamaktır.

3. Bağlam Mühendisliği Kararlılığı Neden Belirler?

Transformer dikkat karmaşıklığı O(n²)'dir. Bağlam ne kadar uzun olursa, anahtar sinyallerin gürültü tarafından seyreltilmesi o kadar kolay olur. Yaygın bir hata modu, alakasız içeriğin bağlama hakim olduğu ve Agent karar kalitesinin düşmesine neden olan "Bağlam Çürümesi"dir (Context Rot). Model yetersizliği olarak görünen birçok sorun aslında zayıf bağlam organizasyonundan kaynaklanır.

Bağlam Neden Katmanlanmalıdır?

Sorun genellikle pencerenin yeterince uzun olmaması değil, bilgi yoğunluğunun yanlış olmasıdır. Nadiren kullanılan öğeleri her seferinde yüklemek veya kararlı kuralları dinamik durumlarla karıştırmak, modelin yararlı olanı fark etmesini zorlaştırır.

Çözüm, bilgiyi sıklık ve kararlılığa göre katmanlamaktır:

• Kalıcı Katman: Kimlik, proje kuralları, mutlak yasaklar. Her oturumda geçerli olması gereken içerik. Kısa, net ve yürütülebilir tutun.
• İsteğe Bağlı Yükleme: Beceriler ve alan bilgisi. Tanımlayıcıları kalıcı tutun, ancak tam içeriği yalnızca tetiklendiğinde enjekte edin.
• Çalışma Zamanı Enjeksiyonu: Geçerli saat, kanal kimliği, kullanıcı tercihleri gibi dinamik bilgiler. Gerektiğinde her turda enjekte edilir.
• Bellek Katmanı: Oturumlar arası deneyim MEMORY.md dosyasına yazılır. Doğrudan sistem prompt'unda değil; yalnızca ihtiyaç duyulduğunda okunur.
• Sistem Katmanı: Belirleyici mantık için Hook'lar veya kod kuralları. Bağlamın tamamen dışında kalır.

Belirleyici mantığı bağlama koymayın. Hook'lar, kod kuralları veya araç kısıtlamaları ile ifade edilebilen her şey dış sistemler tarafından yönetilmelidir.

Üç Yaygın Sıkıştırma Stratejisi

1. Kayan Pencere (Sliding Window): Eski mesajları atar. Düşük maliyetlidir ancak erken bağlamı kaybeder. Kısa sohbetler için iyidir.
2. LLM Özeti (LLM Summary): Model bir özet oluşturur. Orta maliyetlidir, ayrıntıları kaybeder ancak kararları korur. Uzun görevler için iyidir.
3. Araç Sonucu Değiştirme (Tool Result Replacement): Ham çıktıyı yer tutucularla değiştirir. Düşük maliyetlidir, araç yoğun görevler için iyidir.

Kayan pencereler en kolayıdır ancak erken arka planı kaybeder. Gelişmiş LLM özetleri, "dal özetleme" kullanarak mimari kararları, tamamlanmamış görevleri ve anahtar kısıtlamaları açıkça korur. Araç değiştirmede, micro_compact her turda eski araç çıktılarını değiştirirken, auto_compact bağlam bir eşiği aştığında tetiklenir.

Gereksiz Yükü Azaltmak için Prompt Önbelleğe Alma

LLM çıkarımı, her token için Anahtar-Değer çiftlerini hesaplar. Bir önek, önceki bir istekle tam olarak eşleşirse, önbellekten okunur. Önbelleğe alma, tam önek eşleştirmesi gerektirir. Önbellek dostu tasarım kararlılığa odaklanır: sistem prompt'ları, araç tanımları ve uzun belgeler kararlıdır ve önbelleğe almaya uygundur. Dinamik bilgiler (zaman, girdi, araç sonuçları) sona yerleştirilmelidir.

Bu, bağlam katmanlamasıyla ilgilidir. Kalıcı katman ne kadar kararlı olursa, önbellek isabet oranı o kadar yüksek ve marjinal maliyet o kadar düşük olur. "Kısa ve kararlı" sadece token tasarrufu için değildir; önbelleği korur. Gecikmeli beceri yükleme de, içeriği kararlı önekten sonra ekleyerek yardımcı olur. Sezgilere aykırı bir nokta: kararlı, büyük bir sistem prompt'u, sık sık değişen küçük bir prompt'tan daha ucuz olabilir çünkü sonraki okumalardaki %90 indirim, ilk yazma maliyetinden daha ağır basar.

Beceriler Neden İsteğe Bağlı Yüklenmelidir?

Beceriler etkili bir desendir: sistem prompt'unda yalnızca dizini tutun, tam bilgiyi gerektiğinde yükleyin.

1const systemPrompt = `
2Mevcut Beceriler:
3- deploy: Tam üretim dağıtım süreci
4- code-review: Kod inceleme kontrol listesi
5- git-workflow: Dal stratejisi ve PR normları
6`;
7
8async function executeLoadSkill(name: string): Promise<string> {
9  return fs.readFile(`./skills/${name}.md`, "utf-8");
10}

Beceri açıklamaları, token şişkinliğini önlemek için kısa olmalı ve yönlendirme koşulları olarak işlev görmelidir. Ne zaman kullanılacağını, ne zaman KULLANILMAYACAĞINI ve çıktının ne olduğunu açıklayın. "Şu durumda kullan / Şu durumda kullanma" ifadelerini olumsuz örneklerle birlikte kullanın. Birçok yönlendirme hatası, model yeteneğinden değil, belirsiz sınırlardan kaynaklanır. Sistem prompt'u kuralları netleştirmelidir: her yanıttan önce available_skills'i tara, eşleşme varsa ilgili SKILL.md'yi yükle ve her seferinde yalnızca bir tane yükle.

Veriler açıktır: olumsuz örnekler olmadan doğruluk %73'ten %53'e düşer; eklenmesiyle %85'e çıkar ve yanıt süresini %18,1 azaltır. Olumsuz örnekler anahtardır.

Beceri tanımlayıcılarının iki tuzağı vardır. Birincisi, kelime sayısı: her beceri için uzun açıklamalar birikir. İkincisi, kesinlik: "backend'e yardımcı olur" çok belirsizdir. Etkili tanımlayıcılar, özellik tanıtımları değil, yönlendirme koşullarıdır. "Ne yapabilirim"den çok "Beni ne zaman kullanmalısın" önemlidir.

Miktarı kontrol edin: kalıcı prompt'ta yalnızca yüksek frekanslı becerileri tutun. Düşük frekanslı olanlar manuel olarak tanıtılabilir veya belge olarak saklanabilir. Tipik anti-desenler, bir beceriye yüzlerce satırlık kılavuz doldurmak veya bir becerinin çok fazla farklı görevi (inceleme, dağıtım, hata ayıklama) kapsamasıdır.

Sıkıştırma En Kolay Neyi Kaybeder?

En yaygın sorun, özetin çok uzun olması değil, saklama önceliğinin yanlış olmasıdır. LLM'ler genellikle yeniden elde edilebilir görünen bilgileri siler. Araç çıktıları ilk gidenlerdir, ancak ilgili mimari kararlar ve başarısızlık yolları da genellikle kaybolur. CLAUDE.md dosyasında saklama önceliklerini açıkça tanımlayın:

1### Sıkıştırma Talimatları: Anahtar bilgiler nasıl korunur
2Öncelik:
31. Mimari kararlar (özetleme)
42. Değiştirilen dosyalar ve anahtar değişiklikler
53. Doğrulama durumu (başarılı/başarısız)
64. Çözülmemiş YAPILACAKLAR ve geri alma notları
75. Araç çıktısı (silinebilir, yalnızca başarılı/başarısız sonucunu tut)

Başka bir tuzak: tanımlayıcıları değiştirmeyin. UUID'ler, hash'ler, IP'ler ve dosya adları aynen korunmalıdır. Bir commit hash'indeki tek bir yanlış karakter, sonraki araç çağrılarını bozar.

Dosya Sistemleri Neden Harika Bağlam Arayüzleridir?

Cursor buna "Dinamik Bağlam Keşfi" adını verir: varsayılan olarak daha az ver, gerektiğinde oku. Dosya sistemleri doğal arayüzlerdir. Araç çağrıları genellikle büyük JSON döndürür; bunu bağlama doldurmak yerine bir dosyaya yazın. Agent, gerektiğinde okumak için grep veya rg kullanabilir. Bu, bağlamı temiz tutar ve geliştirici tarafından okunabilir.

Cursor bunu MCP araçlarıyla doğruladı: araç açıklamalarını klasörlere senkronize ederler. Agent'lar varsayılan olarak yalnızca araç adlarını görür ve tanımları gerektiğinde sorgular. A/B testlerinde bu, toplam token tüketimini %46,9 oranında azalttı.

Bu aynı zamanda uzun görev sıkıştırması için de çalışır. Geçmişi atmak yerine, tam sohbet günlüğünü bir dosyaya kaydedin ve özetteki yola referans verin. Agent'ın ayrıntıya ihtiyacı olursa, dosyadan alabilir, bu da sıkıştırmayı kayıplı ancak izlenebilir bir işlem haline getirir.

4. Araç Tasarımı, Agent'ın Ne Yapabileceğini Belirler

Bağlam, modelin ne gördüğünü belirler; araçlar, ne yapabileceğini belirler. Kalite, nicelikten daha önemlidir. Sadece 5 MCP sunucusu, tanımlarda yaklaşık 55.000 token'a mal olabilir - sohbet daha başlamadan 200K bağlamın neredeyse %30'u. Çok fazla araç, modelin dikkatini dağıtır.

Çoğu araç sorunu, çok az sayıda olmasıyla değil, yanlış olanı seçmek, anlaşılmaz açıklamalar veya işe yaramaz veriler döndürmekle ilgilidir.

Araç Tasarımı Nasıl Evrilir?

Araç tasarımı üç aşamadan geçmiştir. Başlangıçta, mevcut API'ler sadece araç olarak sarılırdı. Daha sonra, seçim hatalarının genellikle araçların mühendisler için tasarlanmasından, Agent'lar için değil, kaynaklandığı bulundu.

1. Nesil: API Sarma: Her uç nokta bir araçtır. Çok ayrıntılıdır; Agent'lar tek bir hedef için birden çok aracı koordine etmelidir.

2. Nesil: ACI (Agent-Bilgisayar Arayüzü): Araçlar, düşük seviyeli API'lere değil, Agent hedeflerine karşılık gelir. create_file ve set_permissions yerine create_script(path, content, executable) sağlayın.

3. Nesil: Gelişmiş Araç Kullanımı: Keşif ve çağrıyı optimize etme:

• Araç Arama: Tüm tanımları bir kerede doldurmayın. Agent'lar tanımları search_tools aracılığıyla bulur. Bağlam tutma oranı %95'e ulaşır.
• Programatik Araç Çağırma: Modelin birden çok çağrıyı düzenlemek için kod kullanmasına izin verin. Ara sonuçlar, LLM bağlamında değil, yürütme ortamında kalır. Token'lar 150.000'den 2.000'e düşebilir.
• Araç Kullanım Örnekleri: Her araç 1-5 gerçek örnek alır. JSON Schema türleri tanımlar, ancak örnekler kullanımı gösterir. Doğruluk %72'den %90'a yükselebilir.

ACI Araç Tasarım İlkeleri

Araç tasarımı Agent'ları doğrudan etkiler. Sadece "çağrılabilir mi" değil, "yanlış çağrılırsa kendi kendini düzeltebilir mi" önemlidir.

Kötü tasarımların belirsiz parametreleri ve düzeltilemeyen hataları vardır. İyi tasarımlar, tanım ve uygulamayı birleştirmek için betaZodTool kullanır, format kısıtlamaları ve yapılandırılmış hata önerileri için Zod kullanır:

1const updateTool = betaZodTool({
2  name: "update_yuque_post",
3  description: "Yuque gönderi içeriğini günceller; yeni gönderi oluşturmak için kullanılmaz",
4  inputSchema: z.object({
5    post_id: z.string().describe("Yuque gönderi kimliği, '12345678' gibi sayısal dize"),
6    title: z.string().optional().describe("Gönderi başlığı, değişmediyse atlayın"),
7    content_markdown: z.string().describe("Markdown gövdesi"),
8  }),
9  run: async (input) => {
10    const post = await getPost(input.post_id);
11    if (!post) throw new ToolError("Gönderi kimliği mevcut değil", {
12      error_code: "POST_NOT_FOUND",
13      suggestion: "Geçerli bir post_id almak için önce list_yuque_posts'u çağırın",
14    });
15    return await updatePost(input.post_id, input.title, input.content_markdown);
16  },
17});

Kötü tasarım yalnızca ne yaptığını söyler, ne zaman kullanılacağını söylemez. İyi ACI tasarımının net sınırları ve yapılandırılmış hataları vardır, Agent'ların doğru seçim yapmasına ve başarısızlıkları hızlı bir şekilde düzeltmesine yardımcı olur. Önce araçlarda hata ayıklayın; çoğu hata, model yeteneğinde değil, açıklamalardadır.

Araç Mesajları Neden İzole Edilmelidir?

Çerçeveler, dahili olaylar (sıkıştırma, bildirimler) oluşturur. Bunlar oturum geçmişinde olmalı ancak LLM'ye gönderilmemelidir, çünkü token'ları boşa harcar ve modelin kafasını karıştırır. Çözüm, iki mesaj türüdür: uygulama katmanı için AgentMessage (özel alanlarla) ve LLM için standart Message (user, assistant, tool_result).

5. Bellek Sistemini Tasarlamak

Agent'lar doğal zamansal süreklilikten yoksundur. Bağlam, bir oturumdan sonra temizlenir. Oturumlar arası tutarlılık elde etmek için, bir bellek katmanı sonradan akla gelen bir şey olarak değil, altyapı olarak tasarlanmalıdır.

Dört Bellek Türü Nerede Yaşar?

Çözdükleri soruna göre kategorize edilir:

• Bağlam Penceresi (Çalışma Belleği): Geçerli görev için minimum bilgi. Sınırlı token; yönetilmelidir.
• Beceriler (Prosedürel Bellek): İşlerin nasıl yapılacağı (iş akışları, normlar). İsteğe bağlı yüklenir.
• JSONL Oturum Geçmişi (Epizodik Bellek): Ne oldu. Diske kaydedilir; aranabilir.
• MEMORY.md (Anlamsal Bellek): Agent tarafından yazılan kararlı gerçekler. Sistem prompt'larına enjekte edilir.

MEMORY.md ve Beceriler Nasıl İşbirliği Yapar?

Temel, önemli gerçekleri korurken içerik hacmini kontrol etmektir.

ChatGPT'nin 4 Katmanlı Belleği: Basit yapı. Oturum Meta Verileri (kalıcı değil), Kullanıcı Belleği (~33 gerçek, kalıcı/enjekte edilmiş), Konuşma Özeti (~15 son özet, kalıcı), Geçerli Oturum (kayan pencere).

OpenClaw Hibrit Alma: Günlük günlükler (memory/YYYY-MM-DD.md), düzenlenmiş gerçekler için MEMORY.md ve hibrit alma kullanan memory_search (%70 vektör benzerliği + %30 anahtar kelime). Çoğu Agent için, yapılandırılmış Markdown + anahtar kelime araması, hata ayıklanabilirlik ve maliyet için yeterlidir.

Bellek Birleştirmeyi Tetikleme ve Geri Alma

tokenUsage / maxTokens >= 0.5 olduğunda, birleştirmeyi tetikleyin. Mesajları özetleyin, MEMORY.md dosyasına ekleyin ve dizini güncelleyin. Başarısız olursa, ham mesajları bir arşive yazın. İşlem tersine çevrilebilir olmalıdır; işaretçileri taşıyın, ham verileri silmeyin.

6. Agent Özerkliğini Kademeli Olarak Artırmak

Özerklik üç altyapı parçası gerektirir: oturumlar arası devam ettirme, oturum içi ilerleme kısıtlamaları ve yavaş görevler için arka plan G/Ç.

Uzun Görevler Oturumlar Arasında Nasıl Devam Ettirilir?

Uzun görevler, oturumlar tamamlanmadan sona erdiğinde başarısız olur. Kararlı bir yaklaşım, bir Başlatıcı Agent ve bir Kodlama Agent kullanır. Başlatıcı Agent bir kez çalışarak feature-list.json, init.sh ve claude-progress.txt dosyalarını oluşturur. Kodlama Agent daha sonra birden çok oturumda çalışır, bu dosyalardan devam eder, bir özellik uygular, testleri çalıştırır ve ilerleme dosyasını günceller. Bu, görevi harici bir durum haline getirir.

İlerlemeyi bağlamda değil, dosyalarda tutun. Yapı için JSON kullanın. Görev, yalnızca feature-list.json dosyasındaki tüm özellikler passes: true olduğunda tamamlanır.

Görev Durumu Neden Açıkça Yazılmalıdır?

Harici çapalar olmadan, Agent'lar sürüklenir veya erken tamamlanır. Durumu harici bir kontrol nesnesi olarak kaydedin:

1{
2  "tasks": [
3    {"id": "1", "desc": "Yapılandırmayı oku", "status": "completed"},
4    {"id": "2", "desc": "Şemayı değiştir", "status": "in_progress"}
5  ]
6}

Kısıtlama: aynı anda yalnızca bir in_progress. Her adımdan sonra durumu güncelleyin.

Arka Plan G/Ç'yi Entegre Etme

Yavaş G/Ç (dosya işlemleri, ağ) ana döngüyü engellememelidir. Yavaş alt süreçleri arka plan iş parçacıklarına koyun ve sonuçları bir sonraki LLM çağrısından önce bir bildirim kuyruğu aracılığıyla enjekte edin. Bu, karmaşık bir async çalışma zamanından daha sürdürülebilirdir.

7. Çoklu-Agent Sistemlerini Düzenlemek

Çoklu-agent sistemlerini mühendislik açısından ele almak, izolasyon ve işbirliği ile ilgilidir.

Yönetmen Modu: Senkron. İnsan, bir Agent ile yakın etkileşim halindedir. Oturum sona erdiğinde bağlam kaybolur.

Koordinatör Modu: Asenkron delegasyon. İnsan hedefler belirler, Agent'lar paralel çalışır, insan çıktıyı inceler. Çıktı, kalıcı yapıtlar haline gelir (PR'ler, dallar).

Bir Orkestratör, paralel çalışan alt-agent'ları yönetir, JSONL gelen kutusu protokolleri aracılığıyla iletişim kurar ve izolasyon için Worktrees kullanır.

Alt-Agent'lar Neye İyi Gelir?

Arama ve deneme-yanılma, ana Agent'ın bağlamını kirletmemelidir. Ana Agent'ın yalnızca sonuca ihtiyacı vardır.

1const result = await runAgentLoop(task, { messages: [] });
2return summarize(result); // Ana bağlam yalnızca bu satırı görür

İşbirliği Neden Bir Protokol Olarak Yazılmalıdır?

Doğal dil işbirliği, Agent'lar sözleri unuttuğunda başarısız olur. Yapılandırılmış bir protokol kullanın:

1{ request_id, from_agent, to_agent, content, status: 'pending', timestamp }

Çökme kurtarma için salt-ekleme JSONL gelen kutusu kullanın. Önce izolasyon, sonra işbirliği.

Halüsinasyonlar Çoklu-Agent Sistemlerinde Artar

Hatalar Agent'lar arasında kademeli olarak yayılır. Çapraz doğrulama, bağımsız bir Agent veya harici geri bildirimin (testler, derleyiciler) sonucu yargılamasıyla bu zinciri kırar.

8. Agent'lar Nasıl Değerlendirilir?

Değerlendirme, test senaryoları, puanlama standartları ve otomatik doğrulama gerektirir.

Geleneksel tek turlu değerlendirme (Prompt -> Yanıt) yetersizdir. Agent değerlendirmesi, araçlar ve ortamlar gerektirir. Puanlama, Agent'ın söylediklerine değil, ortamda olanlara dayanır.

Anahtar kavramlar: Görev, Deneme, Değerlendirici. Transkript (yürütme günlüğü) ve Sonuç (son durum). Her ikisine de ihtiyacınız var. Bir Agent "bilet rezerve edildi" diyebilir (transkript) ancak veritabanı kaydını oluşturamayabilir (sonuç).

Değerlendirme Durumu ve Metrikler

Birçok ekip hâlâ manuel inceleme veya LLM değerlendiricilerine güveniyor. Yaygın metrikler: Pass@k (teorik olarak yapabilir mi?) ve Pass^k (üretim için kararlı mı?). Bunları karıştırmayın.

Üç Tür Değerlendirici

1. Kod Değerlendiricileri: Dize eşleştirme, birim testleri. En yüksek kesinlik.
2. Model Değerlendiricileri: Kriterlere dayalı LLM değerlendiricileri. Anlamsal kalite için iyidir.
3. İnsan Değerlendiricileri: Uzman incelemesi. Yavaştır ancak temel çizgiyi oluşturur.

Sıfırdan Bir Değerlendirme Sistemi Kurmak

20-50 gerçek başarısızlık vakasıyla başlayın. Testlerin birbirini kirletmemesi için ortam izolasyonunu sağlayın. Hem olumlu hem de olumsuz vakaları dahil edin. İki uzman bir vaka hakkında aynı fikirde değilse, kriterler henüz net değildir.

Ajanı Düzeltmeden Önce Değerlendirmeyi Düzeltin

Puanlar düşerse, önce değerlendirme sistemini kontrol edin. Ortam sorunları (bellek sınırları, değerlendiricilerdeki hatalar) model bozulması gibi görünür.

9. Yürütme Sürecini İzleme

İzlemeler olmadan, başarısızlıklar tekrarlanamaz. APM metrikleri (gecikme, hata oranı) yeterli değildir; akıl yürütme zincirine ihtiyacınız vardır.

Bir İzlemede Ne Kaydedilmeli?

Tam istem, çok turlu mesajlar, araç çağrıları/argümanları/dönüşleri, düşünme zinciri, nihai çıktı, token'lar ve gecikme süresi.

İki Katmanlı Gözlemlenebilirlik

1. Manuel Örnekleme: Başarısızlık modellerini bulmak için hataların veya olumsuz geri bildirimlerin kural tabanlı örneklemesi.
2. LLM Otomatik Değerlendirme: Manuel katmanı bir kalibrasyon temeli olarak kullanarak izlemelerin tam kapsamı.

Olay Akışları Temel Olarak

tool_start, tool_end ve turn_end noktalarında olaylar yayınlayın. Alt sistemler (günlükler, kullanıcı arayüzü, değerlendirme), çekirdek döngü kodunu değiştirmeden bu olayları tüketir.

10. OpenClaw ile Ajanları Yerleştirme

OpenClaw beş ayrıştırılmış katman kullanır: Ağ Geçidi, Kanal Adaptörleri, Pi Ajanı (çekirdek döngü), Araç Setleri (ACI tasarımı) ve Bağlam/Bellek.

Mesaj Veri Yolu ile Ayrıştırma

Bir Mesaj Veri Yolu, kanalları Ajandan ayırır. Kanallar yalnızca G/Ç işlemlerini halleder; Ajan yalnızca işlemeyi halleder.

Katmanlar Halinde Sistem İstemleri

SOUL.md kimlik ve tamamlama standartlarını tanımlar. İstemler katmanlıdır: Çalışma Zamanı Bilgisi -> Kimlik -> Bellek -> Beceriler -> Dinamik enjeksiyon.

Önce Güvenlik Sınırları

Özellikler eklemeden önce şunları oluşturun: Kullanıcı Beyaz Listeleri, Çalışma Alanı İzolasyonu (yol kontrolleri) ve Denetim Günlükleri.

İstem Enjeksiyon Koruması: Harici içeriğe güvenilmeyen olarak davranın. Kaynak-hedef ayrımı kullanın. Ajanlara ihtiyaç duymadıkları araçları vermeyin. Hassas eylemler için açık insan onayı gerektirin.

Sağlayıcı Yedekleme: Bir sağlayıcı başarısız olursa (Anthropic -> OpenAI) otomatik olarak sağlayıcı değiştirin.

11. Yaygın Anti-Kalıplar

1. Sistem isteminin bilgi tabanı olarak kullanılması (çok uzun).
2. Araç yayılımı (Ajan yanlış araçları seçer).
3. Eksik doğrulama döngüleri.
4. Sınırları olmayan çoklu ajan sistemleri.
5. Bellek birleştirme olmaması (20 turdan sonra kalite düşer).
6. Değerlendirme sisteminin olmaması.
7. Erken çoklu ajan karmaşıklığı.
8. Mekanik kısıtlamalar yerine beklentilere güvenmek.

12. Sonuç

1. Ajan çekirdeği kararlı bir döngüdür; yeni özellikler dışsallaştırılmalıdır.
2. Yakınsamayı modelden çok Koşum Takımı belirler.
3. Bağlam mühendisliği "Bağlam Çürümesini" önler.
4. ACI araç tasarımı hedeflere ve hata düzeltmeye odaklanır.
5. Bellek katmanlıdır (Çalışan, Prosedürel, Epizodik, Anlamsal).
6. Uzun görevler dışsallaştırılmış duruma ve dosyalara dayanır.
7. Çoklu ajan sistemlerinin protokollere ve izolasyona ihtiyacı vardır.
8. Yetenek için Pass@k, kalite için Pass^k değerlendirmesi.
9. İzleme, hata ayıklamanın ön koşuludur.
10. Kararlı Ajanlar, ayrıştırma ve güvenlik sınırları gibi mühendislik detaylarına dayanır.