​

الوكلاء الفرعيون

​

أمر Slash

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

• تنفيذ أعمال “بحث / مهمة طويلة / أداة بطيئة” بالتوازي دون حجب التشغيل الرئيسي.
• إبقاء الوكلاء الفرعيين معزولين افتراضيًا (فصل الجلسات + عزل اختياري).
• تقليل إساءة استخدام الأدوات: الوكلاء الفرعيون لا يحصلون على أدوات الجلسة افتراضيًا.
• دعم عمق تداخل قابل للتهيئة لأنماط الـ orchestrator.

​

الأداة

• يبدأ تشغيل وكيل فرعي (deliver: false, مسار عام: subagent)
• ثم ينفّذ خطوة announce وينشر رد الإعلان في قناة دردشة الطالب
• النموذج الافتراضي: يرث من المستدعي ما لم تقم بتعيين agents.defaults.subagents.model (أو agents.list[].subagents.model لكل وكيل)؛ أي قيمة sessions_spawn.model صريحة لها الأولوية.
• التفكير الافتراضي: يرث من المستدعي ما لم تقم بتعيين agents.defaults.subagents.thinking (أو agents.list[].subagents.thinking لكل وكيل)؛ أي قيمة sessions_spawn.thinking صريحة لها الأولوية.

• task (مطلوب)
• label? (اختياري)
• agentId? (اختياري؛ الإنشاء تحت معرف وكيل آخر إذا كان مسموحًا)
• model? (اختياري؛ يتجاوز نموذج الوكيل الفرعي؛ القيم غير الصالحة يتم تخطيها ويعمل الوكيل الفرعي على النموذج الافتراضي مع تحذير في نتيجة الأداة)
• thinking? (اختياري؛ يتجاوز مستوى التفكير لتشغيل الوكيل الفرعي)
• runTimeoutSeconds? (الافتراضي 0؛ عند التعيين يتم إيقاف تشغيل الوكيل الفرعي بعد N ثانية)
• cleanup? (delete|keep, الافتراضي keep)

• agents.list[].subagents.allowAgents: قائمة بمعرفات الوكلاء التي يمكن استهدافها عبر agentId (["*"] للسماح للجميع). الافتراضي: فقط وكيل الطالب.

• استخدم agents_list لمعرفة معرفات الوكلاء المسموح بها حاليًا لـ sessions_spawn.

​

الأرشفة التلقائية

• تتم أرشفة جلسات الوكلاء الفرعيين تلقائيًا بعد agents.defaults.subagents.archiveAfterMinutes (الافتراضي: 60).
• تستخدم الأرشفة sessions.delete وتعيد تسمية النص إلى *.deleted.<timestamp> (في نفس المجلد).
• cleanup: "delete" يقوم بالأرشفة فورًا بعد announce (مع الاحتفاظ بالنص عبر إعادة التسمية).
• الأرشفة التلقائية بنمط best-effort؛ يتم فقدان المؤقتات المعلقة إذا أُعيد تشغيل البوابة.
• runTimeoutSeconds لا يقوم بالأرشفة التلقائية؛ بل يوقف التشغيل فقط. تبقى الجلسة حتى الأرشفة التلقائية.
• تنطبق الأرشفة التلقائية على جلسات العمق 1 والعمق 2 على حد سواء.

​

الوكلاء الفرعيون المتداخلون

​

كيفية التمكين

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // السماح للوكلاء الفرعيين بإنشاء أبناء (الافتراضي: 1)
        maxChildrenPerAgent: 5, // الحد الأقصى للأبناء النشطين لكل جلسة وكيل (الافتراضي: 5)
        maxConcurrent: 8, // الحد الأقصى للتزامن على مستوى المسار العام (الافتراضي: 8)
      },
    },
  },
}

​

مستويات العمق

​

سلسلة الإعلان (Announce chain)

1. ينتهي عامل العمق-2 → يعلن إلى والده (orchestrator في العمق-1)
2. يستقبل orchestrator في العمق-1 الإعلان، يركّب النتائج، ينتهي → يعلن إلى الرئيسي
3. يستقبل الوكيل الرئيسي الإعلان ويقوم بالتسليم إلى المستخدم

​

سياسة الأدوات حسب العمق

• العمق 1 (orchestrator، عند maxSpawnDepth >= 2): يحصل على sessions_spawn, subagents, sessions_list, sessions_history لإدارة أبنائه. تظل أدوات الجلسة/النظام الأخرى مرفوضة.
• العمق 1 (عامل نهائي، عند maxSpawnDepth == 1): بدون أدوات جلسة (السلوك الافتراضي الحالي).
• العمق 2 (عامل نهائي): بدون أدوات جلسة — يتم رفض sessions_spawn دائمًا في العمق 2. لا يمكنه إنشاء أبناء إضافيين.

​

حد الإنشاء لكل وكيل

​

الإيقاف المتسلسل (Cascade stop)

• تنفيذ /stop في الدردشة الرئيسية يوقف جميع وكلاء العمق-1 ويتسلسل إلى أبنائهم في العمق-2.
• /subagents kill <id> يوقف وكيلًا فرعيًا محددًا ويتسلسل إلى أبنائه.
• /subagents kill all يوقف جميع الوكلاء الفرعيين للطالب ويتسلسل.

​

المصادقة

• مفتاح جلسة الوكيل الفرعي هو agent:<agentId>:subagent:<uuid>.
• يتم تحميل مخزن المصادقة من agentDir الخاص بذلك الوكيل.
• يتم دمج ملفات تعريف مصادقة الوكيل الرئيسي كـ fallback؛ ملفات تعريف الوكيل تتغلب عند التعارض.

​

Announce

• تعمل خطوة announce داخل جلسة الوكيل الفرعي (وليس جلسة الطالب).
• إذا رد الوكيل الفرعي بالنص ANNOUNCE_SKIP حرفيًا، فلن يتم نشر أي شيء.
• خلاف ذلك، يتم نشر رد الإعلان في قناة دردشة الطالب عبر استدعاء متابعة agent (deliver=true).
• تحافظ ردود الإعلان على توجيه الخيوط/الموضوعات عند توفره (خيوط Slack، موضوعات Telegram، خيوط Matrix).
• يتم توحيد رسائل الإعلان إلى قالب ثابت:
  • Status: مشتق من نتيجة التشغيل (success, error, timeout, أو unknown).
  • Result: محتوى الملخص من خطوة announce (أو (not available) إذا لم يوجد).
  • Notes: تفاصيل الخطأ وسياق مفيد آخر.
• لا يتم استنتاج Status من مخرجات النموذج؛ بل يأتي من إشارات نتيجة وقت التشغيل.

• مدة التشغيل (مثل runtime 5m12s)
• استخدام الرموز (input/output/total)
• التكلفة التقديرية عند تكوين تسعير النموذج (models.providers.*.models[].cost)
• sessionKey وsessionId ومسار النص (ليتمكن الوكيل الرئيسي من جلب السجل عبر sessions_history أو فحص الملف على القرص)

​

سياسة الأدوات (أدوات الوكيل الفرعي)

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny wins
        deny: ["gateway", "cron"],
        // if allow is set, it becomes allow-only (deny still wins)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

​

التزامن

• اسم المسار: subagent
• التزامن: agents.defaults.subagents.maxConcurrent (الافتراضي 8)

​

الإيقاف

• إرسال /stop في دردشة الطالب يجهض جلسة الطالب ويوقف أي عمليات وكيل فرعي نشطة تم إنشاؤها منها، مع التسلسل إلى الأبناء المتداخلين.
• /subagents kill <id> يوقف وكيلًا فرعيًا محددًا ويتسلسل إلى أبنائه.

​

القيود

• إعلان الوكيل الفرعي بنمط best-effort. إذا أُعيد تشغيل البوابة، يتم فقدان أعمال “announce back” المعلقة.
• لا يزال الوكلاء الفرعيون يشاركون نفس موارد عملية البوابة؛ استخدم maxConcurrent كصمام أمان.
• sessions_spawn دائمًا غير حاجب: يعيد { status: "accepted", runId, childSessionKey } فورًا.
• سياق الوكيل الفرعي يحقن فقط AGENTS.md وTOOLS.md (ولا يحقن SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, أو BOOTSTRAP.md).
• الحد الأقصى لعمق التداخل هو 5 (maxSpawnDepth النطاق: 1–5). العمق 2 موصى به لمعظم حالات الاستخدام.
• maxChildrenPerAgent يحدّ عدد الأبناء النشطين لكل جلسة (الافتراضي: 5، النطاق: 1–20).