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

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

1. قبل البدء

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

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

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

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

ما ستتعلمه

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

المتطلبات

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

2. مقدمة

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

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

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

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

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

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

اختيار مشروع Google Cloud أو إنشاؤه

انتقِل إلى Google Cloud Console.
في أعلى الصفحة، انقر على القائمة المنسدلة لأداة اختيار المشاريع (بجانب شعار Google Cloud).
اختَر مشروعًا حاليًا أو أنشِئ مشروعًا جديدًا.

تفعيل الفوترة

تأكَّد من تفعيل الفوترة لمشروع Google Cloud الذي اخترته.
يمكنك التعرّف على كيفية التحقّق من تفعيل الفوترة في مشروع معيّن باتّباع التعليمات الواردة في مستندات الفوترة في Google Cloud.

ضبط Cloud Shell

لنحرص الآن على إعدادك بشكل صحيح في Cloud Shell، وهي واجهة سطر أوامر سهلة الاستخدام مباشرةً في Google Cloud Console.

تشغيل Cloud Shell

في أعلى يسار Google Cloud Console، سيظهر لك رمز يشبه نافذة طرفية (>_). انقر عليه لتفعيل Cloud Shell.

تفويض الوصول

إذا طُلب منك ذلك، انقر على تفويض لمنح Cloud Shell الأذونات اللازمة للتفاعل مع مشروعك على Google Cloud.

إثبات ملكية حسابك:

بعد تحميل Cloud Shell، لنؤكّد أنّك تستخدم حساب Google Cloud الصحيح. نفِّذ الأمر التالي:

gcloud auth list

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

Credentialed Accounts

ACTIVE: *
ACCOUNT: current_account@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

تبديل الحسابات (إذا لزم الأمر):

إذا لم يكن الحساب النشط هو الحساب الذي تريد استخدامه في هذا الدرس العملي، بدِّل إلى الحساب الصحيح باستخدام هذا الأمر، مع استبدال <your_desired_account@example.com> بعنوان البريد الإلكتروني الفعلي الذي ستستخدمه في هذا الدرس العملي:

gcloud config set account <your_desired_account@example.com

تأكيد مشروعك

بعد ذلك، سنتأكّد من ضبط Cloud Shell لاستخدام مشروع Google Cloud الصحيح. التشغيل:

gcloud config list project

ستظهر لك قائمة إعدادات. ابحث عن القسم [core] وتأكَّد من أنّ قيمة المشروع تتطابق مع رقم تعريف مشروع Google Cloud الذي تريد استخدامه في هذا الدرس العملي:

[core]
project = <current-project-id>

ضبط مشروعك (إذا لزم الأمر)

إذا كانت قيمة project ID غير صحيحة، اضبطها على مشروعك المطلوب باستخدام الأمر التالي:

gcloud config set project <your-desired-project-id>

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

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

gcloud services enable aiplatform.googleapis.com

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

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

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

‫uv هي أداة حديثة وسريعة وفعّالة لإدارة مشاريع Python وبيئاتها، وتجمع بين الوظائف التي يمكن العثور عليها عادةً في أدوات مثل pip وvenv وpip-tools وpipx. وهي مكتوبة بلغة Rust لتكون سريعة.

يتوفّر uv في Cloud Shell، لذا يمكننا البدء على الفور.

التحقّق من تثبيت uv بشكل صحيح

uv --version

إنشاء مجلد مشروع جديد لوكيل الذكاء الاصطناعي

uv init ai-agents-adk
cd ai-agents-adk

إنشاء بيئة افتراضية باستخدام الإصدار 3.12 من Python

uv venv --python 3.12

تثبيت مكتبة Google ADK في بيئتك الافتراضية

uv add google-adk

التحقّق مما إذا تم تثبيت حزمة google-adk بنجاح

uv pip list | grep google-adk

إذا ظهر سطر إخراج يتضمّن google-adk وإصداره، يمكنك الانتقال إلى الخطوة التالية.

5- إنشاء وكيل

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

تعمل هذه الملفات الثلاثة معًا لجعل الوكيل قابلاً للاكتشاف والتشغيل والإعداد:

agent.py: هذا هو جوهر وكيلك. يحتوي على رمز Python الأساسي الذي يحدّد سلوك الوكيل، بما في ذلك اسمه والنموذج اللغوي الكبير (LLM) الذي يستخدمه كـ "عقل" والتعليمات الأساسية التي توجّه ردوده.
‫__init__.py: في Python، يحدّد الملف __init__.py مجلدًا كحزمة Python. بالنسبة إلى ADK، يكون ذلك ضروريًا لأنّه يساعد إطار العمل في العثور على تعريف الوكيل وتحميله من agent.py. في مشاريع ADK البسيطة، غالبًا ما يحتوي على سطر واحد لاستيراد وحدة agent، ما يتيح الوصول إلى الوكيل من خلال مشغّل ADK.
.env: يُستخدم هذا الملف (اختصارًا لكلمة "بيئة") لتخزين المعلومات الحساسة ومتغيّرات الإعداد التي يحتاجها برنامجك، مثل مفاتيح واجهة برمجة التطبيقات ومعرّفات المشاريع والمواقع الجغرافية. يُعد الاحتفاظ بهذه التفاصيل في ملف .env منفصل من أفضل الممارسات المتعلّقة بالأمان وإمكانية النقل، لأنّه يمنع الترميز الثابت للبيانات الحساسة مباشرةً في الرمز. ويتيح لك أيضًا تغيير الإعدادات بسهولة بدون تعديل منطق الوكيل الرئيسي.

استخدِم الأوامر أدناه لإنشاء هذه الملفات في مجلد مخصّص لمساعدك الشخصي:

uv run 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

أخيرًا، سيُطلب منك تأكيد رقم تعريف مشروع Google Cloud ومنطقته. إذا كانت القيم المُعبّأة مسبقًا (current-project-id وcurrent-region) هي القيم التي تريد استخدامها، ما عليك سوى الضغط على Enter لكل سؤال.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

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

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

الآن، انقر على الزر فتح المحرّر في أعلى نافذة Cloud Shell. سيؤدي النقر على هذا الزر إلى نقلك إلى نافذة المحرّر، ما يسهّل عليك استكشاف محتوى ملفاتك. قد يستغرق التبديل بعض الوقت. إذا بقيت عالقًا على شاشة تحميل لأكثر من بضع دقائق، جرِّب إعادة تحميل المتصفّح.

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

إذا لم يظهر لك الملف .env في المجلد، انتقِل إلى شريط القوائم في أعلى الصفحة، وانقر على "عرض" (View)، ثم اختَر تبديل الملفات المخفية (Toggle Hidden Files). هذا إعداد شائع لأنّ ملفات .env تكون مخفية غالبًا بشكل تلقائي لمنع عرضها عن طريق الخطأ.

لنستكشف محتوى كل ملف.

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

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

بعد توفّر الملفات الثلاثة، يمكنك تشغيل البرنامج مباشرةً من نافذة الأوامر. لإجراء ذلك، عليك فتح نافذة "الوحدة الطرفية". يمكنك إجراء ذلك من خلال النقر على Terminal في شريط القوائم، ثم اختيار New Terminal.

بعد توفّر الوحدة الطرفية، يمكنك بدء تشغيل الوكيل باستخدام الأمر adk run. بما أنّ هذه نافذة وحدة طرفية جديدة ونحن نستخدم uv، عليك أولاً الانتقال إلى المجلد ai-agent-adk ثم إضافة البادئة uv run إلى الأمر adk run.

اكتب هذه الأوامر في الوحدة الطرفية:

cd ai-agents-adk
uv run adk run personal_assistant

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

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

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

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

إذا كنت لا تزال في الجلسة السابقة، ما عليك سوى كتابة exit في نافذة الجهاز الطرفي لإغلاقها. بعد إغلاق الجلسة السابقة، اكتب الأمر التالي في الوحدة الطرفية:

uv run 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 + النقر أو Cmd + النقر على عناوين URL (مثلاً http://localhost:8000) من النافذة الطرفية.

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

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

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

8. تنظيف

بما أنّ هذا الدرس العملي لا يتضمّن أي منتجات طويلة الأمد، يكفي إيقاف جلسات الوكيل النشطة (مثل مثيل adk web في الوحدة الطرفية) بالضغط على Ctrl + 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 نهائيًا، يُرجى الرجوع إلى الدليل الرسمي للحصول على تعليمات تفصيلية.

9- الخاتمة

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

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