الوكلاء الفرعيون (Subagents): تقسيم المهام وتشغيلها بالتوازي، ولا يتم التقسيم إلا بطلبك
📚 التنقل في السلسلة: المقال السابق [20 · استخدام MCP للاتصال بالأدوات الخارجية] علمك كيفية ربط Codex بالأدوات الخارجية لقراءة الوثائق والاتصال بالخدمات. هذا المقال يغير الاتجاه - فبدلاً من "تزويده بأدوات جديدة"، سنتعلم كيفية تقسيم المهام وتشغيلها بالتوازي: من خلال الوكلاء الفرعيين (Subagents)، وهم مساعدون متخصصون يملكون نماذج وإرشادات وصلاحيات مستقلة، يعملون معاً في نفس الوقت، وعند الانتهاء يجمعون النتائج في تقرير ملخص واحد.
أصدقائي، نتحدث اليوم عن ميزة متميزة جداً في Codex ولكن يسهل الوقوع في أخطاء عند استخدامها - وهي الوكلاء الفرعيون.
الاسم يبدو جذاباً، "تعدد الوكلاء بالتوازي"، وكأنك تقود فرقة عمل خاصة. عندما تعرفت على هذه الميزة لأول مرة، تحمست كثيراً وحاولت تقسيم كل مهمة لـ 5 أو 6 وكلاء فرعيين للعمل معاً، ظناً مني أن هذا هو الأسلوب الاحترافي.
ولكن لنكن صادقين: يعمل الوكلاء الفرعيون في Codex بطريقة مختلفة عن الأدوات الأخرى، وهناك سلوك افتراضي هام يجب معرفته - وهو أن النظام لا يقوم بالتقسيم تلقائياً. تنص الوثائق الرسمية بوضوح على أن Codex لا يفعل الوكلاء الفرعيين إلا إذا طلبت منه ذلك صراحة في رسالتك. فإذا لم تطلب "تشغيل عدة وكلاء بالتوازي"، فسيستمر مساعدك الفردي في العمل بمفرده حتى النهاية. وتحدد هذه القاعدة كيفية ووقت استخدام الميزة.
ولا يقتصر هذا المقال على كيفية استدعاء الوكلاء الفرعيين وكتابة ملفات تعريفهم وتخصيص النماذج لكل منهم، بل يساعدك في وضع حد فاصل: ما هي المهام التي تستحق تقسيمها وتشغيلها بالتوازي، وما هي المهام التي يعد تقسيمها هدراً للوقت والرموز ومصدراً للمشاكل.
بقراءة هذا المقال، ستحصل على:
- مفهوم الوكلاء الفرعيين - وكيف يختلف تقسيم المهام على وكلاء متخصصين بالتوازي وتلخيص النتائج عن قيام مساعد واحد بالعمل بمفرده
- المشكلتان الأساسيتان اللتان تعالجهما الميزة: تلوث السياق (context pollution) وتراجع السياق (context rot)، والمعيار العملي: متى يمنع تقسيم المهام
- الوكلاء الثلاثة المدمجون في Codex (
defaultوworkerوexplorer)، والذين يعملون تلقائياً دون إعداد إضافي - كيفية إنشاء وكيل فرعي مخصص: وضع ملف TOML داخل المجلد
~/.codex/agents/أو.codex/agents/ووظيفة الحقول الثلاثة الإلزامية فيه - كيفية تخصيص نموذج معين ودرجة تفكير لكل وكيل فرعي، لتجعل الوكيل الاستكشافي يستخدم نموذجاً سريعاً والوكيل المراجع يستخدم نموذجاً قوياً
- تدريب عملي متكامل: كتابة وكيل استكشافي للقراءة فقط وتجربته للتأكد من تقديمه للخلاصة والتزامه بالصلاحيات المحددة
⚠️ جميع الأوامر ومفاتيح التكوين والقيم الافتراضية المذكورة أدناه تستند لـ المستندات الرسمية لـ Codex؛ أما أسماء النماذج (مثل
gpt-5.5) فتتغير مع الإصدارات وتعتمد على ما يظهر لديك محلياً.
01 مفهوم الوكلاء الفرعيين (Subagents)
نبدأ بالخلاصة: الوكلاء الفرعيون هم مساعدون متخصصون يقوم Codex بتشغيلهم مؤقتاً - حيث يعمل كل منهم في محادثة مستقلة، وعند الانتهاء يقوم Codex بتلخيص نتائجهم دون ملء محادثتك الرئيسية بتفاصيل عملهم الجانبية.
تشبيه: إسناد قضية كبيرة لعدة محققين للعمل بالتوازي. بصفتك رئيس المحققين (المحادثة الرئيسية)، تواجه قضية معقدة مثل "مراجعة التعديلات الحالية من زوايا الأمان والأداء والاختبارات". ولا تود القيام بالبحث في الجوانب الثلاثة بنفسك بالتتابع. لذا تقوم بإرسال ثلاثة محققين: أحدهم يركز على ثغرات الأمان، والثاني على الأداء، والثالث على الاختبارات، وينطلق الثلاثة في نفس الوقت للعمل. وعند الانتهاء، لن يضعوا مئات الأوراق من سجلات الفحص على مكتبك، بل سيقدم كل منهم خلاصة مثل: "رصدت ثغرتين أمنيتين في الملف X و Y". وتكون النتيجة النهائية التي تحصل عليها هي ملخص مرتب ومصنف بحسب الزوايا الثلاث.
يملك هؤلاء المحققون تفاصيل وسياق عمل خاص بهم، ولا تتداخل مع محادثتك الرئيسية. ونلخص المفاهيم الهامة المذكورة في الوثائق كالتالي:
Subagent (الوكيل الفرعي): وكيل يتم تشغيله بواسطة المساعد الرئيسي للقيام بمهمة محددة. Agent thread (محادثة الوكيل): جلسة العمل المستقلة للوكيل، ويمكنك الدخول إليها ومراجعتها والتبديل بين الجلسات باستخدام الأمر المائل
/agent.
وبناءً على ذلك، يتميز الوكيل الفرعي باستقلالية الجوانب التالية:
| وجه المقارنة | المساعد الرئيسي (محادثتك الحالية) | الوكيل الفرعي (المرسل للمهمة الفرعية) |
|---|---|---|
| المحادثة والسياق | كل القرارات والنقاشات والسجلات التي تمت معك | جلسة عمل مستقلة (agent thread) تقتصر على تفاصيل مهمته، وتظل سجلاته الفنية بداخلها |
| النموذج وقوة الاستدلال | النموذج المعتمد للمحادثة الرئيسية | يمكن تحديده بشكل مخصص (مثل استخدام نموذج سريع للاستكشاف ونموذج قوي للمراجعة) |
| الإرشادات (المهام) | السلوك الافتراضي لـ Codex | إرشادات مخصصة تكتبها له في developer_instructions (مثل "مهمتك الاستكشاف فقط ويحظر تعديل الملفات") |
| صلاحيات بيئة المعزل | إعدادات بيئة المعزل المحددة للمحادثة | يرث إعدادات الجلسة الرئيسية تلقائياً، مع إمكانية تضييقها (مثل جعله للقراءة فقط بشكل إجباري) |
وتكمن أهمية وميزة الوكلاء الفرعيين في Codex في: حظر السجلات الفنية المزعجة عن المحادثة الرئيسية. تنص الوثائق على أن الهدف هو تمكين المساعد الرئيسي من التركيز على القرارات والنتائج النهائية، وإسناد المهام الفنية المزعجة (مثل الفحص، تشغيل الاختبارات، وقراءة السجلات الطويلة) للوكلاء الفرعيين، ليقوموا بتقديم الخلاصة والنتائج النهائية فقط وتجنب عرض السجلات الفنية الطويلة.
وتحدد هذه الميزة نوعية المهام المناسبة للتقسيم، كما سنبين في القسم التالي.
توضح الرسمة مسار عمل الوكلاء الفرعيين: يتولى المساعد الرئيسي تقسيم المهمة وتوزيعها على عدة وكلاء فرعيين للعمل بالتوازي، ويحتفظ كل وكيل فرعي بسياق عمله المستقل (الاستكشاف، الاختبارات، وقراءة الوثائق دون تداخل)، وعند الانتهاء يرسل كل منهم ملخصاً للمساعد الرئيسي - لتظل المحادثة الرئيسية نظيفة وخالية من السجلات الفنية الطويلة.
💡 ملخص في جملة واحدة: الوكلاء الفرعيون هم مساعدون متخصصون يعملون في جلسات مستقلة ولديهم نماذج وصلاحيات مخصصة، وينفذون المهام بالتوازي ويرسلون الخلاصة للمساعد الرئيسي؛ وتكمن فائدتهم في إبعاد السجلات المزعجة عن محادثتك الحالية.
02 المشاكل التي تعالجها الميزة - والحدود الأمنية والعملية
بعد فهم طبيعة الميزة، نوضح المشكلتين الأساسيتين اللتين صممت لمعالجتهما وفقاً للوثائق الرسمية.
المشكلة الأولى: تلوث السياق (context pollution)
تشبيه: تداخل الفواتير والأوراق الشخصية على مكتب العمل. تحتوي محادثتك الرئيسية على البيانات الهامة - القرارات، الإرشادات، والمتطلبات. وعندما تطلب تشغيل الاختبارات للمشروع، تمتلئ المحادثة بمئات السطور من سجلات الاختبارات الفنية. وتتداخل السجلات مع البيانات الهامة، وتضطر لقضاء وقت طويل في البحث عن السطور التي تحتاجها. هذا هو تلوث السياق: تداخل البيانات المزعجة مع البيانات الهامة وتغطيتها.
تعريف الوثائق:
تلوث السياق (Context pollution): تغطية المعلومات المفيدة والهامة نتيجة لامتلاء المحادثة بالسجلات والبيانات الفنية المزعجة.
سيناريو واقعي: كنت أقوم بتعديل واجهة برمجية خارجية العام الماضي، وطلبت من Codex تشغيل الفحص عدة مرات، وكان يعرض مخرجات JSON طويلة في كل مرة. وعند رغبتي في مراجعة المتطلبات الأساسية التي حددتها في بداية المحادثة، اضطررت لتصفح أكثر من 20 شاشة من نصوص JSON للوصول للمعلومة المطلوبة. ومنذ ذلك اليوم أدركت ضرورة إبعاد المهام التي ينتج عنها مخرجات وسجلات طويلة عن المحادثة الرئيسية.
المشكلة الثانية: تراجع وتلف السياق (context rot)
تشبيه: تشتت الذهن عند طول وقت الاجتماعات. يبدأ الاجتماع بتركيز عالٍ ومناقشة النقاط الأساسية؛ ولكن مع امتداد الوقت لعدة ساعات وتداخل مواضيع جانبية وتفاصيل غير هامة، يتراجع تركيز الحاضرين وتقل جودة القرارات المتخذة. ويحدث نفس الأمر للنماذج - فمع زيادة حجم المحادثة وامتلائها بتفاصيل فنية جانبية، يتراجع مستوى أداء واستيعاب النموذج تدريجياً.
تعريف الوثائق:
تراجع السياق (Context rot): تراجع أداء واستجابة النموذج تدريجياً نتيجة لامتلاء المحادثة ببيانات وتفاصيل جانبية غير هامة.
والعلاج للمشكلتين واحد: إبعاد المهام المزعجة عن المحادثة الرئيسية وإسنادها للوكلاء الفرعيين، ليقوموا بمعالجتها وإرسال الخلاصة والنتائج الهامة فقط. وتوضح الوثائق حالة قراءة مستند ضخم يحتوي على ملايين الرموز، حيث يمكن لـ Codex تقسيم المستند وأخذ كل جزء لوكيل فرعي مستقل، ليرسل كل منهم النقاط الهامة المستخلصة للمساعد الرئيسي لتظل المحادثة نظيفة.
الحدود العملية: متى يمنع تقسيم المهام؟
بعد توضيح فوائد الميزة، نعود للسؤال - لماذا يعد التقسيم العشوائي خاطئاً؟
لأن تشغيل الوكلاء الفرعيين يترتب عليه تكلفة مالية. وتؤكد الوثائق على: أن تشغيل كل وكيل فرعي يتطلب استهلاك حصص ونماذج ورموز (tokens) إضافية، مما يجعل تشغيل الوكلاء الفرعيين مكلفاً مقارنة بالعمل الفردي المعتاد. والتقسيم الزائد يزيد التكلفة والوقت. وهناك نقطة تقنية هامة - تشغيل العمليات بالتوازي للقراءة يختلف تماماً عن تشغيلها للكتابة وتعديل الملفات:
ينصح بحصر تشغيل الوكلاء بالتوازي في البداية على مهام القراءة وفحص الكود والاستكشاف وتلخيص الوثائق. وتطلب مهام التعديل والكتابة حذراً شديداً نظراً لمخاطر تداخل وتضارب التعديلات على نفس الملفات وزيادة تكلفة التنظيم.
يوضح الجدول التالي متى يفضل استخدام الميزة ومتى يجب تجنبها:
| طبيعة المهمة | هل يفضل استخدام الوكلاء الفرعيين؟ | الأسباب |
|---|---|---|
| الاستكشاف، تشغيل الاختبارات، قراءة السجلات، وتلخيص الوثائق (مهام القراءة التي ينتج عنها نصوص طويلة) | ✅ نعم، مناسب جداً | لإبعاد السجلات المزعجة عن المحادثة الرئيسية |
| عمليات فحص وبحث مستقلة ومختلفة (البحث في قاعدة البيانات، فحص الأمان، وقراءة واجهة برمجية معاً) | ✅ نعم، مناسب جداً | لتشغيل المهام بالتوازي واختصار الوقت |
| المهام البسيطة والمباشرة التي تعدل ملفاً واحداً واضحاً | ❌ لا، تجنب التقسيم | تشغيل الوكلاء يستهلك حصصاً ورموزاً إضافية دون حاجة |
| تعديل وكتابة كود في نفس الملفات بالتوازي | ⚠️ يحذر منه | لمخاطر تداخل وتضارب التعديلات وصعوبة التنسيق |
| عمليات متتالية تعتمد خطوتها التالية على اكتمال الخطوة السابقة | ⚠️ لا يفيد التقسيم | التشغيل بالتوازي يتطلب استقلالية المهام |
سيناريو واقعي: كنت أحاول إظهار الاحترافية سابقاً وطلبت تشغيل وكيل فرعي لتعديل "اسم دالة برمجية بسيطة". وكانت النتيجة إهدار الوقت والرموز مقارنة بطلب التعديل مباشرة من المساعد الرئيسي. وضعت لنفسي قاعدة: تجنب تقسيم المهام البسيطة والمباشرة التي تنجز برسالة واحدة.
💡 ملخص في جملة واحدة: يعالج الوكلاء الفرعيون مشكلتي "تلوث السياق وتراجع الأداء" بإبعاد المهام الطويلة عن المحادثة الرئيسية؛ وتجنب استخدامهم للمهام البسيطة أو التعديل المتداخل أو العمليات المتتالية لتفادي إهدار الحصص والرموز والمشاكل الفنية.
يوضح المخطط التالي مسار فحص وتحديد الحاجة للتقسيم:
توضح الرسمة خطوات اتخاذ القرار: فحص المهمة أولاً، فإذا كانت بسيطة أو متتالية تنجز في المحادثة الرئيسية؛ وإذا كانت كبيرة ومستقلة وتطلب موافقتك، يقوم Codex بتشغيل الوكلاء بالتوازي وينتظر اكتمال نتائجهم لتلخيصها وعرضها - وتذكر أن التقسيم يتطلب طلباً صريحاً منك.
03 ثلاثة وكلاء مدمجون في Codex وكيفية استدعائهم
بعد شرح المبادئ، نأتي للتطبيق. يوفر Codex ثلاثة وكلاء فرعيين مدمجين ومجهزين للعمل مباشرة دون حاجة لإعداد إضافي.
الوكلاء الثلاثة ووظائفهم:
| الوكيل المدمج | التخصص | المهام المناسبة |
|---|---|---|
default | وكيل عام متعدد الاستخدامات | عند رغبتك في تقسيم مهام عامة دون تخصيص |
worker | وكيل متخصص في التنفيذ والكتابة | لكتابة الأكواد، إصلاح الأخطاء، والمهام العملية |
explorer | وكيل متخصص في القراءة والاستكشاف | لتصفح الكود وفهمه، والبحث وتلخيص المستندات |
لتشغيل هؤلاء الوكلاء، تذكر القاعدة الذهبية: يحظر على Codex تقسيم المهام تلقائياً، ويجب كتابة طلب التقسيم صراحة في رسالتك. تنص الوثائق على ذلك:
لا يقوم Codex بتشغيل الوكلاء الفرعيين تلقائياً، ويتم تشغيلهم فقط عندما يطلب المستخدم ذلك صراحة.
لذا، لا تحتاج لصيغ أو أوامر معينة للاستدعاء، بل يكفي شرح التقسيم وكيفية توزيع العمل بوضوح في رسالتك. وتوصي الوثائق باستخدام عبارات مثل "spawn two agents" أو "delegate this work in parallel" أو "use one agent per point". ويجب أن تحدد الرسالة ثلاثة أمور: كيفية توزيع العمل، هل ينتظر اكتمال كل الوكلاء أولاً، وشكل الخلاصة المطلوبة.
مثال لكتابة الطلب باللغة العربية:
استخدم الوكلاء الفرعيين بالتوازي لمراجعة التغييرات الحالية ومقارنتها بفرع main. شغل وكيلين: الأول يركز على رصد المشاكل الأمنية والثاني يركز على كفاءة الأداء. وانتظر اكتمال عمل الوكيلين لتلخيص الملاحظات وعرضها لي بشكل مصنف مع تحديد أرقام السطور.بمجرد إرسال الرسالة، يتولى Codex إدارة العمليات في الخلفية - تشغيل الوكلاء وتوجيه المهام وانتظار اكتمالهم وإغلاق جلساتهم عند الانتهاء وعرض الملخص النهائي لك.
سيناريو واقعي: استخدمت الميزة لأول مرة لمراجعة PR كبير، ووزعت المهام على عدة نقاط فحص بالتوازي بناءً على الإرشادات الرسمية، وكانت النتيجة إنجاز الفحص بسرعة وتلقي ملخص منظم بوضوح مقارنة بطلب الفحص المتتالي. تكمن فائدة التشغيل بالتوازي في توفير أوقات الانتظار المتتالية.
⚠️ تنبيه بشأن الواجهة: تظهر حركة وتفاصيل عمل الوكلاء الفرعيين حالياً داخل تطبيق Codex وواجهة CLI، أما إضافات محرر الأكواد IDE فستدعم الميزة قريباً وفقاً للوثائق. لذا يفضل استخدام واجهة CLI أو تطبيق سطح المكتب لمراقبة عمل الوكلاء.
💡 ملخص في جملة واحدة: يوفر Codex ثلاثة وكلاء مدمجين (
defaultوworkerوexplorer) جاهزين للعمل؛ ويجب كتابة طلب التقسيم صراحة في رسالتك ليقوم Codex بتوزيع العمل وانتظار اكتمال الوكلاء وعرض الملخص النهائي.
04 إدارة جلسات الوكلاء النشطة
عند تشغيل عدة وكلاء بالتوازي، ستحتاج لمراقبة حركتهم والتبديل بينهم. يوفر Codex آليتين للتحكم.
الآلية الأولى: استخدام الأمر /agent للمراجعة والتبديل
استخدم الأمر المائل /agent (بصيغة المفرد) داخل واجهة CLI للتبديل بين جلسات الوكلاء النشطة ومراجعة ما يقوم به كل وكيل حالياً:
/agentتنبيه: هذا الأمر ليس مخصصاً لتشغيل الوكيل، بل مخصص للتبديل ومراجعة الجلسات النشطة. ويتم تشغيل الوكلاء بكتابة الطلب صراحة في رسالتك.
الآلية الثانية: التحكم والتوجيه بالرسائل
يمكنك مخاطبة Codex مباشرة باللغة الطبيعية لإدارة العمليات. تنص الوثائق على إمكانية: الطلب من Codex التحكم في وكيل معين، إيقافه، أو إغلاق جلسات الوكلاء التي انتهت مهامها. مثل الطلب منه "أوقف عمل الوكيل الثالث الخاص بفحص الأداء".
تشبيه: غرفة العمليات والتواصل عبر اللاسلكي. بينما يعمل المحققون في الميدان، يمكنك التبديل بين قنواتهم للاستماع لتقدم عملهم (عبر /agent)، أو مخاطبة أحدهم مباشرة عبر اللاسلكي لتوجيهه أو إلغاء مهمته (التحكم بالرسائل). وتظل قيادة وتوجيه العمليات في يدك دائماً.
ونشير لتفصيل هام يتعلق بالموافقات: عند استخدام واجهة CLI التفاعلية، قد تظهر نوافذ طلب الموافقة من وكيل فرعي يعمل في الخلفية. وإذا ظهر الطلب من وكيل آخر غير الذي تتابعه، فيمكنك الضغط على زر o للانتقال فوراً لجلسة هذا الوكيل ومراجعة سياق عمله قبل اتخاذ قرار الموافقة أو الرفض. وفي حال تشغيل المهام عبر السكربتات (غير التفاعلية)، فستفشل العمليات التي تتطلب موافقة تلقائياً ويتم إرسال الخطأ للمستويات الأعلى.
💡 ملخص في جملة واحدة: تدار الجلسات النشطة عبر أمر
/agentللتبديل ومراجعة تقدم الوكلاء، أو بمخاطبة Codex مباشرة لإيقاف أو توجيه وكيل معين؛ ويمكن الضغط علىoللانتقال لجلسة الوكيل الذي يطلب الموافقة لمراجعة سياقه.
05 تخصيص الوكلاء الفرعيين: كتابة ملف TOML وتحديد النماذج
تفي الخيارات المدمجة بالكثير من الاحتياجات، ولكن عند تكرار نفس المهام (مثل مراجعة الكود والتركيز على معايير الأمان وجودة الاختبارات)، يفضل تثبيت هذه الإرشادات في وكيل فرعي مخصص لتسهيل استدعائه مستقبلاً.
كيف تكتب الإعدادات: إنشاء ملف TOML (تنسيق بسيط لكتابة التكوينات يسهل قراءته للجميع) ووضعه في مجلد الوكلاء. وتوفر الوثائق موقعين لحفظ الملف:
| مسار الحفظ | نطاق عمل الوكيل | الاستخدام المناسب |
|---|---|---|
~/.codex/agents/ | يعمل في جميع مشاريعك | للوكلاء الذين تحتاجهم بانتظام في مختلف المشاريع |
.codex/agents/ | يقتصر على المشروع الحالي | لوكيل مخصص للمشروع الحسابي ويدخل في Git لمشاركته مع الفريق |
تشبيه: إعداد بطاقة هوية وتخصص للمحقق. الوكلاء المدمجون هم موظفو الشركة العامون؛ أما ملف TOML الذي تكتبه فهو ملف تعريف لمحقق مخصص تمنحه اسماً وتخصصاً وإرشادات عمل وأدوات ونموذج ذكاء محدد. وبمجرد إعداد الملف، يمكنك استدعاؤه باسمه مباشرة.
يتطلب ملف تعريف الوكيل كتابة ثلاثة حقول إلزامية فقط:
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""نوضح الحقول الأساسية لملف التعريف:
| الحقل | إلزامي | وظيفته | ملاحظات هامة |
|---|---|---|---|
name | نعم | الاسم الذي يستخدمه Codex للتعرف على الوكيل واستدعائه | يمثل معرف الهوية الأساسي، ويفضل مطابقة اسم الملف له |
description | نعم | شرح وظيفة ومهمة الوكيل ليقرأها المطورون | اكتب وظيفة الوكيل بوضوح لتسهيل التعرف عليه |
developer_instructions | نعم | الإرشادات والمعايير التي تحدد سلوك وعمل الوكيل | تمثل مهام وتعليمات العمل المخصصة له |
nickname_candidates | لا | قائمة الأسماء المستعارة لعرضها في الواجهة | عند تشغيل عدة نسخ من نفس الوكيل، تستخدم لتلوين واجهة العمل والتمييز بين الجلسات |
والمفاتيح الاختيارية الأخرى (مثل model و model_reasoning_effort و sandbox_mode و mcp_servers و skills.config) يتم وراثتها تلقائياً من الجلسة الرئيسية عند خلوها. وتوضح الوثائق أن ملفات تعريف الوكلاء تعد بمثابة ملفات تكوين إضافية، مما يتيح لك كتابة أي خيارات يدعمها ملف config.toml بداخلها. وتذكر قاعدة الأولويات: إذا تطابق اسم وكيلك المخصص مع اسم وكيل مدمج (مثل explorer)، فسيتم تطبيق إعدادات وكيلك المخصص وإلغاء المدمج.
تخصيص النماذج وقوة الاستدلال للوكلاء الفرعيين
تعد هذه الميزة الأهم للوكلاء المخصصين - حيث تتيح لك تخصيص النموذج الأنسب لكل مهمة:
model: تحديد النموذج. وتوصي الإرشادات بـ "استخدام نماذج سريعة للمهام البسيطة ونماذج قوية للمهام المعقدة" - فعمليات قراءة الملفات وفحص الكود تناسبها نماذج سريعة واقتصادية (مثلgpt-5.4-mini)؛ وعمليات مراجعة الأمان والتحقق من المنطق المعقد تتطلب نماذج قوية (مثلgpt-5.4أوgpt-5.5). واعتمد على النماذج المتاحة في حسابك حالياً.model_reasoning_effort: قوة وقوة تفكير واستدلال النموذج، وتوفر ثلاثة خيارات:
| الخيار | الاستخدام المناسب | التكلفة |
|---|---|---|
high | للمهام المعقدة التي تتطلب فحص الحدود ومراجعة الاحتمالات (وكيل الأمان والمراجعة) | أبطأ ويستهلك رموزاً أكثر، ولكنه يقدم جودة أعلى للمهام الصعبة |
medium | الوضع التلقائي المعتدل لمعظم المهام | معتدل |
low | للمهام البسيطة والمباشرة لإنجازها بسرعة | الأسرع |
لكتابة ملف تعريف لوكيل استكشافي مخصص (سريع، واقتصادي، وصلاحية للقراءة فقط):
قمنا باعتماد اسم النموذج gpt-5.4-mini ليكون متوافقاً مع الحسابات المعتادة:
# .codex/agents/explorer.toml —— وكيل استكشافي للقراءة فقط
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless asked.
"""لاحظ كتابة سطر sandbox_mode = "read-only" - وهذا يضمن تقييد صلاحيات الوكيل المخصص أمنياً بشكل صارم. فمهما حاول الوكيل تعديل الكود فلن يتمكن من ذلك لأن نظام بيئة المعزل تمنعه تلقائياً وتجعله للقراءة فقط.
⚠️ تذكر قاعدة الأولويات: إعدادات الجلسة المؤقتة التي تختارها أثناء العمل (مثل التعديل عبر
/permissionsأو تفعيل وضع--yolo) ستطبق وتتجاوز الإعدادات الثابتة المكتوبة في ملف تعريف الوكيل الفرعي.
ويمكنك ضبط خيارات الوكلاء العامة تحت قسم [agents] في ملف التكوين الرئيسي config.toml (وليس في ملف الوكيل الفردي):
| المفتاح العام | وظيفته | القيمة الافتراضية |
|---|---|---|
agents.max_threads | تحديد الحد الأقصى لعدد الوكلاء الفرعيين الذين يمكن تشغيلهم بالتوازي | عند خلوه يقتصر على 6 وكلاء |
agents.max_depth | تحديد الحد الأقصى لعمق تداخل الوكلاء (تبدأ الجلسة الرئيسية من 0) | افتراضياً 1 (يسمح بتشغيل وكلاء فرعيين للمساعد الرئيسي، ويمنع قيام الوكيل الفرعي بتشغيل وكلاء فرعيين له) |
agents.job_max_runtime_seconds | وقت الانتظار الأقصى لمهام الوكلاء عند استخدام ميزة فحص ملفات CSV بالتوازي | عند خلوه يقتصر على 1800 ثانية |
وتنصح الإرشادات بـ: إبقاء حد max_depth على القيمة الافتراضية 1 وتجنب زيادة تداخل الوكلاء. فرفع القيمة قد يسبب تشغيل عمليات متداخلة معقدة تستهلك الحصص والرموز وتزيد من أوقات الانتظار وموارد الجهاز دون فائدة حقيقية.
💡 ملخص في جملة واحدة: يكتب الوكيل المخصص في ملف TOML في المجلد
~/.codex/agents/أو.codex/agents/ويشترط كتابة حقولnameوdescriptionوdeveloper_instructions؛ ويمكن تخصيص نموذج وقوة استدلال مخصصة له، وتقييد صلاحياته أمنياً عبرsandbox_mode.
06 تدريب عملي: كتابة وكيل استكشافي مخصص وتجربته
نطبق معاً تدريباً عملياً متكاملاً: كتابة ملف تعريف لوكيل استكشافي مخصص للقراءة فقط ← تشغيل جلسة Codex ← استدعاء الوكيل لتفقد الكود ← والتحقق من التزامه بالصلاحيات ومنعه من الكتابة والتعديل.
سنقوم بإنشاء وكيل يسمى scout مخصص للاستكشاف وقراءة الملفات، ومقيد في وضع القراءة فقط لضمان الأمان (sandbox_mode = "read-only").
الخطوة الأولى: إنشاء مجلد التدريب ومجلد الوكلاء (لأنظمة Mac / Linux)
mkdir sub-demo
cd sub-demo
mkdir -p .codex/agentsالمتوقع: إنشاء المجلد sub-demo ويحتوي على مجلد الإعدادات الفرعي .codex/agents/. ويمكنك فحص المجلد بكتابة ls .codex.
لأنظمة Windows استخدم PowerShell:
mkdir sub-demo; cd sub-demo; mkdir .codex\agents -Force. واستبدل بقية الأوامر مثلechoوcatبأوامر PowerShell المناسبة.
الخطوة الثانية: كتابة ملف تعريف الوكيل المخصص
افتح محرر الأكواد، وأنشأ ملفاً جديداً في المسار sub-demo/.codex/agents/scout.toml واكتب بداخله:
name = "scout"
description = "وكيل استكشافي للقراءة فقط لفحص الملفات وتلخيص الأخطاء دون إجراء تعديلات."
sandbox_mode = "read-only"
model_reasoning_effort = "low"
developer_instructions = """
مهمتك الاستكشاف وقراءة الكود فقط دون إجراء أي تعديل على الملفات.
وعند استدعائك:
1. اقرأ الملف المحدد من قبل المستخدم.
2. لخص الملاحظات في ثلاثة أقسام: سهولة القراءة، التسميات، والمشاكل المحتملة.
3. قدم مقترحات للحلول، وتجنب تعديل أي ملف نهائياً.
واقتصر على تقديم ملخص بسيط ومباشر، وتجنب عرض محتويات الكود الطويلة.
"""لاحظ أننا لم نكتب حقل model ليرث النموذج الافتراضي للجلسة الرئيسية. وتم كتابة sandbox_mode = "read-only" لتقييده أمنياً، وكتابة model_reasoning_effort = "low" لتسريع عمل المهام الاستكشافية البسيطة.
الخطوة الثالثة: إنشاء ملف كود يحتوي على مشكلة للفحص
echo 'def f(a, b):
return a / b' > calc.pyتتميز الدالة بضعف التسميات (f و a و b) وغياب معالجة الخطأ عند القسمة على صفر - لتكون هدفاً مناسباً لفحص وكيلنا الاستكشافي.
الخطوة الرابعة: تشغيل Codex والطلب من الوكيل المخصص بدء العمل
codexاكتب الطلب صراحة مستدعياً الوكيل باسمه (تذكر قاعدة ضرورة الطلب صراحة لتفعيل التقسيم بالتوازي):
استخدم الوكيل الفرعي scout لفحص ملف calc.py، واطلب منه تقديم ملخص للمشاكل بناءً على إرشادات عمله دون إجراء أي تعديل للملف.المتوقع: سيقوم Codex بتشغيل الوكيل scout في جلسة مستقلة (وستشاهد مؤشرات تشغيل الوكيل وتسميته في الواجهة). وسيتولى قراءة ملف calc.py بشكل معزول ومستقل، ثم يرسل لك ملخصاً بالنقاط الأساسية فقط - ليوضح مثلاً ضرورة تعديل أسماء الدالة والمعاملات وإضافة معالجة القسمة على صفر. وتلاحظ أن الملف يظل كما هو دون تعديل. ويمكنك مراجعة تقدم عمله أثناء الجلسة بكتابة /agent.
الخطوة الخامسة: التحقق من عدم تعديل الملف
اخرج من جلسة Codex، وراجع محتويات ملف الكود:
cat calc.py(لأنظمة Windows PowerShell استخدم type calc.py)
المتوقع: بقاء ملف calc.py كما هو دون تغيير - وهذا يثبت فاعلية قيود الأمان لبيئة المعزل: فحتى لو حاول الوكيل تعديل الملف، فإن تحديد صلاحياته كـ read-only تمنعه تماماً وتجعل عمله مقتصراً على القراءة وتقديم التقارير.
بإتمام هذه الخطوات الخمس، تكون قد تحققت عملياً من مسار عمل الوكلاء الفرعيين بالكامل: كتابة ملف تعريف الوكيل المخصص ← طلب تشغيل الوكيل صراحة ← إدارة وحفظ سياق العمل بشكل مستقل ← والالتزام بالصلاحيات الأمنية المفروضة.
⚠️ إذا لم يقم Codex بتشغيل الوكيل scout وقام بمعالجة الملف بنفسه في المحادثة الرئيسية، فتأكد من صياغة رسالتك بوضوح وطلب تشغيل الوكيل المخصص بالاسم صراحة لتفعيل الميزة.
💡 ملخص في جملة واحدة: خطوات التدريب هي: إنشاء ملف تعريف الوكيل scout كـ
read-only← إنشاء ملف كود اختبار ← الطلب من الوكيل فحص الكود صراحة ← والتأكد من تقديم الملخص وبقاء كود الاختبار دون تعديل؛ لفهم أسلوب عزل وسياق وصلاحيات الوكلاء الفرعيين.
07 ميزة إضافية: فحص ملفات CSV بالتوازي (ميزة تجريبية)
⚠️ تصف الوثائق ميزة تشغيل الوكلاء لمعالجة ملفات CSV كـ ميزة تجريبية قد تتغير مع تحديثات البرمجيات - ونذكرها هنا للعلم بوجودها وتجنب الاعتماد عليها كأداة أساسية مستقرة حالياً.
إذا واجهت مجموعة كبيرة من المهام المتشابهة - مثل "فحص قائمة طويلة من الملفات، أو مراجعة مجموعة من PRs، أو إدارة مهام نقل كود متشابهة" بالتتابع - فيوفر Codex ميزة spawn_agents_on_csv: حيث يقوم بقراءة ملف CSV، ويقوم بتشغيل وكيل فرعي مستقل لكل سطر في الملف بالتوازي، وعند انتهاء المهمة يجمع النتائج ويصدرها في ملف CSV جديد.
تشبيه: خط الفرز والتعبئة التلقائي. تصل البضائع (كل سطر في ملف CSV يمثل بضاعة)، ويتولى مجموعة من العمال (الوكلاء المساعدون) فحص وتصنيف المنتجات في نفس الوقت، ويتم جمع البيانات النهائية في جدول واحد. ويشترط على كل وكيل استدعاء دالة report_agent_job_result لمرة واحدة بدقة لتسجيل نتيجته، وبدون ذلك يتم تعليم السطر كخطأ في ملف المخرجات. لمزيد من التفاصيل والخيارات راجع المستندات الرسمية لـ Codex.
يوضح الجدول التالي متى يفضل استخدام ميزة فحص ملفات CSV:
| السيناريو | هل تناسبه ميزة فحص CSV بالتوازي؟ | الأسباب |
|---|---|---|
| مراجعة وفحص عشرات من PRs المتشابهة في البنية | ✅ نعم، مناسبة جداً | لتشغيل نفس المهام البرمجية بالتوازي واختصار الوقت |
| ترجمة التعليقات البرمجية لعشرات من الملفات المستقلة | ✅ نعم، مناسبة جداً | استقلالية الملفات والسطور تجعلها مثالية للفحص بالتوازي |
| مهام متتالية تعتمد خطوتها التالية على نتائج السطر السابق | ❌ لا، تجنب استخدامها | يتم تشغيل أسطر CSV بالتوازي ولا يضمن ترتيب معالجتها |
| مهام فحص لعدد قليل جداً من الملفات (3 أو 4 ملفات) | ❌ لا، تجنب استخدامها | إعداد ملفات CSV والتشغيل التجريبي يستهلك وقتاً أطول من طلب الفحص المباشر |
| عمليات تعديل متداخلة على نفس الملفات | ⚠️ يحذر منه | لمخاطر تداخل وتضارب التعديلات بين الوكلاء |
💡 ملخص في جملة واحدة: تصلح ميزة
spawn_agents_on_csv(التجريبية) للمهام التكرارية المتشابهة والمستقلة التي تطبق على أعداد كبيرة من الملفات أو المهام؛ وتجنب استخدامها للمهام المتتالية أو الأعداد القليلة أو مهام التعديل المتداخل.
08 ملخص
شرحنا في هذا المقال نظام الوكلاء الفرعيين (Subagents) في Codex - وكيفية تقسيم المهام وتوزيعها للعمل بالتوازي، والحدود الفاصلة والعملية للتقسيم، وكتابة وتأمين الوكلاء المخصصين.
دعنا نلخص النقاط الأساسية معاً بشكل سريع:
| الجانب | المفهوم الأساسي | نقاط هامة |
|---|---|---|
| مفهوم الوكيل الفرعي | مساعد متخصص يعمل في جلسة عمل مستقلة (thread) | يعمل بالتوازي، ويرسل الخلاصة والنتائج للمساعد الرئيسي لتجنب السجلات الطويلة |
| المشاكل المعالجة | تلوث السياق وتراجع الأداء | إبعاد السجلات والعمليات الفنية المزعجة عن المحادثة الرئيسية |
| الحدود العملية | متى يتجنب التقسيم | في المهام البسيطة والمباشرة، عمليات التعديل المتداخل، والعمليات المتتالية لتفادي إهدار الحصص والرموز |
| كيفية الاستدعاء | الطلب صراحة من المستخدم | يحظر تشغيل الوكلاء تلقائياً، ويجب كتابة طلب التقسيم والتوزيع صراحة في رسالتك |
| الوكلاء المدمجون | ثلاثة خيارات جاهزة | وكيل default للمهام العامة، و worker للتنفيذ والكتابة، و explorer للاستكشاف والقراءة |
| الوكلاء المخصصون | كتابة ملف TOML | يكتب في المجلد ~/.codex/agents/ أو .codex/agents/ ويشترط حقول name و description و developer_instructions |
| تخصيص النماذج | توزيع النماذج أمنياً ومالياً | استخدام نماذج سريعة واقتصادية للاستكشاف، ونماذج قوية ذات استدلال عالٍ للمراجعة، وتقييد الصلاحيات أمنياً |
يجب أن تكون الآن قادراً على: تقييم المهام وتحديد ما يناسب تقسيمها للعمل بالتوازي وما يجب معالجته في المحادثة الرئيسية؛ واستدعاء الوكلاء المدمجين الثلاثة في رسائلك؛ وإنشاء ملفات تعريف لوكلاء مخصصين وتحديد نماذج وصلاحيات مستقلة لهم؛ ومراقبة وتوجيه الجلسات النشطة بأمر /agent. هذا التقسيم والتنسيق للمهام هو ما يتيح لك إدارة المشاريع البرمجية الكبيرة بالاستعانة بفرقة عمل متكاملة يقودها Codex.
تذكر دائماً القاعدة الأمنية والعملية: تظل قيادة وتوزيع العمليات وإدارة الصلاحيات في يدك دائماً، ولا يقوم Codex باتخاذ قرار التقسيم والتشغيل بالتوازي إلا بطلب صريح ومحدد منك.
المقال التالي [22 · مهارات الوكيل (Skills)] - ساعدنا الوكلاء الفرعيون على تنظيم وسياق العمل للمشاريع الكبيرة، ولكن قد تجد نفسك تكرر كتابة إرشادات العمل الطويلة developer_instructions عند إعداد كل وكيل مخصص. ماذا لو تمكنا من حزم وتغليف هذه الإرشادات والمهام البرمجية في مهارة برمجية مكررة وقابلة للاستدعاء (Skill) بكلمة واحدة لتسهيل العمل؟ سنتحدث في المقال القادم عن تفاصيل مهارات الوكيل وكيفية بنائها واستدعائها لتسهيل وتطوير وسرعة العمل.