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

1. مقدمة

يستكشف هذا الدرس التطبيقي حول الترميز إدارة حركة البيانات الصادرة في بوابة الوكيل لوكلاء الذكاء الاصطناعي الذين يصلون إلى خوادم 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
• إمكانية ربط أداة MCP خارجية بمجموعات البيانات العامة في Data Commons
• سياسات التفويض مع التحكّم في الوصول من خلال "إدارة الهوية وإمكانية الوصول"

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

ما ستتعلمه

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

ما تحتاج إليه

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

2. المفاهيم

تسلسل النشر

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

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

1. البدء في وضع DRY_RUN: تأكَّد من وصول طلبات الوكيل إلى البوابة بنجاح ومن اجتيازها (وضع التدقيق فقط).
2. تسجيل جميع الخدمات: سجِّل جميع المكوّنات المستندة إلى وكيل في "سجلّ الوكلاء" وأكِّد إمكانية الوصول إلى أدوات الوكيل.
3. إنشاء سياسات التفويض: أنشئ سياسات التفويض وطبِّقها للسماح بخروج البيانات من الوكلاء إلى خوادم MCP ونقاط النهاية.
4. التبديل إلى وضع ENFORCED: عدِّل سياسة إضافة تفويض التحديث لفرض السياسات وحظر حركة الخروج غير المصرّح بها.

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

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

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

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

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

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

فحص بروتوكول MCP

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

تستخدم طلبات MCP عادةً تنسيق بروتوكول JSON-RPC السلكي ونقل HTTP. يتم تضمين تفاصيل طريقة MCP التي يتم استدعاؤها (مثل tools/call) واسم الأداة المستهدَفة وأي وسيطات في حمولة JSON ضمن نص HTTP.

يتم استخراج السمة iap.googleapis.com/mcp.toolName من خلال Agent Gateway عن طريق تحليل نص JSON للعثور على معرّف الأداة المحدّد في الطلب.

لا يتم عادةً إرسال سمات مثل iap.googleapis.com/mcp.tool.isReadOnly وmcp.tool.isDestructive في نص كل طلب. بدلاً من ذلك، تكون هذه التعليقات التوضيحية (البيانات الوصفية) مرتبطة بالأداة. لذلك، عندما يستخرج Agent Gateway toolName من النص الأساسي، يبحث عن تعريف الأداة والخصائص المرتبطة بها من Agent Registry، حيث تم تسجيل محتوى toolspec.json.

الشكل 4. فحص MCP في Agent Gateway

تستخدم تعبيرات CEL المستخدَمة في شروط "إدارة الهوية وإمكانية الوصول" (IAM) في "الشراء داخل التطبيق" التنسيق العادي api.getAttribute('iap.googleapis.com/ATTRIBUTE_NAME', 'DEFAULT_VALUE')== 'DESIRED_VALUE'.

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

السمة	طريقة / موقع MCP	الوصف
mcp.toolName	‫tools/call (النص)	معرّف الأداة المستهدَفة المطلوب في حمولة RPC (مثلاً، "delete_instance")
mcp.tool.isReadOnly	Agent Registry (toolspec.json)	تشير إلى ما إذا كانت الأداة للقراءة فقط (لا تعدّل بيئتها)
mcp.tool.isDestructive	Agent Registry (toolspec.json)	توضّح ما إذا كان استخدام الأداة قد يؤدي إلى تعديلات غير قابلة للإرجاع أو فقدان البيانات
mcp.tool.isIdempotent	Agent Registry (toolspec.json)	توضّح ما إذا كان تنفيذ الأداة المتكرّر باستخدام الوسيطات المتطابقة ينتج الحالة نفسها بالضبط
mcp.tool.isOpenWorld	Agent Registry (toolspec.json)	تشير إلى ما إذا كانت الأداة تصل إلى ما هو أبعد من الأنظمة الداخلية ذات الحدود إلى الإنترنت العام غير المحدود

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

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
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-datacommons"
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}"
export MCP_DISPLAY_NAME="api.datacommons.org"
export MCP_RESOURCE_NAME="${REGION}-datacommons-mcp"
export MCP_URL="https://api.datacommons.org/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_RESOURCE_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

تعديل gcloud cli (إجراء مُقترَح)

في حال تنفيذ عملية تثبيت مُدارة ذاتيًا لحزمة تطوير البرامج (SDK) من Google Cloud (أي خارج Cloud Shell)، يجب تعديل المكوّنات إلى أحدث إصدار.

# update gcloud cli
gcloud components update

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

# 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

ملاحظة: قد تستخدم بعض الميزات أوامر 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. قاعدة الرموز البرمجية

يتم الاحتفاظ برمز الوكيل ونص تسجيل نقطة النهاية المستخدَمَين في هذا الدرس التطبيقي حول الترميز في مستودع 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_emcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_emcp/codelabs/agw-cuj-arun-egress-emcp/agent-datacommons ./agent-datacommons
cp -r temp_agw_cuj_arun_egress_emcp/codelabs/agw-cuj-arun-egress-emcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_emcp

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

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

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

8. Data Commons

Data Commons هي مبادرة من Google لتنظيم مجموعات البيانات العامة وإتاحتها للجميع. هذه الخدمة مجانية ويمكن الوصول إليها باستخدام مفتاح واجهة برمجة التطبيقات بعد إنشاء حساب.

إنشاء مفتاح واجهة برمجة تطبيقات

بعد إنشاء حساب، اتّبِع الخطوات التالية للحصول على مفتاح واجهة برمجة التطبيقات:

• تسجيل الدخول إلى بوابة API في Data Commons
• انقر على الزر تطبيقاتي في أعلى يسار الصفحة
• انقر على الزر "+ تطبيق جديد" في أعلى يسار الصفحة تحت اسم المستخدم
• أدخِل اسمًا لتطبيقك (مثل "Codelab Agent MCP")
• انقر على الزر تفعيل لواجهة برمجة التطبيقات Data Commons API api.datacommons.org
• انقر على الزر حفظ في أسفل يسار الصفحة.

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

# set api key env var
 export DC_API_KEY="YOUR_API_KEY_HERE"

إنشاء خادم MCP toolspec

عند تسجيل خادم MCP يدويًا، يجب تضمين ملف مواصفات الأداة أثناء التسجيل. يؤدي تحميل ملف toolspec.json إلى إدراج جميع الأدوات التي توفّرها نقطة النهاية وإتاحتها للمستخدمين الآخرين.

ينشئ النص البرمجي test_mcp.py، المضمّن في قاعدة الرموز agent-datacommons/، ملف toolspec.json من خلال الاتصال بخادم MCP المستهدف (عبر SSE أو HTTP) ويطلب list_tools() لاسترداد جميع الأدوات المتاحة التي يعرضها الخادم.

# generate toolspec for registry ingestion
uv --directory agent-datacommons run python3 test_mcp.py --toolspec=include --token="${DC_API_KEY}"

توضّح نظرة على ناتج toolspec الذي تم إنشاؤه سمات MCP التي يمكن أن تستخدمها Agent Gateway لتقييم سياسة الخروج وتنفيذها.

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' agent-datacommons/toolspec.json

ملاحظة: من الشائع أن تستخدم خوادم MCP مفتوحة المصدر والتابعة لجهات خارجية (مثل Data Commons) الحقول الأساسية المطلوبة فقط: name وdescription وinputSchema(). إنّ تعليقات التوضيح الخاصة بالحوكمة، مثل isReadOnly وisDestructive وisIdempotent وisOpenWorld، هي بيانات وصفية اختيارية. يمكن لمشرفي الأمان ضبط هذه التعليقات التوضيحية في ملف toolspec.json قبل تسجيل خادم MCP في Agent Registry.

تسجيل خادم MCP

# register mcp server
gcloud agent-registry services create ${MCP_RESOURCE_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for data commons" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=agent-datacommons/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_RESOURCE_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_RESOURCE_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

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

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

تم ضبط وكيل agent-datacommons 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-datacommons 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 data commons stats" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --env-var="DC_API_KEY=${DC_API_KEY}"

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

# 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 RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

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

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

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

10. السياسات

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

تتيح أذونات دور "إدارة الهوية وإمكانية الوصول" لخروج 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 في هذا الدرس العملي، تكون سياسة إدارة الهوية وإمكانية الوصول مرتبطة بمستويَي mcpServer وendpoint، ما يمنح الإذن للموارد الفرعية المحدّدة.

لمحة عن فلترة المسارات المتعدّدة القنوات الشرطية

يتضمّن خادم MCP في Data Commons أداتَين:

• ‫search_indicators: للاستفسارات حول اكتشاف البيانات المتاحة أو البحث عن متغيرات أو فهم تغطية البيانات
• ‫get_observations: لطلبات البحث التي تسترد نقاط بيانات أو سلاسل زمنية معيّنة

هناك بعض عمليات MCP العادية التي يجب الانتباه إليها عند إعداد سياسات الحوكمة الشرطية على خوادم MCP. قبل أن يتمكّن عميل MCP من تقديم tools/call لـ search_indicators أو get_observations، يجب أولاً إرسال طلبات اكتشاف ومصافحة البروتوكول:

• initialize
• notifications/initialized
• tools/list

لتوضيح عملية فلترة السياسات الشرطية، سيتم إعداد السياسة وفقًا للشروط التالية:

جدول تقييم السياسات لطلبات MCP

الطلب / الطريقة	قيمة mcp.toolName	تقييم CEL	النتيجة
initialize	""	"" in ['search_indicators', '']	✅ مسموح به (200)
tools/list	""	"" in ['search_indicators', '']	✅ مسموح به (200)
search_indicators	"search_indicators"	"search_indicators" in [...]	✅ مسموح به (200)
get_observations	"get_observations"	"get_observations" in [...]	❌ DENIED (403)

للسماح بعمليات المصافحة بين البروتوكولات و استدعاء أداة search_indicators، تتضمّن قاعدة السياسة الشرطية إذنًا لـ "search_indicators" أو "" (سلسلة فارغة).

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

ملاحظة: في هذه السياسة الشرطية، يُسمح صراحةً باستخدام أداة search_indicators. سيتم رفض الطلبات المقدَّمة إلى أدوات أخرى (مثل get_observations) ضمنيًا.

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

ملاحظة: يجب أن تعرض السمة etag: القيمة التلقائية ACAB لأنّه لم يتم تحديد أي سياسات حتى الآن.

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

# create policy config file
cat > cfg/iap-policy-dc-agent-to-dc-mcp-tool-1.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ],
      "condition": {
        "title": "allow ${RE_AGENT_NAME} to use search_indicators tool for ${MCP_DISPLAY_NAME}",
        "expression": "api.getAttribute('iap.googleapis.com/mcp.toolName', '') in ['search_indicators', '']"
      }
    }
  ],
  "etag": "${IAP_ETAG}",
  "version": 3
}
EOF

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

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

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

11. التدقيق

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

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

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

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

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

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

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

• What data do you have on water quality in Zimbabwe?
• Compare the life expectancy, economic inequality, and GDP growth for BRICS nations

تأكَّد من أنّ طلبات البحث تعرض ردودًا صالحة.

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

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

# list unique urls with http status and iap authorization result
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=200 \
  --format="value(httpRequest.status, jsonPayload.authzPolicyInfo.result, httpRequest.requestUrl)" | sort -u

200     ALLOWED https://api.datacommons.org/mcp
200     ALLOWED https://cloudresourcemanager.googleapis.com:443/google.cloud.resourcemanager.v3.Projects/GetProject
200     ALLOWED https://telemetry.googleapis.com/v1/traces
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}/events
202     ALLOWED https://api.datacommons.org/mcp

ملاحظة: بالإضافة إلى الطلبات المُرسَلة إلى نقطة نهاية خادم MCP، يتم أيضًا إرسال طلبات إلى نقاط النهاية telemetry و${REGION}-aiplatform وcloudresourcemanager.

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

منح أذونات خروج الوكيل لنقطة نهاية القياس عن بُعد

# set var for endpoint display name
export ENDPOINT_1_DISPLAY_NAME="telemetry.googleapis.com"
echo ${ENDPOINT_1_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_1_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_1_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_1_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-1.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

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

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

منح أذونات خروج الوكيل لنقطة نهاية aiplatform

# set var for endpoint display name
export ENDPOINT_2_DISPLAY_NAME="${REGION}-aiplatform.googleapis.com"
echo ${ENDPOINT_2_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_2_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_2_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_2_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-2.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

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

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

منح الوكيل أذونات الخروج لنقطة نهاية cloudresourcemanager

# set var for endpoint display name
export ENDPOINT_3_DISPLAY_NAME="cloudresourcemanager.googleapis.com"
echo ${ENDPOINT_3_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_3_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_3_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_3_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-3.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

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

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

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

12. تنفيذ

تمكّن الوكيل من تقديم طلبات ناجحة من خلال البوابة في وضع 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}

التحقّق من السماح المشروط

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

إرسال طلب بحث اختباري إضافي (محاولة استدعاء الأداة المسموح بهاsearch_indicators)...

• What data topics do you have for Peru?

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

# 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
  )"

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

التحقّق من الرفض الشرطي

إرسال طلب بحث اختباري إضافي (محاولة استدعاء أداة الرفضget_observations)...

• What are the diabetes levels in Peru compared to Slovakia?

سينظر الوكيل إلى search_indicators أولاً ثم يحاول استخدام get_observations، ولكن سيتعذّر ذلك وستبقى استجابة الوكيل غير مكتملة.

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

TIMESTAMP            STATUS  IAP_AUTHZ  MCP_METHOD                 TOOL_NAME          URL
YYYY-MM-DDTHH:MM:SS  403     DENIED     tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS          ALLOWED    tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  403     DENIED     tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  200     ALLOWED    tools/call                 search_indicators  https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  200     ALLOWED    tools/list                                    https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  202     ALLOWED    notifications/initialized                     https://api.datacommons.org/mcp

يؤكّد ذلك أنّ سياسة الحوكمة تعمل على النحو المتوقّع.

يُرجى العِلم أنّ الصف الثاني الذي يشير إلى حالة فارغة وALLOWED هو حدث سجلّ ثانوي لإيقاف الاتصال صادر عن Agent Gateway عند إغلاق المقبس بعد إرسال الرد 403 (لأنّ أحداث إغلاق الاتصال لا تتضمّن رموز حالة الرد، وبالتالي تكون httpRequest.status فارغة).

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

13. تنظيف

# 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

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

# next

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

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

# next

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

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

# next

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

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

# next

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

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

# next

# remove manual registry entry
gcloud -q agent-registry services delete ${MCP_RESOURCE_NAME} --location=${REGION}

# 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 beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --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-datacommons endpoints

# end

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

14. الخاتمة

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

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

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

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

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

شكرًا