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

1. مقدمة

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

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

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

لمحة عن Agent Gateway

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

يسهّل مسارَين أساسيَّين للوصول الخاضع للإدارة:

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

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

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

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

  • Agent Registry: مكتبة مركزية تضمّ الوكلاء والأدوات المعتمدة (بما في ذلك خوادم 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 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 ونظير DNS من 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
terraform apply

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

  • أساسيات المشروع (واجهات برمجة التطبيقات، وهويات الخدمات، والحصص)
  • السحابة الإلكترونية الخاصة الافتراضية (VPC) والشبكات الفرعية (الأساسية، والوكيل فقط، وPSC، وPSC-Interface، والموقع الجغرافي المشترك لبوابة Agent)، و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 الإذن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..) في "منصة التجارة المتعددة الشركاء" (MCP) المرتبطة بشبكة VPC
  • وحدة منطقة نظام أسماء النطاقات العامة (عمليات تفويض نظام أسماء النطاقات في Certificate Manager) + شهادة إقليمية تديرها Google
  • منطقة نظام أسماء النطاقات لواجهة PSC (تكون غير مرتبطة عندما لا تكون هناك أسماء مضيفين خاصة يمكن تحويلها، لذا يتم أيضًا التحكم فيها باستخدام العلامة الرئيسية)
  • نظير نظام أسماء النطاقات (DNS) لبوابة الوكيل في mcp.. (يتمّ إلحاقه تلقائيًا)

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

سجلّ الوكلاء هو فهرس لكل مشروع من الخدمات (واجهات برمجة تطبيقات Google وخوادم 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=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

المصدر: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl

9- مراجعة إعدادات "بوابة الوكيل"

بوابة الوكيل هي مستوى إدارة تديره Google بين Agent Runtime وأدواتك. في وضع AGENT_TO_ANYWHERE، يتم ربطها بـ "سجلّ الوكلاء" الخاص بالمشروع وتخرج من خلال واجهة PSC يملكها العميل حتى تتمكّن من الوصول إلى خوادم MCP الخاصة في شبكة VPC.

إذا كنت تستورد هذه البوابة يدويًا، سيبدو ترميز YAML على النحو التالي:

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

تأكَّد من صحة البوابة التي أنشأتها Terraform:

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

10. فحص تفويض الشراء داخل التطبيق وModel Armor

تفوّض Agent Gateway عملية منح الإذن إلى إضافات الخدمة. يتضمّن العرض التوضيحي ملفَّي سياسات:

  • ‫REQUEST_AUTHZ: يتم تقييمها مرة واحدة لكل طلب في مرحلة العناوين. يُستخدَم هنا لاستدعاء IAP، الذي يتحقّق مما إذا كانت هوية وكيل الاتصال تتضمّن roles/iap.egressor على خادم MCP المستهدَف.
  • ‫CONTENT_AUTHZ: يرسل أحداث النص إلى الإضافة لتنظيف المحتوى. يُستخدم هنا للإشارة إلى Model Armor، التي تفحص الطلبات بحثًا عن عمليات حقن الطلبات، وعمليات كسر الحماية، وانتهاكات سياسة الذكاء الاصطناعي المسؤول، و (اختياريًا) المعلومات التي تكشف الهوية الشخصية من خلال "حماية البيانات الحسّاسة" (SDP).

إضافة REQUEST_AUTHZ في واجهة برمجة التطبيقات IAP

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

اربطه بـ Agent Gateway باستخدام سياسة REQUEST_AUTHZ:

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

إضافة Model Armor CONTENT_AUTHZ

يحمل metadata.model_armor_settings الإضافة أرقام تعريف نماذج الطلبات والاستجابات التي تستخدمها Model Armor لتقييم كل وسيلة شرح:

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

نماذج مخصّصة لمنع فقدان البيانات

تستخدم Model Armor sdpSettings.basicConfig قائمة مدمجة بأنواع المعلومات. للحصول على تحكّم أدق (أنواع معلومات مخصّصة، وحجب جزئي، واستبدال ببيانات بديلة، وإخفاء محتوى حسب الاحتمالية)، يمكنك توجيه Model Armor إلى نماذج الفحص وإخفاء معلومات تحديد الهوية الخاصة بك في منع فقدان البيانات من خلال sdpSettings.advancedConfig.

أنشئ نموذج فحص يضع علامة على أرقام التأمين الاجتماعي في الولايات المتحدة باحتمالية POSSIBLE أو أعلى:

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
  -d '{
    "templateId": "agw-ssn-inspect-template",
    "inspectTemplate": {
      "displayName": "SSN Inspect Template",
      "inspectConfig": {
        "infoTypes": [
          { "name": "US_SOCIAL_SECURITY_NUMBER" }
        ],
        "minLikelihood": "POSSIBLE"
      }
    }
  }'

أنشئ نموذجًا لإزالة التعريف يستبدل كل نتيجة برمز نوع المعلومات (مثل [US_SOCIAL_SECURITY_NUMBER]):

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
  -d '{
    "templateId": "agw-ssn-redaction-template",
    "deidentifyTemplate": {
      "displayName": "SSN Redaction Template",
      "deidentifyConfig": {
        "infoTypeTransformations": {
          "transformations": [{
            "primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
          }]
        }
      }
    }
  }'

بعد ذلك، أشر إلى إعدادات استجابة نموذج Model Armor باستخدام الزوج من خلال sdpSettings.advancedConfig (هذا هو المكان الذي سيضبط فيه وحدة model_armor في Terraform advanced_config إذا ربطتها):

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

إدارة الهوية وإمكانية الوصول (IAM) الخاصة ببرنامج IAP الخارجي (لكل خادم MCP فقط)

لا تنشئ Terraform ربطًا على مستوى المشروع roles/iap.egressor في سجلّ وكيل IAP الضمني. يتم تقييم ربط IAP REQUEST_AUTHZ فعليًا لكل خادم MCP ولكل محرك استدلال، ويتم منحه بعد نشر الوكيل ومعرفة رقم تعريف الوكيل. تنفِّذ الخطوة "منح الوكيل إذن الخروج لكل خادم MCP" الأمر scripts/grant_agent_mcp_egress.sh لهذا الغرض.

11. إنشاء خوادم MCP ونشرها على Cloud Run

تشير الملفات cloudrun/*.yaml.tmpl وskaffold.yaml.tmpl إلى ${PROJECT_ID} و${REGION} و${MCP_INGRESS} (التعليق التوضيحي الوارد في Cloud Run). استخدِم المصدر MCP_INGRESS من ناتج Terraform لتبقى البيانات التي تم عرضها متزامنة مع enable_cloud_run_private_networking، ثم اعرضها باستخدام envsubst:

صدِّر إعدادات الدخول في Cloud Run.

  • all
  • internal-and-cloud-load-balancing (عند استخدام نهج الشبكات الخاصة)
export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

تعمل كل خدمة من خدمات Cloud Run كحساب خدمة وقت التشغيل الذي أنشأته Terraform لكل خدمة (مثل mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). ولتتمكّن من النشر بصفتك هذه الحسابات، يجب أن يكون لديك إذن roles/iam.serviceAccountUser:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

إنشاء التطبيقات باستخدام Cloud Build ونشرها باستخدام Skaffold:

skaffold run

تنشئ Skaffold ثلاث صور (legacy-dms وcorporate-email وincome-verification-api) في مستودع Artifact Registry وتعدّل كل خدمة من خدمات Cloud Run للإشارة إلى الملخّص الجديد.

يجب التأكّد مما يلي:

gcloud run services list --region=${REGION}

من المفترض أن تظهر لك جميع الخدمات الثلاث بحالة ACTIVE.

12. نشر وكيل الرهن العقاري في Agent Runtime

ثبِّت التبعيات الخاصة بالوكيل ونفِّذ ما يلي:

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

عند اكتمال النص البرمجي، انسخ reasoningEngines/ المطبوع إلى الصدفة:

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. منح الوكيل إذن الخروج لكل خادم MCP

تمنح إضافة IAP REQUEST_AUTHZ إذنًا لكل استدعاء أداة من خلال التحقّق من roles/iap.egressor الخاص بالوكيل على خادم MCP محدّد أو نقطة نهاية يتم استدعاؤها. اطّلِع على إنشاء سياسة خروج من الخادم إلى MCP.

يسرد النص البرمجي (scripts/grant_agent_mcp_egress.sh) خوادم MCP في "سجلّ الوكيل" ضمن projects/${PROJECT_ID}/locations/${REGION} ويدمج ربط roles/iap.egressor لمدير الوكيل في سياسة إدارة الهوية وإمكانية الوصول لكل خادم (مع عكس دلالات gcloud add-iam-policy-binding).

حالة الاستخدام 1: منح الموافقة غير المشروطة لنطاق خوادم MCP محدّدة

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

حالة الاستخدام 2: إذن مشروط (CEL) محدد النطاق لخادم MCP معيّن

لتقييد وصول البرنامج إلى مجموعة فرعية من الأدوات على خادم MCP واحد، أرفِق شرط IAM. تنشر Agent Gateway سمات خاصة بكل أداة يعرضها IAP REQUEST_AUTHZ إلى CEL، بما في ذلك:

  • iap.googleapis.com/mcp.toolName
  • iap.googleapis.com/mcp.tool.isReadOnly
  • iap.googleapis.com/request.auth.type.

حصر وصول الوكيل إلى أدوات القراءة فقط على corporate-email:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

بعد تشغيل هذا الرمز، ستعرض الأدوات المخصصة للكتابة corporate-email القيمة 403 PermissionDenied من IAP REQUEST_AUTHZ، وستستمر الأدوات المخصصة للقراءة فقط في العمل.

التحقّق من عمليات الربط

انتقِل إلى علامة التبويب "السياسات" وستظهر لك قائمة بالسياسات التي تم إنشاؤها مقابل نقاط النهاية وخوادم Mcp.

حالات استخدام إضافية:

منح غير مشروط على كل خادم MCP، ويقتصر على وكيل واحد

نفِّذ هذا الإجراء بعد كل عملية إعادة نشر للوكيل. بدون فلتر وبدون شرط، يحصل الوكيل المسمّى على roles/iap.egressor على كل خادم MCP في السجلّ:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. اختبار الوكيل في وحدة تحكّم "منصة الوكلاء"

تتضمّن وحدة تحكّم Agent Platform ساحة لعب تتيح لك الدردشة مع الوكيل الذي تم نشره مباشرةً. إنّها أسرع طريقة لاختبار وظائف الأدوات وفحص عمليات التتبُّع قبل ربط الوكيل بـ Gemini Enterprise.

  1. افتح صفحة عمليات نشر منصة الوكيل في Google Cloud Console.
  2. استخدِم الحقل فلتر إذا كنت بحاجة إلى تضييق نطاق قائمة أوقات التشغيل، ثم انقر على وقت التشغيل mortgage-agent.
  3. افتح علامة التبويب ساحة اللعب.
  4. اكتب طلبًا للدردشة مع الوكيل:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

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

Can you send a summary of this to my email jane@example.com

يجب أن يوضّح الوكيل أنّه لا يمكنه الوصول إلى أداة send_email وأن يردّ وفقًا لذلك.

بما أنّ الوكيل تم نشره باستخدام أدوات قياس حالة التطبيق OpenTelemetry، يوفّر Playground أربعة طرق عرض في اللوحة الجانبية يمكنك التبديل بينها أثناء ردّ الوكيل:

  • التتبُّع: عمليات التتبُّع الكاملة للمحادثة، بما في ذلك "بوابة الوكيل" وIAP REQUEST_AUTHZ وModel Armor CONTENT_AUTHZ
  • الحدث: رسم بياني للأدوات التي تم استدعاؤها وتفاصيل الحدث في الدور الحالي
  • الحالة: حالة جلسة الوكيل ومدخلات/مخرجات الأداة
  • الجلسات: كل جلسة بدأتها مقابل وقت التشغيل هذا

15. فرض تفويض عمليات الشراء داخل التطبيق

بعد أن تحقّقنا من صحة عملية النشر، يمكننا تعديل وضع "فرض سياسات الشراء داخل التطبيق" إلى null لفرض السياسات. افتح terraform.tfvars وعدِّل الوضع من DRY_RUN إلى null

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

طبِّق التغيير.

terraform apply

ارجع إلى Playground وحاوِل إجراء المحادثة مرة أخرى.

  1. افتح صفحة عمليات نشر منصة الوكيل في Google Cloud Console.
  2. استخدِم الحقل فلتر إذا كنت بحاجة إلى تضييق نطاق قائمة أوقات التشغيل، ثم انقر على وقت التشغيل mortgage-agent.
  3. افتح علامة التبويب ساحة اللعب.
  4. اكتب طلبًا للدردشة مع الوكيل:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

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

Can you send a summary of this to my email jane@example.com

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

16. إعداد Gemini Enterprise واختباره

إعداد Gemini Enterprise

اتّبِع دليل بدء استخدام Gemini Enterprise.

تسجيل وكيل ADK في Gemini Enterprise

اتّبِع الخطوات لتسجيل وكيلنا في Gemini Enterprise، ويمكنك الاطّلاع على الخطوات هنا.

  1. في Google Cloud Console، انتقِل إلى صفحة Gemini Enterprise.
  2. اختَر تطبيق Gemini Enterprise الذي تم تسجيل الوكيل فيه.
  3. افتح عنوان URL المعروض في قسم تطبيق Gemini Enterprise للويب جاهز.
  4. انقر على علامة التبويب الوكيل من القائمة اليمنى لفتح معرض الوكلاء.
  5. اختَر وكيل "مساعد الرهن العقاري" وابدأ الدردشة.

جرِّب الطلبات نفسها من "بيئة اختبار وقت التشغيل للوكيل":

الطلب الأوّلي:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

طلب المتابعة:

Can you send a summary of this to my email jane@example.com

إذا رجعت إلى قسم "نشر الوكيل" في وحدة التحكّم، واختَرت عملية نشر الوكيل وانتقلت إلى علامة التبويب "عمليات التتبّع"، سيظهر لك الآن وكيل "مساعد Gemini" في النطاق الذي يعرض المكالمة التي تم إجراؤها من Gemini Enterprise.

17. تحديد المشاكل وحلّها

  • تعذُّر تنفيذ terraform apply على Agent Gateway مع ظهور الخطأ "يتم إنشاء المورد وبالتالي لا يمكن تعديله" — يستغرق مشروع المستأجر في البوابة حوالي 30 ثانية حتى يتم إعداده قبل أن يتم ربط سياسات التفويض. يتولّى time_sleep.wait_for_gateway في الوحدة النمطية تنفيذ هذه العملية، ما عليك سوى إعادة تشغيل terraform apply.
  • يُبلغ الوكيل عن "عدم العثور على أي خوادم MCP" أو يتم تشغيله باستخدام أدوات مساعدة فقط: تأكَّد من enable_agent_registry_endpoints = true في terraform.tfvars، ثم:
    gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION}
    من المفترض أن تظهر لك ثلاثة إدخالات (إدخال واحد لكل خدمة MCP على Cloud Run). إذا كانت القائمة فارغة، تأكَّد من إمكانية الوصول إلى خدمات MCP من داخل سحابة VPC ومن أنّ Agent Gateway قد ملأ قاعدة بيانات المسجّلين (يتم ذلك بشكل غير مباشر عند عرض قائمة الأدوات التي تم توجيهها لأول مرة).
  • تعرض طلبات الأدوات الخطأ 403 PermissionDenied — أعِد تشغيل scripts/grant_agent_mcp_egress.sh. السبب الأكثر شيوعًا هو نسيان إعادة منح الإذن بعد إعادة نشر الوكيل (يتغيّر reasoningEngines/ في كل عملية نشر).
  • تعذُّر تنفيذ skaffold run مع ظهور الخطأ "تم رفض الإذن لحساب الخدمة" — يجب منح إذن roles/iam.serviceAccountUser. أعِد تنفيذ عملية منح الإذن الذاتي في الخطوة السابقة.
  • أخطاء ربط نظام أسماء النطاقات من Agent Gateway إلى MCP LB: تأكَّد من أنّ agent_gateway_dns_peering_config.target_network يتطابق مع projects/${PROJECT_ID}/global/networks/${VPC_NAME} تمامًا، وأنّ كل إدخال domains ينتهي بنقطة لاحقة.
  • يستمر terraform plan في طلب تعديل علامات صور Cloud Run، وهذا لا يفترض أن يحدث بسبب قاعدة lifecycle { ignore_changes }. إذا كان الأمر كذلك، تأكَّد من أنّك لم تعدّل mcp_services[*].image في terraform.tfvars بعد skaffold run.

18 تَنظيم

لا تتم إدارة محرك الاستدلال من خلال Terraform (تنشئه حزمة تطوير البرامج (SDK) الخاصة بـ ADK). يمكنك حذفها يدويًا باتّباع الخطوات التالية:

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

إزالة كل ما أنشأته Terraform:

cd terraform
terraform destroy
cd ..

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

gcloud dns managed-zones delete agw-example-com

أخيرًا، احذف حزمة حالة Terraform:

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

19. تهانينا

تهانينا! لقد نفّذت بنجاح إدارة شاملة للوكيل باستخدام وكيل ADK متعدد الأدوات من خلال Agent Gateway. من خلال العمل كمركز تحكّم مركزي في الشبكة، أتاحت لك Agent Gateway إنشاء مسار خروج آمن إلى الأدوات الخاصة، وفرض سياسات دقيقة لإدارة الهوية وإمكانية الوصول استنادًا إلى الهوية من خلال Identity-Aware Proxy، وتنظيف تفاعلات المحتوى باستخدام ضوابط Model Armor المدمجة.

ما تعلّمته

  • كيفية تفعيل "بوابة الوكيل" وإعدادها كطبقة إدارة مركزية لحركة الخروج من "الوكيل إلى أي مكان"
  • كيفية دمج "سجلّ الوكلاء" لاكتشاف الأدوات الديناميكية التي يتم تشغيلها في وقت التشغيل والتي تخضع للإدارة
  • كيفية كتابة سياسات إدارة الهوية وإمكانية الوصول المستندة إلى الأداة والشروط وتطبيقها للتحكّم بشكل صارم في مسارات تنفيذ الوكيل
  • كيفية الاستفادة من إضافات خدمة Agent Gateway لتطبيق سياسات Model Armor، ما يؤدي إلى اعتراض حركة بيانات الوكيل الحسّاسة وإخفائها تلقائيًا

المستندات المرجعية