إنشاء ونشر وكيل ADK يستخدم خادم MCP على Cloud Run

1. مقدمة

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

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

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

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

• خادم MCP قيد التشغيل على Cloud Run أو عنوان URL للخدمة المرتبط به
• مشروع Google Cloud تم تفعيل الفوترة فيه

ما ستتعلمه

• كيفية تنظيم مشروع Python لنشر حزمة تطوير التطبيقات (ADK)
• كيفية تنفيذ وكيل يستخدم أدوات باستخدام google-adk
• كيفية ربط وكيل بخادم MCP بعيد لمجموعة أدواته
• كيفية نشر تطبيق Python كحاوية بدون خادم على Cloud Run
• كيفية إعداد مصادقة آمنة بين الخدمات باستخدام أدوار إدارة الهوية وإمكانية الوصول (IAM)
• كيفية حذف موارد Cloud لتجنُّب تحمّل تكاليف مستقبلية

المتطلبات

• حساب Google Cloud ومشروع Google Cloud
• متصفّح ويب، مثل Chrome

2. لماذا يجب النشر على Cloud Run؟

‫Cloud Run هو خيار رائع لاستضافة وكلاء ADK لأنّه نظام أساسي بدون خادم، ما يعني أنّه يمكنك التركيز على الرمز البرمجي وليس على إدارة البنية الأساسية. نتولّى نحن العمليات التشغيلية نيابةً عنك.

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

الميزات الأساسية

تشغيل الحاويات في أي مكان:

• يمكنك إحضار حاوية (صورة Docker) تحتوي على تطبيقك.
• وتشغِّل Cloud Run هذه الحاويات على البنية الأساسية من Google.
• لا داعي للقلق بشأن تصحيح نظام التشغيل أو إعداد الآلة الافتراضية أو توسيع نطاقها.

التدرّج التلقائي:

• إذا لم يكن هناك أي مستخدمين لتطبيقك → يتم تشغيل 0 مثيل (يتم تقليل عدد المثيلات إلى صفر، ما يجعله فعالاً من حيث التكلفة).
• إذا وصل إلى 1,000 طلب، سيتم إنشاء العدد المطلوب من النسخ.

عدم الاحتفاظ بالحالة تلقائيًا:

• يمكن أن ينتقل كل طلب إلى نسخة مختلفة.
• إذا كنت بحاجة إلى تخزين الحالة، استخدِم خدمة خارجية مثل Cloud SQL أو Firestore أو Memorystore.

التوافق مع أي لغة أو إطار عمل:

• طالما أنّ التطبيق يعمل في حاوية Linux، لا يهمّ Cloud Run ما إذا كان مكتوبًا بلغة Python أو Go أو Node.js أو Java أو ‎ .Net.

الدفع مقابل الاستخدام:

• الفوترة المستندة إلى الطلبات: تتم فوترة كل طلب بالإضافة إلى وقت الحساب (بحدّ أدنى 100 ملي ثانية).
• الفوترة المستندة إلى المثيل: يتم تحصيل الرسوم عن مدة بقاء المثيل بالكامل (بدون رسوم لكل طلب).

3- الإعداد والمتطلبات

إعداد البيئة بالسرعة التي تناسبك

1. سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.

• اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
• معرّف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console سلسلة فريدة تلقائيًا، ولا يهمّك عادةً ما هي. في معظم دروس الترميز، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم PROJECT_ID). إذا لم يعجبك رقم التعريف الذي تم إنشاؤه، يمكنك إنشاء رقم تعريف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم مستخدم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع.
• للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات حول هذه القيم الثلاث في المستندات.

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

ملاحظة: إذا كنت تستخدم حساب Gmail، يمكنك ترك الموقع الجغرافي التلقائي مضبوطًا على لا توجد مؤسسة. إذا كنت تستخدم حسابًا على Google Workspace، اختَر موقعًا جغرافيًا مناسبًا لمؤسستك.

2. بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس البرمجي الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف فوترة تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن للمستخدمين الجدد في Google Cloud الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.

بدء Cloud Shell

انتقِل إلى محرّر Cloud Shell

إذا لم تظهر الوحدة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:

• انقر على Terminal.
• انقر على نافذة طرفية جديدة.

في الوحدة الطرفية، اضبط مشروعك باستخدام هذا الأمر. إذا أكملت التمرين العملي 1، تأكَّد من استخدام رقم تعريف المشروع نفسه:

gcloud config set project [YOUR-PROJECT-ID]

إذا لم تتمكّن من تذكُّر رقم تعريف مشروعك، يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:

gcloud projects list | awk '/PROJECT_ID/{print $2}'

4. إذا طُلب منك منح الإذن، انقر على منح الإذن للمتابعة.

5- من المفترض أن تظهر لك هذه الرسالة:

Updated property [core/project].

If you see a `WARNING` and are asked `Do you want to continue (Y/n)?`,

then you have likely entered the project ID incorrectly. Press `n`,

press `Enter`, and try to run the `gcloud config set project` command again.

4. قبل البدء

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

فعِّل جميع الخدمات اللازمة:

gcloud services enable \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    aiplatform.googleapis.com \
    compute.googleapis.com 

الناتج المتوقّع

Operation "operations/acat.p2-[GUID]" finished successfully.

5- إنشاء مجلد المشروع

أنشئ دليل المشروع.

ينشئ هذا الأمر مجلدًا رئيسيًا للدرس التطبيقي يحتوي على الرمز المصدري للوكيل.

cd && mkdir zoo_guide_agent && cd zoo_guide_agent

أنشئ ملف requirements.txt. يسرد هذا الملف مكتبات Python التي يحتاجها برنامجك. ينشئ الأمر التالي الملف ويملأه.

cloudshell edit requirements.txt

google-adk==1.14.0
langchain-community==0.3.27
wikipedia==1.4.0

اضبط المتغيّرات لمشروعك ومنطقتك ومستخدمك الحاليين. هذه طريقة أكثر فعالية لتنفيذ هذه الأوامر.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}[e-mail]"

أنشئ ملف .env وافتحه للمصادقة على الوكيل في الدليل zoo_guide_agent.

cloudshell edit .env

سيفتح الأمر cloudshell edit الملف .env في المحرِّر أعلى الوحدة الطرفية. أدخِل ما يلي في ملف .env ثم ارجع إلى الوحدة الطرفية.

MODEL="gemini-2.5-flash"
SERVICE_ACCOUNT="${PROJECT_NUMBER}[e-mail]"

إضافة عنوان URL لخادم MCP إذا أكملت التمرين العملي 1، اتّبِع الخطوات التالية لاستخدام خادم MCP الذي أنشأته في التمرين العملي 1:

ملاحظة: نفِّذ الأوامر الثلاثة التالية إذا أكملت الدرس التطبيقي 1 وأردت استخدام خادم MCP الذي تم إنشاؤه في هذا الدرس التطبيقي. لست بحاجة إلى تنفيذ هذين الأمرَين إذا كنت تستخدم حاليًا رابط خادم MCP العام الذي تم تقديمه إليك أثناء حدث مباشر.

1. منح إذن هوية خدمة Cloud Run لاستدعاء خادم MCP البعيد

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

2. احفظ عنوان URL لخادم MCP من Lab 1 في متغيّر بيئة.

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp" >> .env

إذا كنت تستخدم رابط خادم MCP عامًا، نفِّذ ما يلي، واستبدِل PROJECT_NUMBER بالمعلومات المقدَّمة.

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp" >> .env

6. إنشاء سير عمل الوكيل

إنشاء ملف init.py

أنشِئ ملف init.py. يُعلم هذا الملف لغة Python أنّ دليل zoo_guide_agent هو حزمة.

cloudshell edit __init__.py

يفتح الأمر أعلاه محرِّر الرموز البرمجية. أضِف الرمز التالي إلى __init__.py:

from . import agent

إنشاء ملف agent.py الرئيسي

أنشئ ملف agent.py الرئيسي. ينشئ هذا الأمر ملف Python ويلصق فيه الرمز الكامل لنظامك المستند إلى عدّة وكلاء.

cloudshell edit agent.py

الخطوة 1: عمليات الاستيراد والإعداد الأولي

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

أضِف الرمز التالي إلى ملف agent.py:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

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

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

الخطوة 2: تحديد الأدوات (إمكانات الوكيل)

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

أضِف الرمز التالي إلى أسفل ملف agent.py:

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}


# Configuring the MCP Tool to connect to the Zoo MCP server

mcp_server_url = os.getenv("MCP_SERVER_URL")
if not mcp_server_url:
    raise ValueError("The environment variable MCP_SERVER_URL is not set.")

def get_id_token():
    """Get an ID token to authenticate with the MCP server."""
    target_url = os.getenv("MCP_SERVER_URL")
    audience = target_url.split('/mcp/')[0]
    request = google.auth.transport.requests.Request()
    id_token = google.oauth2.id_token.fetch_id_token(request, audience)
    return id_token

"""
# Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools
mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url=mcp_server_url
    )
)
"""

mcp_tools = MCPToolset(
            connection_params=StreamableHTTPConnectionParams(
                url=mcp_server_url,
                headers={
                    "Authorization": f"Bearer {get_id_token()}",
                },
            ),
        )

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

شرح الأدوات الثلاث

1. add_prompt_to_state 📝

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

الطريقة: هي دالة Python تكتب طلب الزائر في قاموس tool_context.state المشترَك. يمثّل سياق الأداة هذا الذاكرة القصيرة المدى للوكيل في محادثة واحدة. يمكن للوكيل التالي في سير العمل قراءة البيانات التي حفظها الوكيل السابق في الحالة.

2. MCPToolset 🦁

يُستخدَم هذا الإعداد لربط وكيل دليل الجولات بخادم MCP الخاص بحديقة الحيوانات الذي تم إنشاؤه في التمرين العملي 1. يتضمّن هذا الخادم أدوات خاصة للبحث عن معلومات محدّدة حول حيواناتنا، مثل اسمها وعمرها ومكان إقامتها.

الطريقة: يتم الاتصال بشكل آمن بعنوان URL الخاص بالخادم الخاص بحديقة الحيوانات. يستخدم get_id_token للحصول تلقائيًا على "بطاقة مفتاح" آمنة (رمز مميّز لمعرّف حساب الخدمة) لإثبات هويته والحصول على إذن الوصول.

3. LangchainTool 🌍

يمنح هذا الإجراء وكيل دليل الجولات المعرفة العامة بالعالم. عندما يطرح زائر سؤالاً غير متوفّر في قاعدة بيانات حديقة الحيوانات، مثل "ماذا تأكل الأسود في البرية؟"، تتيح هذه الأداة للوكيل البحث عن الإجابة على Wikipedia.

الطريقة: يعمل هذا المكوّن كمحوّل، ما يسمح للوكيل باستخدام أداة WikipediaQueryRun المُنشأة مسبقًا من مكتبة LangChain.

المصادر:

• مجموعة أدوات MCP
• أدوات الدوال
• الولاية

الخطوة 3: تحديد "الوكلاء المتخصّصون"

بعد ذلك، سنحدّد وكيل الباحث ووكيل تنسيق الردود. يُعدّ وكيل الباحث "العقل المدبّر" لعمليتنا. يستقبل هذا الوكيل طلب المستخدم من State المشترَكة، ويفحص أدواتها الفعّالة (أداة خادم MCP في Zoo وأداة Wikipedia)، ويقرّر الأدوات التي سيستخدمها للعثور على الإجابة.

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

أضِف الرمز التالي إلى أسفل agent.py:

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    {{ PROMPT }}
    """,
    tools=[
        mcp_tools,
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    {{ research_data }}
    """
)

الخطوة 4: وكيل سير العمل

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

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

أضِف مجموعة الرموز هذه إلى أسفل agent.py:

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

الخطوة الأخيرة: تجميع سير العمل الرئيسي

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

أضِف مجموعة الرموز النهائية هذه إلى أسفل agent.py:

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

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

7. تجهيز التطبيق للنشر

بعد إعداد بيئتك المحلية، تكون الخطوة التالية هي تجهيز مشروعك على Google Cloud للنشر. يتضمّن ذلك إجراء فحص نهائي لبنية ملف الوكيل للتأكّد من توافقه مع أمر النشر. والأهم من ذلك، يمكنك ضبط إذن IAM مهم يسمح لخدمة Cloud Run التي تم نشرها بالتصرّف نيابةً عنك واستدعاء نماذج Vertex AI. يضمن إكمال هذه الخطوة أنّ بيئة السحابة الإلكترونية جاهزة لتشغيل البرنامج بنجاح.

حمِّل المتغيرات في جلسة shell من خلال تنفيذ الأمر source.

source .env

امنح حساب الخدمة دور "مستخدم Vertex AI"، ما يمنحه الإذن بتقديم توقّعات واستدعاء نماذج Google.

# Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

8. نشر الوكيل باستخدام واجهة سطر الأوامر (CLI) الخاصة بـ ADK

بعد أن يصبح الرمز البرمجي المحلي جاهزًا ومشروع Google Cloud معدًا، حان وقت نشر الوكيل. ستستخدِم الأمر adk deploy cloud_run، وهو أداة سهلة الاستخدام تعمل على أتمتة سير عمل النشر بالكامل. تتضمّن هذه العملية الموحّدة تجميع الرمز البرمجي وإنشاء صورة حاوية وتحميلها إلى Artifact Registry وتشغيل الخدمة على Cloud Run، ما يتيح الوصول إليها على الويب.

نشر

نفِّذ الأوامر التالية لنشر وكيلك. يتيح لك الأمر uvx تشغيل أدوات سطر الأوامر المنشورة كحِزم Python بدون الحاجة إلى تثبيت هذه الأدوات على مستوى العالم.

ملاحظة: سيستغرق تنفيذ أمر النشر أدناه بضع دقائق.

# Run the deployment command
uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk

قبول الإشعارات

قد يُطلب منك تنفيذ ما يلي:

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?

اكتب Y واضغط على ENTER.

قد يُطلب منك تنفيذ ما يلي:

Allow unauthenticated invocations to [your-service-name] (y/N)?.

في هذا الدرس التطبيقي، نريد السماح بعمليات استدعاء غير مصادَق عليها لتسهيل الاختبار، لذا اكتب y واضغط على Enter.

ملاحظة: يمكن لأي شخص لديه عنوان URL الوصول إلى هذا الوكيل، لذا يُنصح باستخدام هذه الطريقة للاختبار.

الحصول على رابط النشر

عند التنفيذ بنجاح، سيوفّر الأمر عنوان URL لخدمة Cloud Run التي تم نشرها. (سيبدو على النحو التالي: https://zoo-tour-guide-123456789.europe-west1.run.app). انسخ عنوان URL هذا للمهمة التالية.

9- اختبار الوكيل الذي تم نشره

بعد أن يصبح وكيلك متاحًا على Cloud Run، ستجري اختبارًا للتأكّد من أنّ عملية النشر تمت بنجاح وأنّ الوكيل يعمل على النحو المتوقّع. ستستخدم عنوان URL العام للخدمة (على سبيل المثال، https://zoo-tour-guide-123456789.europe-west1.run.app/) للوصول إلى واجهة الويب الخاصة بـ ADK والتفاعل مع الوكيل.

افتح عنوان URL لخدمة Cloud Run العامة في متصفّح الويب. بما أنّك استخدَمت --with_ui flag، من المفترض أن تظهر لك واجهة مستخدم المطوّرين في "حزمة تطوير البرامج".

فعِّل Token Streaming في أعلى يسار الشاشة.

يمكنك الآن التفاعل مع وكيل Zoo.

اكتب hello واضغط على Enter لبدء محادثة جديدة.

راقِب النتيجة. على الوكيل الردّ بسرعة مع صيغة الترحيب:

"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

اطرح على الوكيل أسئلة مثل:

Where can I find the polar bears in the zoo and what is their diet?

شرح Agent Flow

يعمل نظامك كفريق ذكي ومتعدّد الوكلاء. تتم إدارة العملية من خلال تسلسل واضح لضمان تدفق سلس وفعّال من سؤال المستخدم إلى الإجابة النهائية التفصيلية.

1. موظف الاستقبال في حديقة الحيوان (مكتب الاستقبال)

تبدأ العملية بأكملها مع وكيل الترحيب.

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

الأداة: عندما يردّ المستخدم، تستخدم أداة Greeter add_prompt_to_state لالتقاط كلماته بالضبط (مثلاً، أريد معلومات عن الأسود") وحفظها في ذاكرة النظام.

التسليم: بعد حفظ الطلب، يتم على الفور نقل عناصر التحكّم إلى الوكيل الفرعي tour_guide_workflow.

2. الباحث الشامل (الباحث المتميّز)

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

مهمتها: تحليل سؤال المستخدم ووضع خطة ذكية. تستفيد هذه الأداة من إمكانات النموذج اللغوي الفعّالة في استخدام الأدوات لتحديد ما إذا كانت بحاجة إلى:

• بيانات داخلية من سجلات حديقة الحيوانات (عبر خادم MCP)
• معلومات عامة من الويب (عبر Wikipedia API)
• أو كلاهما في حال الأسئلة المعقّدة.

الإجراء الذي يتّخذه: ينفّذ الأداة أو الأدوات اللازمة لجمع كل البيانات الأولية المطلوبة. على سبيل المثال، إذا طُرح السؤال "كم تبلغ أعمار الأسود وماذا تأكل في البرية؟"، سيتم استدعاء خادم MCP للحصول على الأعمار وأداة Wikipedia للحصول على معلومات النظام الغذائي.

3. أداة تنسيق الردود (المقدِّم)

بعد أن يجمع Comprehensive Researcher كل الحقائق، يكون هذا هو الوكيل النهائي الذي سيتم تشغيله.

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

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

النتيجة النهائية: النص الذي ينشئه هذا الوكيل هو الإجابة الكاملة والمفصّلة التي يراها المستخدم في نافذة المحادثة.

إذا كنت مهتمًا بمعرفة المزيد حول إنشاء وكلاء، يمكنك الاطّلاع على الموارد التالية:

1. مستندات ADK
2. إنشاء أدوات مخصّصة لوكلاء "حزمة تطوير التطبيقات"

10. تنظيف البيئة

gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

11. تهانينا

تهانينا على إكمال تجربة البرمجة.

المواضيع التي تناولناها

• كيفية تنظيم مشروع Python لنشره باستخدام واجهة سطر الأوامر في "حزمة تطوير التطبيقات"
• كيفية تنفيذ سير عمل متعدد الوكلاء باستخدام SequentialAgent وParallelAgent
• كيفية الاتصال بخادم MCP بعيد باستخدام MCPToolset لاستخدام أدواته
• كيفية تحسين البيانات الداخلية من خلال دمج أدوات خارجية، مثل Wikipedia API
• كيفية نشر وكيل كحاوية بدون خادم على Cloud Run باستخدام الأمر adk deploy

12. استطلاع

إخراج:

كيف ستستخدم هذا البرنامج التعليمي؟

قراءة المحتوى فقط قراءة المحتوى وإكمال التمارين