مجموعة أدوات تطوير التطبيقات (ADK): من الأساسيات إلى أدوات الذكاء الاصطناعي المتعددة

1. مقدمة

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

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

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

النماذج اللغوية الكبيرة مقابل الوكلاء

الدماغ (نموذج لغوي كبير): يوفّر إمكانات التحليل والتخطيط وفهم اللغة الطبيعية. وهي تحدّد الإجراءات التي يجب اتّخاذها.

الأيدي (الأدوات): هي واجهات برمجة التطبيقات وحِزم تطوير البرامج والوظائف المخصّصة التي تسمح للوكيل بالتفاعل مع العالم الواقعي. ينفّذ الخطة.

حزمة تطوير الوكلاء (ADK)

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

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

ما ستنشئه

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

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

مشروع Google Cloud تم تفعيل الفوترة فيه
متصفّح الويب

إنشاء مشروعك

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

تفعيل Cloud Shell

ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud Console ومحمَّلة مسبقًا باللغات المطلوبة. من Cloud Console، انقر على تفعيل Cloud Shell في أعلى يسار الصفحة:

بعد الاتصال بـ Cloud Shell، من المفترض أن يظهر لك أنّه تم إثبات هويتك وأنّ المشروع مضبوط على رقم تعريف مشروعك. نفِّذ الأمر التالي في Cloud Shell للتأكّد من إثبات هويتك:

gcloud auth list

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك:

gcloud config list project

إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:

gcloud config set project <YOUR_PROJECT_ID>

راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.

فتح "المحرّر"

في هذا الدرس التطبيقي، سنستخدم محرّر Cloud المضمّن. في نافذة Cloud Shell، انقر على الزر "فتح المحرّر" (Open editor) في أعلى يسار الصفحة. سيؤدي ذلك إلى فتح محرِّر VSCode.

3- إعداد ADK

لننتقل إلى "وحدة طرفية Cloud Shell" التي فعّلناها في القسم السابق:

إنشاء بيئة افتراضية وتفعيلها (يُنصح به)

من Cloud Shell Terminal، أنشئ بيئة افتراضية:

python -m venv .venv

تفعيل البيئة الافتراضية:

source .venv/bin/activate

تثبيت "حزمة تطوير التطبيقات"

pip install google-adk

4. مفتاح Google API

إنشاء مفتاح Google API باستخدام AI Studio:

انتقِل إلى https://aistudio.google.com/ وانقر على Get API Key من القائمة في أسفل يمين الصفحة.

ستظهر لك نافذة "مفاتيح واجهة برمجة التطبيقات"، انقر على "إنشاء مفتاح واجهة برمجة التطبيقات" في هذه النافذة:

سيظهر لك إشعار منبثق لإنشاء مفتاح جديد. سمِّ المفتاح بالاسم: healthy-hints-key

انتقِل إلى القائمة المنسدلة "اختيار مشروع مستورَد".

انقر على Import Project ، وستظهر نافذة جانبية تعرض جميع مشاريعك على Google Cloud، ثم اختَر المشروع الذي تريد العمل عليه.

انقر على "استيراد".

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

5- وكيل نموذجي

من نافذة Cloud Shell Terminal، أنشئ دليلاً جذريًا للوكيل في موقع المشروع المطلوب:

adk create healthy_hints

يمكنك اختيار أي نموذج، ولكن في هذا الدرس التطبيقي حول الترميز، سنستخدم gemini-2.5-flash.

في هذا الدرس التطبيقي، سنستخدم Google AI. الصِق مفتاح واجهة برمجة التطبيقات الذي أنشأته في الخطوة السابقة.

لنفتح المجلد الذي أنشأناه للتو. في القائمة الموجودة في أقصى اليمين، انقر على الرمز ، ثم انقر على "ملف" (File) -> "فتح مجلد" (Open Folder). اختَر المجلد healthy_hints الذي تم إنشاؤه للتو، وسيكون عادةً في المجلد /home/<username>.
عادةً ما يبدو هيكل المجلد healthy_hints على النحو التالي:

سيظهر ملف ‎ .env يحتوي على مفتاح Google API. يمكنك استخدام هذا الملف لضبط أي متغيّر بيئة.
يتم أيضًا إنشاء ملف آخر باسم agent.py، وهو ملف الوكيل الرئيسي. هذا هو المكان الذي يتم فيه إنشاء نموذج لوكيل رئيسي. لنلقِ نظرة فاحصة على محتوى هذا الملف. أولاً، نستورد llm_agent من ADK. بعد ذلك، نستخدم ADK DSL لإنشاء الوكيل الجذر. نحدّد اسم النموذج على أنّه Gemini-2.5-flash، ونسمّي الوكيل، ونقدّم وصفًا جيدًا له. التعليمات هي أهم شيء هنا، وهي المكان الذي نخبر فيه الوكيل بما عليه فعله بلغة طبيعية.
هذا الوكيل النموذجي عام جدًا، فهو يجيب عن أي سؤال يطرحه المستخدم.
لننفّذ هذا الوكيل الآن على جهازك. هناك طريقتان يمكنك من خلالهما التفاعل مع هذا الوكيل : واجهة سطر الأوامر والويب.
CLI: نفِّذ الأمر التالي من خارج دليل healthy_hints

adk run healthy_hints

أو إذا كنت داخل دليل healthy_hints، نفِّذ الأمر التالي:

adk run .

ستظهر لك نتيجة مشابهة لما يلي:

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

الويب: نفِّذ الأمر التالي من الدليل الرئيسي لـ healthy_hints :

adk web

6. Multi-tool Agent

الأداة هي جزء معياري من الرمز البرمجي، وهي عادةً عبارة عن دالة أو واجهة برمجة تطبيقات، وتسمح للوكيل بالتفاعل مع العالم الخارجي خارج نطاق معرفته الداخلية.

أنواع الأدوات في "مجموعة أدوات Android"

أدوات الدوال: منطق مخصّص تكتبه بنفسك. على سبيل المثال، دالة تتصل بقاعدة البيانات المحدّدة أو "محلّل سجلّ" مخصّص لتنسيق شركتك الفريد.
الأدوات المضمّنة: إمكانات جاهزة للاستخدام تقدّمها Google أو ADK، مثل بحث Google أو Code Interpreter أو محرك RAG من Google.
Agents-as-Tools: في أنظمة "الأدوات المتعددة" أو "الوكلاء المتعددين" المتقدّمة، يمكن أن يعمل وكيل متخصص كأداة لوكيل آخر. على سبيل المثال، يمكن أن يكون "وكيل البحث" أداة يستخدمها "وكيل مدير البحث".

في هذا الدرس التطبيقي حول الترميز، سنتناول "أدوات الدوال". الآن، لنطوّر الوكيل ونجعله متعدد الأدوات.

لنضِف طريقة جديدة get_weather في الملف agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

لنعدّل الملف agent.py ونغيّر اسم الوكيل ووصفه وتعليماته:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

لقد أنشأنا حتى الآن أداة واحدة فقط. لننشئ الآن أدوات متعددة:

لننشئ طريقة أخرى باسم get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

لنعدّل الوكيل لاستدعاء هذه الأداة أيضًا:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

لقد عدّلنا الوصف والتعليمات والأدوات وفقًا لذلك. لنبدأ الآن بتشغيل هذا الوكيل المعدَّل. في هذه المرة، سيردّ الوكيل أيضًا بالوقت الحالي وحالة الطقس.

7. دمج حزمة تطوير البرامج (SDK)

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

لننشئ حزمة أولاً لتحميل الصورة في Google Cloud Storage. لنفتح علامة تبويب جديدة وننتقل إلى https://console.cloud.google.com/ ثم نكتب "التخزين في السحابة الإلكترونية" في شريط البحث. الآن، اختَر Cloud Storage ضمن "المنتجات والصفحات":

سينقلك هذا الإجراء إلى صفحة النظرة العامة في Google Cloud Storage. انقر على الزر Create bucket. في صفحة إنشاء حزمة، أدخِل اسم الحزمة. يمكن أن يكون الاسم أي شيء، ولكن في هذا الدرس البرمجي، سنستخدم healthy-hints-bucket-kolkata . اترك كل الخيارات الأخرى كما هي وانقر على الزر Create.

لننشئ ملفًا جديدًا باسم requirements.txt ونضيف إليه google-cloud-storage. سنستخدم حزمة تطوير البرامج (SDK) الخاصة بخدمة "مساحة تخزين Google Cloud" في Python لتحميل الصورة في "مساحة التخزين".

لنبدأ أولاً بتثبيت التبعيات:

pip install -r requirements.txt

قد تحتاج إلى تفعيل Storage API أولاً. نفِّذ الأمر التالي في الوحدة الطرفية لإجراء ذلك:

gcloud services enable storage.googleapis.com

لنبدأ الآن بإضافة أداة جديدة لتحميل الصورة.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

لنعدّل الآن الوكيل لكي يستخدم الأداة الجديدة:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

سنضيف الآن أداة أخرى لقراءة المكوّنات من الصورة. لنضِف google-cloud-vision في requirements.txt ونثبّت التبعية الجديدة.

pip install -r requirements.txt

مرة أخرى، قد تحتاج إلى تفعيل Vision API أولاً. نفِّذ الأمر التالي في الوحدة الطرفية لإجراء ذلك:

gcloud services enable vision.googleapis.com

لنضِف الآن أداة جديدة read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

والآن، لنعدّل الوكيل لاستخدام هذه الأداة

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. الخاتمة

تهانينا على إكمال برنامج Healthy Hints التعليمي. لقد نجحت في تحويل الذكاء الاصطناعي العادي من نظام إنشاء النص إلى وكيل متعدد الأدوات استباقي. باستخدام "حزمة تطوير التطبيقات" لدمج Vision API وCloud Storage SDK، منحتَ الوكيل "عيونًا" لقراءة التصنيفات و"ذاكرة" لأرشفتها. لقد رأيت كيف يقرّر الوكيل بشكل مستقل متى يجب حفظ ملف وكيفية تفسير البيانات الأولية لتقديم نصائح صحية واقعية.

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