خروج Agent Gateway از Agent Runtime به MCP خارجی

۱. مقدمه

این آزمایشگاه کد، مدیریت خروجی دروازه عامل (Agent Gateway) را برای عامل‌های هوش مصنوعی که به سرورهای خارجی پروتکل زمینه مدل (MCP) که خارج از Google Cloud میزبانی می‌شوند، دسترسی دارند، بررسی می‌کند.

برنامه‌های هوش مصنوعی، از چت‌بات‌های مستقل گرفته تا سیستم‌های خودگردان با گردش‌های کاری چندعاملی، می‌توانند به صورت پویا ابزارهای خارجی را فراخوانی کنند. فراهم کردن دسترسی کنترل‌شده برای عامل‌ها جهت پرس‌وجو از پایگاه‌های داده، دریافت محتوای وب و اجرای اقدامات، برای عامل‌های ایمن و کارآمد ضروری است. با این حال، در محیط‌های سازمانی، ایمن‌سازی اجرای ابزار عامل یک چالش است. اگر یک عامل دسترسی مستقیم به شبکه داشته باشد، حملات تزریق سریع یا توهمات مدل می‌تواند باعث شود عامل داده‌های حساس را استخراج کند یا دستورات مخرب را اجرا کند.

برای مدیریت عامل‌های خودمختار در مقیاس بزرگ، Agent Gateway یک نقطه اجرای متمرکز و بدون اعتماد (zero-trust) را فراهم می‌کند که مستقیماً در معماری Agent Platform ادغام شده است. Agent Gateway به جای تکیه بر پیاده‌سازی‌های سفارشی منحصر به فرد برای هر برنامه یا کد عامل، مسیریابی شبکه، مدیریت عامل و امنیت زمان اجرا را در سطح پلتفرم اعمال می‌کند.

وقتی Agent Gateway در حالت خروجی ( agent-to-anywhere ) عمل می‌کند، تمام درخواست‌های خروجی از Agentهایی که برای استفاده از Gateway پیکربندی شده‌اند را پروکسی می‌کند. هر درخواست بار کاری Agent با استفاده از هویت منحصر به فرد Agent احراز هویت شده و با استفاده از سیاست‌های Identity-Aware Proxy (IAP) مجاز می‌شود. فراخوانی‌های ابزار MCP به صورت پویا رمزگشایی و برای اجرای سیاست‌ها بررسی می‌شوند. مدیران امنیتی می‌توانند مجوزهای دقیق را به صورت مرکزی اعمال کنند تا اطمینان حاصل شود که Agentها فقط می‌توانند نقاط پایانی و روش‌های تأیید شده را فراخوانی کنند.

آنچه می‌سازید

• دروازه عامل در حالت خروج ( عامل به هر جایی )
• افزونه‌ی مجوز پروکسی آگاه از هویت (IAP)
• عامل ADK Runtime با هویت عامل
• ثبت نماینده با API گوگل و نقاط پایانی MCP
• اتصال ابزار MCP خارجی به مجموعه داده‌های عمومی Data Commons
• سیاست‌های مجوزدهی با کنترل دسترسی IAM

شکل 1. معماری Codelab

آنچه یاد می‌گیرید

• نحوه استقرار Agent Gateway در یک توالی پیکربندی ساختاریافته
• چگونه سیاست‌های مجوزدهی را از حالت آزمایشی به حالت اجباری منتقل کنیم؟
• نحوه ثبت نقاط پایانی API گوگل و سرورهای MCP در رجیستری نمایندگان
• نحوه استفاده از سیاست‌های مجوزدهی مشروط بر اساس ویژگی‌های پروتکل MCP
• نحوه ممیزی لاگ‌های Agent Gateway برای اعتبارسنجی مدیریت خروجی

آنچه شما نیاز دارید

• یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
• مجوزهای IAM برای ارائه خدمات شبکه و منابع پلتفرم عامل
• یک پوسته سازگار با POSIX ( bash یا zsh ) با رابط خط فرمان گوگل کلود (اجزای gcloud و bq ) نصب شده
• ابزارهای خط فرمان: git ، curl ، jq (پردازشگر JSON)، پایتون ۳ و uv (مدیر بسته پایتون)
• یک کلید API رایگان Data Commons برای دسترسی به مجموعه داده‌های آزمایشی پرس‌وجو

۲. مفاهیم

توالی استقرار

این آزمایشگاه کد از یک توالی پیکربندی ساختاریافته پیروی می‌کند، بنابراین عامل‌ها در هنگام راه‌اندازی اولیه به منابع لازم دسترسی دارند و اتصال می‌تواند قبل از اعمال سیاست‌های دسترسی اجباری تأیید شود.

این Codelab از توالی استقرار زیر استفاده می‌کند:

1. شروع در حالت DRY_RUN : اطمینان حاصل کنید که درخواست‌های عامل با موفقیت به دروازه می‌رسند و عبور می‌کنند (حالت فقط حسابرسی).
2. ثبت تمام سرویس‌ها: تمام اجزای عامل را در رجیستری عامل ثبت کنید و دسترسی به ابزار عامل را تأیید کنید.
3. ایجاد سیاست‌های مجوزدهی: سیاست‌های مجوزدهی را ایجاد و اعمال کنید تا ترافیک خروجی از Agentها به سرورهای MCP و Endpointها مجاز باشد.
4. به حالت ENFORCED بروید: سیاست گسترش مجوز را به‌روزرسانی کنید تا سیاست‌ها اعمال شوند و ترافیک خروجی غیرمجاز مسدود شود.

شکل ۲. توالی استقرار

توپولوژی مسیریابی خروجی

خروجی Agent Gateway ( agent-to-anywhere ) به عنوان یک پروکسی خروجی متمرکز و بدون اعتماد برای بارهای کاری agentic عمل می‌کند. هنگامی که یک agent درخواستی به یک ابزار یا API خارجی ارسال می‌کند، درخواست خروجی توسط Agent Gateway رهگیری شده و قبل از مسیریابی به مقصد، در برابر سیاست‌های حاکمیتی ارزیابی می‌شود. در معماری پلتفرم Google Cloud Agent، Agent Gateway اتصال سطح داده را برای موارد زیر فراهم می‌کند:

• شبکه‌های خصوصی (VPC): ترافیک خروجی که APIهای داخلی سازمان، میکروسرویس‌ها، پایگاه‌های داده میزبانی‌شده در VPCهای خصوصی و شبکه‌های داخلی یا بین ابری قابل دسترسی از طریق اتصال ترکیبی را هدف قرار می‌دهد.
• شبکه‌های خارجی (اینترنت): ترافیک خروجی که سرویس‌های وب شخص ثالث، APIهای SaaS یا نقاط پایانی عمومی را هدف قرار می‌دهد.
• سرویس‌های هوش مصنوعی و پلتفرم عامل: هدف‌گیری ترافیک خروجی، APIهای مدیریت‌شده‌ی Google Cloud، مدل‌های پایه، نقاط پایانی Google MCP (مانند BigQuery) و سرویس‌های مدیریت پلتفرم (ثبت عامل و سیاست‌های IAP).

شکل ۳. توپولوژی مسیریابی خروجی دروازه عامل

تمرکز این Codelab بر ترافیک خروجی از یک عامل سفارشی در Agent Runtime است که یک نقطه پایانی سرور MCP شخص ثالث خارجی را که از طریق اینترنت قابل دسترسی است، هدف قرار می‌دهد.

بازرسی پروتکل MCP

خروجی دروازه عامل ( عامل به هر جایی ) قادر است محتوای درخواست‌های MCP را تجزیه و تحلیل کند و سیاست‌های دسترسی را بر اساس ویژگی‌های دقیق پروتکل ارزیابی کند. سیاست‌های خروجی سرور عامل به 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 ثبت شده است، جستجو می‌کند.

شکل ۴. بازرسی MCP توسط Agent Gateway

عبارات CEL که در شرط‌های IAP 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	رجیستری عامل ( toolspec.json )	نشان می‌دهد که آیا ابزار فقط خواندنی است (محیط آن را تغییر نمی‌دهد)
mcp.tool.isDestructive	رجیستری عامل ( toolspec.json )	نشان می‌دهد که آیا فراخوانی ابزار می‌تواند منجر به تغییرات برگشت‌ناپذیر یا از دست رفتن داده‌ها شود یا خیر
mcp.tool.isIdempotent	رجیستری عامل ( toolspec.json )	نشان می‌دهد که آیا اجرای مکرر ابزار با آرگومان‌های یکسان، دقیقاً همان حالت را ایجاد می‌کند یا خیر
mcp.tool.isOpenWorld	رجیستری عامل ( toolspec.json )	نشان می‌دهد که آیا این ابزار فراتر از سیستم‌های داخلی محدود به اینترنت عمومی نامحدود دسترسی دارد یا خیر.

این بخش مفاهیم را به پایان می‌رساند... و در ادامه به بخش تنظیمات می‌پردازیم.

۳. راه‌اندازی

نقش‌های مورد نیاز IAM

برای ایجاد منابع در این Codelab، نقش‌های زیر مورد نیاز است:

دسته بندی	نقش IAM مورد نیاز (شناسه)	توضیحات
مدیریت API	roles/serviceusage.serviceUsageAdmin	فعال کردن سرویس‌های Google Cloud API
شبکه و درگاه	roles/networkservices.admin	دروازه عامل تأمین
افزونه‌های سرویس	roles/serviceextensions.admin	پیکربندی افزونه‌های مسیریابی
امنیت شبکه	roles/networksecurity.admin	استقرار سیاست‌های مجوزدهی
ثبت نماینده	roles/agentregistry.admin	میزبان‌های مجاز کاتالوگ
هوش مصنوعی و عامل‌های Vertex	roles/aiplatform.admin	بارهای کاری Agent Runtime را مستقر کنید
سیاست‌های خروج	roles/iap.admin	اعمال سیاست‌های roles/iap.egressor
فضای ذخیره‌سازی ابری	roles/storage.admin	مدیریت سطل‌های مرحله‌بندی استقرار
گزارش‌ها و حسابرسی	roles/logging.viewer	بررسی ردپاها و گزارش‌های حسابرسی

روش دیگر، استفاده از یک نقش اساسی گسترده مانند roles/admin یا نقش قدیمی roles/owner .

به پروژه خود دسترسی پیدا کنید

این Codelab از یک پروژه Google Cloud واحد استفاده می‌کند. مراحل پیکربندی از gcloud CLI و دستورات پوسته لینوکس استفاده می‌کنند.

با دسترسی به خط فرمان پروژه Google Cloud خود شروع کنید:

• کلود شل در 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

تنظیم متغیرهای محیطی پوسته

# 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 (توصیه می‌شود)

اگر نصب خودمدیریت‌شده‌ی Google Cloud SDK (یعنی خارج از Cloud Shell) را اجرا می‌کنید، اجزا را به آخرین نسخه به‌روزرسانی کنید.

# update gcloud cli
gcloud components update

فعال کردن سرویس‌های API

# 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 اجرا کنید.

این بخش تنظیمات را به پایان می‌رساند... و در ادامه به بخش دروازه (Gateway) می‌پردازیم.

۴. دروازه

قبل از اعمال کنترل‌های دسترسی، 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}

این بخش مربوط به درگاه (gateway) است... که در کنار بخش مجوز (Authorization) قرار دارد.

۵. مجوز

افزونه‌ی مجوزدهی Agent Gateway برای Identity-Aware Proxy (IAP) نوعی افزونه‌ی سرویس است که برای واگذاری تصمیمات مجوزدهی برای تمام ارتباطات Agent Platform استفاده می‌شود.

1. جریان واگذاری: وقتی یک عامل تلاش می‌کند تا یک نقطه پایانی خارجی یا سرور MCP را فراخوانی کند، درخواست را به Agent Gateway هدایت می‌کند. به جای ارزیابی دسترسی به صورت محلی، Gateway از افزونه مجوز برای ارسال یک فراخوان به سرویس ارزیابی IAP استفاده می‌کند. IAP هویت عامل ( مبتنی بر SPIFFE ) را در برابر سیاست IAM منبع هدف در رجیستری عامل ارزیابی می‌کند. IAP تصمیم ALLOW یا DENY را به Gateway برمی‌گرداند، که یا ترافیک را به جلو هدایت می‌کند یا آن را با کد وضعیت HTTP 403 Forbidden مسدود می‌کند.
2. حالت‌های اجرا: در حالت DRY_RUN ، IAP درخواست‌ها را ارزیابی می‌کند و بدون مسدود کردن ترافیک، تصمیمات ثبت وقایع را در Cloud Logging ثبت می‌کند. در حالت ENFORCE ، هرگونه درخواست از یک عامل غیرمجاز یا به یک هدف ثبت نشده بلافاصله مسدود می‌شود.
3. لایه اتصال: افزونه سرویس با استفاده از یک سیاست مجوز پیکربندی شده با پروفایل REQUEST_AUTHZ به Agent Gateway متصل می‌شود.

تمدید مجوز

ایجاد افزونه مجوز

# 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}

این بخش مجوزدهی را که در کنار بخش Codebase قرار دارد، به پایان می‌رساند.

۶. کدبیس

کد عامل و اسکریپت ثبت نقطه پایانی مورد استفاده برای این Codelab در یک مخزن راه دور Google Cloud GitHub نگهداری می‌شوند. مراحل زیر مخزن را به صورت محلی کلون می‌کند، فایل‌های لازم را در ساختار دایرکتوری کاری فعلی کپی می‌کند و سپس فایل‌های موقت را پاکسازی می‌کند.

یک مخزن ذخیره‌سازی برای Agent Runtime ایجاد می‌شود تا کد برنامه عامل بسته‌بندی‌شده و مصنوعات وابستگی آن را آپلود، ساخت و مستقر کند.

مصنوعات از راه دور را دریافت کنید

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

این بخش کدبیس را به پایان می‌رساند... و در ادامه به بخش رجیستری می‌پردازیم.

۷. رجیستری

رجیستری عامل، فهرستی متمرکز از تمام عامل‌ها، سرورهای MCP و نقاط پایانی (API) در اکوسیستم هوش مصنوعی است. همچنین، کاتالوگی است که می‌تواند برای فهرست کردن، جستجو و کشف سایر ابزارها و سرویس‌های ثبت‌شده برای استفاده توسط برنامه‌های هوش مصنوعی استفاده شود. حالت خروجی دروازه عامل ( عامل به هر جایی ) از مدل داده‌های رجیستری به عنوان چارچوب مدیریتی برای اجرای کنترل دسترسی خروجی استفاده می‌کند. اعطای نقش IAM برای عامل‌های اصلی فراخوانی‌کننده، در برابر سیاستی که به منبع رجیستری متصل است، بررسی می‌شود.

به منظور راه‌اندازی مجدد محیط و پشتیبانی از عامل‌ها با استفاده از APIها و سرویس‌های مختلف گوگل ، از یک اسکریپت برای ثبت سریع مجموعه‌ای مشترک از نقاط انتهایی API با استفاده از نام‌های میزبان و مکان‌ها از 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 قرار دارد.

۸. داده‌های مشترک

Data Commons ابتکاری از گوگل برای سازماندهی مجموعه داده‌های عمومی و در دسترس قرار دادن و در دسترس قرار دادن آنها برای همه است. این یک سرویس رایگان است و پس از ایجاد یک حساب کاربری، با استفاده از یک کلید API قابل دسترسی است.

ایجاد کلید API

پس از ایجاد حساب کاربری، برای دریافت کلید API مراحل زیر را دنبال کنید:

• وارد پورتال API Data Commons شوید
• روی دکمه « برنامه‌های من » در گوشه بالا سمت راست کلیک کنید
• روی دکمه « + برنامه جدید » در گوشه بالا سمت راست زیر نام کاربری خود کلیک کنید
• به برنامه خود یک نام بدهید (مثلاً "Codelab Agent MCP")
• روی دکمه‌ی « فعال کردن » برای API مربوط به Data Commons api.datacommons.org کلیک کنید
• روی دکمه « ذخیره » در گوشه پایین سمت راست کلیک کنید

این یک کلید API و رمز ایجاد می‌کند. برای « کپی کلید API » روی نماد «کپی» در کنار مقدار کلید کلیک کنید. مقدار را در دستور ترمینال جایگذاری کنید تا متغیر محیطی DC_API_KEY تنظیم شود.

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

ایجاد toolspec MCP server

هنگام ثبت دستی یک سرور MCP، یک فایل مشخصات ابزار باید در طول ثبت نام گنجانده شود. آپلود فایل toolspec.json تمام ابزارهای موجود توسط endpoint را فهرست می‌کند و به سایر کاربران امکان می‌دهد آنها را کشف کنند.

اسکریپت test_mcp.py که در کدبیس agent-datacommons/ قرار دارد، با اتصال به سرور MCP هدف (از طریق SSE یا HTTP) یک فایل toolspec.json تولید می‌کند و 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 فراداده‌های افزونه اختیاری هستند. مدیران امنیتی می‌توانند این حاشیه‌نویسی‌ها را قبل از ثبت سرور MCP در Agent Registry در فایل toolspec.json تنظیم کنند.

سرور 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 را به پایان می‌رساند... و در کنار بخش Runtime قرار می‌گیرد.

۹. زمان اجرا

عامل ADK مربوط به agent-datacommons که در Agent Runtime مستقر شده است، با تنظیمات زیر در اسکریپت استقرار پیکربندی شده است تا با Agent Platform ادغام شود:

• "identity_type": types.IdentityType.AGENT_IDENTITY برای ارائه یک هویت اصلی منحصر به فرد مبتنی بر SPIFFE برای عامل
• "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } برای هدایت تمام ترافیک خروجی آغاز شده توسط agent به 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 ) را نشان می‌دهد.

۱۰. سیاست‌ها

سیاست‌های مجوزدهی مدیریت عامل، ترافیک را از یک عامل هوش مصنوعی از طریق دروازه عامل و به مقصد (مثلاً یک نقطه پایانی سرور MCP شخص ثالث برای یک برنامه SaaS) مجاز می‌کند. پس از رسیدن ترافیک به مقصد، مجوزهای منظم در سطح سرویس یا سطح برنامه، دسترسی به داده‌ها را مجاز می‌کنند.

اعطای نقش IAM برای خروج Agent Gateway، سیاست‌های دسترسی را فعال می‌کند که به هویت اصلی Agent اجازه دسترسی به منابع مقصد ثبت‌شده را از طریق Agent Gateway می‌دهد. این سیاست‌ها در سطح Agent Gateway اعمال شده و با استفاده از سیاست‌های IAM مربوط به Identity-Aware Proxy (IAP) اعتبارسنجی می‌شوند.

به مامور IAM برای خروج Agent Gateway نقش‌های IAM اعطا کنید

Agent Gateway درخواست‌های ورودی را بررسی می‌کند تا هویت عامل فراخوانی‌کننده را که دارای مجوز iap.webServiceVersions.egressViaIAP (اعطا شده توسط نقش roles/iap.egressor ) در منبع هدف است، تأیید کند.

اعطای roles/iap.egressor به هویت عامل یا مجموعه اصلی Agent Runtime روی منبع مقصد انتخاب شده، این ترافیک خروجی را مجاز می‌کند. در این آزمایشگاه کد، این نقش به عامل اصلی اعمال می‌شود که به هویت عامل خاص Agent Runtime اجازه می‌دهد.

سیاست‌های IAM همانطور که در مدل داده Agent Registry تعریف شده است، به منابع مقصد محدود می‌شوند. منبع iap_web/agentRegistry نشان دهنده یک سطح " در سطح رجیستری " در سلسله مراتب IAM است. که در آن agentRegistry به عنوان والد برای منابع فرزند برای agents ، mcpServers و endpoints عمل می‌کند. در این آزمایشگاه کد، سیاست IAM به سطوح mcpServer و endpoint محدود می‌شود که مجوز را به منابع فرزند خاص اعمال می‌کند.

درباره فیلترینگ شرطی MCP

سرور Data Commons MCP دو ابزار دارد:

• search_indicators : برای پرس‌وجوهایی در مورد کشف داده‌های موجود، جستجوی متغیرها یا درک پوشش داده‌ها
• get_observations : برای کوئری‌هایی که می‌خواهند نقاط داده یا سری‌های زمانی خاصی را بازیابی کنند.

برخی عملیات استاندارد MCP وجود دارد که باید هنگام پیکربندی سیاست‌های مدیریت شرطی در سرورهای MCP از آنها آگاه باشید. قبل از اینکه یک کلاینت MCP بتواند برای search_indicators یا get_observations tools/call انجام دهد، ابتدا باید درخواست‌های protocol handshake و discovery را ارسال کند:

• 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 [...]	❌ رد شد (403)

برای مجاز کردن دست‌دهی پروتکل و فراخوانی ابزار search_indicators ، قانون سیاست شرطی شامل اجازه برای "search_indicators" یا "" (رشته خالی) می‌شود.

پیکربندی رجیستری IAP MCP سرور IAM policy

توجه: در این سیاست مشروط، ابزار 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}

این بخش سیاست‌ها را به پایان می‌رساند... که در کنار بخش حسابرسی قرار دارد.

۱۱. حسابرسی

افزونه‌ی مجوز Agent Gateway در حالت DRY_RUN فعال است. درخواست‌های خروجی مشاهده و ثبت می‌شوند اما مسدود نمی‌شوند.

سوالات مربوط به عامل تست

یک پنجره مرورگر را باز کنید و به رابط کاربری کنسول Google Cloud بروید و به مسیر زیر بروید:

• پلتفرم عامل → عامل‌ها → استقرارها → 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، سیاست IAM

اعطای مجوزهای خروج به عامل برای نقطه پایانی تله‌متری

# 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}

این بخش حسابرسی را به پایان می‌رساند... و پس از آن بخش اجرا قرار دارد.

۱۲. اجرا

عامل توانست درخواست‌های موفقیت‌آمیزی را از طریق دروازه در حالت DRY_RUN ارسال کند. با به‌روزرسانی سیاست مجوز، افزونه مجوز 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}

تأیید اجازه مشروط

در رابط کاربری کنسول به محیط بازی عامل (agent Playground) برگردید.

یک پرس‌وجوی آزمایشی دیگر ارسال کنید (سعی کنید ابزار search_indicators مجاز را فراخوانی کنید)...

• What data topics do you have for Peru?

مشاهده کنید که درخواست‌های عامل به مدل پایه Gemini ( ${REGION}-aiplatform.googleapis.com/... )، رابط برنامه‌نویسی کاربردی تله‌متری ( telemetry.googleapis.com/... ) و نقطه پایانی سرور Data Commons MCP ( 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 خالی است).

این بخش اجرا را به پایان می‌رساند... که در کنار بخش پاکسازی قرار دارد.

۱۳. پاکسازی

# 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

این بخش پاکسازی را به پایان می‌رساند... و بعد از نتیجه‌گیری !

۱۴. نتیجه‌گیری

تبریک! شما با موفقیت ارتباطات خروجی را برای یک عامل که به ابزارها با استفاده از Agent Gateway دسترسی دارد، مستقر و مدیریت کردید!

کازموپاپ فکر می‌کند Codelabs مثل زنبور عسل است!

قدم بعدی چیست؟

• برای ویژگی‌ها و آموزش‌های پیشرفته ، مستندات پلتفرم Gemini Enterprise Agent را بررسی کنید.
• پیکربندی گاردریل‌های مدل آرمور روی Agent Gateway برای ایمنی و امنیت بیشتر هوش مصنوعی
• بررسی سیاست‌های مدیریت معنایی برای اجرای قوانین کسب‌وکار و انطباق با پرس‌وجوهای زبان طبیعی

با استفاده از این فرم بازخورد، می‌توانید هرگونه نظر، سوال یا اصلاحیه‌ای را ارائه دهید.

متشکرم!