كيف تبني نظام وكلاء متعددين: دليل عملي إلى نمط supervisor

بعد أن استوعبت مفهوم «تنسيق عدة نماذج ذكاء اصطناعي» في مقال ما هو نظام الوكلاء المتعددين؟، يأتي السؤال التالي: كيف تبني واحداً فعلياً. يشرح هذا المقال للمبتدئين عملية عملية من 5 خطوات، باستخدام المعيار الفعلي لعام 2026: نمط supervisor (المنسّق المركزي).

قبل الحديث عن أي إطار عمل، إليك أهم مبدأ: «ابنِ بوكيل واحد أولاً، ولا تضِف وكلاء — وبأقل قدر ممكن — إلا بعد أن تصطدم بحدّ فعلي.» البدء بعدد كبير من الوكلاء منذ اليوم الأول غالباً ما يكون إفراطاً في الهندسة. في النصف الثاني ستجد شيفرة مصغّرة مقروءة تتبع الوثائق الرسمية لـ Claude Agent SDK وOpenAI Agents SDK، إلى جانب طريقة تقسيم الأدوار والإخفاقات التي تحدث فعلاً. والمنطق نفسه ينطبق إذا ربطت الأدوات عبر MCP.

ملاحظة: كُتبت الشيفرة وفق الوثائق الرسمية لـ Claude Agent SDK وOpenAI Agents SDK (تحقّقنا منها في 4 أكتوبر 2026). تتغيّر هذه الحزم بسرعة، فتحقّق من أسماء المعاملات في الوثائق الرسمية قبل التشغيل. كل رقم في المقال مذكور مصدره.

1. قبل البناء: هل تحتاج فعلاً إلى نظام متعدد؟

البوابة الأولى ليست تقنية — بل هي قرار تقديري. نظام الوكلاء المتعددين قوي، لكنه لا يفيد في كل عمل. إذا لم تنطبق أيٌّ من النقاط التالية، فابنِ بـوكيل واحد أولاً.

وعلى العكس، وكما ذكرنا في المقال السابق، فإن استخدام نظام متعدد لعملية أحادية المسار يكلّفك. في دراسة من Google Research (نُشرت في يناير 2026 وقارنت 180 تكويناً)، جاءت جميع تكوينات الوكلاء المتعددين المختبرة أسوأ من الوكيل الواحد بنسبة 39–70% في مهمة تتطلب استدلالاً تسلسلياً صارماً (PlanCraft). وترتفع التكلفة أيضاً: تذكر Anthropic في شرحها لوكيل البحث الخاص بها أن الوكلاء يستهلكون نحو 4 أضعاف رموز المحادثة العادية، وأنظمة الوكلاء المتعددين نحو 15 ضعفاً. انطلِق من فرضية أن «المزيد من الوكلاء لا يعني ذكاءً أكبر».

2. الشكل الأساسي: نمط supervisor

إذا لم تكن متأكداً من النمط الذي ستبنيه، فالبدء بـنمط supervisor هو الخيار الآمن. تصفه الحزم الرئيسية في وثائقها نمطاً أساسياً. في Claude Agent SDK يستدعي الوكيلُ الرئيسي الوكلاءَ الفرعيين عبر أداة Agent، وفي OpenAI Agents SDK يقابله نمط «agents as tools»، حيث يستدعي وكيلٌ مدير الوكلاءَ المتخصصين كأدوات.

الآلية بسيطة. يتلقى الـ supervisor المهمة الكلية، ويقسّمها إلى مهام فرعية، ويفوّضها إلى workers متخصصين، ثم يجمّع النتائج. لا يحتاج الـ supervisor إلى معرفة كيف ينجز الـ worker عمله — بل فقط أيّ worker يستدعي وبأيّ صيغة إخراج. الخبرة تكمن في الـ workers.

انتبه: في OpenAI Agents SDK يحمل التسليم (handoff) معنى أضيق من تمرير العمل عموماً في الخطوة 4: يسلّم وكيل الفرز المحادثة نفسها إلى وكيل متخصص، يتولّى بعدها الرد على المستخدم مباشرة. لا يبقى supervisor هنا، لذا تعامل معه كنمط مختلف عن نمط supervisor (القسم 6 يشرح متى تختار كلاً منهما).

3. ابنه في 5 خطوات

جمّع إعداد supervisor بالحد الأدنى في خمس خطوات. القاعدة العملية: ابدأ بـ2-3 workers، ثم أضِف المزيد فقط عندما يبرّر القياس ذلك.

4. أصغر شيفرة ①: Claude Agent SDK (Python)

أولاً، نبني supervisor واحداً واثنين من الـ workers (باحث ومراجع) باستخدام Claude Agent SDK من Anthropic. التحضير هو فقط pip install claude-agent-sdk ومتغير البيئة ANTHROPIC_API_KEY (دليل البدء الرسمي؛ لا تقرأ الحزمة ملفات .env تلقائياً). تتبع الشيفرة صفحة Subagents الرسمية. وللحزمة ككل، راجع دليل Claude Agent SDK.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

options = ClaudeAgentOptions(
    model="claude-opus-5-5",  # الـ supervisor (الوكيل الرئيسي)
    system_prompt=(
        "You coordinate a research report. Delegate research to researcher and fact-checking "
        "to reviewer, and write the final text yourself. When delegating, always state the "
        "goal, the output format, and the scope."
    ),
    allowed_tools=["Agent", "WebSearch", "WebFetch"],  # أدوات تعمل دون طلب إذن
    agents={
        "researcher": AgentDefinition(
            description="Gathers primary sources. Use when facts or figures are needed.",
            prompt="Find primary sources for the question and return bullet points with source URLs. Never fill gaps with guesses.",
            tools=["WebSearch", "WebFetch"],  # الأدوات الوحيدة لهذا الدور
            model="sonnet",
            maxTurns=15,
        ),
        "reviewer": AgentDefinition(
            description="Fact-checks drafts. Always use before finalizing text.",
            prompt="Check each claim in the draft against its source and list every sentence that lacks support.",
            tools=["WebFetch"],
            model="sonnet",
            maxTurns=10,
        ),
    },
    max_turns=30,         # حد الدورات للتشغيل كله
    max_budget_usd=5.0,   # حد الإنفاق (تقدير الحزمة)
    env={"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"},  # لا ينشئ الـ workers وكلاء فرعيين
)


async def main():
    try:
        async for message in query(
            prompt="Find three official statistics on workplace use of generative AI and write a short report",
            options=options,
        ):
            if isinstance(message, ResultMessage):
                print(message.subtype, message.total_cost_usd)
                print(message.result)
    except Exception as error:
        print(f"Stopped early: {error}")  # بلوغ أي حد ينتهي هنا أيضاً


asyncio.run(main())

خمس نقاط ينبغي الانتباه إليها:

• توضع الـ workers في agents كمدخلات AgentDefinition. يقرأ الـ supervisor حقل description لكل worker ليقرّر من يستدعي ومتى، لذا صِف بدقة ما يفعله الدور ومتى يُستخدم.
• عندما تسرد tools، لا يملك الدور إلا تلك الأدوات. لهذا لا يملك المراجع أدوات كتابة. أما allowed_tools فهي قائمة الأدوات التي تعمل دون طلب إذن، ولا تقيّد شيئاً (مرجع Python الرسمي).
• ضع الحدود في ثلاثة مواضع. maxTurns لكل دور، وmax_turns للتشغيل كله، وحدّ الإنفاق max_budget_usd. عند بلوغ حدّ عام يصبح النوع الفرعي للنتيجة error_max_turns أو error_max_budget_usd ويتوقف التشغيل (شرح حلقة الوكيل).
• أوقِف التداخل. يمكن للوكلاء الفرعيين إنشاء وكلاء فرعيين خاصين بهم. إذا ضبطت متغير البيئة CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH على 1، أنجز الـ workers العمل بأنفسهم. ويحدّ CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (القيمة الافتراضية 20) عدد ما يعمل في الوقت نفسه.
• أسماء حقول AgentDefinition بصيغة camelCase. كتابة max_turns بدل maxTurns تُطلق TypeError عند الإنشاء (ملاحظة رسمية). يستخدم الـ supervisor النموذج الحالي claude-opus-5-5، ويستخدم الـ workers الاسم المستعار "sonnet" كي تبقى الشيفرة صالحة عند صدور إصدار جديد.

تشير الوثائق الرسمية إلى أن Opus 5 يفوّض إلى الوكلاء الفرعيين بسهولة أكبر من النماذج السابقة، وتوصي بوضع حدود للعمق والتزامن والإنفاق إلى جانب التعليمات في الموجّه. التعليمات تغيّر فقط طريقة طلب Claude للمساعدة؛ أما الحدود فهي وحدها ما يوقف التشغيل بثقة.

5. أصغر شيفرة ②: OpenAI Agents SDK (Python)

في Agents SDK من OpenAI، يُبنى الشكل نفسه بتحويل الوكلاء المتخصصين إلى أدوات عبر as_tool() وتمريرها إلى tools الخاصة بالـ supervisor (قسم agents as tools الرسمي). التحضير هو pip install openai-agents ومتغير البيئة OPENAI_API_KEY (دليل البدء الرسمي). إذا حذفت model استُخدم النموذج الافتراضي للحزمة، وهذا الافتراضي يتغيّر بين الإصدارات، فتحقّق منه في صفحة Models.

import asyncio
from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    instructions="Find primary sources for the question and return bullet points with source URLs. Never fill gaps with guesses.",
    tools=[WebSearchTool()],
)
reviewer = Agent(
    name="Reviewer",
    instructions="Check each claim in the draft you receive against its source and list every sentence that lacks support.",
)

manager = Agent(
    name="Manager",
    instructions=(
        "You coordinate a research report. Delegate research to research and fact-checking "
        "to review, and write the final text yourself."
    ),
    tools=[
        researcher.as_tool(
            tool_name="research",
            tool_description="Gather primary sources with citations",
            max_turns=10,  # حد الدورات لهذا الدور
        ),
        reviewer.as_tool(
            tool_name="review",
            tool_description="Fact-check a draft",
        ),
    ],
)


async def main():
    result = await Runner.run(
        manager,
        input="Find three official statistics on workplace use of generative AI and write a short report",
        max_turns=10,  # تجاوزه يُطلق MaxTurnsExceeded
    )
    print(result.final_output)


asyncio.run(main())

ما تشترك فيه الحزمتان وما تختلفان فيه:

• لا يعرف الـ worker محادثة الوكيل الأب. الوكيل المستدعى عبر as_tool() لا يرث تلقائياً حالة محادثة التشغيل الأب (الوثائق الرسمية). والأمر نفسه في Claude Agent SDK: كل ما يتلقاه الوكيل الفرعي من الأب هو نص التكليف في أداة Agent. اكتب مسارات الملفات ورسائل الخطأ والقرارات المتخذة داخل التكليف نفسه.
• الحد هو Runner.run(..., max_turns=). عند تجاوزه يُطلَق MaxTurnsExceeded. وبتمرير error_handlers={"max_turns": ...} يمكنك إعادة رد محدد مسبقاً بدلاً من الاستثناء (Running agents).
• مع التسليم ستكتب Agent(..., handoffs=[billing_agent, refund_agent]). يتولّى الوكيل المستلِم المحادثة، ويرى افتراضياً سجلّها السابق كاملاً. إن كانت هناك معلومات لا ينبغي أن تصله، فقيّدها بـ input_filter.

6. كيف تقسّم الأدوار: تقسيم جيد وتقسيم سيئ

تقسيم الأدوار أصعب من الشيفرة. تكتب Anthropic أن كل وكيل فرعي يحتاج إلى هدف، وصيغة إخراج، وإرشاد إلى الأدوات والمصادر التي يستخدمها، وحدود واضحة للمهمة (الشرح نفسه). إليك تقسيمات تستوفي هذه الشروط الأربعة وأخرى لا تستوفيها.

ويقدّم الشرح نفسه دليلاً لعدد الوكلاء. أدرجت Anthropic قواعد للحجم في موجّه الـ supervisor لوكيل البحث لديها: البحث البسيط عن حقيقة يحتاج إلى وكيل واحد مع 3–10 استدعاءات للأدوات، والمقارنة المباشرة إلى 2–4 وكلاء فرعيين مع 10–15 استدعاءً لكل منهم، وقد يستخدم البحث المعقّد أكثر من 10 وكلاء فرعيين. هذه أرقام لعمل بحثي، فابدأ في عملك من الطرف الأصغر ولا تُضِف إلا بعد القياس.

للاختيار بين supervisor والتسليم، تعطي وثائق OpenAI معياراً واضحاً. إذا أردت أن يملك وكيل واحد الإجابة النهائية أو أن تجمع نتائج عدة متخصصين، فاستخدم supervisor (agents as tools). وإذا كان التوجيه هو العمل نفسه، وكان على المتخصص المختار أن يرد على المستخدم مباشرة (مثل فرز طلبات الدعم)، فاستخدم التسليم. ويمكن الجمع بينهما.

7. إخفاقات شائعة وحلولها

مواضع التعثّر متوقعة. فيما يلي إخفاقات تقول Anthropic إنها حدثت فعلاً مع وكيل البحث لديها، والنقاط التي تحذّر منها الوثائق الرسمية للحزمتين.

الدرس المشترك: «الموجّهات وتصميم الأدوات وحزمة التقييم تحدد النجاح أكثر مما يحدده إطار العمل.» وتذكر وثائق OpenAI بدورها الاستثمار في موجّهات جيدة، والمراقبة والتحسين المتكرر، والوكلاء المتخصصين، والتقييم. فوق البنية المبهرة، فإن انضباط البناء على نطاق صغير، والقياس، والإضافة فقط عندما تكون مجدية هو الأسرع في نهاية المطاف.

الخلاصة

بناء نظام وكلاء متعددين ليس مخيفاً إذا بدأت بـنمط supervisor من إعداد بالحد الأدنى. لنُلخّص.

«ابنِ صغيراً، قِس، ثم أضِف». التزِم بهذا الانضباط ويصبح نظام الوكلاء المتعددين شريكاً قوياً للأعمال المعقدة. للاطّلاع على المفهوم، راجع ما هو نظام الوكلاء المتعددين؟؛ ولبناء وكيل واحد، راجع كيف تبني وكيل ذكاء اصطناعي.

الأسئلة الشائعة