Subagent'lar, ana agent'ın bir işi kendi başına bitiremeyeceği ya da bitirmemesi gereken durumlarda devreye giren yardımcı agent'lardır. Büyük bir kod tabanında onlarca dosyayı tarayıp yalnızca sonucu geri getirmek, ya da bağımsız bir alt görevi baştan sona tamamlamak için biçilmiş kaftandır. Bu rehberde, Agent SDK ile sıfırdan bir subagent kuracak; ne zaman kullanılacağını, nasıl tanımlanacağını ve nasıl tetikleneceğini birlikte göreceğiz.
Subagent ne zaman mantıklı?
Her şeyi subagent'a devretmek cazip görünür ama çoğu zaman gereksizdir. İyi adaylar şunlardır:
- Geniş arama: Çok sayıda dosyada bir şey arıyorsun ve ana sohbeti onlarca dosya çıktısıyla kirletmeden yalnızca sonucu istiyorsun.
- Bağımsız alt görev: Kendi içinde tamamlanan, net bir girdi–çıktısı olan bir iş (örneğin "şu modülün testlerini yaz").
- Paralellik: Ana akış beklerken arka planda ilerleyebilecek işler.
Buna karşılık, bağlamın sürekli ana sohbette kalması gereken, adım adım birlikte ilerlediğin işleri subagent'a verme — her çağrı sıfırdan başladığı için bağlamı tekrar tekrar aktarmak zahmetli olur.
Tanımı yazmak
Bir subagent'ı, projenin .claude/agents/ klasöründe bir Markdown dosyasıyla tanımlarsın. Frontmatter bölümü agent'ın adını, ne zaman kullanılacağını ve hangi araçlara erişebileceğini belirler; gövde ise onun sistem yönergesidir:
# .claude/agents/kod-arama.md --- name: kod-arama description: Kod tabanında geniş arama yapar; sadece ilgili dosya yollarını ve kısa gerekçeyi döndürür. tools: Glob, Grep, Read --- Sen bir arama uzmanısın. Verilen terimi tüm projede bul. Yalnızca ilgili dosya yollarını ve her biri için tek cümlelik gerekçeyi döndür. Kod gövdesini kopyalama.
İki ayrıntı kritiktir: description alanı, ana agent'ın bu subagent'ı ne zaman çağıracağını belirler — bu yüzden tetikleyici niyeti açıkça yaz. tools alanı ise yetkiyi daraltır; bir arama agent'ının dosya yazmasına gerek yoktur, o yüzden ona yalnızca okuma araçlarını ver.
Tetiklemek ve sonucu almak
Ana agent, uygun bir görev geldiğinde işi bu subagent'a devreder. Subagent kendi temiz context'inde çalışır, görevini bitirir ve bir rapor döndürür. Burada çoğu kişinin atladığı nokta şudur: subagent'ın çıktısı doğrudan kullanıcıya değil, ana agent'a döner. Onu özetleyip kullanıcıya aktarmak ana agent'ın işidir.
Sık yapılan hatalar
- Çok geniş görev: "Projeyi iyileştir" gibi muğlak brief'ler işe yaramaz. Dar ve ölçülebilir tut.
- Gereksiz yetki: Her subagent'a tüm araçları vermek; en az yetki ilkesine uy.
- Bağlam varsayımı: Subagent senin ana sohbetini görmez; neyi bilmesi gerekiyorsa brief'e koy.
Özet
Dar görev, net brief, doğrulanmış sonuç — üç kural bu kadar. Subagent'lar doğru yerde kullanıldığında bağlamı temiz tutar, hızı artırır ve ana agent'ı asıl işine odaklı bırakır. Yanlış yerde kullanıldığında ise yalnızca gidip gelen bir gürültü katmanı olur. Farkı brief'in netliği belirler.