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

1. مقدمة

نظرة عامة

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

ما ستنشئه

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

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

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

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

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

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

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

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

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

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

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

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

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

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

حساب Google

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

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

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

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

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

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

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

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

إذا أعددت الفوترة باستخدام أرصدة 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

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

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

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

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

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

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

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

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

  1. في قائمة "محرّر Cloud Shell"، اختَر ملف > فتح مجلد....
    قائمة "ملف" في "محرّر Cloud Shell" مع تحديد "فتح مجلد"
  2. في المربّع الذي يظهر، أضِف معلومات المجلد التالية بعد اسم المستخدم: adk_multiagent_systems/. انقر على حسنًا.
    من المفترض أن يظهر بالشكل التالي:
    فتح مربّع الحوار "فتح المجلد" مع مسار المشروع
  3. سيتم إعادة تحميل لوحة "المستكشف" على يمين الصفحة. من المفترض أن تظهر لك الآن بنية مشروعك الكاملة، مع الدليلَين الفرعيَين parent_and_subagents وworkflow_agents، لتكون جاهزًا للخطوات التالية.
    لوحة "المستكشف" التي تعرض المجلد المفتوح adk_multiagent_systems

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

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

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

  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
    يجب أن تبدو بنية الملف الآن على النحو التالي:
    لوحة "المستكشف" التي تعرض المجلد المفتوح 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 ~/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. شغِّل واجهة مستخدم الويب لحزمة Agent Development Kit باستخدام الأمر التالي في الوحدة الطرفية:
    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 ~/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. في واجهة مستخدم ADK Dev، انقر على رمز آخر وكيل في سجلّ المحادثات لفتح عرض الأحداث.
  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. عدِّل قائمة sub_agents الخاصة بـ SequentialAgent film_concept_team لتضمين 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. تهانينا!

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

ملخّص

في هذه الميزة الاختبارية، نفّذت ما يلي:

  • تنظيم العملاء في شجرة هرمية مع علاقات بين العملاء الرئيسيين والفرعيين
  • عمليات النقل بين الوكلاء الخاضعة للرقابة، سواء تلقائيًا (باستخدام 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 لعمليات سير العمل التي لا تتناسب مع النماذج العادية. جرِّب إنشاء وكيل، على سبيل المثال، لا يتم تشغيله بشكل مشروط إلا إذا كان مفتاح معيّن متوفّرًا في حالة الجلسة.