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

1. مقدمة

نظرة عامة

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

ما ستنشئه

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

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

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

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

المتطلبات الأساسية

• الإلمام بلغة Python وواجهات سطر الأوامر
• الوصول إلى مشروع على Google Cloud تم تفعيل الفوترة فيه
• أدوات واجهة سطر الأوامر المثبَّتة: gcloud وuv

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

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

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

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

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

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

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

تبدأ البنية بأكملها بـ 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. إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على تفويض للمتابعة.
3. إذا لم تظهر النافذة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
   • انقر على عرض.
   • انقر على Terminal.
4. في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:

   gcloud config set project [PROJECT_ID]
   

   • مثال:

     gcloud config set project lab-project-id-example
     

   • إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:

     gcloud projects list
     

     
5. من المفترض أن تظهر لك هذه الرسالة:

   Updated property [core/project].
   

   إذا رأيت WARNING وطُلب منك Do you want to continue (Y/n)?، من المحتمل أنّك أدخلت رقم تعريف المشروع بشكل غير صحيح. اضغط على n، ثم على Enter، وحاوِل تنفيذ الأمر gcloud config set project مرة أخرى.

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

لاستخدام Gemini Enterprise Agent Platform API والتفاعل مع نموذج Gemini، عليك تفعيل واجهة برمجة التطبيقات في مشروع على السحابة الإلكترونية على Google Cloud.

1. في الوحدة الطرفية، فعِّل واجهة برمجة التطبيقات:

   gcloud services enable aiplatform.googleapis.com
   

مقدمة إلى حزمة تطوير البرامج (SDK) من Google GenAI للغة Python

للتفاعل مع النماذج المستضافة على "منصة وكلاء Gemini Enterprise" من تطبيق Python، عليك استخدام حزمة Google GenAI SDK للغة Python. تُبسّط حزمة SDK هذه عملية إرسال الطلبات وتحديد مَعلمات النموذج وتلقّي الردود بدون الحاجة إلى التعامل مع تعقيدات طلبات البيانات من واجهة برمجة التطبيقات الأساسية مباشرةً.

يمكنك العثور على مستندات شاملة حول حزمة تطوير البرامج (SDK) من Google للذكاء الاصطناعي التوليدي في Python هنا: مستندات حزمة تطوير البرامج (SDK) من Google للذكاء الاصطناعي التوليدي.

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"، انقر على ملف (File) > فتح مجلد (Open Folder)....
   
   
2. في المربّع الذي يظهر، أضِف معلومات المجلد التالية بعد اسم المستخدم: adk_multiagent_systems/. انقر على حسنًا.
   من المفترض أن يظهر على النحو التالي:
   
3. سيتم إعادة تحميل لوحة "المستكشف" على اليمين. من المفترض أن تظهر لك الآن بنية مشروعك الكاملة، مع الدليلَين الفرعيَين parent_and_subagents وworkflow_agents، لتكون جاهزًا للخطوات التالية.
   

   إذا اختفت النافذة الطرفية عند إجراء ذلك، يمكنك إعادة فتحها من خلال النقر على عرض ثم النافذة الطرفية في القائمة العلوية.

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

1. في وحدة التحكّم، أنشئ بيئة افتراضية وفعّلها باستخدام uv. يضمن ذلك عدم تعارض تبعيات مشروعك مع نظام Python أو المشاريع الأخرى.

   uv venv
   source .venv/bin/activate
   

   إذا تمّت إعادة تحميل جلسة Cloud Shell أو فتح علامة تبويب طرفية جديدة، قد تحتاج إلى إعادة تفعيل البيئة الافتراضية من خلال تنفيذ source .venv/bin/activate من داخل الدليل adk_multiagent_systems.

2. في وحدة التحكّم، ثبِّت google-adk والعناصر التابعة الأخرى من الملف requirements.txt:

   uv pip install -r requirements.txt
   

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

1. أنت مدرَج في دليل adk_multiagent_systems. في وحدة التحكّم، أنشئ ملف .env لتخزين متغيرات البيئة:

   cloudshell edit .env
   

2. ألصِق ما يلي في ملف .env الذي يفتح في المحرِّر:

   GOOGLE_GENAI_USE_ENTERPRISE=true
   GOOGLE_CLOUD_PROJECT="[YOUR-PROJECT-ID]"
   GOOGLE_CLOUD_LOCATION=global
   MODEL="gemini-3.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
   

   من المفترض أن تبدو بنية الملف الآن على النحو التالي:
   

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: تساعد المستخدم في إعداد قائمة بالأنشطة التي يمكنه ممارستها في بلد معيّن.

   ملاحظة: لقراءة ملف agent.py بترتيب تسلسل المحادثة، غالبًا ما يكون من الأسهل البدء بالقراءة من root_agent في أسفل الصفحة ثم الانتقال إلى الأعلى. ويرجع ذلك إلى أنّ رمز Python يتطلّب تحديد الوكلاء الفرعيين قبل إضافتهم إلى وكيل.

2. اجعل travel_brainstormer وattractions_planner وكيلَين فرعيَين من root_agent من خلال إضافة السطر التالي إلى عملية إنشاء root_agent:

       sub_agents=[travel_brainstormer, attractions_planner]
   

   ملاحظة: يتم تحديد التسلسل الهرمي للوكيل من خلال قائمة sub_agents الخاصة بالعنصر الرئيسي فقط، ولا يحتاج الوكلاء الفرعيون إلى مَعلمة parent.

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. يُسمح بذلك تلقائيًا.

    إذا أردت منع النقل، يمكنك ضبط disallow_transfer_to_peers=True على وكيل 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.
   

   لاحظ القسم بين الأقواس المعقوفة: { attractions? }. تعمل ميزة إنشاء نماذج للمفاتيح في حزمة تطوير البرامج (ADK) هذه على إدخال قيمة المفتاح attractions من الحالة إلى طلب وكيل المستخدم. يجعل ? هذا الخيار اختياريًا، ما يمنع حدوث أخطاء إذا لم يكن المفتاح متوفّرًا بعد.

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)
   

   ملاحظة: إذا كان المنفذ 8000 قيد الاستخدام، يمكنك التشغيل على منفذ مختلف، مثل: adk web --port 8001. يجب تعديل رقم المنفذ الذي تم إدخاله في الخطوات التالية ليتطابق مع رقم المنفذ الجديد.

6. في نافذة Cloud Shell، انقر على الزر معاينة الويب، ثم اختَر تغيير المنفذ لعرض واجهة الويب في علامة تبويب جديدة.
   
7. أدخِل رقم المنفذ 8000 وانقر على تغيير ومعاينة. سيتم فتح علامة تبويب متصفّح جديدة تعرض واجهة مستخدم ADK Dev.
   
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. انقر على مربّع أداة الردّ (المميّز بعلامة اختيار) لعرض الحدث الذي تم إنشاؤه من ردّ الأداة.
    لاحظ أنّه يتضمّن الحقل actions الذي يتضمّن stateDelta يصف التغييرات في الحالة.
14. الردّ باقتراح آخر من قائمة الوكيل
15. في قائمة التنقّل على يمين الصفحة، انقر على "X" للخروج من التركيز على الحدث الذي فحصته سابقًا.
16. في الشريط الجانبي الأيمن، انقر على علامة التبويب الحالة. يمكنك الآن الاطّلاع على مصفوفة attractions في حالة الجلسة، والتي من المفترض أن تحتوي على كلا العنصرَين المحدّدَين.
17. أرسِل الرسالة التالية إلى الوكيل:

    What is on my list?
    

    من المفترض أن يقرأ الوكيل الآن من الحالة ويعرض قائمتك.
18. عند الانتهاء من تجربة الوكيل، أغلِق علامة تبويب متصفّح الويب واضغط على CTRL + C في "وحدة Cloud Shell الطرفية" لإيقاف الخادم.

لتخزين ردّ نصي كامل من الوكيل في الحالة، يمكنك ضبط المَعلمة output_key عند تحديد الوكيل، وسيتم تخزين الناتج الكامل في قاموس الحالة ضمن اسم الحقل هذا.

ملخّص القسم

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

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

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

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

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

• SequentialAgent
• LoopAgent
• ParallelAgent

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

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

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

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

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

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

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

• سيرحّب 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
   

   ملاحظة: إذا كان المنفذ 8000 قيد الاستخدام، يمكنك التشغيل على منفذ مختلف، مثل: adk web --reload_agents --port 8001.

4. في نافذة Cloud Shell، انقر على الزر معاينة الويب، ثم اختَر تغيير المنفذ لعرض واجهة الويب في علامة تبويب جديدة.
   
5. أدخِل رقم المنفذ 8000 وانقر على تغيير ومعاينة. سيتم فتح علامة تبويب جديدة في المتصفّح تتضمّن واجهة مستخدم ADK Dev.
   
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، والتي استدعت بدورها كل وكيل فرعي بالترتيب.
13. يمكنك النقر على علامتَي التبويب الطلب والردّ لأي وكيل في الرسم البياني لفحص البيانات الدقيقة التي تم تمريرها، بما في ذلك حالة الجلسة.

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

ملخّص القسم

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

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

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

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

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

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

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,
   )
   

   يُرجى التأكّد من المَعلمة 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) النتائج.

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

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