إدارة أحمال العمل المستندة إلى الذكاء الاصطناعي الوكيل باستخدام Agent Gateway على "منصة وكيل Gemini Enterprise"

1. مقدمة

منصة وكيل Gemini Enterprise هي منصة مفتوحة لإنشاء وكلاء الذكاء الاصطناعي المستند إلى بيانات محدَّدة المصدر والمصمَّمة للمؤسسات، وتوسيع نطاقهم وإدارتهم وتحسينهم.

توفّر بيئة تشغيل الوكيل بيئة تنفيذ مُدارة لتشغيل الوكلاء، مثل الوكلاء الذين تم إنشاؤهم باستخدام حزمة تطوير الوكلاء (ADK) مفتوحة المصدر، بأمان ضمن Google Cloud.

يستكشف هذا الدرس التطبيقي حول الترميز كيفية استخدام هذه اللبنات الأساسية لإدارة وكيل بدأه مستخدم في Gemini Enterprise أثناء وصوله بأمان إلى الأدوات الداخلية.

لمحة عن Agent Gateway

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

تسهّل هذه الميزة مسارَين أساسيَّين للوصول المُدار:

  • من العميل إلى الوكيل (الدخول): يؤمّن هذا الخيار الاتصالات بين العملاء الخارجيين (مثل Cursor أو Gemini CLI) والوكلاء.
  • الوكيل إلى أي مكان (الخروج): يؤمِّن هذا الخيار الاتصالات بين الوكلاء الذين يعملون على Google Cloud والخوادم أو الأدوات أو واجهات برمجة التطبيقات التي تعمل في أي مكان.

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

التحكّم في الوصول باستخدام Agent Gateway

لفرض سياسات الأمان، تتكامل "بوابة الوكيل" بشكل وثيق مع بقية المنظومة المتكاملة:

  • قاعدة بيانات الوكلاء: هي مكتبة مركزية للوكلاء والأدوات المعتمدة (بما في ذلك خوادم MCP الخارجية).
  • هوية الوكيل: هي شخصية فريدة يمكن تتبّعها لكل وكيل، ويتم تأمينها تلقائيًا باستخدام بروتوكول mTLS المتكامل.
  • ‫Identity-Aware Proxy (IAP) وإدارة الهوية وإمكانية الوصول: هي طبقة التنفيذ التلقائية التي تتحقّق من هوية الوكيل مقارنةً بأذونات إدارة الهوية وإمكانية الوصول الدقيقة قبل السماح بإجراء مكالمات إلى أدوات معيّنة.
  • Model Armor: هي إحدى وسائل الحماية المستندة إلى الذكاء الاصطناعي والمدمجة من خلال "إضافات الخدمة" لتنقية المحتوى والحماية من هجمات حقن الطلبات أو تسرُّب البيانات.

أوضاع النشر (الشبكات العامة مقابل الشبكات الخاصة في Cloud Run)

لإتاحة هذا الدرس التطبيقي حول الترميز، يمكنك الاختيار من بين مسارَين للشبكات لأدواتك الداخلية (خوادم MCP) التي تم نشرها على Cloud Run:

  1. الإعداد التلقائي (الدخول العام): يتم نشر خوادم MCP على Cloud Run باستخدام أسماء مضيفة عامة (ingress=all). يتم توجيه حركة المرور من الوكيل إلى الأدوات عبر عناوين URL عادية *.run.app. لا يتطلّب ذلك نطاقات نظام أسماء نطاقات مخصّصة، وهو أسرع طريقة للتعرّف على مفاهيم الحوكمة.
  2. آمنة (الشبكات الخاصة): بنية اختيارية وخاصة بالكامل. تكون خوادم MCP محظورة (ingress=internal-and-cloud-load-balancing) ويتم عرضها من خلال موازن تحميل التطبيقات الداخلية باستخدام مجموعة نقاط نهاية شبكة بدون خادم. يتطلّب ذلك امتلاك نطاق نظام أسماء نطاقات عام لإعداد شهادة مُدارة من Google.

ستختار المسار المفضّل لديك عند إعداد Terraform.

لمزيد من المعلومات حول إدخال نقاط نهاية الشبكة في Cloud Run، يُرجى قراءة مستنداتنا.

الإجراءات التي ستنفذّها

  • توفير حزمة البنية الأساسية باستخدام Terraform
  • إنشاء أدوات داخلية ونشرها كخوادم MCP على Cloud Run
  • نشر وكيل ADK في Agent Runtime باستخدام خروج واجهة PSC
  • ضبط إضافات خدمة Agent Gateway للوصول المستند إلى الهوية (IAM) وفحص المحتوى (Model Armor)
  • تتبُّع عملية التنفيذ الآمنة والتامّة للوكيل والتحقّق منها

المتطلبات

  • متصفّح ويب، مثل Chrome
  • مشروع على Google Cloud تم تفعيل الفوترة فيه ولديك إذن الوصول مالك
  • أذونات إدارة الهوية وإمكانية الوصول على مستوى المؤسسة (يمنح الدرس التطبيقي حول الترميز أدوارًا على مستوى المؤسسة)
  • نطاق تتحكّم فيه تم تفويضه إلى Cloud DNS (للشهادة المُدارة العامة)
  • الإلمام بـ Terraform وgcloud وأساسيات شبكات Google Cloud

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

البنية الشاملة: من Gemini Enterprise إلى Agent Runtime إلى Agent Gateway إلى خوادم MCP على Cloud Run

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

ستبدأ بتوفير الشبكات الأساسية، بما في ذلك شبكة VPC وApplication Load Balancer داخلي تم إعداده كبوابة الوكيل. بعد ذلك، ستفعّل ثلاثة خوادم Model Context Protocol (MCP) على Cloud Run. تعمل هذه الأدوات كأدوات داخلية خاصة بك:

  • إدارة المستندات (legacy-dms)
  • البريد الإلكتروني للشركة (corporate-email)
  • التحقّق من الدخل (income-verification)

بعد توفّر الأدوات، ستنشئ "مساعدًا بشأن القروض العقارية" (mortgage-agent) باستخدام حزمة ADK وتنشره في Agent Runtime. ستضبط هذا الوكيل لاستخدام واجهة PSC من أجل حركة البيانات الصادرة الخاصة، وستفعّل ميزة "اكتشاف الأدوات في وقت التشغيل" من خلال "سجلّ الوكلاء".

لتأمين عملية النقل، عليك ضبط "بوابة الوكيل" باستخدام امتدادَي خدمة. أولاً، ستتحقّق إحدى REQUEST_AUTHZ الإضافات من هوية الوكيل مقارنةً بسياسات "إدارة الهوية وإمكانية الوصول" لكل أداة، ما يضمن وصول الوكيل إلى الأدوات المصرّح بها فقط. ثانيًا، ستفحص CONTENT_AUTHZ إضافة تستخدم Model Armor طلبات الوكيل وردوده.

أخيرًا، ستسجِّل الوكيل في Gemini Enterprise، وتفعِّل مهمة اكتتاب الرهن العقاري بصفتك مستخدمًا نهائيًا، وتتحقّق من التنفيذ الآمن والمحكوم باستخدام Cloud Trace.

هذا الدرس التطبيقي حول الترميز مخصّص لمهندسي المنصات والأمان من جميع المستويات. من المتوقّع أن يستغرق إكماله حوالي 100 دقيقة.

2. قبل البدء

إنشاء مشروع والمصادقة عليه

أنشئ مشروعًا جديدًا على Google Cloud Platform (أو أعِد استخدام مشروع) مع تفعيل الفوترة، ثمّ أثبِت ملكية Cloud Shell أو جهازك المحلي:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

تفعيل واجهات برمجة التطبيقات الخاصة بالتشغيل الأوّلي

تتيح وحدة الأساس في Terraform تفعيل حوالي 30 واجهة برمجة تطبيقات عند تطبيقها لأول مرة، ولكن يلزم توفير مجموعة صغيرة من عمليات الإعداد الأوّلي لكل من terraform init وحزمة GCS:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

تثبيت الأدوات المطلوبة

ثبِّت مجموعة الأدوات. تتوفّر معظم هذه الأدوات في Cloud Shell، أما على محطة العمل، فيجب اتّباع الخطوات التالية:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

تحتاج أيضًا إلى Terraform >= 1.12.2 وPython 3.12+ وGoogle Cloud SDK (gcloud).

ضبط متغيرات البيئة

تفترض بقية الدرس التطبيقي حول الترميز أنّه تم تصدير هذه المتغيرات في shell.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com"

تأكَّد من أنّ جميع المتغيّرات تمّت تعبئتها بشكل صحيح، ويجب أن يتم عرض ثلاث قيم.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

إذا لم يتم ملء حقل "معرّف المؤسسة" تلقائيًا، يمكنك العثور عليه وتعيينه يدويًا.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3- إنشاء نسخة طبق الأصل من المستودع 

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

في ما يلي جولة سريعة في محتوى دليل العرض التوضيحي:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. إنشاء حزمة حالة Terraform وإعداد الخلفية

أنشِئ حزمة GCS لتخزين الحالة البعيدة، ثم انسخ نموذج الخلفية:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

عدِّل terraform/backend.conf باستخدام قيمك:

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

5- (اختياري) إنشاء منطقة Cloud DNS عامة

بشكلٍ تلقائي، تم ضبط إعدادات الدخول في Cloud Run لهذه البيئة الاختبارية على all، ويسجّل Agent Registry كل خادم MCP في عنوان URL العام *.run.app الخاص به، بدون الحاجة إلى نظام أسماء نطاقات أو شهادات أو موازنة تحميل إضافية. إذا أردت التبديل إلى الشبكات الخاصة (Cloud Run مع ingress = internal-and-cloud-load-balancing خلف موازن تحميل داخلي للتطبيقات)، ستحتاج أيضًا إلى منطقة نظام أسماء النطاقات عامة في Cloud DNS حتى يتمكّن Certificate Manager من التحقّق من صحة شهادة موازن التحميل.

الخطوات العالية المستوى لعملية الربط بالشبكة الخاصة

الخطوات العالية المستوى لخيار الشبكات الخاصة

لاستخدام أسلوب الشبكات الخاصة، اتّبِع الخطوات التالية:

  1. أنشئ منطقة Cloud DNS العامة، إذ يتحقّق Certificate Manager من صحة الشهادة المُدارة الإقليمية من خلال كتابة سجلّات CNAME فيها:
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

يتم إنشاء المنطقة الخاصة المقابلة لـ mcp.${DOMAIN_NAME} (التي يستخدمها موازن التحميل الداخلي في MCP ونظير نظام أسماء النطاقات من Agent Runtime) تلقائيًا بواسطة Terraform، لذا لا تحتاج إلى إنشائها يدويًا. عند إيقاف الشبكات الخاصة، لا يتم توفير أي من المنطقتين العامة أو الخاصة.

6. ضبط متغيرات Terraform

انسخ ملف tfvars النموذجي وعدِّله:

cp terraform/example.tfvars terraform/terraform.tfvars

يتوفّر مساران للعرض التوضيحي، ويتم التحكّم في الوصول إليهما من خلال enable_cloud_run_private_networking.

المسار التلقائي: Cloud Run مع حركة المرور الواردة المتاحة للجميع

أبسط عملية إعداد: بالنسبة إلى المسار التلقائي، ما عليك سوى تعديل ثلاث قيم في terraform.tfvars. تحتوي كل متغيّرات الملف الأخرى على قيمة تلقائية مناسبة للعرض التوضيحي.

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:admin@example.com"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

الاتصال بالشبكات الخاصة (اختياري)

اضبط enable_cloud_run_private_networking = true وأضِف المتغيّرات أدناه لتوفير حزمة آمنة كاملة:

  • موازنة الحمل للتطبيقات الداخلية
  • شهادة تديرها Google
  • ‫Cloud Run مع ingress = internal-and-cloud-load-balancing
  • نظير نظام أسماء النطاقات (DNS) لبوابة الوكيل
enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

7. نشر البنية الأساسية باستخدام Terraform

التهيئة والمراجعة والتطبيق:

cd terraform
terraform init -backend-config=backend.conf
terraform plan -out=tfplan
terraform apply tfplan

توفّر terraform apply حوالي 40 موردًا في المسار التلقائي وتستغرق من 8 إلى 10 دقائق في مشروع جديد (حوالي 60 موردًا / 15 إلى 20 دقيقة عند استخدام enable_cloud_run_private_networking = true). وتنشئ ما يلي:

  • أساسيات المشروع (واجهات برمجة التطبيقات، وهويات الخدمات، والحصص)
  • السحابة الإلكترونية الخاصة الافتراضية (VPC) والشبكات الفرعية (الأساسية، والوكيل فقط، وPSC، وواجهة PSC، والموقع الجغرافي المشترك لبوابة الوكيل)، وCloud NAT، وقواعد جدار الحماية
  • مستودع Artifact Registry لصور Cloud Run
  • ثلاث خدمات Cloud Run + حسابات خدمة وقت التشغيل لكل خدمة (الوصول = all تلقائيًا؛ internal-and-cloud-load-balancing عند تفعيل الشبكات الخاصة)
  • نموذج Model Armor + إدارة الهوية وإمكانية الوصول (IAM)
  • Agent Gateway، وملحق شبكة PSC-I، وملحقَا IAP وModel Armor، وكلتا سياستَي التفويض، وroles/iap.egressor الإذن على مستوى المشروع
  • نقاط نهاية Agent Registry (مثل Vertex AI وIAP وDiscovery Engine وما إلى ذلك) بالإضافة إلى خوادم MCP الثلاثة (المسجّلة في *.run.app/mcp تلقائيًا، وفي ./mcp عند تفعيل الشبكات الخاصة)

فقط عندما enable_cloud_run_private_networking = true:

  • موازنة الحمل الداخلي للتطبيقات على مستوى منطقة واحدة مع مجموعة NEG بدون خادم (توجيه باستخدام إخفاء عنوان URL) + سجلات A لنظام أسماء النطاقات الخاص
  • منطقة نظام أسماء النطاقات الخاص (mcp..) في "برنامج إدارة السحابة المتعددة" المرتبطة بالسحابة الإلكترونية الافتراضية الخاصة
  • وحدة منطقة نظام أسماء النطاقات العامة (عمليات تفويض نظام أسماء النطاقات في Certificate Manager) + شهادة إقليمية تديرها Google
  • منطقة نظام أسماء النطاقات لواجهة PSC (تكون غير مرتبطة عندما لا تكون هناك أسماء مضيفين خاصة يمكن تحويلها، لذا يتم أيضًا التحكم فيها باستخدام العلامة الرئيسية)
  • نظير نظام أسماء النطاقات (DNS) لبوابة الوكيل في "mcp.." (يتم إلحاقه تلقائيًا)

8. فحص نقاط نهاية "سجلّ الوكلاء"

قاعدة بيانات الوكلاء هي فهرس لكل مشروع من الخدمات (واجهات Google API وخوادم MCP الخاصة بك) التي يكتشفها الوكيل في وقت التشغيل. يقرأ وكيل الرهن العقاري هذا الملف عند بدء التشغيل ويربط الأدوات بشكل ديناميكي، ولا يتم تضمين عناوين URL الخاصة بمنصة MCP في رمز الوكيل أو أمر النشر.

نقاط النهاية

ما نفّذه Terraform نيابةً عنك: لكل واجهة Google API في agent_registry_google_apis، تم تسجيل خمسة أنواع (عالمي، وعالمي باستخدام بروتوكول أمان النقل المتبادل، ومحلي، ومحلي باستخدام بروتوكول أمان النقل المتبادل، ومحلي باستخدام REP). على سبيل المثال، بالنسبة إلى aiplatform:

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

خوادم MCP

تسجّل أداة Terraform أيضًا خوادم MCP الثلاثة نيابةً عنك، ولتسجيل خوادم MCP أخرى، يمكنك اتّباع الخطوات الواردة في المستندات.

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

تحقَّق من نقاط النهاية وخوادم MCP المسجّلة.

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=