1. مقدمة
نظرة عامة
يسدّ هذا التمرين المعملي الفجوة المهمة بين تطوير نظام قوي يستند إلى عدّة وكلاء ونشره للاستخدام في الواقع. على الرغم من أنّ إنشاء وكلاء محليًا هو بداية رائعة، تتطلّب تطبيقات الإنتاج منصة قابلة للتوسّع وموثوقة وآمنة.
في هذا المختبر، ستستخدم نظامًا متعدد الوكلاء تم إنشاؤه باستخدام Google Agent Development Kit (ADK) ونشره في بيئة إنتاج على Google Kubernetes Engine (GKE).
وكيل فريق مفاهيم الأفلام
التطبيق النموذجي المستخدَم في هذا التمرين هو "فريق مفهوم فيلم" يتألف من عدة وكلاء متعاونين: باحث وكاتب سيناريو وكاتب ملفات. تعمل هذه البرامج معًا لمساعدة المستخدم في تبادل الأفكار ووضع مخطط لعرض فيلم عن شخصية تاريخية.

لماذا يجب النشر على GKE؟
لإعداد الوكيل لتلبية متطلبات بيئة التشغيل الفعلي، تحتاج إلى منصة مصمَّمة لتحقيق قابلية التوسّع والأمان وفعالية التكلفة. توفّر Google Kubernetes Engine (GKE) هذه البنية الأساسية الفعّالة والمرنة لتشغيل تطبيقك المحفوظ في حاوية.
يوفّر ذلك العديد من المزايا لعبء العمل في مرحلة الإنتاج:
- التوسّع التلقائي والأداء: يمكنك التعامل مع الزيارات غير المتوقّعة باستخدام HorizontalPodAutoscaler (HPA)، الذي يضيف أو يزيل نُسخًا طبق الأصل من الوكيل تلقائيًا استنادًا إلى الحمل. بالنسبة إلى مهام عمل الذكاء الاصطناعي الأكثر تطلّبًا، يمكنك إرفاق أدوات تسريع الأجهزة، مثل وحدات معالجة الرسومات ووحدات معالجة الموتّرات.
- إدارة الموارد بفعالية من حيث التكلفة: يمكنك تحسين التكاليف باستخدام GKE Autopilot، الذي يدير البنية الأساسية تلقائيًا، وبالتالي لا تدفع إلا مقابل الموارد التي يطلبها تطبيقك.
- الأمان وإمكانية تتبّع البيانات المتكاملان: يمكنك الربط بشكل آمن بخدمات Google Cloud الأخرى باستخدام Workload Identity، ما يغنيك عن الحاجة إلى إدارة مفاتيح حساب الخدمة وتخزينها. يتم تلقائيًا نقل جميع سجلّات التطبيقات إلى Cloud Logging لإجراء عمليات الرصد وتصحيح الأخطاء بشكل مركزي.
- التحكّم وإمكانية النقل: تجنَّب الاعتماد الحصري على مورّد واحد باستخدام Kubernetes المفتوحة المصدر. تطبيقك قابل للنقل ويمكن تشغيله على أي مجموعة Kubernetes، سواء في المؤسسة أو في السُحب الأخرى.
أهداف الدورة التعليمية
في هذه الميزة الاختبارية، ستتعرّف على كيفية تنفيذ المهام التالية:
- وفِّر مجموعة GKE Autopilot.
- تضمين تطبيق في حاوية باستخدام ملف Dockerfile ونشر الصورة إلى Artifact Registry
- يمكنك ربط تطبيقك بواجهات Google Cloud APIs بأمان باستخدام Workload Identity.
- كتابة ملفات Kubernetes وتطبيقها على عملية نشر وخدمة
- عرض تطبيق على الإنترنت باستخدام LoadBalancer
- اضبط التدرّج التلقائي باستخدام HorizontalPodAutoscaler (HPA).
المتطلبات الأساسية
- يجب أن يكون لديك معرفة بلغة Python وDocker وKubernetes وواجهات سطر الأوامر.
- مشروع Google Cloud تم تفعيل الفوترة فيه
- أدوات سطر الأوامر المثبَّتة:
dockerوgcloudوkubectlوuv
2. إعداد المشروع
حساب Google
إذا لم يكن لديك حساب Google شخصي، عليك إنشاء حساب Google.
استخدام حساب شخصي بدلاً من حساب تابع للعمل أو حساب تديره المؤسسة التعليمية
تسجيل الدخول إلى Google Cloud Console
سجِّل الدخول إلى Google Cloud Console باستخدام حساب Google شخصي.
تفعيل الفوترة
إعداد حساب فوترة شخصي
إذا أعددت الفوترة باستخدام أرصدة Google Cloud، يمكنك تخطّي هذه الخطوة.
لإعداد حساب فوترة شخصي، انتقِل إلى هنا لتفعيل الفوترة في Cloud Console.
بعض الملاحظات:
- يجب أن تبلغ تكلفة إكمال هذا الدرس التطبيقي أقل من دولار أمريكي واحد في موارد السحابة الإلكترونية.
- يمكنك اتّباع الخطوات في نهاية هذا المختبر لحذف الموارد وتجنُّب تحصيل المزيد من الرسوم.
- يمكن للمستخدمين الجدد الاستفادة من الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.
إنشاء مشروع (اختياري)
إذا لم يكن لديك مشروع حالي تريد استخدامه في هذا المختبر، يمكنك إنشاء مشروع جديد هنا.
3- فتح Cloud Shell Editor
- انقر على هذا الرابط للانتقال مباشرةً إلى محرّر Cloud Shell
- إذا طُلب منك منح الإذن في أي وقت اليوم، انقر على تفويض للمتابعة.

- إذا لم تظهر النافذة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
- انقر على عرض.
- انقر على Terminal
.
- في الوحدة الطرفية، اضبط مشروعك باستخدام الأمر التالي:
gcloud config set project [PROJECT_ID]- مثال:
gcloud config set project lab-project-id-example - إذا تعذّر عليك تذكُّر رقم تعريف مشروعك، يمكنك إدراج جميع أرقام تعريف المشاريع باستخدام:
gcloud projects list
- مثال:
- من المفترض أن تظهر لك هذه الرسالة:
Updated property [core/project].
4. تفعيل واجهات برمجة التطبيقات
لاستخدام GKE وArtifact Registry وCloud Build وGemini Enterprise Agent Platform، عليك تفعيل واجهات برمجة التطبيقات الخاصة بها في مشروعك على Google Cloud.
- في وحدة التحكّم، فعِّل واجهات برمجة التطبيقات:
عند انتهاء هذا الأمر، من المفترض أن تظهر لك نتيجة مشابهة لما يلي:gcloud services enable \ container.googleapis.com \ artifactregistry.googleapis.com \ cloudbuild.googleapis.com \ aiplatform.googleapis.comOperation "operations/acf.p2-176675280136-b03ab5e4-3483-4ebf-9655-43dc3b345c63" finished successfully.
لمحة عن واجهات برمجة التطبيقات
- تتيح لك Google Kubernetes Engine API (
container.googleapis.com) إنشاء وإدارة مجموعة GKE التي تشغّل وكيلك. توفّر GKE بيئة مُدارة لنشر تطبيقاتك المحفوظة في حاويات وإدارتها وتوسيع نطاقها باستخدام البنية الأساسية من Google. - توفّر Artifact Registry API (
artifactregistry.googleapis.com) مستودعًا آمنًا وخاصًا لتخزين صورة حاوية الوكيل. وهي عبارة عن تطوير لخدمة Container Registry وتتكامل بسلاسة مع GKE وCloud Build. - يتم استخدام Cloud Build API (
cloudbuild.googleapis.com) من خلال الأمرgcloud builds submitلإنشاء صورة الحاوية في السحابة الإلكترونية من ملف Dockerfile. وهي منصة CI/CD بدون خادم تنفّذ عمليات الإنشاء على بنية Google Cloud الأساسية. - تتيح واجهة برمجة التطبيقات Gemini Enterprise Agent Platform API (
aiplatform.googleapis.com) للوكيل الذي تم نشره التواصل مع نماذج Gemini لتنفيذ مهامه الأساسية. توفّر هذه المنصة واجهة برمجة تطبيقات موحّدة لجميع خدمات الذكاء الاصطناعي في Google Cloud.
5- تجهيز بيئة التطوير
إنشاء بنية الدليل
- في وحدة التحكّم، أنشئ دليل المشروع والأدلة الفرعية اللازمة:
mkdir -p ~/adk_multiagent_systems/workflow_agents cd ~/adk_multiagent_systems - في الوحدة الطرفية، نفِّذ الأمر التالي لفتح الدليل في مستكشف "محرِّر Cloud Shell".
cloudshell open-workspace ~/adk_multiagent_systems - سيتم إعادة تحميل لوحة "المستكشف" على اليمين. من المفترض أن تظهر لك الآن الأدلة التي أنشأتها.

أثناء إنشاء الملفات في الخطوات التالية، ستظهر الملفات في هذا الدليل.
إنشاء ملفات أوّلية
ستنشئ الآن ملفات البداية اللازمة للتطبيق.
- أنشئ
callback_logging.pyمن خلال تنفيذ ما يلي في الوحدة الطرفية. يتولّى هذا الملف تسجيل البيانات لأغراض المراقبة.cat <<EOF > ~/adk_multiagent_systems/callback_logging.py """ Provides helper functions for observability. Handles formatting and sending agent queries, responses, and tool calls to Google Cloud Logging to aid in monitoring and debugging. """ import logging import google.cloud.logging from google.adk.agents.callback_context import CallbackContext from google.adk.models import LlmResponse, LlmRequest def log_query_to_model(callback_context: CallbackContext, llm_request: LlmRequest): cloud_logging_client = google.cloud.logging.Client() cloud_logging_client.setup_logging() if llm_request.contents and llm_request.contents[-1].role == 'user': if llm_request.contents[-1].parts and "text" in llm_request.contents[-1].parts: last_user_message = llm_request.contents[-1].parts[0].text logging.info(f"[query to {callback_context.agent_name}]: " + last_user_message) def log_model_response(callback_context: CallbackContext, llm_response: LlmResponse): cloud_logging_client = google.cloud.logging.Client() cloud_logging_client.setup_logging() if llm_response.content and llm_response.content.parts: for part in llm_response.content.parts: if part.text: logging.info(f"[response from {callback_context.agent_name}]: " + part.text) elif part.function_call: logging.info(f"[function call from {callback_context.agent_name}]: " + part.function_call.name) EOF - أنشئ
workflow_agents/__init__.pyمن خلال تنفيذ ما يلي في الوحدة الطرفية. يضع هذا الملف علامة على الدليل باعتباره حزمة Python.cat <<EOF > ~/adk_multiagent_systems/workflow_agents/__init__.py """ Marks the directory as a Python package and exposes the agent module, allowing the ADK to discover and register the agents defined within. """ from . import agent EOF - أنشئ
workflow_agents/agent.pyمن خلال تنفيذ ما يلي في الوحدة الطرفية. يحتوي هذا الملف على المنطق الأساسي لفريقك المتعدّد الوكلاء.cat <<EOF > ~/adk_multiagent_systems/workflow_agents/agent.py """ Defines the core multi-agent workflow. Configures individual agents (Researcher, Screenwriter, File Writer), assigns their specific tools, and orchestrates their collaboration using the ADK's SequentialAgent pattern. """ import os import logging import google.cloud.logging from callback_logging import log_query_to_model, log_model_response from dotenv import load_dotenv from google.adk import Agent from google.adk.agents import SequentialAgent, LoopAgent, ParallelAgent from google.adk.tools.tool_context import ToolContext from google.adk.tools.langchain_tool import LangchainTool # import from google.genai import types from langchain_community.tools import WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper cloud_logging_client = google.cloud.logging.Client() cloud_logging_client.setup_logging() load_dotenv() model_name = os.getenv("MODEL") print(model_name) # Tools def append_to_state( tool_context: ToolContext, field: str, response: str ) -> dict[str, str]: """Append new output to an existing state key. Args: field (str): a field name to append to response (str): a string to append to the field Returns: dict[str, str]: {"status": "success"} """ existing_state = tool_context.state.get(field, []) tool_context.state[field] = existing_state + [response] logging.info(f"[Added to {field}] {response}") return {"status": "success"} def write_file( tool_context: ToolContext, directory: str, filename: str, content: str ) -> dict[str, str]: target_path = os.path.join(directory, filename) os.makedirs(os.path.dirname(target_path), exist_ok=True) with open(target_path, "w") as f: f.write(content) return {"status": "success"} # Agents file_writer = Agent( name="file_writer", model=model_name, description="Creates marketing details and saves a pitch document.", instruction=""" PLOT_OUTLINE: { PLOT_OUTLINE? } INSTRUCTIONS: - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE. If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one. - Use your 'write_file' tool to create a new txt file with the following arguments: - for a filename, use the movie title - Write to the 'movie_pitches' directory. - For the 'content' to write, extract the following from the PLOT_OUTLINE: - A logline - Synopsis or plot outline """, generate_content_config=types.GenerateContentConfig( temperature=0, ), tools=[write_file], ) screenwriter = Agent( name="screenwriter", model=model_name, description="As a screenwriter, write a logline and plot outline for a biopic about a historical character.", instruction=""" INSTRUCTIONS: Your goal is to write a logline and three-act plot outline for an inspiring movie about a historical character(s) described by the PROMPT: { PROMPT? } - If there is CRITICAL_FEEDBACK, use those thoughts to improve upon the outline. - If there is RESEARCH provided, feel free to use details from it, but you are not required to use it all. - If there is a PLOT_OUTLINE, improve upon it. - Use the 'append_to_state' tool to write your logline and three-act plot outline to the field 'PLOT_OUTLINE'. - Summarize what you focused on in this pass. PLOT_OUTLINE: { PLOT_OUTLINE? } RESEARCH: { research? } CRITICAL_FEEDBACK: { CRITICAL_FEEDBACK? } """, generate_content_config=types.GenerateContentConfig( temperature=0, ), tools=[append_to_state], ) researcher = Agent( name="researcher", model=model_name, description="Answer research questions using Wikipedia.", instruction=""" PROMPT: { PROMPT? } PLOT_OUTLINE: { PLOT_OUTLINE? } CRITICAL_FEEDBACK: { CRITICAL_FEEDBACK? } INSTRUCTIONS: - If there is a CRITICAL_FEEDBACK, use your wikipedia tool to do research to solve those suggestions - If there is a PLOT_OUTLINE, use your wikipedia tool to do research to add more historical detail - If these are empty, use your Wikipedia tool to gather facts about the person in the PROMPT - Use the 'append_to_state' tool to add your research to the field 'research'. - Summarize what you have learned. Now, use your Wikipedia tool to do research. """, generate_content_config=types.GenerateContentConfig( temperature=0, ), tools=[ LangchainTool(tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())), append_to_state, ], ) film_concept_team = SequentialAgent( name="film_concept_team", description="Write a film plot outline and save it as a text file.", sub_agents=[ researcher, screenwriter, file_writer ], ) root_agent = Agent( name="greeter", model=model_name, description="Guides the user in crafting a movie plot.", instruction=""" - Let the user know you will help them write a pitch for a hit movie. Ask them for a historical figure to create a movie about. - When they respond, use the 'append_to_state' tool to store the user's response in the 'PROMPT' state key and transfer to the 'film_concept_team' agent """, generate_content_config=types.GenerateContentConfig( temperature=0, ), tools=[append_to_state], sub_agents=[film_concept_team], ) EOF
يجب أن تبدو بنية الملف الآن على النحو التالي: 
إعداد البيئة الافتراضية
- في وحدة التحكّم، أنشئ بيئة افتراضية وفعّلها باستخدام
uv. يضمن ذلك عدم تعارض تبعيات مشروعك مع لغة Python في النظام.uv venv source .venv/bin/activate
متطلبات التثبيت
- نفِّذ الأمر التالي في الوحدة الطرفية لإنشاء ملف
requirements.txt.cat <<EOF > ~/adk_multiagent_systems/requirements.txt # Lists all Python dependencies required to run the multi-agent system, # including the Google ADK, LangChain community tools, and web server libraries. langchain-community==0.4.1 wikipedia==1.4.0 google-adk==1.27.5 fastapi==0.135.2 uvicorn==0.42.0 EOF - ثبِّت الحِزم المطلوبة في بيئتك الافتراضية في وحدة التحكّم.
uv pip install -r requirements.txt
إعداد متغيّرات البيئة
- استخدِم الأمر التالي في الوحدة الطرفية لإنشاء ملف
.env، مع إدراج رقم تعريف مشروعك ومنطقتك تلقائيًا.cat <<EOF > ~/adk_multiagent_systems/.env GOOGLE_CLOUD_PROJECT="$(gcloud config get-value project)" GOOGLE_CLOUD_PROJECT_NUMBER="$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')" REGION="us-central1" GOOGLE_CLOUD_LOCATION="global" GOOGLE_GENAI_USE_ENTERPRISE=true MODEL="gemini-3.5-flash" EOF - في وحدة التحكّم، حمِّل المتغيّرات في جلسة shell.
source .env
ملخّص
في هذا القسم، وضعت الأساس المحلي لمشروعك:
- تم إنشاء بنية الدليل وملفات بدء تشغيل الوكيل اللازمة (
agent.pyوcallback_logging.pyوrequirements.txt). - عزل التبعيات باستخدام بيئة افتراضية (
uv) - تم ضبط متغيّرات البيئة (
.env) لتخزين تفاصيل خاصة بالمشروع، مثل رقم تعريف المشروع والمنطقة.
6. استكشاف ملف الوكيل
لقد أعددت رمز المصدر للمختبر، بما في ذلك نظام مكتوب مسبقًا يستند إلى عدّة وكلاء. قبل نشر التطبيق، من المفيد فهم كيفية تحديد العملاء. يقع منطق الوكيل الأساسي في workflow_agents/agent.py.
- في "محرِّر Cloud Shell"، استخدِم مستكشف الملفات على اليمين للانتقال إلى
adk_multiagent_systems/workflow_agents/وفتح الملفagent.py. - يُرجى تخصيص بعض الوقت للاطّلاع على الملف. لست بحاجة إلى فهم كل سطر، ولكن لاحظ البنية العامة:
- الوكلاء الفرديون: يحدّد الملف ثلاثة عناصر
Agentمميزة:researcherوscreenwriterوfile_writer. يتم تزويد كل وكيلinstruction(طلبه) وقائمةtoolsيُسمح له باستخدامها (مثل أداةWikipediaQueryRunأو أداةwrite_fileمخصّصة). - تكوين الوكيل: يتم ربط الوكلاء الفرديين معًا في
SequentialAgentيُسمىfilm_concept_team. يطلب ذلك من حزمة تطوير البرامج (ADK) تشغيل هذه الوكلاء واحدًا تلو الآخر، مع نقل الحالة من وكيل إلى آخر. - الوكيل الجذر: يتم تحديد
root_agent(يُسمى "greeter") للتعامل مع تفاعل المستخدم الأوّلي. عندما يقدّم المستخدم طلبًا، يحفظ هذا الوكيل الطلب في حالة التطبيق ثم ينقل عنصر التحكّم إلى سير عملfilm_concept_team.
- الوكلاء الفرديون: يحدّد الملف ثلاثة عناصر
يساعد فهم هذا الهيكل في توضيح ما أنت بصدد نشره: ليس مجرد وكيل واحد، بل فريق من الوكلاء المتخصصين المنسقين بواسطة ADK.
7. إنشاء مجموعة GKE Autopilot
بعد إعداد بيئتك، تتمثّل الخطوة التالية في توفير البنية الأساسية التي سيتم تشغيل تطبيقك عليها. ستنشئ مجموعة GKE Autopilot، والتي ستكون الأساس لعملية النشر. نستخدم وضع Autopilot لأنّه يتعامل مع الإدارة المعقّدة للعُقد الأساسية للمجموعة وقابلية التوسّع والأمان، ما يتيح لك التركيز فقط على نشر تطبيقك.
- في وحدة التحكّم، أنشئ مجموعة جديدة من GKE Autopilot باسم
adk-cluster. يوفّر هذا الأمر مجموعة Kubernetes مُدارة بالكامل. يضبط وضع التشغيل التلقائي في GKE تلقائيًا الإعدادات المتعلقة بالعُقد وقابلية التوسّع والأمان، ما يسهّل عمليات المجموعات.gcloud container clusters create-auto adk-cluster \ --location=$REGION \ --project=$GOOGLE_CLOUD_PROJECT - بعد إنشاء المجموعة، اضبط
kubectlللاتصال بها من خلال تنفيذ ما يلي في الوحدة الطرفية: يربط هذا الأمر بيئة التطوير المحلية بمجموعة GKE الجديدة. يتم تلقائيًا جلب نقطة نهاية المجموعة وبيانات اعتماد المصادقة وتعديل ملف إعداد محلي (gcloud container clusters get-credentials adk-cluster \ --location=$REGION \ --project=$GOOGLE_CLOUD_PROJECT~/.kube/config). من هذه النقطة فصاعدًا، ستتم مصادقة أداة سطر الأوامرkubectlوتوجيهها للتواصل معadk-cluster.
ملخّص
في هذا القسم، تم توفير البنية الأساسية:
- أنشأنا مجموعة GKE Autopilot مُدارة بالكامل باستخدام
gcloud. - تم ضبط أداة
kubectlالمحلية للمصادقة والتواصل مع المجموعة الجديدة.
8. إنشاء حاوية للتطبيق ونشره
لا يتوفّر رمز وكيلك حاليًا إلا في بيئة Cloud Shell. لتشغيله على GKE، يجب أولاً تجميعه في صورة حاوية. صورة الحاوية هي ملف ثابت وقابل للنقل يجمع الرمز البرمجي لتطبيقك مع جميع العناصر التابعة له. عند تشغيل هذه الصورة، ستصبح حاوية نشطة.
تتضمّن هذه العملية ثلاث خطوات رئيسية:
- إنشاء نقطة دخول: حدِّد ملف
main.pyلتحويل منطق الوكيل إلى خادم ويب قابل للتنفيذ. - تحديد صورة الحاوية: أنشئ Dockerfile يعمل كمخطط لإنشاء صورة الحاوية.
- الإنشاء والنشر: استخدِم Cloud Build لتنفيذ Dockerfile، ما يؤدي إلى إنشاء صورة الحاوية ونشرها في Google Artifact Registry، وهو مستودع آمن لصورك.
تجهيز التطبيق للنشر
يحتاج وكيل ADK إلى خادم ويب لتلقّي الطلبات. سيعمل ملف main.py كنقطة دخول هذه، وسيستخدم إطار عمل FastAPI لعرض وظائف وكيلك عبر HTTP.
- في جذر دليل
adk_multiagent_systemsفي النافذة الطرفية، أنشئ ملفًا جديدًا باسمmain.py. يستخدم هذا الملف مكتبة ADK لاكتشاف الوكلاء في مشروعك وتضمينهم في تطبيق ويب FastAPI. يشغّل الخادمcat <<EOF > ~/adk_multiagent_systems/main.py """ Serves as the application entry point. Initializes the FastAPI web server, discovers the agents defined in the workflow directory, and exposes them via HTTP endpoints for interaction. """ import os import uvicorn from fastapi import FastAPI from google.adk.cli.fast_api import get_fast_api_app # Get the directory where main.py is located AGENT_DIR = os.path.dirname(os.path.abspath(__file__)) # Configure the session service (e.g., SQLite for local storage) SESSION_SERVICE_URI = "sqlite:///./sessions.db" # Configure CORS to allow requests from various origins for this lab ALLOWED_ORIGINS = ["http://localhost", "http://localhost:8080", "*"] # Enable the ADK's built-in web interface SERVE_WEB_INTERFACE = True # Call the ADK function to discover agents and create the FastAPI app app: FastAPI = get_fast_api_app( agents_dir=AGENT_DIR, session_service_uri=SESSION_SERVICE_URI, allow_origins=ALLOWED_ORIGINS, web=SERVE_WEB_INTERFACE, ) # You can add more FastAPI routes or configurations below if needed # Example: # @app.get("/hello") # async def read_root(): # return {"Hello": "World"} if __name__ == "__main__": # Get the port from the PORT environment variable provided by the container runtime # Run the Uvicorn server, listening on all available network interfaces (0.0.0.0) uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080))) EOFuvicornهذا التطبيق، ويستمع إلى المضيف0.0.0.0لقبول الاتصالات من أي عنوان IP وعلى المنفذ المحدّد بواسطة متغيّر البيئةPORT، والذي سنحدّده لاحقًا في بيان Kubernetes.
في هذه المرحلة، يجب أن يبدو هيكل الملف كما يظهر في لوحة المستكشف في "محرّر Cloud Shell" على النحو التالي:
تضمين وكيل ADK في حاوية باستخدام Docker
لنشر تطبيقنا على GKE، علينا أولاً تجميعه في صورة حاوية، والتي تجمع رمز تطبيقنا مع جميع المكتبات والعناصر التابعة التي يحتاجها لتشغيله. سنستخدم Docker لإنشاء صورة الحاوية هذه.
- في جذر دليل
adk_multiagent_systemsفي النافذة الطرفية، أنشئ ملفًا جديدًا باسمDockerfile. في هذه المرحلة، يجب أن يبدو هيكل الملف كما يظهر في لوحة المستكشف في "محرّر Cloud Shell" على النحو التالي:cat <<'EOF' > ~/adk_multiagent_systems/Dockerfile # Defines the blueprint for the container image. Installs dependencies, # sets up a secure non-root user, and specifies the startup command to run the # agent web server. # Use an official lightweight Python image as the base FROM python:3.13-slim # Set the working directory inside the container WORKDIR /app # Create a non-root user for security best practices RUN adduser --disabled-password --gecos "" myuser # Copy and install dependencies first to leverage Docker's layer caching COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # Copy all application code into the container COPY . . # Create the directory where the agent will write files at runtime # The -p flag ensures the command doesn't fail if the directory already exists RUN mkdir -p movie_pitches # Change ownership of EVERYTHING in /app to the non-root user # Without this, the running agent would be denied permission to write files. RUN chown -R myuser:myuser /app # Switch the active user from root to the non-root user USER myuser # Add the user's local binary directory to the system's PATH ENV PATH="/home/myuser/.local/bin:$PATH" # Define the command to run when the container starts CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port $PORT"] EOF
إنشاء صورة الحاوية ونشرها في Artifact Registry
بعد إنشاء Dockerfile، ستستخدم Cloud Build لإنشاء الصورة ونقلها إلى Artifact Registry، وهو سجلّ خاص وآمن ومتكامل مع خدمات Google Cloud. سيجلب GKE الصورة من هذا السجلّ لتشغيل تطبيقك.
- في وحدة التحكّم، أنشئ مستودع Artifact Registry جديدًا لتخزين صورة الحاوية.
gcloud artifacts repositories create adk-repo \ --repository-format=docker \ --location=$REGION \ --description="ADK repository" - في وحدة التحكّم، استخدِم
gcloud builds submitلإنشاء صورة الحاوية ونقلها إلى المستودع. يستخدم هذا الأمر الفردي Cloud Build، وهي منصة دمج مستمر/نشر مستمر بدون خادم، لتنفيذ الخطوات فيgcloud builds submit \ --tag $REGION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo/adk-agent:latest \ --project=$GOOGLE_CLOUD_PROJECT \ .Dockerfile. تنشئ هذه الأداة الصورة في السحابة الإلكترونية، وتضع علامة عليها تتضمّن عنوان مستودع Artifact Registry، ثم ترسلها إلى هناك تلقائيًا. - من الوحدة الطرفية، تأكَّد من إنشاء الصورة:
gcloud artifacts docker images list \ $REGION-docker.pkg.dev/$GOOGLE_CLOUD_PROJECT/adk-repo \ --project=$GOOGLE_CLOUD_PROJECT
ملخّص
في هذا القسم، تم تجميع الرمز البرمجي لنشره:
- تم إنشاء نقطة دخول
main.pyلتضمين الوكلاء في خادم ويب FastAPI. - تم تحديد
Dockerfileلتجميع التعليمات البرمجية والتبعيات في صورة قابلة للنقل. - استخدَم Cloud Build لإنشاء الصورة ونقلها إلى مستودع Artifact Registry آمن.
9. إنشاء ملفات بيانات Kubernetes
بعد إنشاء صورة الحاوية وتخزينها في Artifact Registry، عليك إعطاء تعليمات إلى GKE بشأن كيفية تشغيلها. يتضمّن ذلك نشاطَين رئيسيَّين:
- ضبط الأذونات: عليك إنشاء هوية مخصّصة للوكيل داخل المجموعة ومنحه إذن الوصول الآمن إلى واجهات Google Cloud API التي يحتاجها (Gemini Enterprise Agent Platform على وجه التحديد).
- تحديد حالة التطبيق: ستكتب ملف بيان Kubernetes، وهو مستند YAML يحدّد بشكل تصريحي كل ما يحتاج إليه تطبيقك للتشغيل، بما في ذلك صورة الحاوية ومتغيرات البيئة وكيفية عرضه على الشبكة.
إعداد حساب خدمة Kubernetes لمنصة Gemini Enterprise Agent
يحتاج الوكيل إلى إذن للتواصل مع واجهة برمجة التطبيقات Gemini Enterprise Agent Platform للوصول إلى نماذج Gemini. الطريقة الأكثر أمانًا والمقترَحة لمنح هذا الإذن في GKE هي Workload Identity. تتيح لك ميزة Workload Identity ربط هوية أصلية في Kubernetes (حساب خدمة Kubernetes) بهوية في Google Cloud (حساب خدمة في "إدارة الهوية وإمكانية الوصول")، ما يغنيك تمامًا عن الحاجة إلى تنزيل مفاتيح JSON الثابتة وإدارتها وتخزينها.
- في وحدة التحكّم، أنشئ حساب خدمة Kubernetes (
adk-agent-sa). يؤدي ذلك إلى إنشاء هوية للوكيل داخل مجموعة GKE التي يمكن أن تستخدمها وحداتك.kubectl create serviceaccount adk-agent-sa - في وحدة التحكّم، اربط حساب خدمة Kubernetes بـ Cloud IAM في Google Cloud من خلال إنشاء ربط سياسة. يمنح هذا الأمر الدور
aiplatform.userإلىadk-agent-sa، ما يسمح له باستدعاء واجهة برمجة التطبيقات Gemini Enterprise Agent Platform API بشكل آمن.gcloud projects add-iam-policy-binding projects/${GOOGLE_CLOUD_PROJECT} \ --role=roles/aiplatform.user \ --member=principal://iam.googleapis.com/projects/${GOOGLE_CLOUD_PROJECT_NUMBER}/locations/global/workloadIdentityPools/${GOOGLE_CLOUD_PROJECT}.svc.id.goog/subject/ns/default/sa/adk-agent-sa \ --condition=None
إنشاء ملفات بيان Kubernetes
يستخدم Kubernetes ملفات بيان YAML لتحديد الحالة المطلوبة لتطبيقك. ستنشئ ملف deployment.yaml يحتوي على عنصرَين أساسيَّين من عناصر Kubernetes، وهما Deployment وService.
- من الوحدة الطرفية، أنشئ ملف
deployment.yaml. في هذه المرحلة، يجب أن يبدو هيكل الملف كما يظهر في لوحة المستكشف في "محرّر Cloud Shell" على النحو التالي:cat <<EOF > ~/adk_multiagent_systems/deployment.yaml # Defines the Kubernetes resources required to deploy the application to GKE. # Includes the Deployment (to run the container pods) and the Service # (to expose the application via a Load Balancer). apiVersion: apps/v1 kind: Deployment metadata: name: adk-agent spec: replicas: 1 selector: matchLabels: app: adk-agent template: metadata: labels: app: adk-agent spec: # Assign the Kubernetes Service Account for Workload Identity serviceAccountName: adk-agent-sa containers: - name: adk-agent imagePullPolicy: Always # The path to the container image in Artifact Registry image: ${REGION}-docker.pkg.dev/${GOOGLE_CLOUD_PROJECT}/adk-repo/adk-agent:latest # Define the resources for GKE Autopilot to provision resources: limits: memory: "1Gi" cpu: "1000m" ephemeral-storage: "512Mi" requests: memory: "1Gi" cpu: "1000m" ephemeral-storage: "512Mi" ports: - containerPort: 8080 # Environment variables passed to the application env: - name: PORT value: "8080" - name: GOOGLE_CLOUD_PROJECT value: ${GOOGLE_CLOUD_PROJECT} - name: GOOGLE_CLOUD_LOCATION value: ${GOOGLE_CLOUD_LOCATION} - name: GOOGLE_GENAI_USE_ENTERPRISE value: "true" - name: MODEL value: "gemini-3.5-flash" --- apiVersion: v1 kind: Service metadata: name: adk-agent spec: # Create a public-facing Network Load Balancer with an external IP type: LoadBalancer ports: - port: 80 targetPort: 8080 selector: app: adk-agent EOF
ملخّص
في هذا القسم، حدّدت إعدادات الأمان والنشر:
- تم إنشاء حساب خدمة Kubernetes وربطه بـ Google Cloud IAM باستخدام Workload Identity، ما يتيح لوحدات pod الوصول بأمان إلى "منصة وكيل Gemini Enterprise" بدون إدارة المفاتيح.
- تم إنشاء ملف
deployment.yamlيحدّد عملية النشر (كيفية تشغيل وحدات pod) والخدمة (كيفية عرضها من خلال موازن التحميل).
10. نشر التطبيق على GKE
بعد تحديد ملف البيان ودفع صورة الحاوية إلى Artifact Registry، يمكنك الآن نشر تطبيقك. في هذه المهمة، ستستخدم kubectl لتطبيق الإعدادات على مجموعة GKE، ثم ستراقب الحالة للتأكّد من بدء تشغيل الوكيل بشكلٍ صحيح.
- في الوحدة الطرفية، طبِّق بيان
deployment.yamlعلى مجموعتك. يرسل الأمرkubectl apply -f deployment.yamlkubectl applyملفdeployment.yamlإلى خادم Kubernetes API. بعد ذلك، يقرأ الخادم إعداداتك وينسّق عملية إنشاء كائنَي Deployment وService. - في وحدة التحكّم، تحقَّق من حالة عملية النشر في الوقت الفعلي. انتظِر إلى أن تصبح الحاويات في الحالة
Running. ستلاحظ أنّ الحزمة تنتقل عبر عدة مراحل:kubectl get pods -l=app=adk-agent --watch- في انتظار المراجعة: قبلت المجموعة الوحدة، ولكن لم يتم إنشاء الحاوية بعد.
- إنشاء الحاوية: يسحب GKE صورة الحاوية من Artifact Registry ويبدأ الحاوية.
- الركض: تمّت الإضافة بنجاح. الحاوية قيد التشغيل، وتطبيق الوكيل نشط.
- عندما تظهر الحالة
Running، اضغط على CTRL+C في النافذة الطرفية لإيقاف أمر المراقبة والرجوع إلى موجّه الأوامر.
ملخّص
في هذا القسم، أطلقنا عبء العمل:
- يُستخدَم
kubectlapply لإرسال البيان إلى المجموعة. - تتبُّع دورة حياة Pod (في انتظار المراجعة -> إنشاء الحاوية -> قيد التشغيل) لضمان بدء التطبيق بنجاح
11. التفاعل مع الوكيل
يعمل وكيل ADK الآن مباشرةً على GKE ويمكن الوصول إليه على الإنترنت من خلال جهاز موازنة حمل عام. سيتم ربطك بواجهة الويب الخاصة بالوكيل للتفاعل معه والتأكّد من أنّ النظام بأكمله يعمل بشكل صحيح.
العثور على عنوان IP الخارجي لخدمتك
للوصول إلى الوكيل، عليك أولاً الحصول على عنوان IP متاح للجميع وفّره GKE لخدمتك.
- في الوحدة الطرفية، نفِّذ الأمر التالي للحصول على تفاصيل خدمتك.
kubectl get service adk-agent - ابحث عن القيمة في العمود
EXTERNAL-IP. قد يستغرق تعيين عنوان IP دقيقة أو دقيقتَين بعد نشر الخدمة لأول مرة. إذا ظهرت القيمةpending، انتظِر دقيقة واحدة وأعِد تنفيذ الأمر. ستبدو النتيجة على النحو التالي: العنوان المُدرَج ضمنNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE adk-agent-service LoadBalancer 10.120.12.234 34.123.45.67 80:31234/TCP 5mEXTERNAL-IP(مثلاً، 34.123.45.67) هو نقطة الدخول العلنية إلى الوكيل.
اختبار الوكيل الذي تم نشره
يمكنك الآن استخدام عنوان IP العلني للوصول إلى واجهة مستخدم الويب المضمّنة في حزمة تطوير البرامج (ADK) مباشرةً من المتصفّح.
- انسخ عنوان IP الخارجي (
EXTERNAL-IP) من النافذة الطرفية. - افتح علامة تبويب جديدة في متصفّح الويب واكتب
http://[EXTERNAL-IP]، مع استبدال[EXTERNAL-IP]بعنوان IP الذي نسخته. - من المفترض أن تظهر لك الآن واجهة ADK على الويب.
- تأكَّد من اختيار workflow_agents في القائمة المنسدلة الخاصة بالوكيل.
- فعِّل ميزة بث الرموز المميزة.
- اكتب
helloواضغط على Enter لبدء محادثة جديدة. - لاحظ النتيجة. يجب أن يردّ الوكيل بسرعة بعبارة الترحيب: "يمكنني مساعدتك في كتابة أغنية ترويجية لفيلم ناجح. ما هي الشخصية التاريخية التي تريد صناعة فيلم عنها؟"
- عندما يُطلب منك اختيار شخصية تاريخية، اختَر شخصية تهمّك. إليك بعض الأفكار:
the most successful female pirate in historythe woman who invented the first computer compilera legendary lawman of the American Wild West
ملخّص
في هذا القسم، تحقّقنا من عملية النشر:
- تم استرداد عنوان IP الخارجي الذي خصّصه LoadBalancer.
- الوصول إلى واجهة مستخدم الويب الخاصة بـ ADK من خلال متصفّح للتأكّد من أنّ نظام الوكلاء المتعدّدين يستجيب ويعمل بشكل سليم
12. ضبط القياس التلقائي
من التحديات الرئيسية في مرحلة الإنتاج التعامل مع زيارات المستخدمين غير المتوقّعة. إنّ الترميز الثابت لعدد محدّد من النسخ المتماثلة، كما فعلت في المهمة السابقة، يعني أنّك إما ستدفع مبالغ زائدة مقابل الموارد غير المستخدَمة أو ستواجه أداءً ضعيفًا خلال الارتفاعات المفاجئة في عدد الزيارات. تحلّ GKE هذه المشكلة من خلال التوسّع التلقائي.
ستضبط HorizontalPodAutoscaler (HPA)، وهو أداة تحكّم في Kubernetes تعمل على تعديل عدد الوحدات النشطة تلقائيًا في عملية النشر استنادًا إلى استخدام وحدة المعالجة المركزية في الوقت الفعلي.
- في وحدة التحكّم في "محرّر Cloud Shell"، أنشئ ملف
hpa.yamlجديدًا في جذر الدليلadk_multiagent_systems.cloudshell edit ~/adk_multiagent_systems/hpa.yaml - أضِف المحتوى التالي إلى ملف
hpa.yamlالجديد: يستهدف عنصر HPA هذا عملية النشر# Configures the HorizontalPodAutoscaler (HPA) to automatically scale # the number of running agent pods up or down based on CPU utilization # to handle varying traffic loads. apiVersion: autoscaling/v1 kind: HorizontalPodAutoscaler metadata: name: adk-agent-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: adk-agent minReplicas: 1 maxReplicas: 5 targetCPUUtilizationPercentage: 50adk-agent. يضمن ذلك تشغيل وحدة واحدة على الأقل دائمًا، ويضبط الحد الأقصى على 5 وحدات، كما سيضيف/يزيل النسخ المتماثلة للحفاظ على متوسط استخدام وحدة المعالجة المركزية عند %50 تقريبًا. في هذه المرحلة، يجب أن يبدو هيكل الملف كما هو معروض في لوحة المستكشف في Cloud Shell Editor على النحو التالي:
- طبِّق HPA على مجموعتك عن طريق لصق هذا الرمز في نافذة الأوامر.
kubectl apply -f hpa.yaml
التحقّق من أداة التحجيم التلقائي
أصبحت ميزة "التحجيم التلقائي الأفقي" نشطة الآن وتراقب عملية النشر. يمكنك الاطّلاع على حالته لرؤيته أثناء العمل.
- نفِّذ الأمر التالي في الوحدة الطرفية للحصول على حالة HPA.
ستظهر النتيجة على النحو التالي:kubectl get hpa adk-agent-hpa سيتم الآن توسيع نطاق الوكيل تلقائيًا استجابةً لحجم الزيارات.NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE adk-agent-hpa Deployment/adk-agent 0%/50% 1 5 1 30s
ملخّص
في هذا القسم، تم تحسين الأداء لزيادة عدد الزيارات إلى بيئة الإنتاج:
- تم إنشاء ملف
hpa.yamlلتحديد قواعد تغيير الحجم. - تم نشر HorizontalPodAutoscaler (HPA) لتعديل عدد نُسخ التطبيق المتطابق تلقائيًا استنادًا إلى استخدام وحدة المعالجة المركزية.
13. الاستعداد للإصدار العلني
ملاحظة: الأقسام التالية مخصّصة لأغراض توفير المعلومات فقط ولا تتضمّن خطوات إضافية لتنفيذها. وهي مصمَّمة لتقديم السياق وأفضل الممارسات لنقل تطبيقك إلى مرحلة الإنتاج.
تحسين الأداء من خلال تخصيص الموارد
في وضع GKE Autopilot، يمكنك التحكّم في مقدار وحدة المعالجة المركزية والذاكرة المخصّصة لتطبيقك من خلال تحديد requests الموارد في deployment.yaml.
إذا تبيّن لك أنّ وكيلك بطيء أو يتعطّل بسبب نقص الذاكرة، يمكنك زيادة تخصيص الموارد له من خلال تعديل الحظر resources في deployment.yaml وإعادة تطبيق الملف باستخدام kubectl apply.
على سبيل المثال، لمضاعفة الذاكرة:
# In deployment.yaml
# ...
resources:
requests:
memory: "2Gi" # Increased from 1Gi
cpu: "1000m"
# ...
أتمتة سير العمل باستخدام CI/CD
في هذا التمرين العملي، شغّلت الأوامر يدويًا. تتمثّل الممارسة الاحترافية في إنشاء مسار CI/CD (الدمج المستمر/النشر المستمر). من خلال ربط مستودع الرموز البرمجية (مثل GitHub) بمشغّل Cloud Build، يمكنك أتمتة عملية النشر بأكملها.
باستخدام مسار التعلّم، يمكن لخدمة Cloud Build تلقائيًا في كل مرة تدفع فيها تغييرًا في الرمز:
- أنشئ صورة الحاوية الجديدة.
- ادفع الصورة إلى Artifact Registry.
- طبِّق بيانات Kubernetes المعدَّلة على مجموعة GKE.
إدارة الأسرار بأمان
في هذا الدرس التطبيقي، خزّنت الإعدادات في ملف .env ونقلتها إلى تطبيقك. هذا مناسب للتطوير ولكنه غير آمن للبيانات الحسّاسة مثل مفاتيح واجهة برمجة التطبيقات. أفضل الممارسات المقترَحة هي استخدام Secret Manager لتخزين الأسرار بأمان.
يتضمّن GKE عملية دمج أصلية مع Secret Manager تتيح لك ربط الأسرار مباشرةً في وحدات pod كمتغيّرات بيئية أو ملفات، بدون أن يتم تسجيلها في الرمز المصدر.
إليك قسم مراجع التنظيف الذي طلبته، وقد أدرجناه قبل قسم الخلاصة مباشرةً.
14. تنظيف الموارد
لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، يمكنك إما حذف المشروع الذي يحتوي على الموارد أو الاحتفاظ بالمشروع وحذف الموارد الفردية.
حذف مجموعة GKE
مجموعة GKE هي عامل التكلفة الأساسي في هذا التمرين. سيؤدي حذفها إلى إيقاف رسوم الحوسبة.
- في الوحدة الطرفية، نفِّذ الأمر التالي:
gcloud container clusters delete adk-cluster \ --location=$REGION \ --quiet
حذف مستودع Artifact Registry
تتسبّب صور الحاويات المخزَّنة في Artifact Registry في تكاليف التخزين.
- في الوحدة الطرفية، نفِّذ الأمر التالي:
gcloud artifacts repositories delete adk-repo \ --location=$REGION \ --quiet
حذف المشروع (اختياري)
إذا أنشأت مشروعًا جديدًا خصيصًا لهذا المختبر ولا تخطّط لاستخدامه مرة أخرى، فإنّ أسهل طريقة لتنظيفه هي حذف المشروع بأكمله.
- في الوحدة الطرفية، نفِّذ الأمر التالي (استبدِل
[YOUR_PROJECT_ID]برقم تعريف مشروعك الفعلي):gcloud projects delete [YOUR_PROJECT_ID]
15. الخاتمة
تهانينا! لقد نشرت بنجاح تطبيقًا متعدد الوكلاء باستخدام "حزمة تطوير الوكلاء" (ADK) في مجموعة GKE متوافقة مع بيئة الإنتاج. هذا إنجاز مهم يغطّي دورة الحياة الأساسية لتطبيق حديث متوافق مع السحابة الإلكترونية، ما يوفّر لك أساسًا متينًا لنشر أنظمتك المعقّدة المستندة إلى الوكلاء.
ملخّص
في هذه الميزة الاختبارية، تعرّفت على كيفية:
- توفير مجموعة GKE Autopilot
- إنشاء صورة حاوية باستخدام
Dockerfileونشرها إلى Artifact Registry - يمكنك الاتصال بشكل آمن بواجهات Google Cloud APIs باستخدام Workload Identity.
- اكتب بيانات Kubernetes لعمليات النشر والخدمات.
- عرض تطبيق على الإنترنت باستخدام LoadBalancer
- اضبط التدرّج التلقائي باستخدام HorizontalPodAutoscaler (HPA).