إنشاء وكلاء الذكاء الاصطناعي باستخدام "حزمة تطوير التطبيقات": الأساس

1. قبل البدء

يُرجى قراءة ما يلي:

يتطلّب هذا البرنامج التعليمي مشروعًا على Google Cloud مع حساب فوترة نشط.

للمشاركين في ورش العمل التي تتطلّب الحضور شخصيًا

• اتّبِع تعليمات الإعداد والفوترة المحدّدة التي يقدّمها المعلّم.

للمستخدمين الذين يدرسون بأنفسهم

• اتّبِع الخطوات التالية للاستفادة من فترة تجريبية:

1. افتح نافذة تصفّح متخفّي في المتصفّح.
2. انتقِل إلى بوابة استرداد القيمة هذه.
3. سجِّل الدخول باستخدام حسابك الشخصي على Gmail.
4. اتّبِع التعليمات المفصّلة الواردة في البوابة.

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

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

يمكنك إكمال هذا الدرس التطبيقي حول الترميز في بيئتك المحلية أو على Google Cloud. للحصول على أفضل تجربة متسقة، ننصحك باستخدام Cloud Shell من بيئة Google Cloud. توفّر Cloud Shell أيضًا مساحة تخزين ثابتة بسعة 5 غيغابايت في الدليل $HOME. ويفيد ذلك في تخزين النصوص البرمجية أو ملفات الإعداد أو المستودعات المستنسخة.

يمكنك أيضًا الوصول إلى هذا الدرس التطبيقي حول الترميز من خلال عنوان URL المختصر هذا: goo.gle/adk-foundation.

ملاحظة: إذا اخترت العمل على جهازك، قد تحتاج إلى خطوات إضافية للإعداد والتثبيت والمصادقة، وهي غير مشمولة في قسم إعداد البيئة في هذا المختبر.

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

• فهم مفاهيم الذكاء الاصطناعي التوليدي
• إتقان أساسي للبرمجة بلغة Python
• الإلمام بسطر الأوامر / نافذة الأوامر

ما ستتعلمه

• كيفية إعداد بيئة Python
• كيفية إنشاء وكيل مساعد شخصي بسيط باستخدام حزمة ADK
• كيفية تشغيل الوكيل واختباره وتصحيح أخطائه

المتطلبات

• جهاز كمبيوتر يعمل وشبكة Wi-Fi موثوقة
• متصفّح، مثل Chrome، للوصول إلى Google Cloud Console
• عقل فضولي وشغف بالتعلّم

2. مقدمة

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

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

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

3- إعداد "خدمات Google Cloud"

إنشاء مشروع على Google Cloud

ابدأ بإنشاء مشروع جديد على Google Cloud حتى يتم عزل الأنشطة من هذا الدرس التطبيقي حول الترميز ضمن هذا المشروع الجديد فقط.

1. انتقِل إلى console.cloud.google.com/projectcreate
2. أدخِل المعلومات المطلوبة:

• اسم المشروع: يمكنك إدخال أي اسم تريده (مثل genai-workshop).
• الموقع الجغرافي: اتركه على بدون مؤسسة
• حساب الفوترة: إذا ظهر لك هذا الخيار، اختَر حساب الفوترة التجريبي على Google Cloud Platform. لا تقلق إذا لم يظهر لك هذا الخيار. ما عليك سوى الانتقال إلى الخطوة التالية.

3. انسخ رقم تعريف المشروع الذي تم إنشاؤه، وستحتاج إليه لاحقًا.

4. إذا كانت كلّ التفاصيل صحيحة، انقر على الزر إنشاء.

ضبط Cloud Shell

بعد إنشاء مشروعك بنجاح، اتّبِع الخطوات التالية لإعداد Cloud Shell.

1. تشغيل Cloud Shell

انتقِل إلى shell.cloud.google.com، وإذا ظهرت لك نافذة منبثقة تطلب منك التفويض، انقر على تفويض.

2. تحديد رقم تعريف المشروع

نفِّذ الأمر التالي في نافذة Cloud Shell الطرفية لضبط رقم تعريف المشروع الصحيح. استبدِل <your-project-id> برقم تعريف المشروع الفعلي الذي نسخته من خطوة إنشاء المشروع أعلاه.

gcloud config set project <your-project-id>

من المفترض أن يظهر لك الآن أنّه تم اختيار المشروع الصحيح في نافذة Cloud Shell. يتم تمييز رقم تعريف المشروع المحدّد باللون الأصفر.

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

لاستخدام خدمات Google Cloud، يجب أولاً تفعيل واجهات برمجة التطبيقات الخاصة بها لمشروعك. نفِّذ الأوامر أدناه في وحدة Cloud Shell الطرفية لتفعيل الخدمات لهذا الدرس التطبيقي حول الترميز:

gcloud services enable aiplatform.googleapis.com

إذا تمت العملية بنجاح، سيظهر الرمز Operation/... finished successfully في جهازك.

4. إنشاء بيئة Python افتراضية

قبل بدء أي مشروع Python، من الممارسات الجيدة إنشاء بيئة افتراضية. يؤدي ذلك إلى عزل التبعيات الخاصة بالمشروع، ما يمنع حدوث تعارضات مع المشاريع الأخرى أو حِزم Python العامة للنظام.

ملاحظة: ستستخدم uv لإنشاء بيئتنا الافتراضية بدلاً من حزمة venv العادية. وهي حزمة Python ومدير مشاريع سريعان للغاية ومكتوبان بلغة Rust.

إذا كنت مهتمًا، يمكنك الاطّلاع على مزيد من المعلومات حول هذا الموضوع في مستندات uv الرسمية.

1. أنشئ دليل المشروع وانتقِل إليه:

mkdir -p ai-agents-adk
cd ai-agents-adk

2. إنشاء بيئة افتراضية وتفعيلها:

uv venv --python 3.12
source .venv/bin/activate

سيظهر لك البادئة (ai-agents-adk) قبل طلب المحطة الطرفية، ما يشير إلى أنّ البيئة الافتراضية نشطة.

3. صفحة تثبيت حزمة تطوير التطبيقات

uv pip install google-adk

ملاحظة: إذا أغلقت نافذة الوحدة الطرفية عن طريق الخطأ، عليك الانتقال إلى المجلد ai-agents-adk وتنفيذ source .venv/bin/activate مرة أخرى.

5- إنشاء وكيل

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

• ‫agent.py: يحتوي على رمز Python الأساسي الخاص بالوكيل، ويحدّد اسمه والنموذج اللغوي الكبير الذي يستخدمه والتعليمات الأساسية.
• ‫__init__.py: يحدّد الدليل كحزمة Python، ما يساعد ADK في العثور على تعريف الوكيل وتحميله.
• ‫.env: تخزِّن هذه السمة معلومات حساسة ومتغيّرات الإعدادات، مثل مفتاح واجهة برمجة التطبيقات ورقم تعريف المشروع والموقع الجغرافي.

سينشئ هذا الأمر دليلاً جديدًا باسم personal_assistant يحتوي على الملفات الأساسية الثلاثة.

adk create personal_assistant

بعد تنفيذ الأمر، سيُطلب منك اختيار بعض الخيارات لإعداد برنامجك.

في الخطوة الأولى، اختَر الخيار 1 لاستخدام نموذج gemini-2.5-flash، وهو نموذج سريع وفعّال ومثالي للمهام الحوارية.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

في الخطوة الثانية، اختَر Vertex AI (الخيار 2)، وهي منصة ذكاء اصطناعي مُدارة وفعّالة من Google Cloud، كمزوّد خدمة الخلفية.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

بعد ذلك، عليك التأكّد من أنّ رقم تعريف المشروع المعروض بين قوسين مربّعين [...] تم ضبطه بشكل صحيح. إذا كان كذلك، اضغط على Enter. إذا لم يكن كذلك، أدخِل رقم تعريف المشروع الصحيح في الطلب التالي:

Enter Google Cloud project ID [your-project-id]:

أخيرًا، اضغط على Enter عند السؤال التالي لاستخدام us-central1 كمنطقة لهذا الدرس العملي.

Enter Google Cloud region [us-central1]:

من المفترَض أن تظهر لك نتيجة مشابهة في نافذة الأوامر.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

6. استكشاف رموز الوكلاء

للاطّلاع على الملفات التي تم إنشاؤها، افتح المجلد ai-agents-adk في "محرِّر Cloud Shell".

• انقر على ملف > فتح مجلد... في القائمة العلوية.
• ابحث عن مجلد ai-agents-adk واختَره
• انقر على موافق.

إذا لم يظهر شريط القوائم العلوي، يمكنك أيضًا النقر على رمز المجلدات واختيار فتح المجلد (Open Folder).

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

بعد تحميل نافذة "المحرّر" بالكامل، انتقِل إلى المجلد personal-assistant. ستظهر لك الملفات اللازمة كما هو مذكور أعلاه (agent.py و__init__.py و.env).

يكون ملف .env مخفيًا غالبًا بشكل تلقائي. لإظهارها في محرِّر Cloud Shell، اتّبِع الخطوات التالية:

• انتقِل إلى شريط القوائم في أعلى الصفحة.
• انقر على عرض.
• انقر على تبديل الملفات المخفية.

استكشاف محتوى كل ملف

agent.py

ينشئ هذا الملف مثيلاً للوكيل باستخدام الفئة Agent من المكتبة google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent: يستورد هذا السطر فئة Agent الضرورية من مكتبة ADK.
• root_agent = Agent(...): هنا، يمكنك إنشاء مثيل لوكيل الذكاء الاصطناعي.
• استبدِل name="root_agent" بمعرّف فريد خاص بالوكيل. هذه هي الطريقة التي سيتعرّف بها "مساعد Google" على وكيلك ويشير إليه.
• model="gemini-2.5-flash": تحدّد هذه المَعلمة الأساسية النموذج اللغوي الكبير (LLM) الذي سيستخدمه الوكيل كـ "عقل" أساسي للفهم والاستدلال وإنشاء الردود. ‫gemini-2.5-flash هو نموذج سريع وفعّال ومناسب لمهام المحادثة.
• description="...": تقدّم هذه السمة ملخّصًا موجزًا عن غرض الوكيل أو إمكاناته. الوصف مخصّص بشكل أكبر لفهم البشر أو لكي تفهم الوكلاء الآخرين في نظام يستند إلى عدّة وكلاء ما يفعله هذا الوكيل تحديدًا. ويُستخدَم غالبًا لتسجيل البيانات أو تصحيح الأخطاء أو عند عرض معلومات عن الوكيل.
• instruction="...": هذا هو طلب النظام الذي يوجّه سلوك الوكيل ويحدّد شخصيته. يحدد هذا الإجراء طريقة عمل النموذج اللغوي الكبير والغرض الأساسي منه، وفي هذه الحالة، يحدد هذا الإجراء دور الوكيل على أنّه "مساعد مفيد". هذه التعليمات أساسية لتحديد أسلوب الوكيل الحواري وإمكاناته.

init.py

هذا الملف ضروري لكي يتعرّف Python على personal-assistant كحزمة، ما يسمح لأداة ADK باستيراد ملف agent.py بشكل صحيح.

from . import agent

• from . import agent: ينفّذ هذا السطر عملية استيراد نسبية، ويطلب من Python البحث عن وحدة باسم agent (التي تتوافق مع agent.py) ضِمن الحزمة الحالية (personal-assistant). يضمن هذا السطر البسيط أنّه عندما يحاول ADK تحميل وكيل personal-assistant، يمكنه العثور على root_agent المحدّد في agent.py وتهيئته. وحتى إذا كان فارغًا، فإنّ وجود __init__.py هو ما يجعل الدليل حزمة Python.

‎.env

يحتوي هذا الملف على إعدادات خاصة بالبيئة وبيانات اعتماد حسّاسة.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI: يوضّح هذا الرمز لحزمة تطوير الوكيل أنّك تنوي استخدام خدمة Vertex AI من Google في عمليات الذكاء الاصطناعي التوليدي. وهذا أمر مهم للاستفادة من الخدمات المُدارة والنماذج المتقدّمة في Google Cloud.
• GOOGLE_CLOUD_PROJECT: سيحتوي هذا المتغيّر على المعرّف الفريد لمشروعك على Google Cloud. تحتاج حزمة ADK إلى ذلك لربط وكيلك بموارد السحابة الإلكترونية بشكل صحيح وتفعيل الفوترة.
• استبدِل GOOGLE_CLOUD_LOCATION بمنطقة Google Cloud التي تتوفّر فيها موارد Vertex AI (مثل us-central1). يضمن استخدام الموقع الجغرافي الصحيح قدرة الوكيل على التواصل بفعالية مع خدمات Vertex AI في تلك المنطقة.

ملاحظة: أطلقت Google للتو Gemini 3.0. إذا أردت تجربة ذلك، ما عليك سوى فتح agent.py وتغيير متغيّر النموذج إلى gemini-3.0-pro-preview..

7. تشغيل الوكيل على "الوحدة الطرفية"

بعد توفّر الملفات الثلاثة، يمكنك تشغيل الوكيل مباشرةً من نافذة الأوامر. لتنفيذ ذلك، شغِّل الأمر adk run التالي في الوحدة الطرفية:

adk run personal_assistant

إذا تم إعداد كل شيء بشكل صحيح، ستظهر لك نتيجة مشابهة في نافذة الأوامر. لا تقلق بشأن التحذيرات في الوقت الحالي، فما دام يظهر لك [user]:، يمكنك المتابعة.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

يمكنك الدردشة مع موظّف الدعم. اكتب شيئًا مثل "مرحبًا. ما الذي يمكنك فعله نيابةً عني؟"، وسيصلك ردّ.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

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

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

تتطلّب طريقة واجهة برمجة التطبيقات هذه تفعيل الفوترة

إذا تلقّيت رسالة تفيد بأنّ {‘message': ‘This API method requires billing to be enabled'}، اتّبِع الخطوات التالية:

1. تحقَّق ممّا إذا كنت تستخدم رقم تعريف المشروع الصحيح في ملف .env
2. انتقِل إلى صفحة حساب الفوترة المرتبط لمعرفة ما إذا كان حساب الفوترة مرتبطًا من قبل.
3. إذا لم يكن كذلك، اختَر حساب فوترة تجريبي في Google Cloud Platform من الخيار

لم يتم استخدام Vertex AI API في المشروع

إذا تلقّيت رسالة خطأ تحتوي على {'message': 'Vertex AI API has not been used in project...'}، فعِّل Vertex AI API عن طريق كتابة ما يلي في نافذة الأوامر:

gcloud services enable aiplatform.googleapis.com

إذا تمت العملية بنجاح، سيظهر الرمز Operation/... finished successfully في جهازك.

أخطاء أخرى

إذا تلقّيت أي أخطاء أخرى غير مذكورة أعلاه، حاوِل إعادة تحميل علامة التبويب Cloud Shell في المتصفّح (وأعِد التفويض إذا طُلب منك ذلك).

8. تشغيل الوكيل على واجهة مستخدم الويب الخاصة بالتطوير

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

إذا كانت نافذة الجهاز لا تزال تعمل adk run، اكتب exit لإغلاقها قبل كتابة الأمر.

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

ملاحظة: على الرغم من أنّ تنفيذ الأمر adk web يكفي عادةً في معظم الحالات، لضمان الوصول بشكل صحيح أثناء تشغيل الخادم من نافذة Cloud Shell، عليك تضمين العلامة --allow_origins.

يجب أن تعرض الوحدة الطرفية نتيجة مشابهة لما يلي:

...
INFO:     Started server process [4978]
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)

يمكنك الوصول إلى واجهة مستخدم التطوير باستخدام إحدى الطريقتَين التاليتَين:

1. مباشرةً من خلال "الوحدة الطرفية": استخدِم Ctrl + النقر (أو Cmd + النقر) على الرابط المقدَّم، مثل http://localhost:8000.
2. استخدام ميزة "معاينة الويب":

• انقر على الزر معاينة الويب.
• اختَر تغيير المنفذ.
• أدخِل رقم المنفذ (على سبيل المثال، 8000).
• انقر على تغيير ومعاينة.

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

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

9- التنظيف (اختياري)

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

بما أنّ هذا الدرس التطبيقي حول الترميز لا يتضمّن أي منتجات تعمل لفترة طويلة، يكفي إيقاف جلسات الوكيل النشط (مثل مثيل adk web في Terminal) عن طريق الضغط على Ctrl + C أو Cmd + C في Terminal.

حذف مجلدات وملفات مشاريع الوكلاء

إذا كنت تريد إزالة الرمز من بيئة Cloud Shell فقط، استخدِم الأوامر التالية:

cd ~
rm -rf ai-agents-adk

إيقاف واجهة برمجة التطبيقات Vertex AI API

لإيقاف واجهة برمجة التطبيقات Vertex AI API التي تم تفعيلها سابقًا، نفِّذ الأمر التالي:

gcloud services disable aiplatform.googleapis.com

إيقاف مشروع Google Cloud بالكامل

إذا أردت إيقاف مشروعك على Google Cloud نهائيًا، يُرجى الرجوع إلى الدليل الرسمي للحصول على تعليمات تفصيلية.

10. الخاتمة

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

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