Multi-agent Orkestrasyon: Hub-and-Spoke Pattern

Bu ders, sınavın en fazla “implementation” sorusu çıkardığı yere geliyor: birden fazla agent’ı nasıl koordine edersin? “Sub-agent” kavramını beginner seviyede gördük (kendi context’inde çalışan izole alt-Claude). Şimdi onu production mimaride nasıl kullandığını, hub-and-spoke denen tek doğru pattern’ı, kök neden → sonuç → kontrol ağacıyla nasıl doğru decomposition yaptığını öğreneceksin.

Sınavda en sık gelen tuzak: “Şu görevi 4 sub-agent’a bölelim” diye düşünürken yüzey semptomunu çözen bir decomposition üretmek. Oysa hub-and-spoke’un gücü, sub-agent’ların kendi aralarında konuşmaması, tüm trafiğin coordinator’dan geçmesidir. Bu karar hem state yönetimini hem hata propagation’ı hem de debug edilebilirliği dramatik şekilde kolaylaştırır.

Neden bu konu sınavda çıkıyor

D1 %27 ağırlığında ve multi-agent soruları bu domain’in yaklaşık yarısı. “Multi-Agent Research” senaryosu sınavın 4 seçmeli senaryosundan biri; orada senin hub-and-spoke kurup kurmadığını, parallel task’ları nasıl koordine ettiğini, subagent context’ini nasıl geçtiğini ölçüyor. Yanlış mimari seçimi (peer-to-peer, ring, market) sınavda net olarak “yanlış” işaretlenir.

Temel kavram: Hub-and-Spoke

              +-----------------+
              |   Coordinator   |
              |  (ana agent)    |
              +-----------------+
               |    |    |    |
          Task |    |    |    | Task
               v    v    v    v
          +-----+ +-----+ +-----+ +-----+
          | SA1 | | SA2 | | SA3 | | SA4 |
          +-----+ +-----+ +-----+ +-----+
          (her biri izole context'te çalışır,
           sonuçlarını coordinator'a döner)

Temel kurallar:

Subagent’lar kendi aralarında konuşmaz. Tüm trafik coordinator üzerinden.
Coordinator tek state sahibidir. Hangi subagent ne yaptı, hangi sonucu döndü, hangisi başarısız oldu — hepsi coordinator’ın context’inde.
Subagent’lar kısa, yapılandırılmış sonuç döner. Coordinator’a “şu 3 dosyada şu pattern var” döner, ham log dönmez.
Coordinator’ın allowedTools’unda “Task” olmalı. Bu sınav tuzağı: Task tool’u olmadan coordinator subagent çağıramaz.

Neden peer-to-peer değil?

Sınavda “iki subagent birbirine mesaj göndersin” diye bir pattern ararsan yanlış işaretlenir. Sebebi:

State dağılıyor: hangi agent ne biliyor takip edemezsin.
Hata yayılımı: bir subagent çöktüğünde döngü tıkanır.
Debug imkansızlaşır: conversation trace tek bir noktadan izlenemez.

Hub-and-spoke hepsini çözer: tüm konuşma coordinator’ın message log’unda, tüm hatalar coordinator’a döner, tüm state coordinator’da.

Subagent bağlatısı: Task tool

Coordinator subagent’ı Task tool ile çağırır. Bu, agentic döngüde tool_use olarak görünür (önceki dersteki stop_reason tool_use akışı). Subagent kendi loop’unu çalıştırır, sonunda kısa bir özet döner, coordinator loop’a devam eder.

AgentDefinition yapısı

Bir subagent tanımlarken bu alanlar şart:

---
name: security-reviewer
description: Review code for security issues. Use proactively on auth/ and api/ paths.
tools: Read, Grep, Glob
model: sonnet
---

Sen güvenlik odaklı bir code reviewer'sın.
Verilen dosyalarda şu kategorileri tara:
1. Input validation (path traversal, SQL injection, XSS)
2. Authentication / authorization bypass
3. Sensitive data handling (logs, error messages)
4. Dependency vulnerabilities

Her bulgu için: dosya:satır, kategori, severity (CRITICAL/HIGH/MEDIUM/LOW), 
kısa açıklama ve önerilen fix.
Sorun yoksa "no issues found" de.

name: subagent identifier (Task tool’da referans verilir)
description: modelin ne zaman bu subagent’ı kullanacağını kendisi anlasın diye
tools: açıkça sınırla; Write/Bash vermeden review agent yap
model: opus / sonnet / haiku; pahalı modeli sadece gereken yerde kullan. 📝 Rehber kapsamı dışında: rehberin AgentDefinition alanları name / description / system_prompt / allowed_tools olarak listelenir; model alanı bu dörtlünün dışında.

Subagent context mirası ALMAZ

Bu, sınavda en kritik kural:

Subagent başlatıldığında hiçbir context almaz. Coordinator’ın tüm mesaj geçmişi, dosya okumaları, tool sonuçları subagent için görünmez.

Bu yüzden coordinator subagent’ı çağırırken gerekli tüm bilgiyi prompt’a açıkça yazmak zorundadır. “Bu repo’da authentication nasıl yapılıyor?” diye sormak kötü: subagent yeni baştan keşfetmek zorunda kalır. Doğrusu:

Subagent: security-reviewer

Hedef: src/auth/login.ts dosyasındaki güvenlik açıklarını tara.

Bilgi (context):
- Dosya: src/auth/login.ts (45 satır, express middleware)
- İlgili bağımlılık: passport.js v0.6
- Bu kod production'da aktif, kullanıcı sayısı ~10k
- Dün yapılan değişiklik: rate limiting eklendi (commit abc123)

Görev: ...
Kabul kriterleri: ...
Çıktı formatı: ...

Sınav tuzağı: “Coordinator gerekli bilgiyi vermeden subagent’a ‘şu dosyayı incele’ dedi” — bu yanlış çünkü subagent’ın o bilgiye erişimi yok.

Parallel Task çağrıları

Coordinator tek yanıtında birden fazla Task tool çağırabilir. Bunlar paralel çalışır:

{
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Paralel olarak 3 açıyı araştırıyorum." },
    { "type": "tool_use", "id": "t1", "name": "Task", "input": {
        "subagent_type": "Explore",
        "description": "Tüm API endpointlerini bul",
        "prompt": "src/routes/ altındaki tüm route'ları listele. Her biri için HTTP method, path, handler dosyası döndür."
    }},
    { "type": "tool_use", "id": "t2", "name": "Task", "input": {
        "subagent_type": "Explore",
        "description": "Auth mekanizmasını haritala",
        "prompt": "src/auth/ altındaki tüm auth logic'i özetle. Login, session, JWT kullanımı."
    }},
    { "type": "tool_use", "id": "t3", "name": "Task", "input": {
        "subagent_type": "Explore",
        "description": "DB şemasını çıkar",
        "prompt": "prisma/schema.prisma ve migrations/ içindeki tabloları ve ilişkileri listele."
    }}
  ],
  "stop_reason": "tool_use"
}

Üçü paralel çalışır, hepsinin sonucu tek tool_result listesinde döner. Coordinator bu sonuçları birleştirir, gerekiyorsa ikinci bir tur Task açar.

📝 Rehber kapsamı dışında: örneklerdeki subagent_type alanı Agent SDK’da geçerlidir; rehber sınav kapsamında bu alan adını vermez, sadece “subagent’lara Task tool ile spawn olunur” der.

Doğru decomposition: kök neden ağacı

Sınavda sıkça gelen tuzak: aşırı dar decomposition. Örnek:

“Login sayfası 500 veriyor.” diye görev veriliyor.

Yanlış decomposition:

SA1: Login form HTML’ini düzelt

SA2: Login butonunun rengini değiştir

SA3: Login sonrası redirect URL’ini düzelt

Bu 3’ü de yüzey semptomu. Asıl sorun backend’de olabilir.

Doğru decomposition: kök neden → sonuç → kontrol ağacı:

Görev: Login 500 hatası kök neden analizi
  |
  +-- SA1: Backend log'larını tara, hatanın ilk oluştuğu yeri bul
  |     kabul: stack trace + dosya:satır
  |
  +-- SA2: Aynı hatanın farklı senaryolarda da var mı kontrol et
  |     (farklı kullanıcı, farklı browser, farklı input)
  |     kabul: "evet şu senaryoda, hayır şu senaryoda"
  |
  +-- SA3: Database ve auth servisinin health check'ini yap
  |     kabul: servis durumu, son 10dk metrikleri
  |
  +-- SA4: Son deploy'da auth ile alakalı değişen dosyaları bul
        kabul: git diff summary + ilgili satırlar

Her subagent kabul kriteri ile tanımlı, sonuçlar coordinator’da birleşerek kök nedeni oluşturuyor. Bu sınavda “doğru mimari” işaretlenen cevap.

fork_session ve —resume

İleri multi-agent pattern’ları:

fork_session: Paylaşılan context’ten bağımsız bir dal oluşturur. Her iki fork, branch noktasına kadar olan context’i miras alır, sonrasında bağımsız ilerler. “Şu görevi A yolunu dene, paralel B yolunu dene, hangisi iyiyse onu seç” senaryosunda yaklaşım karşılaştırması için kullanılır. Rehber bunun için bir CLI flag göstermez; CLI tarafında rehberin verdiği tek örnek --resume <session-name>’dir.
--resume <session-name>: Daha önce kaydedilmiş bir session’ı kaldığı yerden devam ettir. Long-running görevlerde (multi-hour research) veya session kesildiğinde.

# Session'ı kaydet
claude -p "Şu repo'yu derinlemesine analiz et" --output-format json > session.json

# Resume: kaldığı yerden (rehber 5.10 örneği: named session)
claude --resume investigation-auth-bug
claude --resume <session-name> -p "Önceki analize ek olarak şunu da yap"

Sınav tuzağı: fork_session’ı bir CLI flag gibi düşünmek — rehber onu session yönetim konsepti olarak anlatır, CLI üzerinde doğrudan karşılığı yoktur (CLI tarafında yalnızca --resume <session-name> örneklenir). Session’ı kaydetmeden fork etmeye çalışmak da hata verir: fork_session mevcut state’in bir kopyasını alır, kopyalanacak bir şey yoksa hata.

Coordinator prompt kalıpları

İyi bir coordinator prompt’u goal + quality criteria yapısındadır:

Sen bir multi-agent coordinator'sın.

AMAÇ: Bu repo'nun refactor'a hazır olup olmadığını değerlendir.

SUBAGENT KULLANIMI:
- "Explore" → codebase taraması için
- "security-reviewer" → auth/api yolları için
- "performance-reviewer" → hot path'ler için

PARALEL ÇALIŞTIR: İlk turda 3 Explore paralel aç (modüller, testler, 
dependency graph). Sonuçları birleştir, risk haritası çıkar.

KALİTE KRİTERLERİ:
- Her bulgu için severity (CRITICAL/HIGH/MEDIUM/LOW) ata
- Çelişen istatistik olursa ikisini de annotation ile sakla, keyfi seçme
- Anahtar bulguları raporun başına ve sonuna koy (lost-in-the-middle etkisi)
- 3+ dosya değişecekse decomposition önerisi ekle

ÇIKTI: Markdown rapor, max 800 kelime, kod bloklarıyla.

Dikkat: “Çelişen istatistik olursa ikisini de sakla” ifadesi bilinçli. D5 (context management) sorularının cevabı bu: attribution loss’a düşmemek için çelişen bilgiyi silmemek gerekiyor.

Sınav tuzakları

Peer-to-peer multi-agent — İki subagent birbirine mesaj göndersin demek yanlış çünkü state dağılır, debug imkansızlaşır, hata kaskadı oluşur. Hub-and-spoke tek doğru mimari.
Coordinator’ın allowedTools’unda “Task” yok — Coordinator subagent çağıramaz. Bu permission hatası sınavda “neden subagent çalışmadı?” sorularının cevabı.
Subagent context’i ALMAMASINA rağmen “bu konuşmada şunu konuştuk” demek — Subagent’ın hafızası yoktur. Coordinator’ın konuşma geçmişi subagent için görünmez. Tüm gerekli bilgi prompt’a açıkça yazılmalı.
Aşırı dar decomposition — Yüzey semptomu çözen 3-4 subagent dağıtmak kök nedeni atlar. Doğrusu: kök neden → sonuç → kontrol ağacı.
Tüm subagent’lara aynı tool seti vermek — Reviewer’a Bash ve Write vermek güvenlik açığı. Her subagent’ın tool seti minimum gerekli olmalı.
Subagent sonuçlarını ham log olarak döndürmek — Coordinator’ın context’ini şişirir. Kısa, yapılandırılmış özet dönmeli.

Hands-on: paralel Task deneyi

# Claude Code'da minimal deney:
# 1. Bir repo'da "claude" aç
# 2. Şunu yaz:
#    "Explore subagent'ı kullanarak 3 paralel analiz yap:
#     - Tüm .ts dosyalarını say ve dizinlere göre grupla
#     - Tüm TODO/FIXME yorumlarını listele
#     - package.json'daki dependency'lerin en son sürümlerini bul"
# 3. Gözlemle: tek yanıtta 3 ayrı Task tool_use göreceksin
# 4. 3'ü paralel çalışıp sonuçları birleşecek
#
# JSON çıktı modunda:
claude --output-format json -p "Aynı repo için 3 paralel Explore aç"

Özet

Hub-and-spoke tek doğru multi-agent pattern: tüm trafik coordinator’dan, subagent’lar kendi aralarında konuşmaz.
Subagent context mirası almaz — tüm gerekli bilgi coordinator tarafından prompt’a açıkça yazılmalı.
Coordinator allowedTools’unda “Task” şart — yoksa subagent çağıramaz.
Doğru decomposition: kök neden → sonuç → kontrol ağacı; yüzey semptomuna değil.
Parallel Task tek yanıtta birden fazla tool_use ile çalışır, sonuçlar tek tool_result listesinde döner.
fork_session alternatif keşif, —resume kesilen session’ı devam ettirir.
Her subagent’ın tool seti minimum gerekli olmalı; reviewer’a Write/Bash verme.