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

1. ما ستتعلمه

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

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

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

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

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

لِنبدأ. 🚀

2. إعداد GCP

إعداد مشروعك على Google Cloud Platform

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

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

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

الخطوة 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: نسخ رقم تعريف مشروعك

  • انتقِل إلى console.cloud.google.com.
  • انقر على القائمة المنسدلة الخاصة بأداة اختيار المشروع في أعلى الصفحة.
  • انقر على علامة التبويب "الكل" (لأنّ المشروع الجديد قد لا يظهر في "الأحدث" بعد).
  • اختَر رقم تعريف المشروع الذي أنشأته الآن.

03-05-project-all.png

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 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 🧠→⛓️→🤖. 🌟

الوكيل التسلسلي

  • إعادة تصميم الوكيل: في خلية الرمز الأولى من هذا القسم، لاحظ التغييرات الرئيسية على foodie_agent وtransportation_agent:
    • لدى foodie_agent الآن output_key="destination". يطلب ذلك من حزمة تطوير التطبيقات (ADK) حفظ إجابتها النهائية في متغيّر اسمه destination في الحالة المشترَكة.
    • يحتوي طلب التعليمات في transportation_agent الآن على العنصر النائب {destination}. تُدرج حزمة تطوير البرامج لإعلانات Google تلقائيًا القيمة من الحالة المشترَكة في هذا العنصر النائب.
  • تحديد سير العمل: يتم تحديد 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

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

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

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

وكيل Loop

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

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

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

👉 يتم توضيح سير العمل هذا بالتفصيل في القسم قوة التوازي مع ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟

Parallel Agent

  • الوكلاء المتخصّصون: يتم تحديد ثلاثة وكلاء متخصّصين، لكل منهم output_key فريد (مثل museum_result).
  • سير العمل المتوازي: يتم تعريف parallel_research_agent على أنّه ParallelAgent، مع إدراج وكلاء البحث الثلاثة كوكلاء فرعيين له.
  • خطوة التجميع: بعد الخطوة المتوازية، يجمع عامل 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. ابدأ الدردشة مع وكيل التخطيط لرحلتك اليومية.

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

إيقاف البيئة

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

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