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

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

1. قبل البدء

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

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

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

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

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

ما ستتعلمه

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

المتطلبات

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

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

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

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

2. مقدمة

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

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

تقدّم حزمة تطوير التطبيقات (ADK) ثلاث فئات من الأدوات:

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

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

3- البدء: الوكيل الأساسي

قبل أن تتمكّن من تزويد وكيل بالأدوات، يجب أن يكون لديك وكيل أساسي للعمل معه. اختَر المسار الأنسب لمستوى تقدّمك.

المسار أ: المتابعة من الدرس التطبيقي الأساسي

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

المسار "ب": البدء من جديد

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

بعد إكمال الخطوات، ستكون جاهزًا لبدء رحلة التعلّم.

4. إنشاء أداة مخصّصة لتحويل العملات

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

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

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

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

أنهِ عملية الوكيل الجارية باستخدام اختصار لوحة المفاتيح Ctrl + C في نافذة الوحدة الطرفية.

إنشاء ملف `custom_functions.py`

أنشئ ملف Python باسم custom_functions.py في المجلد personal_assistant عن طريق كتابة هذا الأمر في الوحدة الطرفية.

touch personal_assistant/custom_functions.py

يجب أن تبدو بنية المجلد على النحو التالي:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

انقر على custom_functions.py في أداة تعديل الرموز. سيحتوي هذا الملف على دالة Python المسؤولة عن استرداد بيانات سعر الصرف من واجهة برمجة تطبيقات خارجية.

انسخ الرمز التالي والصِقه داخل:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

الآن، عدِّل ملف agent.py: استورِد الدالة get_fx_rate وعيِّنها كـ FunctionTool.

تعديل ملف `agent.py`

انسخ كتلة الرموز هذه واستبدِل المحتوى الحالي لملف agent.py بما يلي:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

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',
    tools=[FunctionTool(get_fx_rate)]
)

بعد إجراء التغييرات، ابدأ تشغيل الوكيل مرة أخرى عن طريق كتابة:

adk web

عندما يصبح المساعد متاحًا، اطرح السؤال نفسه مرة أخرى: "ما هو سعر الصرف من الدولار السنغافوري إلى الين الياباني؟"

في هذه المرة، من المفترض أن يظهر لك سعر الصرف الفعلي الذي توفّره أداة get_fx_rate.

يمكنك طرح أي أسئلة متعلّقة بتحويل العملات كما تريد.

5- التكامل مع أداة "بحث Google" المضمّنة

بعد أن أصبح بإمكان الوكيل تقديم أسعار الصرف، تتمثل المهمة التالية في الحصول على توقعات الطقس للشهر القادم. اطرح السؤال التالي على الوكيل: "ما هي توقعات الطقس في طوكيو، اليابان للشهر المقبل؟"

كما هو متوقّع، يتطلّب توقّع حالة الطقس معلومات في الوقت الفعلي لا يملكها الوكيل. على الرغم من أنّه يمكننا ترميز وظائف Python جديدة لكل حالة استخدام تتطلّب بيانات في الوقت الفعلي، فإنّ إضافة المزيد والمزيد من الأدوات المخصّصة يؤدي بسرعة إلى تعقيد الوكيل وصعوبة إدارته.

لحسن الحظ، توفّر "حزمة تطوير الوكيل" (ADK) مجموعة من الأدوات المضمّنة، بما في ذلك "بحث Google"، وهي جاهزة للاستخدام، ما يسهّل طريقة تفاعل الوكيل مع العالم الخارجي. لنضِف أداة "بحث Google" إلى الوكيل من خلال تعديل ملف agent.py على النحو التالي:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import google_search

from .custom_functions import get_fx_rate

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',
    tools=[
        FunctionTool(get_fx_rate), 
        google_search,
    ]
)

بعد تعديل الملف، أعِد تشغيل مثيل adk web. في حال نسيت ذلك،

انقر على الوحدة الطرفية، ثم اضغط على Ctrl + C لإيقاف المثيل.
uv run adk web لبدء المثيل
جرِّب طرح السؤال نفسه: "ما هي توقعات الطقس في طوكيو، اليابان للشهر المقبل؟"

من المفترض أن تتلقّى الآن ردًا يتضمّن معلومات في الوقت الفعلي.

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

إنشاء ملف `custom_agents.py`

الآن، أنشِئ ملف Python باسم custom_agents.py في المجلد personal_assistant من خلال تنفيذ الأمر التالي في الوحدة الطرفية:

touch personal_assistant/custom_agents.py

يجب أن تبدو بنية المجلدات الآن على النحو التالي:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

سيحتوي هذا الملف على رمز google_search_agent المتخصّص. انسخ الرمز التالي إلى ملف custom_agents.py باستخدام محرّر الرموز.

from google.adk.agents import Agent
from google.adk.tools import google_search


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

بعد إنشاء الملف، عدِّل ملف agent.py كما هو موضّح أدناه.

تعديل ملف `agent.py`

انسخ كتلة الرموز هذه واستبدِل المحتوى الحالي لملف agent.py بما يلي:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
    ]
)

لنلقِ نظرة على النمط الجديد الفعّال في الرمز:

وكيل أخصائي جديد: حدّدنا وكيلًا جديدًا تمامًا، وهو google_search_agent. لاحظ الوصف المحدّد لها وأنّ أداتها الوحيدة هي google_search. إنّه متخصص في البحث.
‫agent_tool.AgentTool: هذا غلاف خاص من حزمة تطوير البرامج (ADK). تأخذ هذه الوظيفة وكيلاً كاملاً (google_search_agent) وتجمّعه ليبدو ويتصرّف كأداة عادية.
أكثر ذكاءً **root_agent**: تتضمّن root_agent الآن أداة جديدة هي AgentTool(agent=google_search_agent). لا يعرف كيف يبحث على الويب، لكنّه يعرف أنّ لديه أداة يمكنه تفويض مهام البحث إليها.

لاحظ أنّ حقل التعليمات قد تمت إزالته من root_agent. يتم الآن تحديد تعليماته ضمنيًا من خلال الأدوات المتاحة له.

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

الآن، اكتب

adk web

في نافذة الوحدة الطرفية لبدء المثيل وطرح السؤال نفسه على الوكيل مرة أخرى: "ما هي توقعات الطقس في طوكيو، اليابان للشهر المقبل؟"

يستخدم الوكيل الآن google_search_agent للحصول على أحدث المعلومات

يمكنك أيضًا طرح سؤال حول سعر الصرف الحالي. من المفترض أن يتمكّن الوكيل الآن من استخدام الأداة المناسبة للسؤال المعنيّ.

يمكنك طرح أسئلة أخرى تتطلّب معلومات في الوقت الفعلي على الوكيل ومراقبة طريقة تعامله مع الطلبات باستخدام الأدوات المتاحة له.

6. الاستفادة من أداة Wikipedia في LangChain

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

مع أنّ google_search_agent يمكنه العثور على حقائق ثقافية وتاريخية، إلا أنّ المعلومات الواردة من مصدر مخصّص مثل ويكيبيديا تكون غالبًا أكثر تنظيمًا وموثوقية.

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

أولاً، أوقِف عملية الوكيل الجارية (Ctrl + C) وثبِّت مكتبات إضافية في بيئة Python الافتراضية الحالية عن طريق كتابة الأوامر التالية في الوحدة الطرفية.

uv pip install langchain-community wikipedia

إنشاء ملف `third_party_tools.py`

الآن، أنشئ ملف Python باسم third_party_tools.py في المجلد personal_assistant من خلال تنفيذ الأمر التالي في الوحدة الطرفية:

touch personal_assistant/third_party_tools.py

يجب أن تبدو بنية المجلدات الآن على النحو التالي:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

سيحتوي هذا الملف على رمز التنفيذ الخاص بأداة LangChain Wikipedia. انسخ الرمز التالي إلى third_party_tools.py باستخدام أداة تعديل السحابة الإلكترونية:

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

تعديل ملف `agent.py`

الآن، عدِّل ملف agent.py باستخدام المحتوى أدناه:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

الآن، اكتب

adk web

في نافذة الوحدة الطرفية لبدء المثيل وطرح هذا السؤال على الوكيل: "أريد الاطّلاع على تاريخ مدينة كيوتو".

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

لمعرفة الطريقة التي اتّخذ بها الوكيل هذا القرار، يمكنك استخدام "أداة فحص الأحداث" في adk web واجهة المستخدم. انقر على علامة التبويب "الأحداث"، ثمّ على حدث functionCall الأخير.

يعرض "المفتّش" قائمة بجميع الأدوات المتاحة ويُبرز tool_code للأداة التي نفّذها الوكيل.

7. التنظيف (اختياري)

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

8. الخاتمة

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

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

أنت الآن مستعد تمامًا للتدريب العملي التالي في السلسلة، حيث سنتعمّق أكثر في تنسيق عدة وكلاء وسير عمل. يسعدنا انضمامك إلينا.

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

1. قبل البدء

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

ما ستتعلمه

المتطلبات

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

2. مقدمة

3- البدء: الوكيل الأساسي

4. إنشاء أداة مخصّصة لتحويل العملات

إنشاء ملف custom_functions.py

تعديل ملف agent.py

5- التكامل مع أداة "بحث Google" المضمّنة

إنشاء ملف custom_agents.py

تعديل ملف agent.py

6. الاستفادة من أداة Wikipedia في LangChain

إنشاء ملف third_party_tools.py

تعديل ملف agent.py

7. التنظيف (اختياري)

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

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

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

8. الخاتمة

إنشاء ملف `custom_functions.py`

تعديل ملف `agent.py`

إنشاء ملف `custom_agents.py`

تعديل ملف `agent.py`

إنشاء ملف `third_party_tools.py`

تعديل ملف `agent.py`