دورة مكثّفة حول "حزمة تطوير التطبيقات" (ADK) - من مبتدئ إلى خبير

1- ما ستتعلمه

مرحبًا بك في "الدورة التدريبية المتقدّمة حول مجموعة أدوات تطوير التطبيقات" - رحلتك إلى أنظمة الوكلاء المتعدّدين

أنت على وشك الدخول إلى عالم وكلاء الذكاء الاصطناعي الشيّق. لا تكتفِ باستخدام برامج الدردشة البسيطة التي تجيب عن الأسئلة فقط. نعمل على تطوير Agent Development Kit (ADK) لإنشاء أنظمة متطورة وتلقائية يمكنها التفكير والتخطيط واستخدام الأدوات لإنجاز المهام المعقّدة.

خارطة طريق الدورة التدريبية

في نهاية هذا البرنامج التعليمي، ستتمكّن من:

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

لِنبدأ. 🚀

2. إعداد مفتاح واجهة برمجة التطبيقات في Google Cloud Platform وGemini

إعداد مشروعك على Google Cloud Platform ومفتاح واجهة برمجة التطبيقات في Gemini

لتشغيل وكلاء الذكاء الاصطناعي، نحتاج إلى عنصرَين: مشروع Google Cloud لتوفير الأساس، ومفتاح Gemini API للوصول إلى نماذج Google الفعّالة.

الخطوة 1: تفعيل حساب الفوترة

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

الخطوة 2: إنشاء مشروع جديد على Google Cloud Platform

  • انتقِل إلى Google Cloud Console وأنشِئ مشروعًا جديدًا.

إنشاء حساب جديد على Google Cloud Platform

  • انتقِل إلى Google Cloud Console وأنشِئ مشروعًا جديدًا.
  • افتح اللوحة اليمنى، وانقر على Billing، وتحقّق ممّا إذا كان حساب الفوترة مرتبطًا بحساب Google Cloud Platform هذا.

ربط حساب الفوترة بحساب Google Cloud Platform

إذا ظهرت لك هذه الصفحة، ضَع علامة في المربّع manage billing account، واختَر Google Cloud Trial One واربطه بحسابك.

الخطوة 3: إنشاء مفتاح واجهة Gemini API

قبل أن تتمكّن من تأمين المفتاح، يجب أن يكون لديك مفتاح.

  • انتقِل إلى Google AI Studio.
  • سجِّل الدخول باستخدام حسابك على Gmail.
  • انقر على الزر "الحصول على مفتاح واجهة برمجة التطبيقات"، والذي يظهر عادةً في لوحة التنقّل على يمين الصفحة أو في أعلى يسارها.
  • في مربّع الحوار "مفاتيح واجهة برمجة التطبيقات"، انقر على "إنشاء مفتاح واجهة برمجة التطبيقات في مشروع جديد". إنشاء مفتاح واجهة برمجة التطبيقات في مشروع جديد
  • اختَر المشروع الجديد الذي أنشأته والذي تم إعداد حساب الفوترة فيه. اختَر المشروع الجديد
  • سيتم إنشاء مفتاح واجهة برمجة تطبيقات جديد لك. انسخ هذا المفتاح على الفور وخزِّنه مؤقتًا في مكان آمن (مثل مدير كلمات المرور أو ملاحظة آمنة). هذه هي القيمة التي ستستخدِمها في الخطوات التالية.

3- الجلسة 1: إنشاء أول وكيل باستخدام Runner

roadmap1

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

  • الوكيل: هو المحرّك الأساسي للعملية. يتم تحديد هوية GPT من خلال التعليمات التي يتلقّاها (شخصيته ومهمته) ونموذج الذكاء الاصطناعي الذي يستخدمه (مثل Gemini) والأدوات التي يمكنه الوصول إليها.
  • الجلسة: هي ذاكرة المحادثة. يخزّن سجلّ التفاعلات (رسائل المستخدمين وردود الوكيل)، ما يتيح إجراء حوار متواصل.
  • المشغّل: المحرّك الذي ينفّذ المهمة. تأخذ هذه الخدمة الوكيل والجلسة، وتعالج طلب المستخدم الجديد، وتنسّق الخطوات لإنشاء ردّ.

➡️ مكان العثور على هذه الميزة في دفتر الملاحظات

👉 يتوافق ذلك مع الخلايا ضِمن الجزء 1: وكيلك الأول - جني الرحلات اليومية 🧞.🌟

الروبوت يقرأ

  • تعريف الوكيل: ابحث عن الدالة create_day_trip_agent(). هذا هو المكان الذي يتم فيه تحديد الوكيل. لاحظ سلسلة التعليمات المفصّلة، وهي الطلب الذي يخبر الوكيل بكيفية التصرف. نقدّم أيضًا أول أداة له، وهي "بحث Google".
  • الدالة المساعِدة: يتم تحديد الدالة المساعِدة run_agent_query() هنا. سنستخدم هذه الأداة المساعدة في جميع أنحاء دفتر الملاحظات لتبسيط تنفيذ الاستعلامات.
  • التشغيل التجريبي: تحاكي الدالة run_day_trip_genie() طلبًا من مستخدم يبحث عن رحلة ليوم واحد "بأسعار معقولة" و "مريحة". يستخدم الوكيل التعليمات وأداة "بحث Google" للعثور على مواقع جغرافية مناسبة وإنشاء خطة سفر بتنسيق Markdown.

➡️ الإجراء: افحص طلب التعليمات الخاص بـ "day_trip_agent". لاحظ كيف يرتبط طلب رحلة "بأسعار معقولة" في طلب البحث التجريبي مباشرةً بإرشادات الوكيل بأن يكون "مراعيًا للميزانية".

4. الجلسة 2: أدوات مخصّصة 🛠️

roadmap2

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

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

➡️ مكان العثور على هذه الميزة في دفتر الملاحظات

👉 يتوافق ذلك مع الخلايا ضمن 2.1 The Simple FunctionTool: Calling a Real-Time Weather API. 🌟

adk tools

  • تعريف الأداة: تمثّل الدالة get_live_weather_forecast(location: str) جوهر أداتنا المخصّصة. تتلقّى هذه الدالة اسم مدينة، وترسل طلبًا إلى واجهة برمجة التطبيقات العامة الخاصة بـ "خدمة الأرصاد الجوية الوطنية"، وتعرض قاموسًا يتضمّن درجة الحرارة وتوقّعات الطقس.
  • تعريف الوكيل: يتم إنشاء weather_agent وتزويده بأداتنا الجديدة من خلال تمرير tools=[get_live_weather_forecast] أثناء عملية الإعداد. تطلب تعليمات الوكيل منه صراحةً استخدام هذه الأداة قبل اقتراح أنشطة خارجية.
  • التشغيل التجريبي: يؤدي طلب البحث "أريد الذهاب في رحلة مشي لمسافات طويلة بالقرب من بحيرة تاهو، ما هي حالة الطقس؟" إلى تشغيل الأداة get_live_weather_forecast مباشرةً لأنّ التعليمات تتطلّب ذلك.

➡️ الإجراء: اقرأ سلسلة التوثيق الخاصة بالدالة get_live_weather_forecast وتعليمات weather_agent. لاحظ العلاقة المباشرة بينهما.

5- الجلسة 3: استخدام الذكاء الاصطناعي كأداة 🧑‍🍳

roadmap3

لماذا تنشئ وكيلاً واحدًا ضخمًا بينما يمكنك إنشاء فريق من المتخصصين؟ نمط Agent-as-a-Tool هو طريقة فعّالة لإنشاء أنظمة معقّدة حيث يفوّض وكيل أساسي، يُطلق عليه غالبًا اسم "المنسّق" أو "الموجّه"، المهام إلى وكلاء آخرين أكثر تركيزًا.

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

➡️ مكان العثور على هذه الميزة في دفتر الملاحظات

👉 يتوافق ذلك مع الخلايا ضمن 2.2 استخدام الوكيل كأداة: استشارة اختصاصي 🧑‍🍳.🌟

بيانات الرحلة

ينشئ هذا المثال نظامًا متطوّرًا للوكلاء يتضمّن طبقات متعددة:

  • المتخصّصون:
    • food_critic_agent: وكيل متخصص للغاية يقدّم اقتراحات بشأن المطاعم فقط.
    • db_agent: وكيل وهمي يتظاهر بالبحث في قاعدة بيانات عن معلومات الفنادق.
    • ‫concierge_agent: هو وكيل متوسط المستوى يعمل كموظف استقبال مهذّب. والأهم من ذلك، أنّها تتضمّن food_critic_agent كأداة خاصة بها.
  • المنسّق (trip_data_concierge_agent): هو الوكيل الأعلى مستوى الذي يتفاعل معه المستخدم. تجعله تعليماته "مخططًا رئيسيًا للسفر"، ويتم تزويده بأداتَين تستدعيان الوكلاء الآخرين:
    • call_db_agent: دالة تستدعي db_agent.
    • call_concierge_agent: دالة تستدعي concierge_agent.
  • المسار: يوضّح التشغيل التجريبي في run_trip_data_concierge() سلسلة التفويض الكاملة.
    • يطلب مستخدم من خدمة التنسيق فندقًا ومطعمًا قريبًا.
    • تطلب تعليمات أداة التنسيق منها أولاً استخدام أداة call_db_agent للحصول على بيانات الفنادق.
    • بعد ذلك، تستخدم أداة التنسيق أداة call_concierge_agent للحصول على اقتراح.
    • تستخدم concierge_agent، عند تلقّي الطلب، أداتها الخاصة، food_critic_agent، للحصول على فكرة عن مطعم.

يتم إعادة ردّ ناقد الطعام إلى موظف الاستقبال الذي ينسّقه بأدب ويعيده إلى المنسّق الذي يعرضه أخيرًا على المستخدم.

➡️ الإجراء: تتبُّع مسار التنفيذ في عملية التشغيل التجريبي ضمن run_trip_data_concierge() لاحظ كيف تعرض TOOL CALLED عمليات الطباعة سلسلة التفويض من المنسّق إلى المتخصّصين. هذه سلسلة متسلسلة من الأوامر.

6. الجلسة 4: ذاكرة الوكيل 🧠

roadmap4

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

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

➡️ مكان العثور على هذه الميزة في دفتر الملاحظات

👉 يتوافق ذلك مع الخلايا ضمن الجزء 3: وكيل مزوّد بذاكرة - أداة التخطيط التكيُّفية 🗺️. 🌟

ذاكرة الوكيل

  • تعريف الوكيل: تحدّد الدالة create_multi_day_trip_agent() وكيلًا مصمّمًا للتخطيط لرحلة بشكل تدريجي. تؤكّد تعليماتها على تذكُّر السياق والتعامل مع الملاحظات والتخطيط ليوم واحد في كل مرة.

السيناريو 3 (أ): وكيل مزوّد بميزة "الذاكرة" (✅)

يتم تنفيذ هذا الاختبار في الدالة run_adaptive_memory_demonstration().

  • يتم إنشاء trip_session واحد وإعادة استخدامه لثلاثة أدوار متتالية.
  • الجولة 1: يبدأ المستخدم خطة رحلة لمدة يومَين.
  • الجولة 2: يقدّم المستخدم ملاحظات ("لستُ من محبّي القصور"). وبما أنّ الوكيل يتذكّر المحادثة الأولى، فهو يفهم الجزء الذي يجب تغييره في الخطة ويقدّم بديلاً.
  • الردّ 3: يؤكّد المستخدم التغيير ويطلب الخطوة التالية. يتذكّر الوكيل كل شيء ويواصل التخطيط لليوم الثاني.

السيناريو 3ب: وكيل بدون ذاكرة (❌)

يتم تنفيذ هذا الاختبار في الدالة run_memory_failure_demonstration().

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

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

الإجراء: قارِن بين ردود الوكيل في run_adaptive_memory_demonstration() وrun_memory_failure_demonstration(). هذا هو المفهوم الأهم في دفتر الملاحظات: تتطلّب المحادثة المتواصلة جلسة متواصلة واحدة.

7. الجلسة 5: وكيل التوجيه 🚏

roadmap5

لا يمكن للموظف الواحد إنجاز الكثير. للتعامل مع طلبات المستخدمين المعقّدة حقًا، نحتاج إلى فريق من الموظفين المتخصّصين. ولكن كيف نعرف الوكيل الذي يجب استخدامه لطلب بحث معيّن؟ وهنا يأتي دور Router Agent.

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

على سبيل المثال، يجب توجيه طلب البحث عن "أفضل سوشي" إلى foodie_agent، بينما يجب أن يتعامل weekend_guide_agent مع سؤال عن "حفلات موسيقية في نهاية هذا الأسبوع".

➡️ مكان العثور على هذه الميزة في المفكرة:

👉 هذا المفهوم أساسي في دفتر الملاحظات بأكمله، ولكن يتم تقديمه أولاً في الجزء 1: فوضى الوكلاء المتعدّدين - سير العمل التسلسلي 🧠→🤖→🤖 🌟

Router Agent

  • تعريفات الوكلاء: تحدّد خلية الرمز عدة وكلاء متخصصين (day_trip_agent وfoodie_agent وtransportation_agent)، والأهم من ذلك، router_agent. انتبه جيدًا إلى طلب التعليمات الخاص بـ router_agent، إذ يُطلب منه بشكل صريح عرض اسم أفضل وكيل للمهمة فقط.
  • منطق التنفيذ: توضّح الدالة run_sequential_app كيفية استدعاء router_agent أولاً للحصول على قرار (chosen_route)، ثم استخدام هذا القرار في حظر if/elif لتنفيذ الوكيل المتخصّص المناسب.

8. الجلسة 6: SequentialAgent ⛓️

roadmap6

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

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

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

➡️ مكان العثور على هذه الميزة في المفكرة:

👉 يتم تناول هذا الموضوع في الجزء 2 (طريقة ADK): فوضى الوكلاء المتعدّدين باستخدام SequentialAgent 🧠→⛓️→🤖. 🌟

Sequential Agent

  • إعادة تصميم الوكيل: في خلية الرمز الأولى من هذا القسم، لاحظ التغييرات الرئيسية في foodie_agent وtransportation_agent:
    • تم الآن منح "foodie_agent" "output_key="destination"". يطلب ذلك من حزمة تطوير التطبيقات (ADK) حفظ إجابتها النهائية في متغيّر اسمه destination في الحالة المشترَكة.
    • يحتوي طلب التعليمات في transportation_agent الآن على العنصر النائب {destination}. يُدرج ADK تلقائيًا القيمة من الحالة المشترَكة في هذا العنصر النائب.
  • تحديد سير العمل: يتم تحديد find_and_navigate_agent على أنّه SequentialAgent، ويتم ضبط sub_agents على [foodie_agent, transportation_agent]، ما يضمن تشغيلهما بهذا الترتيب بالضبط.
  • التنفيذ المبسّط: اطّلِع على الدالة run_sequential_app في هذا القسم. تمت إزالة منطق if/elif المعقّد. يتم الآن التعامل مع find_and_navigate_agent كوحدة واحدة قابلة للاستدعاء، ويتعامل حزمة تطوير التطبيقات (ADK) مع الخطوات التسلسلية الداخلية تلقائيًا.

9- الجلسة 7: LoopAgent 🔁

roadmap7

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

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

يوضّح الرسم البياني Planner Agent إنشاء خطة أولاً. بعد ذلك، ندخل LoopAgent. يتحقّق Critic Agent من الخطة. إذا كانت غير مثالية، تنشئ Refiner Agent نسخة جديدة، وتتكرّر العملية. إذا كانت الخطة جيدة، يستدعي Refiner Agent الأداة exit_loop، ويتم عرض الخطة النهائية التي تم التحقّق من صحتها.

وكيل Loop

➡️ مكان العثور على هذه الميزة في المفكرة:

👉 تم توضيح ذلك في أفكار متكرّرة باستخدام LoopAgent 🧠→🔁→🤖. 🌟

  • الوكلاء الأساسيون: يستخدم سير العمل planner_agent وcritic_agent وrefiner_agent.
  • تعريف Loop: يتم تعريف refinement_loop على أنّه LoopAgent ينسّق critic_agent وrefiner_agent وsets max_iterations=3.
  • شرط الخروج: تنتهي حلقة التكرار عندما يوافق critic_agent على الخطة، ما يؤدي إلى أن يستدعي refiner_agent أداة exit_loop المخصّصة.

10. الجلسة 8: ParallelAgent ⚡️

roadmap8

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

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

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

➡️ مكان العثور على هذا الخيار في المفكرة:

👉 يتم تفصيل سير العمل هذا في القسم Parallel Power with ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟

Parallel Agent

  • الوكلاء المتخصّصون: يتم تحديد ثلاثة وكلاء متخصّصين، ولكل منهم output_key فريد (مثل museum_result).
  • سير العمل المتوازي: يتم تعريف parallel_research_agent على أنّه ParallelAgent، مع إدراج وكلاء البحث الثلاثة كـ sub_agents.
  • خطوة التجميع: بعد الخطوة المتوازية، يجمع عامل synthesis_agent النهائي كل النتائج من الحالة المشتركة باستخدام عناصر نائبة ({museum_result} و{concert_result} وما إلى ذلك) لتنسيق ملخّص مرتّب.

11. الملحق: ADK Web - 🍎 لأجهزة Mac/Linux

roadmap9

سيساعدك هذا الدليل في إعداد وتشغيل "وكيل تخطيط الرحلات اليومية" في "حزمة تطوير التطبيقات" على جهازك.

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

  • الإصدار 3.8 أو الإصدارات الأحدث من Python
    • الإصدار 3.9 من Python أو إصدار أحدث: يتم تثبيت google-adk==1.5.0 (أحدث إصدار يتضمّن ميزات كاملة)
    • Python 3.8: تثبيت google-adk==0.3.0 (إصدار متوافق)
  • مفتاح واجهة برمجة التطبيقات في Google AI Studio
  • اتصال بالإنترنت

الخطوة 1: استنساخ المستودع

افتح Terminal ونفِّذ ما يلي:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

الخطوة 2: إعداد البيئة الافتراضية وتثبيت التبعيات

الخيار أ: الإعداد المبرمَج (مقترَح)

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

الخيار "ب": الإعداد اليدوي

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

الخطوة 3: 🔥 مهم - إنشاء متغيّرات البيئة

⚠️ لا تتخطَّ هذه الخطوة! أنشئ ملف .env في الدليل agent/:

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

أضِف الأسطر التالية إلى الملف:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 CRITICAL: استبدِل your_actual_api_key_here بمفتاح واجهة برمجة التطبيقات الفعلي.

الخطوة 4: تفعيل البيئة الافتراضية (إذا لم تكن نشطة)

source .adk_env/bin/activate

من المفترض أن يظهر الرمز (.adk_env) في بداية طلبك في نافذة Terminal.

الخطوة 5: تشغيل واجهة ويب ADK

adk web

الخطوة 6: فتح المتصفّح

  1. افتح المتصفّح وانتقِل إلى عنوان URL المعروض في نافذة الوحدة الطرفية (عادةً http://localhost:8000)
  2. في القائمة المنسدلة أعلى يمين الصفحة، انقر على agent.
  3. ابدأ الدردشة مع وكيل التخطيط لرحلتك اليومية.

ستظهر لك محادثة مثل: مثال على واجهة مستخدم ADK على الويب

إيقاف البيئة

عند الانتهاء من العمل على المشروع:

deactivate

يعمل هذا الأمر بالطريقة نفسها على كلّ من Mac/Linux وWindows. ستلاحظ أنّ البادئة (.adk_env) ستختفي من طلب المحطة الطرفية.

تحديد المشاكل وحلّها على أجهزة Mac

  • لم يتم العثور على Python: استخدِم python3 بدلاً من python
  • تم رفض الإذن: شغِّل chmod +x setup_venv.sh قبل تشغيل النص البرمجي

12. الملحق: ADK Web - 🪟 لمستخدمي Windows

roadmap9

سيساعدك هذا الدليل في إعداد وتشغيل "وكيل تخطيط الرحلات اليومية" في "حزمة تطوير التطبيقات" على جهازك.

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

  • الإصدار 3.8 أو الإصدارات الأحدث من Python
    • الإصدار 3.9 من Python أو إصدار أحدث: يتم تثبيت google-adk==1.5.0 (أحدث إصدار يتضمّن ميزات كاملة)
    • Python 3.8: تثبيت google-adk==0.3.0 (إصدار متوافق)
  • مفتاح واجهة برمجة التطبيقات في Google AI Studio
  • اتصال بالإنترنت

الخطوة 1: استنساخ المستودع

افتح "موجّه الأوامر" أو PowerShell ونفِّذ ما يلي:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

الخطوة 2: إعداد البيئة الافتراضية وتثبيت التبعيات

الخيار أ: الإعداد المبرمَج (مقترَح)

# Run the setup script in Command Prompt
setup_venv.bat

الخيار "ب": الإعداد اليدوي

بالنسبة إلى "موجه الأوامر":

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

بالنسبة إلى PowerShell:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

الخطوة 3: 🔥 مهم - إنشاء متغيّرات البيئة

⚠️ لا تتخطَّ هذه الخطوة! أنشئ ملف .env في الدليل agent/:

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

أضِف الأسطر التالية إلى الملف:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 CRITICAL: استبدِل your_actual_api_key_here بمفتاح واجهة برمجة التطبيقات الفعلي.

الخطوة 4: تفعيل البيئة الافتراضية (إذا لم تكن نشطة)

موجه الأوامر:

.adk_env\Scripts\activate

PowerShell:

.adk_env\Scripts\Activate.ps1

من المفترض أن ترى (.adk_env) في بداية طلبك.

الخطوة 5: تشغيل واجهة ويب ADK

adk web

الخطوة 6: فتح المتصفّح

  1. افتح المتصفّح وانتقِل إلى عنوان URL المعروض في نافذة الوحدة الطرفية (عادةً http://localhost:8000)
  2. في القائمة المنسدلة أعلى يمين الصفحة، انقر على agent.
  3. ابدأ الدردشة مع وكيل التخطيط لرحلاتك اليومية.

تحديد المشاكل وحلّها في Windows

  • خطأ في سياسة تنفيذ PowerShell: شغِّل Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

ستظهر لك محادثة مثل: مثال على واجهة مستخدم الويب في "حزمة تطوير التطبيقات"

إيقاف البيئة

عند الانتهاء من العمل على المشروع:

deactivate

يعمل هذا الأمر بالطريقة نفسها على كل من Mac/Linux وWindows. ستلاحظ أنّ البادئة (.adk_env) ستختفي من طلب المحطة الطرفية.