​

50. Alt Ajanlar

​

Eğik çizgi komutu

• /subagents list
• /subagents kill <id|#|all>
• /subagents log <id|#> [limit] [tools]
• /subagents info <id|#>
• /subagents send <id|#> <message>

• Ana çalışmayı engellemeden “araştırma / uzun görev / yavaş araç” işlerini paralelleştirmek.
• Alt ajanları varsayılan olarak izole tutmak (oturum ayrımı + isteğe bağlı sandbox).
• Araç yüzeyini kötüye kullanıma kapalı tutmak: alt ajanlar varsayılan olarak oturum araçlarını almaz.
• Orkestratör desenleri için yapılandırılabilir iç içe derinlik desteği.

​

Araç

• Bir alt ajan çalıştırması başlatır (deliver: false, global lane: subagent)
• Ardından bir duyuru adımı çalıştırır ve duyuru yanıtını talepte bulunan sohbet kanalına gönderir
• Varsayılan model: agents.defaults.subagents.model (veya ajan başına agents.list[].subagents.model) ayarlamadığınız sürece çağıranı devralır; açık bir sessions_spawn.model her zaman önceliklidir.
• Varsayılan düşünme: agents.defaults.subagents.thinking (veya ajan başına agents.list[].subagents.thinking) ayarlamadığınız sürece çağıranı devralır; açık bir sessions_spawn.thinking her zaman önceliklidir.

• task (zorunlu)
• label? (isteğe bağlı)
• agentId? (isteğe bağlı; izin verildiyse başka bir ajan kimliği altında başlatır)
• model? (isteğe bağlı; alt ajan modelini geçersiz kılar; geçersiz değerler atlanır ve araç sonucunda bir uyarıyla birlikte varsayılan model kullanılır)
• thinking? (isteğe bağlı; alt ajan çalıştırması için düşünme seviyesini geçersiz kılar)
• runTimeoutSeconds? (varsayılan 0; ayarlandığında alt ajan çalıştırması N saniye sonra iptal edilir)
• cleanup? (delete|keep, varsayılan keep)

• agents.list[].subagents.allowAgents: agentId ile hedeflenebilecek ajan kimliklerinin listesi (["*"] herhangi birine izin verir). Varsayılan: yalnızca talepte bulunan ajan.

• sessions_spawn için şu anda hangi ajan kimliklerine izin verildiğini görmek üzere agents_list kullanın.

• Alt ajan oturumları agents.defaults.subagents.archiveAfterMinutes süresi sonunda otomatik olarak arşivlenir (varsayılan: 60).
• Arşivleme sessions.delete kullanır ve dökümü *.deleted.<timestamp> olarak yeniden adlandırır (aynı klasörde).
• cleanup: "delete" duyurudan hemen sonra arşivler (döküm yeniden adlandırılarak korunur).
• Otomatik arşivleme en iyi çaba esaslıdır; gateway yeniden başlatılırsa bekleyen zamanlayıcılar kaybolur.
• runTimeoutSeconds otomatik arşivleme yapmaz; yalnızca çalıştırmayı durdurur. Oturum, otomatik arşivleme gerçekleşene kadar kalır.
• Otomatik arşivleme hem derinlik-1 hem de derinlik-2 oturumlara eşit şekilde uygulanır.

​

İç İçe Alt Ajanlar

​

Nasıl etkinleştirilir

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // alt ajanların çocuk başlatmasına izin ver (varsayılan: 1)
        maxChildrenPerAgent: 5, // ajan oturumu başına maksimum aktif çocuk (varsayılan: 5)
        maxConcurrent: 8, // global eşzamanlılık üst sınırı (varsayılan: 8)
      },
    },
  },
}

​

Derinlik seviyeleri

​

Duyuru zinciri

1. Derinlik-2 çalışan tamamlar → ebeveynine (derinlik-1 orkestratör) duyurur
2. Derinlik-1 orkestratör duyuruyu alır, sonuçları sentezler, tamamlar → ana ajana duyurur
3. Ana ajan duyuruyu alır ve kullanıcıya iletir

​

Derinliğe göre araç politikası

• Derinlik 1 (orkestratör, maxSpawnDepth >= 2 iken): Çocuklarını yönetebilmesi için sessions_spawn, subagents, sessions_list, sessions_history alır. Diğer oturum/sistem araçları yine reddedilir.
• Derinlik 1 (çalışan, maxSpawnDepth == 1 iken): Oturum araçları yoktur (mevcut varsayılan davranış).
• Derinlik 2 (çalışan): Oturum araçları yoktur — derinlik 2’de sessions_spawn her zaman reddedilir. Daha fazla çocuk başlatamaz.

​

Ajan başına başlatma limiti

​

Zincirleme durdurma

• Ana sohbette /stop, tüm derinlik-1 ajanları durdurur ve onların derinlik-2 çocuklarına zincirleme etki eder.
• /subagents kill <id>, belirli bir alt ajanı durdurur ve çocuklarına zincirleme etki eder.
• /subagents kill all, talepte bulunan için tüm alt ajanları durdurur ve zincirleme etki eder.

​

Kimlik Doğrulama

• Alt ajan oturum anahtarı agent:<agentId>:subagent:<uuid> şeklindedir.
• Kimlik doğrulama deposu ilgili ajanın agentDir dizininden yüklenir.
• Ana ajanın kimlik doğrulama profilleri yedek olarak birleştirilir; çakışmalarda ajan profilleri önceliklidir.

​

Duyuru

• Duyuru adımı alt ajan oturumu içinde çalışır (talepte bulunan oturumda değil).
• Alt ajan tam olarak ANNOUNCE_SKIP yanıtını verirse hiçbir şey gönderilmez.
• Aksi takdirde duyuru yanıtı, talepte bulunan sohbet kanalına bir takip agent çağrısı (deliver=true) ile gönderilir.
• Duyuru yanıtları, mevcut olduğunda iş parçacığı/konu yönlendirmesini korur (Slack threads, Telegram topics, Matrix threads).
• Duyuru mesajları sabit bir şablona normalize edilir:
  • Status: çalışma sonucundan türetilir (success, error, timeout veya unknown).
  • Result: duyuru adımındaki özet içerik (yoksa (not available)).
  • Notes: hata ayrıntıları ve diğer yararlı bağlam.
• Status, model çıktısından çıkarılmaz; çalışma zamanı sinyallerinden gelir.

• Çalışma süresi (ör. runtime 5m12s)
• Token kullanımı (input/output/total)
• Model fiyatlandırması yapılandırılmışsa tahmini maliyet (models.providers.*.models[].cost)
• sessionKey, sessionId ve döküm yolu (ana ajanın sessions_history ile geçmişi alabilmesi veya dosyayı diskten inceleyebilmesi için)

​

Araç Politikası (alt ajan araçları)

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny her zaman kazanır
        deny: ["gateway", "cron"],
        // allow ayarlanırsa yalnızca izin verilenler geçerli olur (deny yine kazanır)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

​

Eşzamanlılık

• Hat adı: subagent
• Eşzamanlılık: agents.defaults.subagents.maxConcurrent (varsayılan 8)

​

Durdurma

• Talepte bulunan sohbette /stop göndermek, talep eden oturumu iptal eder ve ondan başlatılmış tüm aktif alt ajan çalışmalarını durdurur; iç içe çocuklara zincirleme etki eder.
• /subagents kill <id>, belirli bir alt ajanı durdurur ve çocuklarına zincirleme etki eder.

​

Sınırlamalar

• Alt ajan duyurusu en iyi çaba esaslıdır. Gateway yeniden başlatılırsa bekleyen “geri duyuru” işleri kaybolur.
• Alt ajanlar aynı gateway süreci kaynaklarını paylaşır; maxConcurrent bir güvenlik supabı olarak düşünülmelidir.
• sessions_spawn her zaman engelleyici değildir: hemen { status: "accepted", runId, childSessionKey } döner.
• Alt ajan bağlamı yalnızca AGENTS.md + TOOLS.md enjekte eder (SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md veya BOOTSTRAP.md yoktur).
• Maksimum iç içe derinlik 5’tir (maxSpawnDepth aralığı: 1–5). Çoğu kullanım durumu için derinlik 2 önerilir.
• maxChildrenPerAgent, oturum başına aktif çocuk sayısını sınırlar (varsayılan: 5, aralık: 1–20).

​

Ayrıca Bakın

• Oturum Araçları — sessions_spawn ve diğer oturum araçları hakkında ayrıntılar
• Çok Ajanlı Sandbox ve Araçlar — ajan başına araç kısıtlamaları ve sandboxing
• Yapılandırma — agents.defaults.subagents referansı
• Kuyruk — subagent hattının nasıl çalıştığı