تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

1. قبل البدء

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

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

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

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

ما ستتعلمه

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

المتطلبات

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

استرداد حساب فوترة تجريبي

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

فتح نافذة تصفُّح متخفٍ على المتصفّح
انتقِل إلى بوابة استلام الجوائز هذه.
سجِّل الدخول باستخدام حسابك الشخصي على Gmail
اتّبِع التعليمات المفصّلة الواردة في البوابة

2. مقدمة

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

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

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

3- إعداد "خدمات Google السحابية"

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

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

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

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

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

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

ضبط 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 العامة في النظام.

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

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

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

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

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

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

uv pip install google-adk

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

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

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'}، اتّبِع الخطوات التالية:

تحقَّق ممّا إذا كنت تستخدم رقم تعريف المشروع الصحيح في ملف .env
انتقِل إلى صفحة حساب الفوترة المرتبط لمعرفة ما إذا كان حساب الفوترة مرتبطًا من قبل.
إذا لم يكن كذلك، اختَر حساب فوترة تجريبي في 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

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

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

يتوفّر لك خياران للوصول إلى واجهة مستخدم التطوير:

الفتح من خلال Terminal

اضغط على Ctrl + Click أو Cmd + Click على الرابط (مثلاً، http://localhost:8000) كما هو موضّح في الوحدة الطرفية.

الفتح من خلال معاينة الويب

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

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

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

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

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

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

إذا كنت تريد إزالة الرمز من بيئة 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.

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