> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

الوكلاء الفرعيون هم عمليات تشغيل وكيل في الخلفية يتم إنشاؤها من عملية وكيل موجودة. يعملون في جلسة خاصة بهم (`agent:<agentId>:subagent:<uuid>`) وعند الانتهاء **يعلنون** نتيجتهم مرة أخرى في قناة دردشة الطالب.

## أمر Slash

استخدم `/subagents` لفحص أو التحكم في عمليات الوكلاء الفرعيين للجلسة **الحالية**:

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

يعرض `/subagents info` بيانات التشغيل (الحالة، الطوابع الزمنية، معرف الجلسة، مسار النص، التنظيف).

الأهداف الرئيسية:

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

ملاحظة التكلفة: لكل وكيل فرعي **سياقه الخاص** واستهلاك الرموز الخاص به. للمهام الثقيلة أو المتكررة، عيّن نموذجًا أقل تكلفة للوكلاء الفرعيين واحتفظ بالوكيل الرئيسي على نموذج أعلى جودة. يمكنك ضبط ذلك عبر `agents.defaults.subagents.model` أو عبر إعدادات خاصة بكل وكيل.

## الأداة

استخدم `sessions_spawn`:

* يبدأ تشغيل وكيل فرعي (`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 على حد سواء.

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

افتراضيًا، لا يمكن للوكلاء الفرعيين إنشاء وكلاء فرعيين خاصين بهم (`maxSpawnDepth: 1`). يمكنك تمكين مستوى واحد من التداخل عبر تعيين `maxSpawnDepth: 2`، مما يسمح بنمط **orchestrator**: الرئيسي → وكيل فرعي orchestrator → وكلاء فرعيون عاملون (sub-sub-agents).

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

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

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

| Depth | Session key shape                            | Role                                         | Can spawn?                   |
| ----- | -------------------------------------------- | -------------------------------------------- | ---------------------------- |
| 0     | `agent:<id>:main`                            | الوكيل الرئيسي                               | دائمًا                       |
| 1     | `agent:<id>:subagent:<uuid>`                 | وكيل فرعي (orchestrator عند السماح بالعمق 2) | فقط إذا `maxSpawnDepth >= 2` |
| 2     | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | وكيل فرعي-فرعي (عامل نهائي)                  | أبدًا                        |

### سلسلة الإعلان (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. لا يمكنه إنشاء أبناء إضافيين.

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

يمكن لكل جلسة وكيل (في أي عمق) أن تمتلك بحد أقصى `maxChildrenPerAgent` (الافتراضي: 5) أبناء نشطين في نفس الوقت. هذا يمنع التوسع المفرط من orchestrator واحد.

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

إيقاف orchestrator في العمق-1 يوقف تلقائيًا جميع أبنائه في العمق-2:

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

## المصادقة

تُحل مصادقة الوكيل الفرعي بحسب **معرّف الوكيل**، وليس بحسب نوع الجلسة:

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

ملاحظة: الدمج تراكمي (additive)، لذا تظل ملفات تعريف الرئيسي متاحة دائمًا كخيارات احتياطية. العزل الكامل للمصادقة لكل وكيل غير مدعوم حاليًا.

## Announce

يقوم الوكلاء الفرعيون بالإبلاغ عبر خطوة 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`

عند تعيين `maxSpawnDepth >= 2`، يحصل وكلاء العمق-1 من نوع orchestrator أيضًا على `sessions_spawn`, `subagents`, `sessions_list`, و`sessions_history` لإدارة أبنائهم.

تجاوز عبر الإعداد:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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).