مدیریت بارهای کاری agentic با Agent Gateway در پلتفرم Gemini Enterprise Agent

۱. مقدمه

پلتفرم Gemini Enterprise Agent یک پلتفرم باز برای ساخت، مقیاس‌بندی، مدیریت و بهینه‌سازی عامل‌های هوش مصنوعی در سطح سازمانی است که مبتنی بر داده‌های شما می‌باشند.

Agent Runtime محیط اجرای مدیریت‌شده‌ای را برای اجرای عامل‌ها، مانند آن‌هایی که با کیت توسعه عامل متن‌باز (ADK) ساخته شده‌اند، به صورت ایمن در Google Cloud فراهم می‌کند.

این آزمایشگاه کد، نحوه استفاده از این بلوک‌های سازنده اصلی را برای مدیریت عاملی که توسط یک کاربر در Gemini Enterprise آغاز شده است، بررسی می‌کند، زیرا این عامل به طور ایمن به ابزارهای داخلی دسترسی پیدا می‌کند.

درباره دروازه عامل

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

این دو مسیر دسترسی اصلی تحت کنترل را تسهیل می‌کند:

  • کلاینت به عامل (ورودی): ارتباطات بین کلاینت‌های خارجی (مانند Cursor یا Gemini CLI) و عامل‌های شما را ایمن می‌کند.
  • عامل به هر کجا (خروجی): ارتباطات بین عامل‌های در حال اجرا در Google Cloud و سرورها، ابزارها یا APIهای در حال اجرا در هر کجا را ایمن می‌کند.

در این آزمایشگاه کد، شما بر روی حالت Agent-to-Anywhere (خروج) تمرکز خواهید کرد.

کنترل دسترسی با Agent Gateway

برای اجرای سیاست‌های امنیتی ، Agent Gateway به طور کامل با بقیه اکوسیستم ادغام می‌شود:

  • رجیستری عامل : یک کتابخانه مرکزی از عامل‌ها و ابزارهای تأیید شده (از جمله سرورهای MCP شخص ثالث).
  • هویت عامل : یک شخصیت منحصر به فرد و قابل ردیابی برای هر عامل، که به طور خودکار با mTLS سرتاسری ایمن می‌شود.
  • پروکسی آگاه از هویت (IAP) و IAM: لایه اجرایی پیش‌فرض که هویت عامل را قبل از اجازه دادن به فراخوانی ابزارهای خاص، در برابر مجوزهای دقیق IAM اعتبارسنجی می‌کند.
  • Model Armor : یک محافظ امنیتی هوش مصنوعی که از طریق Service Extensions یکپارچه شده است تا محتوا را پاکسازی کرده و در برابر حملات تزریق سریع یا نشت داده‌ها محافظت کند.

حالت‌های استقرار (شبکه عمومی در مقابل شبکه خصوصی برای Cloud Run)

برای اینکه این آزمایشگاه کد در دسترس باشد، می‌توانید از بین دو مسیر شبکه برای ابزارهای داخلی خود (سرورهای MCP) که در Cloud Run مستقر شده‌اند، یکی را انتخاب کنید:

  1. پیش‌فرض (ورود عمومی): سرورهای MCP با نام‌های میزبان عمومی ( ingress=all ) در Cloud Run مستقر می‌شوند. مسیرهای ترافیک از عامل به ابزارها از طریق URL های استاندارد *.run.app هدایت می‌شوند. این روش نیازی به دامنه‌های DNS سفارشی ندارد و سریع‌ترین راه برای یادگیری مفاهیم مدیریت است.
  2. امن (شبکه خصوصی): یک معماری کاملاً خصوصی و اختیاری. سرورهای MCP محدود شده‌اند ( ingress=internal-and-cloud-load-balancing ) و از طریق یک متعادل‌کننده بار برنامه داخلی با یک NEG بدون سرور در معرض دید قرار می‌گیرند. این امر مستلزم آن است که شما یک دامنه DNS عمومی داشته باشید تا بتوانید یک گواهی مدیریت‌شده توسط گوگل را ارائه دهید.

هنگام پیکربندی Terraform، مسیر دلخواه خود را انتخاب خواهید کرد.

برای کسب اطلاعات بیشتر در مورد ورود به نقاط انتهایی شبکه برای Cloud Run، لطفاً اسناد ما را مطالعه کنید .

کاری که انجام خواهید داد

  • آماده‌سازی پشته زیرساخت اصلی با استفاده از Terraform
  • ساخت و استقرار ابزارهای داخلی به عنوان سرورهای MCP در Cloud Run
  • با استفاده از خروجی رابط PSC، یک عامل ADK را در Agent Runtime مستقر کنید
  • پیکربندی افزونه‌های سرویس Agent Gateway برای دسترسی مبتنی بر هویت (IAM) و غربالگری محتوا (Model Armor)
  • ردیابی و اعتبارسنجی اجرای امن سرتاسری عامل

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

  • یک مرورگر وب مانند کروم
  • یک پروژه گوگل کلود با قابلیت پرداخت و دسترسی مالک
  • مجوزهای IAM در سطح سازمان (کدلب نقش‌های سازمانی را اعطا می‌کند)
  • دامنه‌ای که کنترل آن به Cloud DNS واگذار شده است (برای گواهی مدیریت‌شده عمومی)
  • آشنایی با Terraform، gcloud و شبکه‌سازی پایه Google Cloud

توپولوژی Codelab

معماری سرتاسری: از Gemini Enterprise به Agent Runtime به Agent Gateway به سرورهای MCP روی Cloud Run

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

شما با تأمین زیرساخت‌های شبکه، شامل یک VPC و یک Application Load Balancer داخلی که به عنوان Agent Gateway شما پیکربندی شده است، شروع خواهید کرد. در مرحله بعد، سه سرور Model Context Protocol (MCP) را در Cloud Run مستقر خواهید کرد. این سرورها به عنوان ابزارهای اختصاصی داخلی شما عمل می‌کنند:

  • مدیریت اسناد ( legacy-dms )
  • ایمیل شرکتی ( corporate-email )
  • تأیید درآمد ( income-verification )

با ابزارهای موجود، شما یک Mortgage Assistant ( mortgage-agent ) ساخته شده با ADK را برای Agent Runtime مستقر خواهید کرد. شما این agent را طوری پیکربندی خواهید کرد که از یک رابط PSC برای خروج خصوصی استفاده کند و کشف ابزار runtime را از طریق Agent Registry فعال کند.

برای ایمن‌سازی جریان، شما Agent Gateway خود را با دو افزونه سرویس پیکربندی خواهید کرد. اول، افزونه REQUEST_AUTHZ هویت Agent را در برابر سیاست‌های IAM هر ابزار تأیید می‌کند و تضمین می‌کند که Agent فقط به ابزارهای مجاز دسترسی دارد. دوم، افزونه CONTENT_AUTHZ با استفاده از Model Armor، اعلان‌ها و پاسخ‌های Agent را بررسی می‌کند.

در نهایت، شما نماینده را در Gemini Enterprise ثبت خواهید کرد، یک وظیفه ضمانت وام مسکن را به عنوان کاربر نهایی آغاز خواهید کرد و اجرای امن و تحت نظارت را با استفاده از Cloud Trace تأیید خواهید کرد.

این آزمایشگاه کد برای مهندسان پلتفرم و امنیت در تمام سطوح است. انتظار می‌رود تقریباً ۱۰۰ دقیقه برای تکمیل آن وقت صرف کنید.

۲. قبل از شروع

ایجاد پروژه و احراز هویت

یک پروژه GCP جدید (یا یک پروژه قابل استفاده مجدد) با قابلیت پرداخت فعال ایجاد کنید، سپس Cloud Shell یا دستگاه محلی خود را احراز هویت کنید:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

فعال کردن API های بوت استرپ

ماژول پایه Terraform در اولین اجرای خود حدود 30 API را فعال می‌کند، اما برای terraform init و سطل وضعیت GCS به یک مجموعه کوچک bootstrap نیاز است:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

نصب ابزارهای مورد نیاز

زنجیره ابزار را نصب کنید. در Cloud Shell اکثر این موارد از قبل موجود هستند؛ در یک ایستگاه کاری:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

همچنین به Terraform >= 1.12.2 ، پایتون 3.12+ و کیت توسعه نرم‌افزار گوگل کلود ( gcloud ) نیاز دارید.

تنظیم متغیرهای محیطی

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

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com"

تأیید کنید که تمام متغیرهای شما به درستی پر شده‌اند، باید سه مقدار برگردانده شود.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

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

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

۳. مخزن را کلون کنید 

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

نگاهی سریع به آنچه در فهرست نسخه‌های نمایشی وجود دارد:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

۴. ایجاد سطل وضعیت Terraform و پیکربندی backend

یک سطل GCS برای نگهداری وضعیت از راه دور ایجاد کنید، سپس الگوی backend را کپی کنید:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

terraform/backend.conf را با مقادیر دلخواه خود ویرایش کنید: 

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

۵. (اختیاری) یک منطقه عمومی DNS ابری ایجاد کنید

به طور پیش‌فرض برای این آزمایشگاه، Cloud Run پیکربندی ورودی خود را روی all تنظیم کرده است و Agent Registry هر سرور MCP را در URL عمومی *.run.app خود ثبت می‌کند - هیچ DNS، گواهی یا متعادل‌کننده بار اضافی مورد نیاز نیست. اگر می‌خواهید به شبکه خصوصی (Cloud Run با ingress = internal-and-cloud-load-balancing پشت یک Application LB داخلی) تغییر دهید، به یک منطقه Cloud DNS عمومی نیز نیاز دارید تا Certificate Manager بتواند گواهی LB را تأیید کند.

جریان سطح بالای شبکه خصوصی

گزینه جریان سطح بالای شبکه خصوصی

برای استفاده از رویکرد شبکه خصوصی:

  1. ایجاد منطقه عمومی DNS ابری — مدیر گواهینامه، گواهینامه مدیریت‌شده منطقه‌ای را با نوشتن CNAMEها در آن تأیید می‌کند: 
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

ناحیه خصوصی مربوطه برای mcp.${DOMAIN_NAME} (که توسط LB داخلی MCP و DNS peering از Agent Runtime استفاده می‌شود) به طور خودکار توسط Terraform ایجاد می‌شود - نیازی نیست آن را به صورت دستی ایجاد کنید. با خاموش بودن شبکه خصوصی، نه ناحیه عمومی و نه ناحیه خصوصی فراهم نمی‌شوند.

۶. پیکربندی متغیرهای Terraform

tfvar های مثال را کپی کرده و ویرایش کنید: 

cp terraform/example.tfvars terraform/terraform.tfvars

دو مسیر آزمایشی وجود دارد که توسط enable_cloud_run_private_networking محدود شده‌اند.

مسیر پیش‌فرض: Cloud Run با دسترسی عمومی

**ساده‌ترین تنظیمات.** برای مسیر پیش‌فرض، فقط باید سه مقدار را در terraform.tfvars ویرایش کنید. هر متغیر دیگری در فایل از قبل یک پیش‌فرض قابل استفاده دارد. 

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:admin@example.com"]

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

شبکه خصوصی (اختیاری)

enable_cloud_run_private_networking = true قرار دهید و متغیرهای زیر را برای تأمین پشته امن کامل اضافه کنید:

  • برنامه داخلی LB
  • گواهینامه تحت مدیریت گوگل
  • اجرای ابری با ingress = internal-and-cloud-load-balancing
  • جفت‌سازی DNS توسط Agent Gateway. 
enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

۷. استقرار زیرساخت با Terraform

مقداردهی اولیه، بررسی و اعمال: 

cd terraform
terraform init -backend-config=backend.conf
terraform plan
terraform apply

terraform apply و در یک پروژه جدید ۸ تا ۱۰ دقیقه طول می‌کشد (حدود ۶۰ منبع / ۱۵ تا ۲۰ دقیقه وقتی enable_cloud_run_private_networking = true ). این فرآیند موارد زیر را ایجاد می‌کند:

  • پایه و اساس پروژه (APIها، هویت سرویس‌ها، سهمیه‌ها)
  • VPC، زیرشبکه‌ها (اولیه، فقط پروکسی، PSC، رابط PSC، هم‌مکانی دروازه عامل)، Cloud NAT، قوانین فایروال
  • مخزن رجیستری مصنوعات برای تصاویر Cloud Run
  • سه سرویس Cloud Run + SA های زمان اجرای هر سرویس (ورودی = all به صورت پیش‌فرض؛ internal-and-cloud-load-balancing هنگام روشن بودن شبکه خصوصی)
  • الگوی زره ​​مدل + IAM
  • دروازه عامل، اتصال شبکه PSC-I، افزونه‌های IAP و Model Armor، هر دو سیاست‌های مجوز، و اعطای roles/iap.egressor در سطح پروژه
  • نقاط پایانی رجیستری عامل (Vertex AI، IAP، Discovery Engine، ...) به علاوه سه سرور MCP (که به طور پیش‌فرض در *.run.app/mcp ثبت شده‌اند؛ در . /mcp وقتی شبکه خصوصی روشن است)

فقط زمانی که enable_cloud_run_private_networking = true :

  • برنامه منطقه‌ای داخلی LB با NEG بدون سرور (مسیریابی URL-mask) + رکوردهای DNS A خصوصی
  • منطقه DNS خصوصی MCP ( mcp. . ) متصل به VPC
  • ماژول منطقه DNS عمومی (مجوزهای DNS مدیریت گواهینامه) + گواهی منطقه‌ای تحت مدیریت گوگل
  • منطقه DNS رابط PSC (یتیم زمانی که هیچ نام میزبان خصوصی برای حل و فصل وجود ندارد، بنابراین روی پرچم اصلی نیز قفل شده است)
  • جفت‌سازی DNS توسط Agent Gateway برای mcp. . (به صورت خودکار اضافه می‌شود)

۸. نقاط پایانی رجیستری Agent را بررسی کنید

رجیستری نماینده (Agent Registry) یک کاتالوگ از خدمات مربوط به هر پروژه (APIهای گوگل و سرورهای MCP خودتان) است که یک نماینده در زمان اجرا آن را کشف می‌کند. نماینده وام مسکن آن را در هنگام راه‌اندازی می‌خواند و ابزارها را به صورت پویا متصل می‌کند - هیچ URL MCP در کد نماینده یا دستور استقرار آن گنجانده نشده است.

نقاط پایانی

آنچه Terraform از طرف شما اجرا کرد - برای هر API گوگل در agent_registry_google_apis ، پنج نوع (جهانی، mTLS جهانی، منطقه‌ای، mTLS منطقه‌ای، REP منطقه‌ای) را ثبت کرد. به عنوان مثال، برای aiplatform : 

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

سرورهای MCP

Terraform همچنین 3 سرور MCP را برای شما ثبت می‌کند، برای ثبت سایر سرورهای MCP می‌توانید مراحل موجود در مستندات را دنبال کنید. 

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

نقاط پایانی و سرورهای MCP ثبت شده را تأیید کنید. 

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

منبع: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl .

۹. پیکربندی Agent Gateway را بررسی کنید

دروازه عامل (Agent Gateway) یک صفحه مدیریتی تحت مدیریت گوگل بین Agent Runtime و ابزارهای شما است. در حالت AGENT_TO_ANYWHERE این دروازه به رجیستری عامل پروژه متصل می‌شود و از طریق رابط PSC متعلق به مشتری خارج می‌شود تا بتواند به سرورهای MCP خصوصی در VPC شما دسترسی پیدا کند.

اگر این دروازه را به صورت دستی وارد می‌کردید، YAML به این شکل می‌شد: 

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

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

تأیید کنید که دروازه Terraform ایجاد شده است: 

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

۱۰. بررسی مجوز IAP و Model Armor

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

  • REQUEST_AUTHZ — یک بار در هر درخواست در مرحله هدرها ارزیابی می‌شود. در اینجا برای فراخوانی IAP استفاده می‌شود، که بررسی می‌کند آیا هویت عامل فراخوانی کننده دارای roles/iap.egressor در سرور MCP هدف است یا خیر.
  • CONTENT_AUTHZ — رویدادهای بدنه را برای پاکسازی محتوا به افزونه ارسال می‌کند. در اینجا برای فراخوانی Model Armor استفاده می‌شود که تزریق سریع، جیلبریک، نقض RAI و (اختیاری) PII را از طریق حفاظت از داده‌های حساس (SDP) بررسی می‌کند.

افزونه‌ی درخواست مجوز استفاده از خدمات در ازای دریافت (IAP REQUEST_AUTHZ) 

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

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

آن را با استفاده از پالیسی REQUEST_AUTHZ به Agent Gateway متصل کنید: 

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

افزونه CONTENT_AUTHZ مدل زره

فایل metadata.model_armor_settings این افزونه، شناسه‌های قالب درخواست و پاسخی را که Model Armor برای ارزیابی هر فراخوانی استفاده می‌کند، در خود جای داده است: 

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

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

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

قالب‌های DLP سفارشی

sdpSettings.basicConfig مدل آرمور از یک لیست نوع اطلاعات داخلی استفاده می‌کند. برای کنترل دقیق‌تر (انواع اطلاعات سفارشی، پوشش جزئی، جایگزینی جایگزین، ویرایش بر اساس احتمال)، مدل آرمور را به Cloud DLP خود ارجاع دهید و از طریق sdpSettings.advancedConfig ، الگوها را شناسایی و حذف کنید .

یک الگوی بازرسی ایجاد کنید که شماره‌های تأمین اجتماعی ایالات متحده را با احتمال POSSIBLE یا بالاتر علامت‌گذاری کند: 

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

یک الگوی حذف هویت ایجاد کنید که هر یافته را با توکن نوع اطلاعات آن جایگزین کند (مثلاً [US_SOCIAL_SECURITY_NUMBER] ): 

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

سپس پیکربندی پاسخ یک الگوی Model Armor را از طریق sdpSettings.advancedConfig به آن جفت ارسال کنید (این جایی است که ماژول model_armor در Terraform در صورت اتصال، advanced_config تنظیم می‌کند): 

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

IAM خروجی IAP (فقط برای هر سرور MCP)

Terraform یک اتصال roles/iap.egressor در سطح پروژه روی رجیستری ضمنی عامل IAP ایجاد نمی‌کند . اتصال IAP REQUEST_AUTHZ در واقع به ازای هر MCP-server و هر Reasoning-engine ارزیابی می‌شود و پس از استقرار عامل و دانستن شناسه عامل اعطا می‌شود. مرحله "اعطای مجوز خروج عامل به ازای هر MCP-server" scripts/grant_agent_mcp_egress.sh را برای آن اجرا می‌کند.

۱۱. سرورهای MCP را روی Cloud Run بسازید و مستقر کنید

فایل‌های cloudrun/*.yaml.tmpl و skaffold.yaml.tmpl به ${PROJECT_ID} ، ${REGION} و ${MCP_INGRESS} (حاشیه‌نویسی ورودی Cloud Run) ارجاع می‌دهند. MCP_INGRESS از خروجی Terraform منبع‌یابی کنید تا مانیفست‌های رندر شده با enable_cloud_run_private_networking همگام بمانند، سپس با envsubst رندر کنید:

پیکربندی ورودی Cloud Run خود را صادر کنید.

  • all
  • internal-and-cloud-load-balancing (هنگام استفاده از رویکرد شبکه خصوصی) 
export MCP_INGRESS=all

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

هر سرویس Cloud Run به عنوان یک SA زمان اجرای هر سرویس که Terraform ایجاد کرده است، اجرا می‌شود (مثلاً mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com ). برای استقرار به عنوان آن SAها، به roles/iam.serviceAccountUser روی خودتان نیاز دارید: 

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

ساخت با ابر ساخت و استقرار با Skaffold: 

skaffold run

Skaffold سه تصویر ( legacy-dms ، corporate-email ، income-verification-api ) را در مخزن Artifact Registry شما ایجاد می‌کند و هر سرویس Cloud Run را به‌روزرسانی می‌کند تا به خلاصه جدید اشاره کند.

تأیید کنید: 

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

شما باید هر سه سرویس را با وضعیت ACTIVE ) ببینید.

۱۲. مشاور وام مسکن را به Agent Runtime منتقل کنید

بخش‌های مربوط به agent را نصب و پیاده‌سازی کنید: 

cd src/mortgage-agent
uv sync

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

وقتی اسکریپت کامل شد، فایل چاپ شده reasoningEngines/ را کپی کنید. reasoningEngines/ به درون پوسته‌ات: 

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

۱۳. به عامل، به ازای هر سرور MCP، مجوز خروج اعطا کنید

افزونه‌ی IAP REQUEST_AUTHZ با بررسی roles/iap.egressor عامل روی سرور MCP یا نقطه‌ی پایانی خاصی که آن را فراخوانی می‌کند، هر فراخوانی ابزار را مجاز می‌کند. به بخش «ایجاد یک سیاست خروج عامل به سرور MCP» مراجعه کنید.

اسکریپت ( scripts/grant_agent_mcp_egress.sh ) سرورهای MCP را در رجیستری Agent در مسیر projects/${PROJECT_ID}/locations/${REGION} فهرست می‌کند و یک اتصال roles/iap.egressor برای agent principal را در سیاست IAM هر سرور ادغام می‌کند (که منعکس‌کننده‌ی معنای gcloud add-iam-policy-binding ).

مورد استفاده ۱ - اعطای بدون قید و شرط محدود به سرورهای خاص MCP 

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

مورد استفاده ۲ - اعطای مشروط (CEL) محدود به یک سرور MCP خاص

برای محدود کردن عامل به زیرمجموعه‌ای از ابزارها در یک سرور MCP واحد، یک شرط IAM ضمیمه کنید. دروازه عامل، ویژگی‌های هر ابزار را که IAP REQUEST_AUTHZ در اختیار CEL قرار می‌دهد، منتشر می‌کند، از جمله:

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

محدود کردن عامل به ابزارهای فقط خواندنی فقط در corporate-email : 

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

پس از اجرا، ابزارهایی را روی corporate-email بنویسید که خطای 403 PermissionDenied from IAP REQUEST_AUTHZ را برمی‌گرداند؛ ابزارهای فقط خواندنی به کار خود ادامه می‌دهند.

تأیید صحت اتصالات

به برگه «سیاست‌ها» بروید تا فهرستی از سیاست‌های ایجاد شده علیه Endpointها و سرورهای Mcp را مشاهده کنید.

موارد استفاده اضافی:

اعطای بدون قید و شرط به هر سرور MCP، محدود به یک عامل

این دستور را بعد از هر بار استقرار مجدد عامل اجرا کنید. بدون فیلتر و بدون شرط، عامل نامگذاری شده در هر سرور MCP در رجیستری، roles/iap.egressor را دریافت می‌کند: 

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

۱۴. تست عامل در کنسول پلتفرم عامل

کنسول Agent Platform با یک Playground ارائه می‌شود که به شما امکان می‌دهد مستقیماً با Agent مستقر شده چت کنید. این سریع‌ترین راه برای تست دودی فراخوانی‌های ابزار و بررسی ردپاها قبل از اتصال Agent به Gemini Enterprise است.

  1. صفحه استقرار پلتفرم عامل (Agent Platform Deployments) را در کنسول گوگل کلود (Google Cloud) باز کنید.
  2. اگر نیاز به محدود کردن لیست زمان‌های اجرا دارید، از فیلد فیلتر استفاده کنید، سپس روی زمان اجرای mortgage-agent خود کلیک کنید.
  3. برگه «زمین بازی» را باز کنید.
  4. برای گفتگو با نماینده، یک درخواست تایپ کنید: 
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

این باید پاسخی از ابزار مدیریت اسناد و ابزار تأیید درآمد برگرداند، شماره تأمین اجتماعی نیز باید در این پاسخ حذف شود. ۵. یک پیام پیگیری تایپ کنید: 

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

عامل باید تشخیص دهد که به ابزار send_email دسترسی ندارد و بر اساس آن پاسخ دهد.

از آنجا که این عامل با ابزار OpenTelemetry مستقر شده است، Playground چهار نمای پنل کناری را نشان می‌دهد که می‌توانید هنگام پاسخ عامل بین آنها جابجا شوید:

  • ردیابی — ردپای کامل مکالمه، شامل Agent Gateway، IAP REQUEST_AUTHZ و Model Armor CONTENT_AUTHZ spans
  • رویداد - نموداری از ابزارهای فراخوانی شده و جزئیات رویداد برای نوبت فعلی
  • وضعیت - وضعیت جلسه عامل و ورودی‌ها/خروجی‌های ابزار
  • جلسات - هر جلسه‌ای که در این زمان اجرا شروع کرده‌اید

۱۵. اعمال مجوز IAP

حالا که استقرار را اعتبارسنجی کردیم، می‌توانیم حالت اجرای IAP را به null به‌روزرسانی کنیم تا سیاست‌ها اعمال شوند. terraform.tfvars را باز کنید و حالت را از DRY_RUN به null به‌روزرسانی کنید. 

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

تغییر را اعمال کنید.

terraform apply

به زمین بازی برگردید و دوباره مکالمه را امتحان کنید.

  1. صفحه استقرار پلتفرم عامل (Agent Platform Deployments) را در کنسول گوگل کلود (Google Cloud) باز کنید.
  2. اگر نیاز به محدود کردن لیست زمان‌های اجرا دارید، از فیلد فیلتر استفاده کنید، سپس روی زمان اجرای mortgage-agent خود کلیک کنید.
  3. برگه «زمین بازی» را باز کنید.
  4. برای گفتگو با نماینده، یک درخواست تایپ کنید: 
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

این باید پاسخی از ابزار مدیریت اسناد و ابزار تأیید درآمد برگرداند، شماره تأمین اجتماعی نیز باید در این پاسخ حذف شود. ۵. یک پیام پیگیری تایپ کنید: 

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

اگر همه چیز به درستی تنظیم شده باشد، اپراتور باید پاسخ دهد که به دلیل سیاست مجوز، نمی‌تواند ایمیل ارسال کند.

۱۶. راه‌اندازی و آزمایش Gemini Enterprise

راه‌اندازی شرکت جمینی

راهنمای شروع به کار با Gemini Enterprise را دنبال کنید.

نماینده ADK ما را در Gemini Enterprise ثبت کنید

مراحل ثبت نماینده ما در Gemini Enterprise را دنبال کنید، می‌توانید مراحل را اینجا دنبال کنید.

  1. در کنسول Google Cloud، به صفحه Gemini Enterprise بروید.
  2. برنامه Gemini Enterprise را که نماینده در آن ثبت شده است، انتخاب کنید.
  3. URL نشان داده شده در بخش «برنامه وب Gemini Enterprise شما آماده است» را باز کنید.
  4. برای باز کردن گالری نمایندگان، از منوی سمت چپ، برگه نمایندگان را انتخاب کنید.
  5. گزینه «دستیار مشاور وام مسکن» را انتخاب کنید و چت را شروع کنید.

همان دستورالعمل‌های Agent Runtime Playground را امتحان کنید:

درخواست اولیه: 

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

پیگیری سریع: 

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

اگر به بخش استقرار عامل (Agent Deployment) در کنسول برگردید، استقرار عامل ما را انتخاب کنید و به تب ردیابی‌ها (traces ) بروید، اکنون عامل دستیار جمینی (Gemini Assistant) را در محدوده‌ای مشاهده خواهید کرد که تماس از جمینی انترپرایز (Gemini Enterprise) آغاز شده است.

۱۷. عیب‌یابی و رفع مشکلات رایج

  • terraform apply در Agent Gateway با عبارت "منبع در حال ایجاد است و بنابراین نمی‌توان آن را به‌روزرسانی کرد" با شکست مواجه می‌شود - پروژه مستاجر Gateway حدود 30 ثانیه طول می‌کشد تا قبل از اینکه سیاست‌های authz بتوانند پیوست شوند، مستقر شود. time_sleep.wait_for_gateway ماژول این مشکل را مدیریت می‌کند؛ فقط terraform apply دوباره اجرا کنید.
  • عامل گزارش می‌دهد که «هیچ سرور MCP یافت نشد» یا فقط با ابزارهای کمکی بوت می‌شود — enable_agent_registry_endpoints = true در terraform.tfvars تأیید کنید، سپس:
    gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION}
    شما باید سه ورودی (یکی برای هر سرویس Cloud Run MCP) ببینید. اگر لیست خالی است، بررسی کنید که سرویس‌های MCP از داخل VPC قابل دسترسی باشند و Agent Gateway رجیستری را پر کرده باشد (این کار را با تنبلی در اولین لیست ابزار پروکسی انجام می‌دهد).
  • فراخوانی‌های ابزار، خطای ۴۰۳ PermissionDenied را برمی‌گردانند — scripts/grant_agent_mcp_egress.sh را دوباره اجرا کنید. شایع‌ترین علت، فراموش کردن اعطای مجدد مجوز پس از استقرار مجدد عامل است (the reasoningEngines/ هر بار که مستقر می‌شوید، تغییر می‌کند).
  • skaffold run با خطای "permission denied on service account" مواجه می‌شود — شما roles/iam.serviceAccountUser را از دست داده‌اید. self-grant مرحله قبل را دوباره اجرا کنید.
  • خطاهای DNS peering از Agent Gateway به MCP LB — بررسی کنید که agent_gateway_dns_peering_config.target_network دقیقاً با projects/${PROJECT_ID}/global/networks/${VPC_NAME} مطابقت داشته باشد، و اینکه هر ورودی domains با یک نقطه انتهایی به پایان برسد.
  • terraform plan مدام می‌خواهد تگ‌های تصویر Cloud Run را به‌روزرسانی کند - این اتفاق نباید به دلیل قانون lifecycle { ignore_changes } رخ دهد. اگر این اتفاق افتاد، تأیید کنید که mcp_services[*].image در terraform.tfvars پس از skaffold run ویرایش نکرده‌اید.

۱۸. تمیز کردن

موتور استدلال توسط Terraform مدیریت نمی‌شود (SDK مربوط به ADK آن را ایجاد می‌کند). آن را به صورت دستی حذف کنید: 

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

هر چیزی که Terraform ساخته را خراب کنید: 

cd terraform
terraform destroy
cd ..

اگر منطقه DNS عمومی را فقط برای این codelab ایجاد کرده‌اید: 

gcloud dns managed-zones delete agw-example-com

در نهایت، سطل وضعیت Terraform را حذف کنید: 

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

۱۹. تبریک

تبریک! شما با موفقیت مدیریت جامع عامل را برای یک عامل ADK چند ابزاری با استفاده از Agent Gateway پیاده‌سازی کرده‌اید. Agent Gateway با ایفای نقش به عنوان صفحه کنترل شبکه متمرکز، به شما این امکان را می‌دهد که یک مسیر خروجی امن به ابزارهای خصوصی ایجاد کنید، سیاست‌های IAM مبتنی بر هویت دقیق را از طریق Identity-Aware Proxy اجرا کنید و تعاملات محتوا را با استفاده از گاردریل‌های یکپارچه Model Armor پاکسازی کنید.

آنچه آموخته‌اید

  • نحوه استقرار و پیکربندی Agent Gateway به عنوان لایه مدیریت مرکزی برای ترافیک خروجی Agent-to-Anywhere.
  • نحوه ادغام رجیستری عامل برای کشف ابزار زمان اجرا به صورت پویا و کنترل‌شده.
  • نحوه نوشتن و اجرای سیاست‌های IAM مبتنی بر ابزار و شرایط برای کنترل دقیق مسیرهای اجرای عامل.
  • نحوه استفاده از افزونه‌های سرویس Agent Gateway برای اعمال سیاست‌های Model Armor، که به طور خودکار ترافیک حساس Agent را رهگیری و ویرایش می‌کند.

اسناد مرجع