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

1. قبل البدء

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

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

ملاحظة: للبدء في استخدام هذا الدرس العملي، يجب أن يكون لديك بيئة Google Cloud وPython تعملان مع رمز أساسي للوكيل.

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

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

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

ما ستتعلمه

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

المتطلبات

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

2. مقدمة

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

لجعل وكيلنا مفيدًا حقًا، علينا تزويده بأدوات.

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

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

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

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

3- إضافة أداة دالة

بالاستناد إلى جلستنا الأخيرة، من المفترض أن يكون لديك وكيل مساعد شخصي يعمل من خلال واجهة الويب.

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

What is the exchange rate from Singapore dollars to Japanese yen?

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

أولاً، أوقِف عملية الوكيل الجارية باستخدام اختصار لوحة المفاتيح Ctrl + C (في نظام التشغيل Windows أو Linux) أو Cmd + C (في نظام التشغيل macOS).

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

إنشاء custom_functions.py:

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

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

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

جارٍ تعديل 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.0-flash-001',
    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)]
)

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

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

uv run adk web

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

What is the exchange rate from Singapore dollars to Japanese yen?

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

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

4. إضافة أداة مضمَّنة

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

What is the weather forecast in Tokyo, Japan for next month?

كما هو متوقّع، يتطلّب توقّع حالة الطقس معلومات في الوقت الفعلي لا يملكها الوكيل. على الرغم من أنّه يمكننا ترميز وظائف 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.0-flash-001',
    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. في حال نسيت ذلك،

1. انقر على الوحدة الطرفية، ثم اضغط على Ctrl + C أو Cmd + C لإيقاف المثيل.
2. uv run adk web لبدء المثيل

سيحدث خطأ.

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

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

الآن، أنشئ ملف Python باسم custom_agents.py. سيحتوي هذا الملف على رمز google_search_agent المتخصّص. انسخ الرمز التالي إلى ملف custom_agents.py.

جارٍ إنشاء 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.0-flash-001',
    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

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

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


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

لنحلّل النمط الجديد الفعّال في الرمز:

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

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

الآن، أعِد تشغيل مثيل adk web واطرح هذا السؤال على الموظف مرة أخرى:

What is the weather forecast in Tokyo, Japan for next month?

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

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

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

5- إضافة أداة خارجية

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

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

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

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

uv add langchain-community
uv add wikipedia

بعد اكتمال عملية التثبيت أنشئ ملفًا باسم 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 import agent_tool
from google.adk.tools import langchain_tool

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.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

الآن، أعِد تشغيل مثيل adk web واطرح هذا السؤال على الموظف مرة أخرى:

Tell me about the history of Kyoto

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

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

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

6. تنظيف

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

7. الخاتمة

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

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

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