AI Atlas
EN TR
İleri · ~2 dk okuma #subagent #multi-agent #context

Subagent

Alt ajan — kendi bağlamıyla çalışan yardımcı

Ana ajanın bir alt görevi devrettiği, kendi bağlam penceresi, talimatları ve araç setiyle çalışıp sadece sonucunu geri döndüren yardımcı ajan.

DEVRET, AMA SADECE ÖZETİ GERİ ALANA AJAN3 özetsecurity-reviewerkendi bağlam penceresion binlerce token okumaperf-reviewerkendi bağlam penceresion binlerce token okumatest-runnerkendi bağlam penceresion binlerce token okumagörev + brifingsadece son mesajparalel çalışır · ara adımlar alt ajanın bağlamında kalırizolasyon ve paralellik kazanırsın — bedeli daha fazla token
Tanım

Bir ajan büyük bir kod tabanında “kimlik doğrulama nerede yapılıyor?” sorusunu kendisi araştırırsa, okuduğu onlarca dosyanın hepsi kendi bağlamına dolar. Subagent bu işi devralır: temiz ve ayrı bir bağlam penceresiyle başlar, aramayı yapar, belki on binlerce token harcar ve ana ajana sadece son mesajını, yani yoğun bir özeti döndürür. Ara adımlar alt ajanın bağlamında kalır.

Üç temel kazanç: - Bağlam izolasyonu — ana ajanın penceresi temiz kalır; context rot ve erken compaction gecikir. - Paralellik — birbirinden bağımsız alt görevler aynı anda koşar; toplam süre, en yavaş alt görev kadar olur. - Uzmanlaşma — her alt ajanın kendi system prompt'u, kısıtlı araç seti ve gerekirse daha ucuz bir modeli olabilir.

Claude Code'da yerleşik alt ajanlar vardır (salt okunur Explore, Plan ve general-purpose); kendininkini .claude/agents/ altında bir Markdown dosyasıyla tanımlarsın. Claude Agent SDK'da agents parametresiyle verilir ve model onları Agent aracıyla çağırır.

Bedeli de var. Anthropic'in çok ajanlı araştırma sistemi yazısındaki verilere göre ajanlar sohbete göre yaklaşık 4 kat, çok ajanlı sistemler yaklaşık 15 kat daha fazla token harcıyor. Alt ajan ana konuşmayı görmez (aksi açıkça ayarlanmadıkça); görevi eksik tarif edersen yanlış işi mükemmel yapar.

Benzetme

Bir proje yöneticisinin araştırma ekibine iş dağıtması gibi. Yönetici her raporu kendisi okusa masası kâğıtla dolar, büyük resmi kaybeder. Bunun yerine üç kişiye “sen rakipleri, sen fiyatları, sen mevzuatı araştır, bana birer sayfa getir” der.

Her biri kendi masasında saatlerce çalışır; yöneticiye sadece özet gelir. Ama brifing kötüyse, örneğin hangi pazar olduğu söylenmemişse, ekip yanlış ülkeyi araştırıp mükemmel bir rapor getirir.

Gerçek dünyadan örnek

Claude Code'a “bu PR'ı güvenlik, performans ve test kapsamı açısından incele” diyorsun. Ana ajan üç alt ajanı paralel başlatır:

- security-reviewer: sadece Read, Grep, Glob araçlarıyla güvenlik açıklarını arar. - perf-reviewer: sıcak yollardaki gereksiz sorguları inceler. - test-runner: Bash ile testleri koşar, kapsamı raporlar.

Her biri onlarca dosya okur; ana ajana her birinden kısa bir bulgu listesi döner. Ana ajanın bağlamında üç özet vardır, yüzlerce dosya satırı değil. Ana ajan bulguları birleştirip tek bir inceleme yazar.

Kod örnekleri
Claude Code · .claude/agents/security-reviewer.md markdown
---
name: security-reviewer
description: Kod değişikliklerini güvenlik açıkları için inceler. Kod yazıldıktan ya da değiştirildikten sonra kullan.
tools: Read, Grep, Glob
model: sonnet
---

Sen bir uygulama güvenliği uzmanısın. Verilen değişiklikleri
enjeksiyon, yetki atlama, sır sızıntısı ve güvensiz
deserializasyon açısından incele.

Her bulgu için: dosya:satır, risk seviyesi, kısa açıklama ve
önerilen düzeltme. Bulgu yoksa bunu açıkça söyle.
Claude Agent SDK · alt ajanları kodda tanımlamak python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    async for message in query(
        prompt="Kimlik doğrulama modülünü güvenlik açısından incele",
        options=ClaudeAgentOptions(
            # Alt ajanlar Agent aracıyla çağrılır
            allowed_tools=["Read", "Grep", "Glob", "Agent"],
            agents={
                "security-reviewer": AgentDefinition(
                    # Ana ajan, ne zaman devredeceğine buna bakarak karar verir
                    description="Güvenlik incelemesi uzmanı. Güvenlik sorularında kullan.",
                    prompt="Sen bir güvenlik uzmanısın. Bulguları dosya:satır ile raporla.",
                    tools=["Read", "Grep", "Glob"],   # salt okunur
                    model="sonnet",                   # daha ucuz model
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())
Ne zaman kullan
  • Çok okuma gerektiren ama sonucu kısa olan işler — kod tabanında arama, log inceleme, doküman tarama
  • Birbirinden bağımsız, paralel yürütülebilen alt görevler — çok yönlü inceleme, çok kaynaklı araştırma
  • Farklı yetki ya da uzmanlık gereken adımlar — salt okunur inceleyici, sadece test koşan ajan
  • Ana konuşmanın bağlamını uzun bir oturum boyunca temiz tutmak istediğinde
Ne zaman kullanma
  • Küçük, hızlı işler — alt ajanı başlatmanın ve brifing yazmanın maliyeti işin kendisinden büyük
  • Adımların sıkı bağımlı olduğu işler — her adım öncekinin tüm ayrıntısını gerektiriyorsa özet yetmez
  • Aynı dosyalara yazan paralel işler — alt ajanlar birbirinin değişikliğini ezebilir
  • Token bütçesi dar, işin değeri düşükse — çok ajanlı yapı token tüketimini katlar
Sık yapılan hatalar

Eksik brifing

Alt ajan ana konuşmayı görmez. Hedefi, kısıtları, ilgili dosya yollarını ve beklenen çıktı biçimini görev mesajına açıkça yaz; “yukarıda konuştuğumuz hata” gibi göndermeler alt ajan için anlamsızdır.

Özete körü körüne güvenmek

Ana ajan sadece alt ajanın son mesajını görür. Alt ajan bir şeyi yanlış anladıysa ya da atladıysa bu özetten anlaşılmayabilir. Kritik iddialar için dosya:satır gibi doğrulanabilir kanıt iste.

Her şeyi alt ajana bölmek

Her alt ajan kendi system prompt'u, araç tanımları ve okumalarıyla sıfırdan bağlam kurar. Gereksiz bölme, toplam maliyeti ve süreyi tek ajanın üstüne çıkarır.

Alt ajana fazla yetki vermek

Araç listesini belirtmezsen alt ajan kullanılabilir araçların tamamını devralabilir. İnceleme yapan bir alt ajana yazma ya da kabuk erişimi verme; tools alanıyla sınırla.