خروج Agent Gateway من Agent Runtime إلى Google MCP

1. مقدمة

يستكشف هذا الدرس التطبيقي حول الترميز إدارة حركة البيانات الصادرة في Agent Gateway لوكلاء الذكاء الاصطناعي الذين يصلون إلى خوادم Model Context Protocol (MCP) البعيدة على Google Cloud.

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

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

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

ما يمكنك إنشاؤه

• Agent Gateway في وضع الخروج (الوكيل إلى أي مكان)
• إضافة تفويض Identity-Aware Proxy (IAP)
• وكيل Agent Runtime ADK مع هوية الوكيل
• Agent Registry مع نقاط نهاية Google API وMCP
• سياسات التفويض مع التحكّم في الوصول من خلال "إدارة الهوية وإمكانية الوصول"
• مجموعة بيانات BigQuery التي سيتم طلب البحث فيها باستخدام MCP

الشكل 1. بنية Codelab

ما ستتعلمه

• كيفية نشر Agent Gateway في تسلسل إعدادات منظَّم
• كيفية نقل سياسات التفويض من وضع التشغيل التجريبي إلى الوضع الإلزامي
• كيفية تسجيل نقاط نهاية Google API وخوادم MCP في Agent Registry
• كيفية تدقيق سجلّات Agent Gateway للتحقّق من صحة إدارة الخروج

ما تحتاج إليه

• مشروع Google Cloud تم تفعيل الفوترة فيه
• أذونات إدارة الهوية وإمكانية الوصول لتوفير خدمات الشبكات ومجموعات بيانات BigQuery وموارد "منصّة الوكيل"
• برنامج shell متوافق مع POSIX ‏(bash أو zsh) مع تثبيت واجهة سطر الأوامر (CLI) في Google Cloud (المكوّنان gcloud وbq)
• أدوات سطر الأوامر: git وcurl وjq (معالج JSON) وPython 3 وuv (مدير حزم Python)

2. المفاهيم

تسلسل النشر

عند نشر Agent Gateway مع عناصر التحكّم في الإدارة، من المهم اتّباع تسلسل إعداد منظَّم لكي تتمكّن البرامج من الوصول إلى الموارد اللازمة عند بدء التشغيل وتنجح طلبات الشبكة.

يستخدم هذا الدرس التطبيقي حول الترميز تسلسل النشر التالي:

• البدء في وضع التشغيل التجريبي: إذا تم ضبط وقت تشغيل الوكيل لتوجيه المكالمات الصادرة إلى البوابة قبل توفير البوابة بالكامل، سيتعذّر بدء تشغيل عبء العمل. يضمن ضبط إعدادات إضافة تفويض البوابة في وضع DRY_RUN أولاً عدم تجاهل أي طلبات عند وصول زيارات الوكيل إلى البوابة.
• تسجيل جميع الخدمات: يجب تسجيل جميع البرامج والخوادم ونقاط النهاية التي تستخدم Agent Gateway في Agent Registry. يتم رفض الطلبات لأي مصادر أو وجهات غير مسجّلة. يتم تسجيل العملاء الذين تم نشرهم على Agent Runtime وخوادم Google MCP تلقائيًا. يجب تسجيل أي نقطة نهاية لواجهة Google API أو خادم MCP مخصّص يدويًا.
• فرض سياسات التفويض: تُستخدَم سياسات التفويض للسماح للوكلاء المسجّلين بالوصول إلى المكوّنات المستندة إلى الوكلاء من خلال منح الدور roles/iap.egressor إلى كيان هوية الوكيل وربطه بمورد قاعدة بيانات المسجّلين المستهدف. قيِّم سلوك الوكيل باستخدام وضع التشغيل التجريبي، ثم حدِّد السياسات للسماح بمرور زيارات الخروج المحدّدة عبر البوابة. بعد وضع السياسات، يمكنك التبديل إلى وضع ENFORCED لتفعيل البوابة من أجل فرض سياسات الحوكمة بشكل نشط.

الشكل 2. تسلسل النشر

طوبولوجيا توجيه الخروج

تُدير البوابات عادةً حركة المرور الواردة (ingress) إلى الخدمات الخلفية. تعمل Agent Gateway في وضع الخروج (agent-to-anywhere) كخادم وكيل مركزي صادر يعتمد على نهج الثقة المعدومة لأحمال العمل القائمة على وكلاء الذكاء الاصطناعي.

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

• الشبكات الخاصة (VPC): الزيارات الصادرة التي تستهدف واجهات برمجة التطبيقات الداخلية للمؤسسة والخدمات المصغّرة وقواعد البيانات المستضافة ضِمن شبكات VPC الخاصة والشبكات المحلية أو الشبكات المتعددة السحابات التي يمكن الوصول إليها من خلال الاتصال المختلط
• الشبكات الخارجية (الإنترنت): الزيارات الصادرة التي تستهدف خدمات الويب التابعة لجهات خارجية أو واجهات برمجة التطبيقات الخاصة بالبرامج كخدمة (SaaS) أو نقاط النهاية العامة
• خدمات الذكاء الاصطناعي ومنصة Agent: تشمل هذه الفئة الزيارات الصادرة التي تستهدف واجهات Google Cloud API المُدارة والنماذج الأساسية ونقاط نهاية Google MCP (مثل BigQuery) وخدمات إدارة المنصة (Agent Registry وسياسات IAP).

الشكل 3. بنية توجيه الخروج في Agent Gateway

يركّز هذا الدرس التطبيقي حول الترميز على الزيارات الصادرة من وكيل مخصّص على Agent Runtime يستهدف نقطة نهاية خادم Google MCP البعيد لخدمة BigQuery.

3- الإعداد

أدوار "إدارة الهوية وإمكانية الوصول" المطلوبة

يجب توفّر الأدوار التالية لإنشاء الموارد في هذا الدرس العملي:

الفئة	دور "إدارة الهوية وإمكانية الوصول" المطلوب (المعرّف)	الوصف
إدارة واجهة برمجة التطبيقات	roles/serviceusage.serviceUsageAdmin	تفعيل خدمات Google Cloud API
الشبكات والبوابة	roles/networkservices.admin	Provision Agent Gateway
إضافات الخدمات	roles/serviceextensions.admin	ضبط إضافات التوجيه
أمان الشبكات	roles/networksecurity.admin	نشر سياسات التفويض
Agent Registry	roles/agentregistry.admin	المواقع الإلكترونية المضيفة المسموح بها في الكتالوج
‫Vertex AI والوكلاء	roles/aiplatform.admin	نشر أحمال عمل Agent Runtime
سياسات الخروج	roles/iap.admin	تطبيق سياسات roles/iap.egressor
BigQuery	roles/bigquery.admin	إعداد المخططات ومجموعات البيانات الاختبارية
Cloud Storage	roles/storage.admin	إدارة حِزم الإعداد المؤقت لعمليات النشر
السجلات والتدقيق	roles/logging.viewer	فحص عمليات التتبُّع وسجلّات التدقيق

بدلاً من ذلك، استخدِم دورًا أساسيًا واسع النطاق، مثل roles/admin أو دورًا قديمًا، مثل roles/owner.

الوصول إلى مشروعك

يستخدم هذا الدرس التطبيقي حول الترميز مشروعًا واحدًا على Google Cloud. تستخدم خطوات الإعداد واجهة سطر الأوامر gcloud وأوامر واجهة مستخدم Linux.

ابدأ بالوصول إلى سطر الأوامر في مشروعك على Google Cloud:

• ‫Cloud Shell على shell.cloud.google.com، أو
• تطبيق طرفي محلي gcloud CLI مثبَّت

ضبط رقم تعريف المشروع

gcloud config set project SET_YOUR_PROJECT_ID_HERE

مصادقة الجلسة

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

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

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-dj"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

تفعيل خدمات واجهة برمجة التطبيقات

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  discoveryengine.googleapis.com

ملاحظة: قد تستخدم بعض الميزات أوامر gcloud beta. إذا لم يكن مثبّتًا، شغِّل gcloud components install beta لتفعيله.

بهذا نكون قد انتهينا من جزء الإعداد... ننتقل الآن إلى قسم البوابة.

4. البوابة

قبل فرض عناصر التحكّم في الوصول، يجب نشر Agent Gateway وضبط إضافة التفويض في وضع DRY_RUN. يسمح ذلك بإنجاح عمليات استدعاء الأدوات الصادرة مع تسجيل نتائج التقييم لأغراض التدقيق.

يستخدم Agent Gateway هنا سجلّ إقليمي لتوفير موارد Agent Runtime إقليمية.

إنشاء بوابة

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}.yaml" \
  --location=${REGION}

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

بهذا نكون قد انتهينا من جزء البوابة... ننتقل الآن إلى قسم التفويض.

5- التفويض

إضافة تفويض Agent Gateway لخدمة Identity-Aware Proxy (IAP) هي نوع من إضافات الخدمة تُستخدَم لتفويض قرارات التفويض لجميع عمليات التواصل في منصة Agent Platform.

1. مسار التفويض: عندما يحاول وكيل استدعاء نقطة نهاية خارجية أو خادم MCP، يوجّه الطلب إلى Agent Gateway. بدلاً من تقييم إذن الوصول محليًا، تستخدم البوابة إضافة التفويض لإرسال وسيلة شرح إلى خدمة تقييم IAP. تقيّم خدمة IAP هوية الوكيل (استنادًا إلى SPIFFE) مقارنةً بسياسة إدارة الهوية وإمكانية الوصول الخاصة بالمرجع المستهدف في "قاعدة بيانات الوكلاء". تعرض خدمة IAP القرار ALLOW أو DENY إلى البوابة، التي إما تعيد توجيه الزيارات أو تحظرها باستخدام رمز حالة HTTP 403 Forbidden.
2. أوضاع التنفيذ: في وضع DRY_RUN، تقيِّم خدمة IAP الطلبات وتسجّل القرارات في Cloud Logging بدون حظر الزيارات. في وضع ENFORCE، يتم حظر أي طلب من وكيل غير مصرَّح به أو إلى هدف غير مسجَّل على الفور.
3. طبقة الربط: يتم ربط إضافة الخدمة بـ Agent Gateway باستخدام سياسة تفويض تم إعدادها باستخدام الملف الشخصي REQUEST_AUTHZ.

إضافة التفويض

إنشاء إضافة تفويض

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

# show authz extension details (verify extension state)
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

سياسة التفويض

تربط سياسة التفويض موفّر الأمان (IAP) بمورد البوابة المستهدَف وتحدّد ملف تعريف الاعتراض (REQUEST_AUTHZ).

إنشاء سياسة تفويض

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

# show authz policy details (verify dry run mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

بهذا نكون قد انتهينا من جزء التفويض... لننتقل الآن إلى قسم قاعدة الرموز البرمجية.

6. قاعدة الرموز البرمجية

يتم الاحتفاظ برمز الوكيل ومجموعة بيانات BigQuery ونص التسجيل المستخدَم في هذا الدرس التطبيقي حول الترميز في مستودع Google Cloud GitHub بعيد. ستؤدي الخطوات التالية إلى استنساخ المستودع محليًا، ونسخ الملفات اللازمة إلى بنية دليل العمل الحالي، ثم تنظيف الملفات المؤقتة غير الضرورية.

يتم إنشاء حزمة تخزين مؤقتة لوقت تشغيل الوكيل من أجل تحميل الرمز البرمجي لتطبيق الوكيل المجمَّع وعناصر الاعتمادية الخاصة به وإنشائه ونشره.

استرداد البيانات عن بُعد

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

إنشاء مجموعة بيانات BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

إنشاء حزمة مرحلية

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

بهذا نكون قد انتهينا من جزء قاعدة الرموز البرمجية... ننتقل الآن إلى قسم قاعدة بيانات المسجّلين.

7. اسم السجلّ

قاعدة بيانات Agent Registry هي مستودع مركزي لجميع الوكلاء وخوادم MCP ونقاط النهاية (واجهات برمجة التطبيقات) في منظومة الذكاء الاصطناعي المتكاملة. وهو أيضًا فهرس يمكن استخدامه لإدراج الأدوات والخدمات الأخرى المسجّلة والبحث عنها واكتشافها لاستخدامها في تطبيقات الذكاء الاصطناعي. يستخدم وضع الخروج من Agent Gateway (agent-to-anywhere) نموذج البيانات في السجلّ كإطار عمل للحوكمة من أجل فرض عناصر التحكّم في الوصول إلى الخروج. يتم التحقّق من أذونات دور "إدارة الهوية وإمكانية الوصول" الممنوحة لوكلاء الاتصال الأساسيين مقارنةً بالسياسة المرتبطة بمورد السجلّ.

من أجل إعداد البيئة وتوفير الدعم للوكلاء باستخدام Google APIs and Services المختلفة، يتم استخدام نص برمجي لتسجيل مجموعة شائعة من نقاط نهاية واجهة برمجة التطبيقات بسرعة باستخدام أسماء المضيفين والمواقع الجغرافية من endpoints/googleapis.txt.

تسجيل نقاط النهاية

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

التحقّق من نقاط النهاية

# list regional endpoints (verify registration)
gcloud agent-registry endpoints list --location=${REGION} \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces[0].url:label=URL)"

بهذا نكون قد انتهينا من جزء قاعدة بيانات المسجّلين... وسننتقل الآن إلى قسم وقت التشغيل.

8. وقت التشغيل

تم ضبط وكيل agent-dj ADK الذي تم نشره في Agent Runtime باستخدام الإعدادات التالية في نص البرمجة الخاص بعملية النشر من أجل الدمج مع Agent Platform:

• "identity_type": types.IdentityType.AGENT_IDENTITY لتوفير هوية أساسية فريدة مستندة إلى SPIFFE للوكيل
• ‫"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } لتوجيه جميع الزيارات الصادرة التي يبدأها الوكيل إلى Agent Gateway من أجل تقييم السياسات وتنفيذها

نشر الوكيل

# deploy agent runtime workload
uv --directory agent-dj run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

جلب مؤشرات الأداء الأساسية لعمليات النشر

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET \
  "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" \
  '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

التحقّق من إدخال السجلّ

# show agent resource registry details
gcloud agent-registry agents describe ${AGENT_UID} --location=${REGION}

ملاحظة: يؤدي نشر الوكيل على Agent Runtime إلى إنشاء رابط سجلّ تلقائيًا (RuntimeReference)، وعرض مدير هوية الوكيل المستخدَم في سياسات الخروج من IAP (RuntimeIdentity)، وعرض عملية البحث الديناميكي عن نقاط النهاية (protocols.interfaces).

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

التحقّق من إعدادات البوابة

# verify agent gateway routing specification
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

التحقّق: تأكَّد من أنّ agentGateway يعرض معرّف الموارد المنتظم (URI) الخاص بمورد البوابة...
"agentGateway": "projects/PROJ_ID/locations/REGION/agentGateways/agw-SLUG-REGION-ata"

منح أدوار "إدارة الهوية وإمكانية الوصول" للوكيل من أجل الوصول إلى الموارد

تتيح أذونات دور "إدارة الهوية وإمكانية الوصول" للموارد وصول هوية مدير الوكيل إلى BigQuery وأدوات MCP (لواجهات Google APIs) وخدمات منصة الذكاء الاصطناعي الأخرى المطلوبة. يتم فرض هذه السياسات باستخدام "إدارة الهوية وإمكانية الوصول" (IAM) على مستوى المورد.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

التحقّق من أدوار إدارة الهوية وإمكانية الوصول (IAM) للوكيل في الموارد

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

بهذا نكون قد انتهينا من جزء وقت التشغيل... ننتقل الآن إلى قسم السياسات.

9- السياسات

تسمح سياسات تفويض إدارة الوكيل بمرور الزيارات من وكيل الذكاء الاصطناعي من خلال Agent Gateway وإلى الوجهة (مثل نقطة نهاية خادم MCP في Google Cloud لخدمة BigQuery). بعد وصول عدد الزيارات إلى الوجهة، تمنح أذونات إدارة الهوية وإمكانية الوصول العادية إذن الوصول إلى البيانات (وقد تم تفعيلها في القسم السابق).

تتيح أذونات دور "إدارة الهوية وإمكانية الوصول" لخروج Agent Gateway سياسات الوصول التي تسمح لهوية المستخدم الأساسي للوكيل بالوصول إلى موارد الوجهة المسجّلة من خلال Agent Gateway. يتم فرض السياسات على مستوى Agent Gateway والتحقّق من صحتها باستخدام سياسات إدارة الهوية وإمكانية الوصول (IAM) في Identity-Aware Proxy (IAP).

منح أدوار "إدارة الهوية وإمكانية الوصول" للوكيل من أجل خروج Agent Gateway

تتحقّق Agent Gateway من الطلبات الواردة للتأكّد من أنّ هوية الوكيل المتصل لديها إذن iap.webServiceVersions.egressViaIAP (ممنوح من الدور roles/iap.egressor) على المورد المستهدف.

يسمح منح roles/iap.egressor لهوية الوكيل أو مجموعة الأساسيات في Agent Runtime على مورد الوجهة المحدّد بنقل بيانات الخروج هذا. في هذا الدرس التطبيقي حول الترميز، يتم تطبيق الدور على مجموعة المستخدمين الأساسيين التي تمنح الإذن لجميع هويات وكيل Agent Runtime في المشروع.

ترتبط سياسات "إدارة الهوية وإمكانية الوصول" بالموارد الوجهة على النحو المحدّد في نموذج البيانات الخاص بـ "سجلّ الوكلاء". يمثّل مورد iap_web/agentRegistry مستوى "على مستوى السجلّ" في التسلسل الهرمي لإدارة الهوية وإمكانية الوصول. حيث يمثّل agentRegistry العنصر الرئيسي لموارد العناصر الفرعية الفردية agents وmcpServers وendpoints في هذا الدرس العملي، يتم ربط سياسة "إدارة الهوية وإمكانية الوصول" (IAM) بمستوى السجلّ الذي يطبّق الإذن على جميع الموارد الفرعية.

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

ضبط سياسة إدارة الهوية وإمكانية الوصول في سجلّ IAP الإقليمي

# show iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

# retrieve active etag on policy for regional registry
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION} --format="value(etag)")
echo ${IAP_ETAG}

# create policy config file
cat > cfg/iap-policy-re-agent-set-to-registry-${REGION}.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_ID_SET}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

# import policy file (bind iam policy)
gcloud beta iap web set-iam-policy cfg/iap-policy-re-agent-set-to-registry-${REGION}.json \
  --resource-type=agent-registry \
  --region=${REGION}

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

بهذا نكون قد انتهينا من جزء السياسات... سننتقل الآن إلى قسم التدقيق.

10. التدقيق

تعمل إضافة تفويض Agent Gateway في وضع DRY_RUN. يتم رصد الطلبات الصادرة وتسجيلها ولكن لا يتم حظرها.

اختبار طلبات الوكيل

افتح نافذة متصفّح لواجهة مستخدم Google Cloud Console وانتقِل إلى:

• منصة الوكيل → الوكلاء → عمليات النشر → agent-dj
• انقروا على علامة التبويب الملعب

أو نفِّذ أمر الوحدة الطرفية هذا وانقر على الرابط للانتقال إلى ساحة تجارب الوكيل:

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

أرسِل بعض طلبات البحث الاختبارية....

• How many DJs do we have on file?
• What is the phone number of DJ Cosmopup?

تأكَّد من أنّ طلبات البحث تعرض ردودًا صالحة (مثلاً، "هناك 12 منسّق أغاني مسجّلين في الملف").

تحليل سجلات التدقيق

الاطّلاع على السجلّات وفحص عمليات تقييم السياسات في الوضع التجريبي

# query gateway logs for dry run
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL
  )"

التحقّق: تأكَّد من أنّ النتيجة IAP_AUTHZ تعرض ALLOWED.

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

بهذا نكون قد انتهينا من جزء التدقيق... لننتقل الآن إلى قسم فرض.

11. تنفيذ

تمكّن الوكيل من تقديم طلبات ناجحة من خلال البوابة في وضع DRY_RUN. يمكنك نقل إضافة تفويض Agent Gateway IAP إلى وضع ENFORCE من خلال تعديل سياسة التفويض.

تعديل إضافة التفويض

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

تعديل سياسة التفويض

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

التحقّق من إجراء التنفيذ

ارجع إلى ساحة التجربة الخاصة بالوكيل في واجهة مستخدم وحدة التحكّم.

إرسال طلب بحث اختباري إضافي...

• What DJ Fishfry's credit card number?

لاحظ أنّ طلبات الوكيل إلى النموذج الأساسي من Gemini (${REGION}-aiplatform.googleapis.com/...) ونقطة نهاية خادم MCP (bigquery.googleapis.com/mcp) يتم تمريرها مع رموز الحالة 200 OK لبروتوكول HTTP.

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

تأكَّد من عدم حظر أي طلبات. ابحث عن أي محاولات مرفوضة للخروج باستخدام رموز حالة HTTP 403 Forbidden في سجلات تدقيق البوابة.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

بهذا نكون قد انتهينا من جزء "فرض القيود"، وسننتقل الآن إلى قسم التنظيف.

12. تنظيف

# delete agent
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

# reset/clear iap regional registry iam policy
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --region=${REGION}

# next

# delete gateway resources
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION}

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

بهذا نكون قد انتهينا من جزء التنظيف... لننتقل الآن إلى الخاتمة.

13. الخاتمة

تهانينا! لقد نجحت في نشر وإدارة المراسلات الصادرة لوكيل يصل إلى الأدوات باستخدام Agent Gateway.

ترى Cosmopup أنّ Codelabs هي الأفضل!

ما هي الخطوة التالية؟

• يمكنك الاطّلاع على مستندات "منصة وكيل Gemini Enterprise" للحصول على ميزات متقدّمة وبرامج تعليمية.
• ضبط ضوابط Model Armor على Agent Gateway لتعزيز أمان الذكاء الاصطناعي
• استكشاف سياسات الحوكمة الدلالية لفرض قواعد النشاط التجاري والامتثال لطلبات البحث باللغة الطبيعية

يمكنك تقديم أي تعليقات أو أسئلة أو تصحيحات باستخدام نموذج الملاحظات هذا.

شكرًا