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

1. ما ستتعلمه

مرحبًا بك في "الدورة التدريبية المتقدّمة حول حزمة تطوير التطبيقات" (ADK): رحلتك إلى أنظمة المتعدّدة الوكلاء

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

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

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

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

لِنبدأ. 🚀

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

إعداد مشروعك على Google Cloud Platform ومفتاح Gemini API

لتشغيل وكلاء الذكاء الاصطناعي، نحتاج إلى عنصرين: مشروع على 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 : https://aistudio.google.com/
  • سجِّل الدخول باستخدام حسابك على Gmail.
  • انقر على الزر "الحصول على مفتاح واجهة برمجة التطبيقات"، والذي يظهر عادةً في لوحة التنقّل على يمين الصفحة أو في أعلى يسارها.
  • في مربّع الحوار "مفاتيح واجهة برمجة التطبيقات"، انقر على "إنشاء مفتاح واجهة برمجة التطبيقات في مشروع جديد". إنشاء مفتاح واجهة برمجة التطبيقات في مشروع جديد
  • اختَر المشروع الجديد الذي أنشأته والذي تم إعداد حساب الفوترة فيه. اختَر المشروع الجديد
  • سيتم إنشاء مفتاح واجهة برمجة تطبيقات جديد لك. انسخ هذا المفتاح على الفور وخزِّنه مؤقتًا في مكان آمن (مثل مدير كلمات المرور أو ملاحظة آمنة). هذه هي القيمة التي ستستخدِمها في الخطوات التالية.

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

roadmap1

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

  • العميل: هو العقل الأساسي للعملية. ويتم تحديدها من خلال التعليمات (شخصيتها ومهمتها) ونموذج الذكاء الاصطناعي الذي تستخدمه (مثل 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 أداة Simple FunctionTool: استدعاء واجهة برمجة تطبيقات للطقس في الوقت الفعلي. 🌟

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 الوكيل كأداة: استشارة أحد المتخصّصين 🧑‍🍳.🌟

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

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

  • The Specialists:
    • 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 Agent

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

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

  • الوكلاء الأساسيون: تستخدم مهمة سير العمل planner_agent وcritic_agent وrefiner_agent.
  • تعريف الحلقة: يتم تعريف 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.
  • خطوة التجميع: بعد الخطوة المتوازية، يجمع عامل التجميع النهائي جميع النتائج من الحالة المشترَكة باستخدام عناصر نائبة ({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 API
  • اتصال بالإنترنت

الخطوة 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

🚨 مهم: استبدِل 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. ابدأ الدردشة مع وكيل التخطيط لرحلتك اليومية.

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

إيقاف البيئة

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

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 API
  • اتصال بالإنترنت

الخطوة 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

🚨 مهم: استبدِل 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) ستختفي من طلبك في الجهاز.