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

۱. مقدمه

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

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

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

When Agent Gateway operates in egress ( agent-to-anywhere ) mode, it proxies all outbound requests from agents configured to use the gateway. Each agent workload request is authenticated using the unique Agent Identity and authorized using Identity-Aware Proxy (IAP) policies. MCP tool calls are dynamically decoded and inspected for policy enforcement. Security admins can centrally enforce fine-grained permissions to ensure agents can only invoke approved endpoints and methods.

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

• Agent Gateway in egress ( agent-to-anywhere ) mode
• افزونه‌ی مجوز پروکسی آگاه از هویت (IAP)
• عامل ADK Runtime با هویت عامل
• ثبت نماینده با API گوگل و نقاط پایانی MCP
• سیاست‌های مجوزدهی با کنترل دسترسی IAM
• مجموعه داده BigQuery برای پرس و جو با استفاده از MCP

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

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

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

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

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

۲. مفاهیم

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

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

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

• شروع در حالت dry-run: اگر زمان اجرای یک عامل طوری پیکربندی شده باشد که تماس‌های خروجی را قبل از آماده‌سازی کامل دروازه به دروازه هدایت کند، بار کاری در مقداردهی اولیه با شکست مواجه خواهد شد. پیکربندی افزونه مجوز دروازه در حالت DRY_RUN ابتدا تضمین می‌کند که وقتی ترافیک عامل به دروازه می‌رسد، هیچ درخواستی حذف نشود.
• ثبت همه سرویس‌ها: همه Agentها، سرورهای MCP و Endpointهایی که از Agent Gateway استفاده می‌کنند باید در Agent Registry ثبت شوند. درخواست‌ها برای هر منبع یا مقصد ثبت نشده رد می‌شوند. Agentهای مستقر در Agent Runtime و سرورهای Google MCP به طور خودکار ثبت می‌شوند. هر Endpoint یا سرور MCP سفارشی Google API باید به صورت دستی ثبت شود.
• اجرای سیاست‌های مجوزدهی: سیاست‌های مجوزدهی برای اجازه دادن به عامل‌های ثبت‌شده برای دسترسی به اجزای عامل ، با اعطای نقش roles roles/iap.egressor به شناسه عامل اصلی و اتصال آن به منبع رجیستری هدف، استفاده می‌شوند. رفتار عامل را با استفاده از حالت dry-run ارزیابی کنید و سپس سیاست‌هایی را تعریف کنید تا ترافیک خروجی انتخاب‌شده از طریق دروازه مجاز باشد. پس از اعمال سیاست‌ها، به حالت ENFORCED بروید تا دروازه بتواند سیاست‌های حاکمیتی را به‌طور فعال اجرا کند.

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

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

دروازه‌ها معمولاً ترافیک ورودی (ingress) به سرویس‌های backend را مدیریت می‌کنند. دروازه عامل (Agent Gateway) که در حالت خروجی ( agent-to-anywhere ) عمل می‌کند، به عنوان یک پروکسی خروجی متمرکز و بدون اعتماد (zero-trust) برای بارهای کاری عامل عمل می‌کند.

وقتی یک برنامه هوش مصنوعی یا بار کاری agentic سعی می‌کند یک ابزار یا API خارجی را فراخوانی کند، درخواست خروجی توسط Agent Gateway رهگیری شده و قبل از مسیریابی به مقصد، در برابر سیاست‌های مدیریتی ارزیابی می‌شود:

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

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

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

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

نقش‌های مورد نیاز 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/bigquery.admin	طرحواره‌های راه‌اندازی و مجموعه داده‌های آزمایشی
فضای ذخیره‌سازی ابری	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-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

فعال کردن سرویس‌های 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 \
  discoveryengine.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 قرار دارد، به پایان می‌رساند.

۶. کدبیس

کد عامل، مجموعه داده BigQuery و اسکریپت ثبت نام مورد استفاده برای این 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_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)"

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

۷. رجیستری

رجیستری عامل، فهرستی متمرکز از تمام عامل‌ها، سرورهای 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 regional endpoints (verify registration)
gcloud agent-registry endpoints list --location=${REGION} \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces[0].url:label=URL)"

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

۸. زمان اجرا

ایجنت ADK مربوط به agent-dj که در 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-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 آدرس منبع Gateway را نمایش دهد...
"agentGateway": "projects/ PROJ_ID /locations/ REGION /agentGateways/agw- SLUG - REGION -ata"

نقش‌های IAM را برای منابع به نماینده اعطا کنید

اعطای نقش IAM برای منابع، دسترسی هویتی عامل اصلی به BigQuery، ابزارهای MCP (برای APIهای گوگل) و سایر سرویس‌های مورد نیاز پلتفرم هوش مصنوعی را فراهم می‌کند. این سیاست‌ها با استفاده از 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)"

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

۹. سیاست‌ها

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

اعطای نقش 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 ) در منبع هدف است، تأیید کند.

Granting roles/iap.egressor to the agent identity or Agent Runtime principal set on the selected destination resource permits this egress traffic. In this codelab, the role is applied to the principal set which grants permission to all Agent Runtime agent identities in the project.

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

توجه : در یک استقرار عملیاتی، می‌توان سیاست‌های جزئی‌تری را برای محدود کردن خروج از عامل‌های خاص به نقاط انتهایی خاص پیاده‌سازی کرد. کنترل‌های جزئی‌تر و سیاست‌های اجازه مشروط در Codelabs آینده بررسی خواهند شد.

پیکربندی سیاست IAM رجیستری منطقه‌ای 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}

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

۱۰. حسابرسی

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

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

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

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

تأیید کنید که پرس‌وجوها پاسخ‌های معتبری برمی‌گردانند (مثلاً « ۱۲ دی‌جی در پرونده وجود دارد »).

تجزیه و تحلیل گزارش‌های حسابرسی

گزارش‌ها را مشاهده کنید و ارزیابی‌های سیاست آزمایشی را بررسی کنید.

# 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

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

۱۱. اجرا

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

ارسال درخواست تست اضافی...

• What DJ Fishfry's credit card number?

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

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

۱۲. پاکسازی

# 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

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

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

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

کازموپاپ فکر می‌کند Codelabs در صدر است!

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

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

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

متشکرم!