Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

1- قبل البدء

يُرجى القراءة:

يتطلّب هذا البرنامج التعليمي مشروعًا على Google Cloud يتضمّن حساب فوترة نشطًا.

بالنسبة إلى المشاركين في ورشة العمل التي تتطلّب الحضور شخصيًا

يُرجى اتّباع تعليمات الإعداد والفوترة المحدّدة التي يقدّمها المعلّم.

بالنسبة إلى المستخدمين الذين يدرسون بأنفسهم

يُرجى اتّباع الخطوات التالية لاسترداد إصدار تجريبي:

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

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

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

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

يمكنك أيضًا الوصول إلى هذا الدرس التطبيقي حول الترميز من خلال عنوان URL المختصر هذا: goo.gle/adk-using-tools.

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

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

ما ستتعلمه

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

ما ستحتاج إليه

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

2. مقدمة

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

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

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

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

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

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

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

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

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

إذا لم يظهر لك (ai-agents-adk) في موجه Cloud Shell، شغِّل الأوامر التالية لتفعيل البيئة الافتراضية لـ Python:

cd ~/ai-agents-adk
source .venv/bin/activate

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

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

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

4. إنشاء أداة مخصّصة لصرف العملات

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

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

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

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

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

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

نفِّذ هذا الأمر في الوحدة الطرفية لإنشاء ملف Python باسم custom_functions.py في مجلد personal_assistant وافتحه أيضًا في "محرّر الرموز البرمجية".

cloudshell edit 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-3.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 --allow_origins "regex:https://.*\.cloudshell\.dev"

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

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

يمكنك طرح أي أسئلة ذات صلة بصرف العملات كما تشاء.

5. دمج الأداة المضمّنة "بحث Google"

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

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

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

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

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

شغِّل هذا الأمر في الوحدة الطرفية لـ إنشاء ملف Python باسم custom_agents.py في مجلد personal_assistant وافتحه في "محرّر الرموز البرمجية":

cloudshell edit personal_assistant/custom_agents.py

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

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.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-3.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-3.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") ويجمّعه ليبدو ويتصرف كأداة عادية.
`root_agent` أكثر ذكاءً: يحتوي root_agent الآن على أداة جديدة: AgentTool(agent=google_search_agent).root_agent لا يعرف كيفية البحث على الويب، ولكنّه يعرف أنّه يتضمّن أداة يمكنه تفويض مهام البحث إليها.

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

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

الآن، اكتب هذا الأمر في الوحدة الطرفية لبدء المثال:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

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

يستخدم الوكيل الآن 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 وافتحه في "محرّر Cloud":

cloudshell edit 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

سيحتوي هذا الملف على عملية تنفيذ أداة Wikipedia في LangChain. انسخ الرمز التالي إلى ملف 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-3.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 --allow_origins "regex:https://.*\.cloudshell\.dev"

عندما يصبح الوكيل جاهزًا، اطرح هذا السؤال على الوكيل: "أخبرني عن تاريخ كيوتو".

يحدّد الوكيل هذا السؤال بشكلٍ صحيح على أنّه استعلام تاريخي ويستخدم أداة 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" في الوقت الفعلي. يُرجى قراءة هذه المستندات الرسمية حول استخدام الأدوات مع حزمة تطوير الوكلاء (ADK) من 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`