إنشاء أنظمة متعددة الوكلاء باستخدام ADK

1. مقدمة

نظرة عامة

يعلّمك هذا المختبر كيفية تنسيق الأنظمة المعقّدة والمتعدّدة الوكلاء باستخدام مجموعة أدوات تطوير الوكلاء من Google (Google ADK). ستنتقل من تسلسل الوكلاء البسيط إلى إنشاء مهام سير عمل تعاونية ومؤتمتة.

ما ستنشئه

ستنشئ نظامَين مختلفَين يستندان إلى عدّة وكلاء:

  • وكيل بسيط للتخطيط للسفر يتعلّم نقل المحادثات بين وكيل "تبادل الأفكار" ووكيل "التخطيط لزيارة المعالم السياحية"
  • مولّد أكثر تقدّمًا لاقتراحات الأفلام يستخدم "غرفة كتابة" من الوكلاء الآليين (مثل باحث وكاتب سيناريو وناقد) للعمل معًا في حلقة مكررة لإنشاء حبكة فيلم كاملة

أهداف الدورة التعليمية

  • كيفية إنشاء علاقات بين حساب رئيسي وحسابات فرعية
  • كيفية كتابة البيانات في الجلسة state من إحدى الأدوات
  • كيفية القراءة من state باستخدام نماذج المفاتيح (مثل {my_key?}).
  • كيفية استخدام SequentialAgent لمهام سير العمل المفصّلة
  • كيفية استخدام LoopAgent لإنشاء دورات تحسين متكرّرة
  • كيفية استخدام ParallelAgent لتنفيذ مهام مستقلة في الوقت نفسه

2. الأنظمة المتعددة الوكلاء

تتيح حزمة تطوير الوكلاء (ADK) للمطوّرين الحصول على سلوكيات أكثر موثوقية وتطوّرًا ومتعددة الخطوات من النماذج التوليدية. بدلاً من طلب معقّد واحد، تتيح لك "مجموعة أدوات تطوير التطبيقات" إنشاء سلسلة من الوكلاء المتعدّدين والأبسط الذين يتعاونون في حلّ مشكلة ما من خلال تقسيم العمل.

يتميّز هذا الأسلوب بعدة مزايا مقارنةً باستخدام طلب واحد وشامل:

  • تصميم أبسط: من الأسهل تصميم وتنظيم سلسلة من العملاء الصغار المتخصصين بدلاً من تصميم طلب كبير ومعقّد.
  • الموثوقية: تكون الوكلاء المتخصّصون أكثر موثوقية في مهامهم المحدّدة من وكيل واحد كبير ومعقّد.
  • سهولة الصيانة: من الأسهل إصلاح أو تحسين وكيل صغير ومتخصّص بدون إتلاف أجزاء أخرى من النظام.
  • التصميم المعياري: يمكن بسهولة إعادة استخدام الوكلاء المصمَّمين لسير عمل واحد في عمليات أخرى.

شجرة الوكلاء الهرمية

بنية شجرية تعرض العملاء الهرميين

في "مجموعة أدوات Android"، يمكنك تنظيم البرامج في بنية شجرية. يُعدّ هذا التسلسل الهرمي أساسيًا للتحكّم في سير المحادثة، لأنّه يحدّد الموظّف الذي يمكنه "نقل" المحادثة إلى موظّف آخر. ويجعل ذلك سلوك النظام أكثر قابلية للتوقّع وأسهل في تصحيح الأخطاء. تشمل المزايا ما يلي:

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

تبدأ البنية بأكملها بـ root_agent. يعمل هذا العنصر كـ عنصر رئيسي ويمكن أن يتضمّن عنصرًا فرعيًا واحدًا أو أكثر، ويمكن أن تكون العناصر الفرعية بدورها عناصر رئيسية لعناصر فرعية أخرى، ما يؤدي إلى تكوين الشجرة.

3- إعداد المشروع

حساب Google

إذا لم يكن لديك حساب شخصي على Google، عليك إنشاء حساب على Google.

استخدام حساب شخصي بدلاً من حساب تابع للعمل أو تديره مؤسسة تعليمية

تسجيل الدخول إلى Google Cloud Console

سجِّل الدخول إلى Google Cloud Console باستخدام حساب Google شخصي.

تفعيل الفوترة

تحصيل قيمة رصيد Google Cloud بقيمة 5 دولار أمريكي (اختياري)

لإجراء ورشة العمل هذه، تحتاج إلى حساب فوترة يتضمّن بعض الرصيد. إذا كنت تخطّط لاستخدام نظام الفوترة الخاص بك، يمكنك تخطّي هذه الخطوة.

  1. انقر على هذا الرابط وسجِّل الدخول باستخدام حساب Google شخصي.سيظهر لك ما يلي:انقر هنا للانتقال إلى صفحة الأرصدة
  2. انقر على الزر انقر هنا للوصول إلى رصيدك.سينقلك هذا الزر إلى صفحة لإعداد ملف الفوترةصفحة إعداد ملف الفوترة
  3. انقر على تأكيد.

أنت مرتبط الآن بحساب فوترة تجريبي على Google Cloud Platform.

لقطة شاشة لنظرة عامة على الفوترة

إعداد حساب فوترة شخصي

إذا أعددت الفوترة باستخدام أرصدة Google Cloud، يمكنك تخطّي هذه الخطوة.

لإعداد حساب فوترة شخصي، يُرجى الانتقال إلى هنا لتفعيل الفوترة في Cloud Console.

ملاحظات:

  • يجب أن تكلّف إكمال هذا المختبر أقل من دولار أمريكي واحد من موارد السحابة الإلكترونية.
  • يمكنك اتّباع الخطوات في نهاية هذا المختبر لحذف الموارد وتجنُّب المزيد من الرسوم.
  • يمكن للمستخدمين الجدد الاستفادة من الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

إنشاء مشروع (اختياري)

إذا لم يكن لديك مشروع حالي تريد استخدامه لهذا التصنيف، يمكنك إنشاء مشروع جديد هنا.

4. فتح Cloud Shell Editor

  1. انقر على هذا الرابط للانتقال مباشرةً إلى محرّر Cloud Shell
  2. إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على منح الإذن للمتابعة.انقر لتفويض Cloud Shell
  3. إذا لم تظهر المحطة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
    • انقر على عرض.
    • انقر على Terminalفتح نافذة طرفية جديدة في "محرِّر Cloud Shell"
  4. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
    gcloud config set project [PROJECT_ID]
    • مثال:
      gcloud config set project lab-project-id-example
    • إذا تعذّر عليك تذكُّر معرّف مشروعك، يمكنك إدراج جميع معرّفات المشاريع باستخدام:
      gcloud projects list
      ضبط رقم تعريف المشروع في نافذة Cloud Shell Editor
  5. من المفترض أن تظهر لك هذه الرسالة:
    Updated property [core/project].

5- تفعيل واجهات برمجة التطبيقات

لاستخدام Vertex AI API والتفاعل مع نموذج Gemini، عليك تفعيل Vertex AI API في مشروعك على Google Cloud.

  1. في الوحدة الطرفية، فعِّل واجهة برمجة التطبيقات:
    gcloud services enable aiplatform.googleapis.com

في ما يلي الأقسام المعدَّلة التي تستبدل عملية إنشاء الملف يدويًا بتعليمات لاستنساخ مستودع GitHub وتثبيت التبعيات.

مقدمة عن حزمة تطوير البرامج (SDK) لخدمة Vertex AI في Python

للتفاعل مع النماذج المستضافة على Vertex AI من تطبيق Python، عليك استخدام حزمة تطوير البرامج (SDK) الخاصة بمنصة Vertex AI للغة Python. تُبسّط حزمة تطوير البرامج هذه عملية إرسال الطلبات وتحديد مَعلمات النموذج وتلقّي الردود بدون الحاجة إلى التعامل مع تعقيدات طلبات واجهة برمجة التطبيقات الأساسية مباشرةً.

يمكنك العثور على مستندات شاملة حول حزمة تطوير البرامج (SDK) الخاصة بـ Vertex AI في Python هنا: مقدمة عن حزمة تطوير البرامج (SDK) الخاصة بـ Vertex AI في Python | Google Cloud.

6. إعداد بيئة المشروع

إنشاء نسخة طبق الأصل من المستودع

  1. في وحدة التحكّم، استنسِخ المستودع الذي يحتوي على ملفات البداية.
    git clone --depth 1 https://github.com/GoogleCloudPlatform/devrel-demos.git
    لا تنسخ العلامة --depth 1 سوى أحدث إصدار، ما يجعل العملية أسرع.
  2. في الوحدة الطرفية، انتقِل إلى دليل العمل الصحيح لهذا الدرس التطبيقي.
    cd devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems

تفعيل بيئة افتراضية

  1. في وحدة التحكّم، أنشئ بيئة افتراضية وفعّلها باستخدام uv:
    uv venv
source .venv/bin/activate
  2. في وحدة التحكّم، ثبِّت google-adk والعناصر التابعة الأخرى من ملف requirements.txt:
    uv pip install -r requirements.txt

مراجعة بنية الملف

بعد إنشاء جميع ملفاتك، افتح المجلد adk_multiagent_systems في المستكشف للاطّلاع على البنية الكاملة.

  1. في قائمة "محرّر Cloud Shell"، اختَر ملف > فتح مجلد....
    قائمة "ملف" في Cloud Shell Editor مع تحديد "فتح مجلد"
  2. في المربّع الذي يظهر، أضِف معلومات المجلد التالية بعد اسم المستخدم: devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems/. انقر على حسنًا.
    من المفترض أن يظهر بالشكل التالي:
    فتح مربّع الحوار "فتح المجلد" مع مسار المشروع
  3. سيتم إعادة تحميل لوحة "المستكشف" على اليمين. من المفترض أن تظهر لك الآن بنية مشروعك الكاملة، مع الدليلَين الفرعيَين parent_and_subagents وworkflow_agents، لتكون جاهزًا للخطوات التالية.
    لوحة Explorer (المستكشف) التي تعرض مجلد adk_multiagent_systems المفتوح

إعداد المتغيرات البيئية

  1. أنت حاليًا في دليل adk_multiagent_systems. في وحدة التحكّم، أنشئ ملف .env لتخزين متغيرات البيئة:
    cloudshell edit .env
  2. الصِق ما يلي في ملف .env الذي يفتح في المحرِّر:
    GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT="[YOUR-PROJECT-ID]"
GOOGLE_CLOUD_LOCATION=global
MODEL="gemini-2.5-flash"
  3. استبدِل [YOUR-PROJECT-ID] برقم تعريف مشروع Google Cloud الفعلي. (مثلاً PROJECT_ID = "google-cloud-labs")
    إذا لم تتمكّن من تذكُّر رقم تعريف مشروعك، نفِّذ الأمر التالي في الوحدة الطرفية. ستظهر لك قائمة بجميع مشاريعك وأرقام تعريفها.
    gcloud projects list
  4. في نافذة الأوامر، انسخ ملف .env هذا إلى أدلة الوكلاء الفرعيين حتى يتمكّنوا أيضًا من الوصول إلى المتغيرات:
    cp .env parent_and_subagents/.env
cp .env workflow_agents/.env
    يجب أن تبدو بنية الملف الآن على النحو التالي:
    لوحة Explorer (المستكشف) التي تعرض مجلد adk_multiagent_systems المفتوح

7. استكشاف عمليات النقل بين الوكيل الرئيسي والوكيل الفرعي والوكلاء النظراء

تبدأ المحادثة دائمًا بـ root_agent. تستخدم وكالة رئيسية بشكلٍ تلقائي description الوكالات الفرعية لتحديد الوقت المناسب لنقل المحادثة. يمكنك أيضًا توجيه عمليات النقل هذه بشكل صريح في instruction الخاص بالوكيل الرئيسي باستخدام name الخاص بالوكلاء الفرعيين.

لنجرّب ذلك.

  1. في "محرِّر Cloud Shell"، افتح adk_multiagent_systems/parent_and_subagents/agent.py. لاحظ الوكلاء الثلاثة في ملف agent.py:
    • root_agent (الاسم steering): يطرح على المستخدم سؤالاً لتحديد الوكيل الفرعي الذي سيتم نقل المحادثة إليه. في البداية، يعتمد فقط على description الوكلاء الفرعيين.
    • travel_brainstormer: تساعد المستخدم في استلهام أفكار بشأن الوجهات.
    • ‫attractions_planner: تساعد المستخدم في إعداد قائمة بالأنشطة التي يمكنه ممارستها في بلد معيّن.
  2. اجعل travel_brainstormer وattractions_planner برنامجَين وكيلَين لـ root_agent من خلال إضافة السطر التالي إلى عملية إنشاء root_agent:
        sub_agents=[travel_brainstormer, attractions_planner]
  3. في نافذة الأوامر، يمكنك الدردشة مع وكيلك:
    cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
adk run parent_and_subagents
  4. في طلب [user]: في الوحدة الطرفية، اكتب:
    hello
    مثال على الناتج (قد يختلف الناتج الذي يظهر على جهازك قليلاً):
    [steering]: Hi there! Do you already have a country in mind for your trip, or would you like some help deciding where to go?
  5. الآن، أخبر الوكيل في الوحدة الطرفية:
    I could use some help deciding.
    مثال على الناتج (قد يختلف الناتج الذي يظهر على جهازك قليلاً):
    [travel_brainstormer]: Okay! To give you the best recommendations, I need to understand what you're looking for in a trip.
...
    لاحظ العلامة [travel_brainstormer]. تم نقل عنصر التحكّم root_agent استنادًا إلى description الخاص بالوكيل الفرعي فقط.
  6. في موجه الأوامر user: في وحدة التحكم الطرفية، اكتب exit واضغط على ENTER لإنهاء المحادثة.
  7. لنكن أكثر وضوحًا الآن. في agent.py، أضِف ما يلي إلى instruction في root_agent:
            If they need help deciding, send them to 'travel_brainstormer'.
        If they know what country they'd like to visit, send them to the 'attractions_planner'.
  8. في الوحدة الطرفية، شغِّل الوكيل مرة أخرى:
    adk run parent_and_subagents
  9. في طلب [user]: في الوحدة الطرفية، اكتب:
    hello
  10. يمكنك الردّ بما يلي:
    I would like to go to Japan.
    مثال على الناتج (قد يختلف الناتج الذي يظهر على جهازك قليلاً):
    [attractions_planner]: Okay, I can help you with that! Here are some popular attractions in Japan:
...
    لاحظ عملية النقل إلى attractions_planner، كما هو موضّح في التعليمات الجديدة.
  11. الردّ الآن:
    Actually I don't know what country to visit.
    مثال على الناتج (قد يختلف الناتج الذي يظهر على جهازك قليلاً):
    [travel_brainstormer]: Okay! I can help you brainstorm some countries for travel...
    يُرجى العلم أنّه تم نقلك إلى travel_brainstormer، وهو نظير لـ attractions_planner. يتم السماح بذلك تلقائيًا.
  12. في طلب المستخدم، اكتب exit لإنهاء الجلسة.

ملخّص

في هذا القسم، تعرّفت على أساسيات التسلسل الهرمي للوكلاء ومسار المحادثة:

  • تبدأ المحادثة دائمًا بـ root_agent.
  • يمكن أن يحوّل وكيل رئيسي المحادثة تلقائيًا إلى وكيل فرعي استنادًا إلى description.
  • يمكنك التحكّم في هذا المسار بشكلٍ صريح من خلال منح الوالد instruction إذن النقل إلى وكيل فرعي من خلال name.
  • بشكلٍ تلقائي، يمكن للوكلاء النقل إلى وكلاء peer (الوكلاء الفرعيون في التسلسل الهرمي).

8. استخدام حالة الجلسة لتخزين المعلومات واسترجاعها

تحتوي كل محادثة في "حزمة تطوير التطبيقات" على Session، والذي يتضمّن قاموسًا لحالة الجلسة. يمكن لجميع الوكلاء الوصول إلى هذه الحالة، ما يجعلها الطريقة المثالية لنقل المعلومات بين الوكلاء أو الاحتفاظ بالبيانات (مثل قائمة) طوال المحادثة.

لاستكشاف كيفية إضافة بيانات إلى الحالة وقراءتها:

  1. الرجوع إلى الملف adk_multiagent_systems/parent_and_subagents/agent.py
  2. الصِق تعريف الدالة التالي بعد العنوان # Tools:
    def save_attractions_to_state(
tool_context: ToolContext,
attractions: List[str]
) -> dict[str, str]:
    """Saves the list of attractions to state["attractions"].

    Args:
        attractions [str]: a list of strings to add to the list of attractions

    Returns:
        None
    """
    # Load existing attractions from state. If none exist, start an empty list
    existing_attractions = tool_context.state.get("attractions", [])

    # Update the 'attractions' key with a combo of old and new lists.
    # When the tool is run, ADK will create an event and make
    # corresponding updates in the session's state.
    tool_context.state["attractions"] = existing_attractions + attractions

    # A best practice for tools is to return a status message in a return dict
    return {"status": "success"}
    في هذا الرمز، لاحظ ما يلي:
    • تتلقّى الدالة tool_context: ToolContext. هذا العنصر هو بوابتك إلى الجلسة.
    • يقرأ السطر tool_context.state["attractions"] = ... ويكتب مباشرةً في قاموس حالة الجلسة. يتولّى حزمة تطوير التطبيقات بقية المهام.
  3. أضِف الأداة إلى الوكيل attractions_planner من خلال إضافة المَعلمة tools:
        tools=[save_attractions_to_state]
  4. أضِف نقاطًا إلى instruction الحالية الخاصة بعميل attractions_planner:
            - When they reply, use your tool to save their selected attraction and then provide more possible attractions.
        - If they ask to view the list, provide a bulleted list of { attractions? } and then suggest some more.
  5. شغِّل واجهة مستخدم الويب الخاصة بـ "حزمة تطوير الوكيل" باستخدام الأمر التالي في الوحدة الطرفية:
    adk web
    الناتج
    INFO:     Started server process [2434]
INFO:     Waiting for application startup.
+-------------------------------------------------------+
| ADK Web Server started                                |
|                                                       |
| For local testing, access at http://localhost:8000.   |
+-------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  6. في نافذة Cloud Shell، انقر على الزر معاينة الويب، ثم اختَر تغيير المنفذ لعرض واجهة الويب في علامة تبويب جديدة.
    قائمة "معاينة الويب"
  7. أدخِل رقم المنفذ 8000 وانقر على تغيير ومعاينة. سيتم فتح علامة تبويب متصفّح جديدة تحتوي على واجهة مستخدم ADK Dev.
    تغيير مربّع المنفذ المنبثق مع إدخال 8000 في مربّع النص
  8. من القائمة المنسدلة اختيار وكيل على يمين الصفحة، اختَر parent_and_subagents.
  9. ابدأ المحادثة بـ: hello
  10. بعد أن يرحّب بك الوكيل، يمكنك الردّ بما يلي:
    I'd like to go to Egypt.
    من المفترض أن تتم إعادة توجيهك إلى attractions_planner وتزويدك بقائمة بأماكن الجذب السياحي.
  11. اختَر مَعلمًا سياحيًا، مثل:
    I'll go to the Sphinx
  12. من المفترض أن تتلقّى ردًا مشابهًا لما يلي: حسنًا، لقد حفظتُ "أبو الهول" في قائمتك...
  13. انقر على مربّع أدوات الردّ (المميّز بعلامة اختيار) لعرض الحدث الذي تم إنشاؤه من ردّ الأداة.
    لاحظ أنّه يتضمّن حقل الإجراءات الذي يتضمّن stateDelta يصف التغييرات في الحالة.
  14. الردّ باقتراح آخر من قائمة الوكيل
  15. في قائمة التنقّل على يمين الصفحة، انقر على "X" للخروج من التركيز على الحدث الذي فحصته سابقًا.
  16. في الشريط الجانبي الأيمن، انقر على علامة التبويب الحالة. يمكنك الآن الاطّلاع على مصفوفة attractions في حالة الجلسة، والتي من المفترض أن تحتوي على كلا العنصرَين المحدّدَين.معاينة "حالة الجلسة" في واجهة مستخدم الويب
  17. أرسِل الرسالة التالية إلى الموظّف:
    What is on my list?
    من المفترض أن يقرأ الوكيل الآن من الحالة ويعرض قائمتك.
  18. عند الانتهاء من تجربة الوكيل، أغلق علامة تبويب متصفّح الويب واضغط على CTRL + C في "وحدة Cloud Shell الطرفية" لإيقاف الخادم.

ملخّص القسم

في هذا القسم، تعرّفت على كيفية استخدام حالة Session لمشاركة البيانات:

  • لكتابة الحالة: يمكنك الكتابة إلى قاموس الحالة من داخل إحدى الأدوات باستخدام الكائن tool_context.state (مثلاً tool_context.state["my_list"] = [...]).
  • لقراءة الحالة: يمكنك إدخال بيانات الحالة مباشرةً في instruction الخاص بأحد العملاء باستخدام نماذج المفاتيح (مثل Here is your list: {my_list?}).
  • فحص الحالة: يمكنك مراقبة حالة الجلسة مباشرةً في واجهة مستخدم ADK Dev باستخدام علامة التبويب "الحالة".

9- وكلاء سير العمل

حتى الآن، رأيت كيف يحوّل وكيل رئيسي المحادثة إلى وكيل فرعي ثم ينتظر رد المستخدم. تختلف برامج وكيل سير العمل عن غيرها، فهي تنفّذ برامج الوكيل الفرعية واحدة تلو الأخرى في سير عمل آلي، بدون انتظار إدخال المستخدم.

هذه الميزة مثالية للمهام الآلية المتعددة الخطوات، مثل مسار "التخطيط والتنفيذ" أو "الصياغة والمراجعة". توفّر "حزمة تطوير التطبيقات" ثلاثة وكلاء مدمجين لسير العمل لإدارة ذلك:

  • SequentialAgent
  • LoopAgent
  • ParallelAgent

سيركّز الجزء المتبقي من هذا الدرس التطبيقي على إنشاء نظام متعدد الوكلاء باستخدام وكلاء سير العمل الثلاثة هؤلاء.

ستنشئ وكيلاً يطوّر مستندًا ترويجيًا لفيلم جديد عن شخصية تاريخية. ستتولّى هذه البرامج إجراء الأبحاث والكتابة بشكل متكرّر وإنشاء التقارير.

في النهاية، سيبدو نظامك على النحو التالي:

مخطّط بياني لنظام يستند إلى عدّة وكلاء خاص بفريق_مفهوم_فيلم

ستنشئ هذا النظام خطوة بخطوة، بدءًا من أبسط سير عمل.

10. إنشاء نظام متعدد الوكلاء باستخدام SequentialAgent

SequentialAgent هو وكيل سير عمل ينفّذ الوكلاء الفرعيين في تسلسل خطي بسيط. يتم تشغيل كل وكيل في قائمة sub_agents واحدًا تلو الآخر، بالترتيب. هذا الخيار مثالي لخطوط الإنتاج التي يجب تنفيذ المهام فيها بترتيب معيّن، مثل وكيل اقتراح الأفلام الذي ستنشئه الآن.

سيكون الإصدار الأول منظَّمًا على النحو التالي:

Film_concept_team multi-agent system step 1

  • سيرحّب root_agent (greeter) بالمستخدم ويحصل على موضوع الفيلم.
  • سيتم بعد ذلك نقلها إلى SequentialAgent باسم film_concept_team، والذي سيتم فيه ما يلي:
    1. تشغيل researcher للحصول على حقائق من ويكيبيديا
    2. شغِّل وكيل screenwriter لاستخدام هذه الحقائق في كتابة حبكة.
    3. شغِّل وكيل file_writer لحفظ الرسم البياني النهائي في ملف.

لننفّذها.

  1. في محرِّر Cloud Shell، افتح adk_multiagent_systems/workflow_agents/agent.py.
    اطّلِع على ملف تعريف هذا الوكيل. بما أنّه يجب تحديد الوكلاء الفرعيين قبل إمكانية تعيينهم لوكيل رئيسي، لقراءة الملف بترتيب سير المحادثة، يمكنك قراءة الوكلاء من أسفل الملف إلى أعلاه.
  2. لاحظ الأداة append_to_state. تتيح دالة المساعدة هذه للوكلاء إلحاق البيانات بقائمة في حالة الجلسة، وهي الطريقة التي ستمرر بها الدالتان researcher وscreenwriter عملهما.
  3. جرِّب الوكيل. في وحدة التحكّم، شغِّل واجهة الويب مع تفعيل إعادة التحميل المباشر:
    cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
adk web --reload_agents
  4. في نافذة Cloud Shell، انقر على الزر معاينة الويب، ثم اختَر تغيير المنفذ لعرض واجهة الويب في علامة تبويب جديدة.
    قائمة "معاينة الويب"
  5. أدخِل رقم المنفذ 8000 وانقر على تغيير ومعاينة. سيتم فتح علامة تبويب متصفّح جديدة تحتوي على واجهة مستخدم ADK Dev.
    تغيير مربّع المنفذ المنبثق مع إدخال 8000 في مربّع النص
  6. من القائمة المنسدلة اختيار وكيل، اختَر workflow_agents.
  7. ابدأ المحادثة بـ: hello. سيردّ عليك الوكيل greeter.
  8. عندما يُطلب منك ذلك، أدخِل اسم شخصية تاريخية. يمكنك استخدام أحد هذه الخيارات أو خيارك الخاص:
    • تشانغ تشونغجينغ
    • هبة فاروق
    • ماركوس أوريليوس
  9. سيتولّى SequentialAgent الآن عملية التحديث. لن تظهر لك أي رسائل وسيطة. سيتم تشغيل researcher وscreenwriter وfile_writer واحدًا تلو الآخر. لن يردّ الوكيل إلا بعد اكتمال التسلسل بأكمله.
    إذا تعذّر ذلك، يمكنك النقر على + جلسة جديدة في أعلى يسار الصفحة وإعادة المحاولة.
  10. بعد أن يؤكّد الوكيل أنّه تمّت كتابة الملف، ابحث عن ملف .txt الجديد وافتحه في الدليل movie_pitches في Cloud Shell Editor للاطّلاع على الناتج.
  11. في واجهة مستخدم المطوّر في "حزمة تطوير التطبيقات"، انقر على رمز آخر وكيل في سجلّ المحادثات لفتح عرض الأحداث.
  12. يعرض عرض الأحداث رسمًا بيانيًا مرئيًا لشجرة الوكيل. يمكنك الاطّلاع على الطريقة التي استدعت بها greeter الدالة film_concept_team، والتي استدعت بدورها كلًا من العناصر الفرعية بالترتيب.adk web graph
  13. يمكنك النقر على علامتَي التبويب الطلب والردّ لأي وكيل في الرسم البياني لفحص البيانات الدقيقة التي تم تمريرها، بما في ذلك حالة الجلسة.

ملخّص القسم

في هذا القسم، تعرّفت على كيفية استخدام وكيل سير العمل:

  • ينفّذ SequentialAgent وكيلاته الفرعية واحدة تلو الأخرى، بالترتيب، بدون انتظار إدخال المستخدم بين الخطوات.
  • هذا "سير عمل" لأنّ المستخدم يتحدث إلى root_agent، الذي يسلّم العمل إلى SequentialAgent لإكماله.
  • تستخدم البرامج الفرعية في التسلسل حالة الجلسة (مثل { PLOT_OUTLINE? }) للوصول إلى عمل العملاء السابقين.
  • يمكنك استخدام الرسم البياني للأحداث في واجهة مستخدم المطوّر لتصوُّر سير العمل الكامل من وكيل إلى وكيل وتصحيح أخطائه.

11. إضافة LoopAgent للعمل التكراري

LoopAgent هو وكيل سير عمل يشغّل الوكلاء الفرعيين بالتسلسل ثم يكرّر العملية بدءًا من البداية. تستمر هذه "الحلقة" إلى أن يتم استيفاء شرط معيّن، مثل الوصول إلى عدد max_iterations أو استدعاء وكيل فرعي للأداة المضمّنة exit_loop.

وهي مفيدة للمهام التي تتطلب تحسينًا متكررًا. ستضيف هذا LoopAgent لإنشاء "غرفة كاتب" لوكيلك المسؤول عن عرض فكرة الفيلم. يتيح ذلك لـ "researcher" و"screenwriter" و"critic" الجديدة العمل في حلقة، ما يؤدي إلى تحسين الحبكة في كل مرة إلى أن تقرّر "critic" أنّها جاهزة. يساعد ذلك أيضًا البرنامج على التعامل مع طلبات المستخدمين الأقل وضوحًا (مثل "طبيب قديم") من خلال السماح له بالبحث عن فكرة وتحسينها.

Film_concept_team multi-agent system step 2

لإجراء هذه التغييرات، اتّبِع الخطوات التالية:

  1. في adk_multiagent_systems/workflow_agents/agent.py، أضِف عملية الاستيراد الخاصة بـ exit_loop (بالقرب من عمليات الاستيراد الأخرى الخاصة بـ google.adk):
    from google.adk.tools import exit_loop
  2. أضِف وكيل critic جديدًا. سيراجع هذا الوكيل الحبكة. إذا كانت جيدة، سيتم استدعاء exit_loop. إذا لم يكن الأمر كذلك، يضيف ملاحظات إلى الحالة في التكرار التالي.
    ألصِق تعريف الوكيل التالي ضمن القسم # Agents:
    critic = Agent(
    name="critic",
    model=model_name,
    description="Reviews the outline so that it can be improved.",
    instruction="""
    INSTRUCTIONS:
    Consider these questions about the PLOT_OUTLINE:
    - Does it meet a satisfying three-act cinematic structure?
    - Do the characters' struggles seem engaging?
    - Does it feel grounded in a real time period in history?
    - Does it sufficiently incorporate historical details from the RESEARCH?

    If the PLOT_OUTLINE does a good job with these questions, exit the writing loop with your 'exit_loop' tool.
    If significant improvements can be made, use the 'append_to_state' tool to add your feedback to the field 'CRITICAL_FEEDBACK'.
    Explain your decision and briefly summarize the feedback you have provided.

    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    RESEARCH:
    { research? }
    """,
    before_model_callback=log_query_to_model,
    after_model_callback=log_model_response,
    tools=[append_to_state, exit_loop]
)
  3. أنشئ writers_room LoopAgent. سيحتوي هذا المتغير على الوكلاء الثلاثة الذين سيعملون في الحلقة.
    ألصِق الرمز التالي أعلى تعريف وكيل film_concept_team:
    writers_room = LoopAgent(
    name="writers_room",
    description="Iterates through research and writing to improve a movie plot outline.",
    sub_agents=[
        researcher,
        screenwriter,
        critic
    ],
    max_iterations=5,
)
  4. عدِّل film_concept_team SequentialAgent لاستخدام حلقة writers_room الجديدة. استبدِل researcher وscreenwriter بعامل writers_room واحد.استبدِل تعريف film_concept_team الحالي بما يلي:
    film_concept_team = SequentialAgent(
    name="film_concept_team",
    description="Write a film plot outline and save it as a text file.",
    sub_agents=[
        writers_room,
        file_writer
    ],
)
  5. ارجع إلى علامة التبويب "واجهة مستخدم المطوّر في حزمة تطوير التطبيقات" (ADK) وانقر على + جلسة جديدة في أعلى يسار الصفحة.
  6. ابدأ محادثة جديدة مع: hello
  7. عندما يُطلب منك ذلك، قدِّم للموظف موضوعًا أوسع هذه المرة. في ما يلي بعض الأفكار:
    • مصمّم صناعي صنع منتجات للجميع
    • رسّام خرائط
    • ذلك الرجل الذي جعل المحاصيل تنتج المزيد من الطعام
    سيعمل الوكيل الآن من خلال التكرار الحلقي. في واجهة مستخدم ADK Dev، ستظهر السجلات عند تشغيل الوكلاء عدة مرات (على سبيل المثال، "[باحث]"، "[كاتب سيناريو]"، "[ناقد]"، "[باحث]"، "[كاتب سيناريو]"، "[ناقد]...").
  8. عند اكتمال التكرار الحلقي، سيكتب الوكيل الملف. راجِع الملف الذي تم إنشاؤه في الدليل adk_multiagent_systems/movie_pitches.
  9. افحص الرسم البياني للأحداث في واجهة مستخدم المطوّرين للاطّلاع على بنية الحلقة.

ملخّص القسم

في هذا القسم، تعرّفت على كيفية استخدام LoopAgent:

  • LoopAgent هو وكيل سير عمل يكرّر تسلسل الوكلاء الفرعيين، ما يؤدي إلى إنشاء "حلقة داخلية" للمهام المتكررة.
  • تستخدم الوكالات داخل حلقة التكرار حالة الجلسة لتمرير العمل (مثل، PLOT_OUTLINE) والملاحظات (مثل CRITICAL_FEEDBACK) في كل تمريرة لاحقة.
  • يمكن إيقاف الحلقة عن طريق بلوغ الحدّ max_iterations أو من خلال وكيل يستدعي الأداة exit_loop.

12. استخدام ParallelAgent لتنفيذ عملية "التوزيع والتجميع"

ParallelAgent هو وكيل سير عمل ينفّذ جميع الوكلاء الفرعيين في الوقت نفسه (بشكل متزامن). ويكون ذلك مفيدًا للمهام التي يمكن تقسيمها إلى مهام فرعية مستقلة، مثل تنفيذ مهمتَي بحث مختلفتَين.

ستستخدم ParallelAgent لإنشاء "فريق ما قبل الإنتاج" الذي يعمل بالتوازي. سيبحث أحد المساعدين في إمكانية تحقيق إيرادات كبيرة في شباك التذاكر، بينما يتبادل مساعد آخر الأفكار حول اختيار الممثلين في الوقت نفسه. يُطلق على هذا غالبًا اسم نمط "التوزيع والتجميع": يوزّع ParallelAgent العمل، ثم يجمع وكيل لاحق (file_writer) النتائج.

Film_concept_team multi-agent system step 3

سيكون مسار وكيلك النهائي على النحو التالي:

  1. يبدأ greeter (المستند الجذر) المحادثة.
  2. يتم تحويلها إلى film_concept_team (SequentialAgent)، والتي يتم تشغيلها:
    • writers_room (LoopAgent) لإنشاء الرسم البياني
    • preproduction_team (ParallelAgent) الجديد للبحث عن إيرادات شباك التذاكر وفريق التمثيل في الوقت نفسه
    • انقر على file_writer لجمع كل النتائج وحفظ الملف.

لإجراء هذه التغييرات، اتّبِع الخطوات التالية:

  1. في adk_multiagent_systems/workflow_agents/agent.py، الصِق ParallelAgent الجديد والوكلاء الفرعيين ضمن العنوان # Agents.
    box_office_researcher = Agent(
    name="box_office_researcher",
    model=model_name,
    description="Considers the box office potential of this film",
    instruction="""
    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    INSTRUCTIONS:
    Write a report on the box office potential of a movie like that described in PLOT_OUTLINE based on the reported box office performance of other recent films.
    """,
    output_key="box_office_report"
)

casting_agent = Agent(
    name="casting_agent",
    model=model_name,
    description="Generates casting ideas for this film",
    instruction="""
    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    INSTRUCTIONS:
    Generate ideas for casting for the characters described in PLOT_OUTLINE
    by suggesting actors who have received positive feedback from critics and/or
    fans when they have played similar roles.
    """,
    output_key="casting_report"
)

preproduction_team = ParallelAgent(
    name="preproduction_team",
    sub_agents=[
        box_office_researcher,
        casting_agent
    ]
)
  2. عدِّل قائمة film_concept_team SequentialAgent sub_agents لتضمين preproduction_team الجديد (بين writers_room وfile_writer).استبدِل تعريف film_concept_team الحالي بما يلي:
    film_concept_team = SequentialAgent(
    name="film_concept_team",
    description="Write a film plot outline and save it as a text file.",
    sub_agents=[
        writers_room,
        preproduction_team,
        file_writer
    ],
)
  3. عدِّل file_writer وكيل instruction لكي "يجمع" التقارير الجديدة من الحالة ويضيفها إلى الملف.
    استبدِل السلسلة instruction الخاصة بـ file_writer بما يلي:
        instruction="""
    INSTRUCTIONS:
    - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE.
    If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one.
    - Use your 'write_file' tool to create a new txt file with the following arguments:
    - for a filename, use the movie title
    - Write to the 'movie_pitches' directory.
    - For the 'content' to write, include:
    - The PLOT_OUTLINE
    - The BOX_OFFICE_REPORT
    - The CASTING_REPORT

    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    BOX_OFFICE_REPORT:
    { box_office_report? }

    CASTING_REPORT:
    { casting_report? }
    """,
  4. ارجع إلى علامة التبويب "واجهة مستخدم ADK Dev" وانقر على + جلسة جديدة.
  5. اضغط على hello لبدء المحادثة.
  6. عندما يُطلب منك ذلك، أدخِل فكرة جديدة لشخصية. في ما يلي بعض الأفكار:
    • تلك الممثلة التي اخترعت تكنولوجيا شبكة Wi-Fi
    • طاهٍ مثير
    • الجهات الفاعلة الرئيسية في معارض المعرض العالمي
  7. عندما يكمل العامل عمله، افحص الملف النهائي في الدليل adk_multiagent_systems/movie_pitches. من المفترض أن يحتوي الآن على الحبكة وتقرير شباك التذاكر وتقرير اختيار الممثلين في مستند واحد.

ملخّص القسم

في هذا القسم، تعرّفت على كيفية استخدام ParallelAgent:

  • تنفّذ مهمة ParallelAgent "التوزيع" جميع المهام الفرعية في الوقت نفسه، بدلاً من تنفيذها بالتسلسل.
  • ويكون هذا الإجراء فعّالاً للغاية في تنفيذ المهام التي لا تعتمد على بعضها البعض (مثل البحث عن موضوعَين مختلفَين).
  • يتم "جمع" نتائج البرامج الوكيلة المتوازية بواسطة برنامج وكيل لاحق. يتم ذلك من خلال جعل البرامج المساعدة المتوازية تحفظ عملها في حالة الجلسة (باستخدام output_key)، وجعل برنامج مساعد نهائي (مثل file_writer) يقرأ هذه المفاتيح.

13. وكلاء سير العمل المخصّصون

عندما لا تكون وكلاء سير العمل المحدّدين مسبقًا في SequentialAgent وLoopAgent وParallelAgent كافية لتلبية احتياجاتك، يوفّر لك CustomAgent المرونة اللازمة لتنفيذ منطق جديد لسير العمل.

يمكنك تحديد أنماط للتحكّم في التدفق أو التنفيذ الشرطي أو إدارة الحالة بين الوكلاء الفرعيين. ويفيد ذلك في مهام سير العمل المعقّدة أو عمليات التنسيق التي تتضمّن حالات أو دمج منطق نشاط تجاري مخصّص في طبقة التنسيق الخاصة بالإطار.

لا يتناول هذا الدرس التطبيقي كيفية إنشاء CustomAgent، ولكن من الجيد معرفة أنّه متاح إذا احتجت إليه.

14. تهانينا!

لقد أنشأت بنجاح نظامًا معقّدًا متعدد العملاء باستخدام حزمة تطوير العملاء (ADK) من Google. لقد انتقلت من علاقة بسيطة بين وكيل رئيسي ووكيل ثانوي إلى تنسيق عمليات سير عمل معقّدة ومبرمَجة يمكنها البحث والكتابة وتحسين مشروع إبداعي.

ملخّص

في هذا الدرس التطبيقي، نفّذت ما يلي:

  • وكلاء منظَّمون في شجرة هرمية مع علاقات بين الوكيل الرئيسي والوكلاء الفرعيين
  • عمليات النقل من وكيل إلى آخر الخاضعة للتحكّم، سواء تلقائيًا (باستخدام description) أو بشكل صريح (باستخدام instruction)
  • استخدِم أداة لكتابة البيانات في قاموس tool_context.state.
  • استخدام نماذج المفاتيح (مثل { PLOT_OUTLINE? }) لقراءة حالة الجلسة وتوجيه طلب أحد العملاء.
  • تم تنفيذ SequentialAgent لإنشاء سير عمل بسيط خطوة بخطوة (البحث -> الكتابة -> الحفظ).
  • استخدام LoopAgent مع وكيل critic وأداة exit_loop لإنشاء دورة تحسين تكرارية
  • استخدام ParallelAgent لتنفيذ مهام مستقلة بالتوازي (مثل البحث عن الممثلين والإيرادات)

مواصلة التجربة

هناك العديد من الطرق للاستفادة من المعلومات التي تعلّمتها. وفي ما يلي بعض الأفكار:

  • إضافة المزيد من الوكلاء: حاوِل إضافة وكيل جديد إلى preproduction_team ParallelAgent. على سبيل المثال، يمكنك إنشاء marketing_agent يكتب جملة ترويجية للفيلم استنادًا إلى PLOT_OUTLINE.
  • إضافة المزيد من الأدوات: يمكنك منح وكيل researcher المزيد من الأدوات. يمكنك إنشاء أداة تستخدم إحدى واجهات برمجة التطبيقات في "بحث Google" للعثور على معلومات غير متوفرة على Wikipedia.
  • الاستكشاف CustomAgent: ذكر المختبر CustomAgent لعمليات سير العمل التي لا تتناسب مع النماذج العادية. جرِّب إنشاء برنامج، على سبيل المثال، يشغّل وكيلاً بشكل مشروط فقط إذا كان مفتاح معيّن متوفّرًا في حالة الجلسة.