ایمن‌سازی پیاده‌سازی‌های سازمانی عامل‌گرای بین‌ابری

۱. مقدمه

در این codelab، بااستفاده از Agent Development Kit (ADK)،‏ Agent Engine، و Google Kubernetes Engine، استقرار تک‌عاملی / چندابزاری را به‌طور ایمن مستقر خواهید کرد. یاد خواهید گرفت که چگونه یک عامل هوشواره‌ای که توسط کاربر در Gemini Enterprise راه‌اندازی شده است، به‌طور ایمن در Google Cloud پیمایش می‌کند و با تکیه بر GKE Gateway با Service Extensions، داده‌های حساس را درحین انتقال از پاسخ‌های ابزار MCP حذف می‌کند.

آنچه می‌آموزید

  • مستقر کردن عامل دستیار رهن ADK در Agent Engine با ابزار دقیق OpenTelemetry
  • مستقر کردن سرورهای MCP پس‌بخش در Google Kubernetes Engine‏ (GKE) پشت «دروازه» داخلی
  • متصل کردن Agent Engine به VPC پروژه بااستفاده از میانای PSC و همتای ساناد
  • نمایان کردن میاناهای برنامه‌سازی کاربردی REST به‌عنوان ابزارهای MCP بااستفاده از Apigee MCP Discovery Proxy
  • پیکربندی کردن GKE Gateway برای خروجی عامل تحت نظارت با افزونه‌های سرویس برای ویرایش DLP و صدور مجوز MCP
  • اعمال کردن حفاظ‌های هوش مصنوعی با Model Armor برای غربال کردن پیام‌واره و پاسخ

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

  • مرورگر وب مانند Chrome
  • پروژه Google Cloud با صورت‌حساب فعال‌شده
  • آشنایی اولیه با Terraform،‏ Kubernetes، و Python

این codelab برای توسعه‌دهندگان و متخصصان امنیتی است که می‌خواهند گردش‌های کار عامل‌گرا را در محیط‌های سازمانی مستقر و ایمن کنند.

۲. قبل‌از شروع

پروژه Google Cloud ایجاد کنید و میاناهای برنامه‌سازی کاربردی لازم را فعال کنید.

  1. در «کنسول Google Cloud»، در صفحه انتخابگر پروژه، پروژه Google Cloud را انتخاب یا ایجاد کنید.
  2. مطمئن شوید که صورت‌حساب برای پروژه Cloud شما فعال است. با نحوه بررسی اینکه صدور صورت‌حساب در پروژه فعال است یا نه آشنا شوید.

نقش‌های IAM الزامی

این codelab فرض می‌کند که شما نقش مالک پروژه را برای پروژه Google Cloud خود دارید.

فعال کردن میاناهای برنامه‌سازی کاربردی

  1. در کنسول Google Cloud، روی فعال کردن Cloud Shell کلیک کنید: اگر قبلاً از Cloud Shell استفاده نکرده‌اید، پانلی ظاهر می‌شود که به شما امکان می‌دهد Cloud Shell را در محیطی مطمئن با یا بدون تقویت شروع کنید. اگر از شما خواسته شد Cloud Shell را مجاز کنید، روی مجاز کردن کلیک کنید.
  2. در Cloud Shell، همه میاناهای برنامه‌سازی کاربردی لازم را فعال کنید:
    gcloud services enable \
    compute.googleapis.com \
    container.googleapis.com \
    dns.googleapis.com \
    certificatemanager.googleapis.com \
    dlp.googleapis.com \
    aiplatform.googleapis.com \
    discoveryengine.googleapis.com \
    apigee.googleapis.com
    

نصب وابستگی‌ها

در Cloud Shell، مطمئن شوید ابزارهای لازم را نصب کرده‌اید. Terraform،‏ kubectl، و Go معمولاً ازپیش نصب شده‌اند. باید uv (مدیر بسته Python) و Skaffold را نصب کنید:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

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

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

متغیرهای محیطی زیر را که در سراسر این codelab استفاده می‌شوند تنظیم کنید:

export PROJECT_ID=$(gcloud config get project)
export REGION=us-central1
export LOCATION=${REGION}

ایجاد منطقه ساناد عمومی

این codelab به یک منطقه ساناد عمومی نیاز دارد که قبل‌از اعمال پیکربندی Terraform در پروژه شما وجود داشته باشد. این منطقه برای واگذاری کارگزار نام لازم است تا راه‌اندازی بتواند ایجاد گزارش‌های لازم برای مدیر گواهی را خودکار کند.

فرمان زیر را در Cloud Shell اجرا کنید تا منطقه ایجاد شود:

gcloud dns managed-zones create "inference-gateway-zone" \
    --dns-name="gateway.example.com." \
    --description="Public zone for Inference Gateway" \
    --visibility="public" \
    --project="${PROJECT_ID}"

۳. همسانه‌سازی مخزن GitHub

  1. در پایانه ماشین محلی‌تان، مخزن cloud-networking-solutions را کلون کنید:
    git clone https://github.com/googleCloudPlatform/cloud-networking-solutions.git
    
  2. به دایرکتوری مخزن بارگیری‌شده بروید:
    cd cloud-networking-solutions/demos/service-extensions-gke-gateway
    

۴. پیاده‌سازی کردن زیرساخت با Terraform

از Terraform برای تأمین شبکه بنیادی، خوشه GKE، و پیکربندی‌های هویت موردنیاز استفاده خواهید کرد.

  1. به دایرکتوری terraform در مخزن همسانه‌سازی‌شده بروید:
    cd terraform
    
  2. پیکربندی کردن Terraform backend. فایل backend.conf برای پیکربندی جزئی پس‌نما ایجاد کنید. را با نام باکت یکتا درسطح جهانی جایگزین کنید.
    cat <<EOF > backend.conf
    bucket = "<YOUR_TERRAFORM_STATE_BUCKET>"
    prefix = "terraform"
    EOF
    
  1. فایل متغیر نمونه را کپی کنید و آن را با مقادیر پروژه خود به‌روز کنید:
    cp example.tfvars terraform.tfvars
    
  2. terraform.tfvars را ویرایش کنید و مقادیر جای‌بان را جایگزین کنید.موارد زیر را جایگزین کنید:
    • project_id: شناسه پروژه Google Cloud شما.
    • organization_id: شناسه عددی سازمان GCP شما.
    • dns_zone_domain: دامنه‌ای که کنترل می‌کنید (مثلاً demo.example.com.). باید با نقطه تمام شود.
    مطمئن شوید پرچم‌های ویژگی زیر فعال باشند (این پرچم‌ها در فایل نمونه ازپیش پیکربندی شده‌اند):
    • enable_certificate_manager = true
    • enable_model_armor = true
    • enable_agent_engine = true
    • enable_psc_interface = true
  3. پیکربندی Terraform را مقداردهی اولیه و اعمال کنید:
    terraform init -backend-config=backend.conf
    terraform plan -out=tfplan
    terraform apply "tfplan"
    

۵. مستقر کردن نمونه حجم‌های کاری با Skaffold

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

  1. به خوشه GKE ایجادشده توسط Terraform متصل شوید:
    gcloud container clusters get-credentials gateway-cluster \
        --region=${REGION} \
        --project=${PROJECT_ID}
    
  2. به ریشه پروژه برگردید و الگوهای مانیفست Kubernetes را پیکربندی کنید. پیکربندی نمونه را کپی کنید و شناسه پروژه و دامنه پایه را تنظیم کنید:BASE_DOMAIN را طوری تنظیم کنید که با محیط شما مطابقت داشته باشد. ‫BASE_DOMAIN باید با متغیر Terraform dns_zone_domain شما مطابقت داشته باشد (بدون نقطه پایانی).
    export BASE_DOMAIN=example.com
    
  3. تولید مانیفست‌های Kubernetes و skaffold.yaml از الگوها:
    bash k8s/generate.sh
    envsubst '${PROJECT_ID}' < skaffold.yaml.tmpl > skaffold.yaml
    
  4. همه سرویس‌های زیرینه را مستقر کنید:
    skaffold run -m legacy-dms,income-verification-api,corporate-email,dlp-ext-proc
    
  5. پیکربندی Gateway و HTTPRoute را مستقر کنید:
    kubectl apply -k k8s/gateway-internal/
    

‫۶. اعمال کردن حفاظ‌های هوش مصنوعی با Model Armor

می‌توانید تصمیمات مربوط به امنیت محتوا، مانند حذف پیام‌واره‌های مضر یا جلوگیری از نشت داده‌ها را به Model Armor واگذار کنید.

پیش‌نیازها: اعطای نقش‌های IAM

باید نقش‌های لازم را به حساب سرویس GKE Gateway اعطا کنید. حساب سرویس از این قالب پیروی می‌کند: service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com.

فرمان‌های زیر را اجرا کنید تا اجازه‌های لازم را اعطا کنید:

export GATEWAY_PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# Grant roles in the Gateway project
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser

gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer

# Grant role in the project containing Model Armor templates
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.user

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

افزونه‌ای را تعریف کنید که به سرویس Model Armor در منطقه شما اشاره می‌کند. این پیکربندی را به‌عنوان ma-content-authz-extension.yaml ذخیره کنید.

شناسه الگوی Model Armor ایجادشده توسط Terraform را صادر کنید.

export MA_TEMPLATE_ID=$(cd terraform && terraform output -raw model_armor_template_id)
cat >ma-content-authz-extension.yaml <<EOF
name: ma-ext
service: modelarmor.$LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
  {
  "response_template_id": "projects/${PROJECT_ID}/locations/$LOCATION/templates/${MA_TEMPLATE_ID}",
  "request_template_id": "projects/${PROJECT_ID}/locations/$LOCATION/templates/${MA_TEMPLATE_ID}"
  }
  ]'
failOpen: true
EOF

gcloud beta service-extensions authz-extensions import ma-ext \
    --source=ma-content-authz-extension.yaml \
    --location=$LOCATION

ایجاد خط‌مشی مجوزدهی Model Armor

خط‌مشی‌ای ایجاد کنید که افزونه Model Armor را با Agent Gateway شما مرتبط کند. این پیکربندی را به‌عنوان ma-content-authz-policy.yaml ذخیره کنید.

cat >ma-content-authz-policy.yaml <<EOF
name: ma-content-authz-policy
target:
  resources:
  -   "projects/$PROJECT_ID/locations/$LOCATION/gateways/mortgage-gateway"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    -   "projects/$PROJECT_ID/locations/$LOCATION/authzExtensions/ma-ext"
EOF

gcloud network-security authz-policies import ma-content-authz-policy \
    --source=ma-content-authz-policy.yaml \
    --location=$LOCATION

‫۷. پیکربندی Gemini Enterprise

فعال کردن مشاهده‌پذیری

عامل رهن با ابزار OpenTelemetry و متغیرهای محیطی تله‌متری زیر که به‌طور پیش‌فرض فعال هستند مستقر می‌شود:

  • GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
  • OTEL_TRACES_SAMPLER=parentbased_traceidratio

برای جزئیات مربوط به پیکربندی ردیابی‌ها و بازه‌ها در Gemini Enterprise، به مدیریت تنظیمات مشاهده‌پذیری مراجعه کنید.

فعال کردن Model Armor در Gemini Enterprise

فیلتر کردن Model Armor را روی دستیار Gemini Enterprise اعمال کنید تا هم پیام‌واره‌های کاربر و هم پاسخ‌های مدل را غربال کند. برنامه‌های سراسری Gemini Enterprise به الگوی Model Armor در چندمنطقه us نیاز دارند، بنابراین Terraform الگوی جداگانه‌ای برای این منظور مستقر می‌کند.

نام الگو را از خروجی Terraform بازیابی کنید:

cd terraform
export GE_MA_TEMPLATE_NAME=$(terraform output -raw model_armor_gemini_enterprise_template_name)

شناسه برنامه نمونه Gemini Enterprise خود را واکشی کنید:

  1. در کنسول Google Cloud، به صفحه Gemini Enterprise بروید.
  2. از منو پیمایش، روی «برنامه‌ها» کلیک کنید.
  3. شناسه «نمونه Gemini Enterprise» را کپی کنید

شناسه را به‌عنوان متغیر محیطی صادر کنید.

export APP_ID=<PASTE_APP_ID>

برای فعال کردن Model Armor، دستیار را وصله کنید:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_ID}" \
  "https://global-discoveryengine.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/collections/default_collection/engines/${APP_ID}/assistants/default_assistant?update_mask=customerPolicy" \
  -d '{
    "customerPolicy": {
      "modelArmorConfig": {
        "userPromptTemplate": "'"$GE_MA_TEMPLATE_NAME"'",
        "responseTemplate": "'"$GE_MA_TEMPLATE_NAME"'",
        "failureMode": "FAIL_OPEN"
      }
    }
  }'

failureMode را روی FAIL_OPEN تنظیم کنید تا وقتی Model Armor دردسترس نیست درخواست‌ها مجاز شوند، یا روی FAIL_CLOSED تنظیم کنید تا مسدود شوند.

‫۸. استقرار عامل و افزودن عامل در Gemini Enterprise

دریافت جزئیات مجوز

برای دریافت جزئیات مجوز، این مراحل را دنبال کنید.

  1. در کنسول Google Cloud، در صفحه «میاناهای برنامه‌سازی کاربردی و سرویس‌ها»، به صفحه «اطلاعات اعتباری» بروید.
  2. به اطلاعات کاربری بروید
  3. روی «ایجاد اطلاعات کاربری» کلیک کنید و «شناسه کارخواه OAuth» را انتخاب کنید.
  4. در «نوع برنامه»، «برنامه وب» را انتخاب کنید.
  5. در بخش «شناسه‌های URI هدایت مجاز»، شناسه‌های URI زیر را اضافه کنید:
  • https://vertexaisearch.cloud.google.com/oauth-redirect
  • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
  1. روی «ایجاد کردن» کلیک کنید.
  2. «شناسه کارخواه» و «رمز کارخواه» را برای استقرار صادر کنید.
export OAUTH_CLIENT_ID=<Client ID>
export OAUTH_CLIENT_SECRET=<Client Secret>

استقرار عامل وام مسکن

اسکریپت src/mortgage-agent/deploy_agent.py عامل ADK را در Agent Engine مستقر می‌کند و به‌طور اختیاری آن را در Gemini Enterprise ثبت می‌کند. برای اطلاعات بیشتر درباره جریان ثبت Gemini Enterprise، به ثبت و مدیریت عامل A2A مراجعه کنید.

متغیرها را از استقرار Terraform صادر کنید.

export VPC_NAME=$(cd terraform && terraform output -raw vpc_name)
export PSC_ATTACHMENT=$(cd terraform && terraform output -raw psc_interface_network_attachment_id)
export DNS_PEERING_DOMAIN=$(cd terraform && terraform output -raw psc_interface_dns_peering_domain)

نصب وابستگی‌ها و استقرار:

cd src/mortgage-agent
uv sync

«عامل» را در Vertex Agent Engine مستقر کنید و در Gemini Enterprise ثبت کنید:

uv run python deploy_agent.py \
    --project=${PROJECT_ID} \
    --dms-mcp-url=https://dms.${DNS_PEERING_DOMAIN%%.}/mcp \
    --income-verification-url=https://income-verification.${DNS_PEERING_DOMAIN%%.} \
    --email-mcp-url=https://email.${DNS_PEERING_DOMAIN%%.}/mcp \
    --network-attachment=projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/${PSC_ATTACHMENT} \
    --dns-peering-domain=${DNS_PEERING_DOMAIN} \
    --dns-peering-target-project=${PROJECT_ID} \
    --dns-peering-target-network=${VPC_NAME} \
    --enable-agent-identity \
    --ge-deploy \
    --app-id=${APP_ID} \
    --oauth-client-id=${OAUTH_CLIENT_ID} \
    --agent-name=mortgage-agent

پرچم‌گذاری مرجع

پرچم

پیش‌فرض

شرح

--project

$PROJECT_ID

شناسه پروژه GCP

--dms-mcp-url

(الزامی)

نشانی وب سرور MCP DMS

--income-verification-url

(الزامی)

نشانی وب پایه Income Verification API؛ /mcp به‌طور خودکار اضافه می‌شود

--email-mcp-url

(الزامی)

نشانی وب سرور MCP ایمیل

--region

$REGION

منطقه GCP

--staging-bucket

gs://PROJECT-staging

باکت GCS برای آماده‌سازی

--display-name

Mortgage Assistant Agent

نام نمایشی برای نماینده مستقرشده

--update

(اختیاری)

به‌روزرسانی عامل موجود در محل (نام کامل منبع را ارسال کنید)

--network-attachment

(اختیاری)

پیوست شبکه برای میانای PSC (مسیر کامل یا نام)

--dns-peering-domain

(اختیاری)

دامنه ساناد برای همتاسازی ساناد PSC-I (باید با نقطه تمام شود)

--dns-peering-target-project

(اختیاری)

پروژه میزبان شبکه VPC هدف برای همتاسازی ساناد

--dns-peering-target-network

(اختیاری)

نام شبکه VPC برای همتاسازی ساناد

--enable-agent-identity

false

فعال کردن اطلاعات اعتباری با کمترین امتیاز برای هر عامل

--ge-deploy

false

ثبت عامل در Gemini Enterprise پس‌از استقرار

--app-id

(اختیاری)

شناسه موتور Gemini Enterprise (با --ge-deploy الزامی است)

--oauth-client-id

$OAUTH_CLIENT_ID

شناسه کارخواه OAuth2 (با --ge-deploy الزامی است)

--oauth-client-secret

$OAUTH_CLIENT_SECRET

رمز کارخواه OAuth2 (با --ge-deploy الزامی است)

--model

gemini-3.1-flash-lite-preview

نام مدل Gemini برای عامل

--agent-name

mortgage-agent

مجوز Gemini Enterprise و نام عامل

--ge-deploy-only

(اختیاری)

ثبت موتور استدلال موجود در Gemini Enterprise بدون بازاستقرار (نام کامل منبع را ارسال کنید)

افزودن کاربران دارای اجازه

برای افزودن کاربران دارای اجازه به عامل ADK بااستفاده از کنسول Google Cloud، به افزودن یا اصلاح کاربران و اجازه‌های آن‌ها مراجعه کنید.

‫۹. امتحان کردن «عامل»

اکنون که عامل، GKE Gateway، و همه سرویس‌های پس‌بک را مستقر و پیکربندی کرده‌اید، جریان سرتاسری را آزمایش کنید تا مطمئن شوید خط‌مشی‌های امنیتی طبق انتظار کار می‌کنند. با «mortgage-agent» در میانای Gemini Enterprise تعامل خواهید داشت.

دسترسی به «عامل»

  1. به صفحه Gemini Enterprise در «کنسول Google Cloud» بروید.
  2. «برنامه Gemini Enterprise» را که قبلاً پیکربندی کرده‌اید و «mortgage-agent» در آن ثبت شده است انتخاب کنید.
  3. در «زبانه نمای کلی»، به نشانی وب نشان‌داده‌شده در بخش «برنامه تحت وب Gemini Enterprise شما آماده است» بروید.
  4. «برگه نماینده» را از منوِ سمت راست با نام گالری نماینده انتخاب کنید
  5. اکنون باید بتوانید با «نماینده دستیار رهن» گپ بزنید.

چارچوب تست ۱: «مسیر شاد» - خلاصه کردن داده‌ها با ویرایش اطلاعات شناساننده شخصی

این آزمایش تأیید می‌کند که نماینده می‌تواند ازطریق «دروازه نماینده» به سیستم‌های پس‌بک دسترسی داشته باشد و خط‌مشی‌های «جلوگیری از لو رفتن داده‌ها» (DLP) برای ویرایش اطلاعات حساس اجرا می‌شوند.

  1. پیام‌واره زیر را به «نماینده دستیار وام مسکن» ارسال کنید:
    I'm reviewing the Sterling family's 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?
    
  2. آنچه در پشت صحنه اتفاق می‌افتد:
    • نماینده در Gemini Enterprise درخواست‌ها را برای ابزارهای لازم (مثلاً «سیستم مدیریت سند» (DMS) برای اظهارنامه‌های مالیاتی، «میانای برنامه‌سازی کاربردی تأیید درآمد») فرمول‌بندی می‌کند.
    • Model Armor محموله‌های درخواست و پاسخ را ازنظر تهدیدات بررسی می‌کند.
    • «خط‌مشی مجوز مبتنی بر محتوا» که پیکربندی کرده‌اید، افزونه سفارشی «جلوگیری از گم شدن داده‌ها» (dlp-content-authz-ext) را راه‌اندازی می‌کند. این افزونه داده‌های واکشی‌شده از سیستم‌های پس‌بخش را بازرسی می‌کند.
    • سرویس «جلوگیری از گم شدن داده‌ها» هرگونه «اطلاعات شناساننده شخص» (PII)، مانند شماره تأمین اجتماعی (SSN)، را از داده‌های اظهارنامه مالیاتی قبل‌از رسیدن به نماینده محو می‌کند.
  3. نتیجه موردانتظار:نماینده خلاصه‌ای از اظهارنامه‌های مالیاتی و وضعیت درستی‌سنجی درآمد را برمی‌گرداند. خلاصه ارائه‌شده توسط نماینده را به‌دقت بررسی کنید. باید مشاهده کنید که اطلاعات حساس، مانند شناسه‌های مؤدی (SSN)، با جای‌بان‌ها (مثلاً [REDACTED]) جایگزین شده‌اند. این امر اجرای خط‌مشی «جلوگیری از اتلاف داده» را ازطریق درگاه تأیید می‌کند.

مشاهده‌پذیری و حسابرسی

درطول این آزمایش‌ها، «پلاتفرم نماینده» و سرویس‌های مرتبط، دورسنجی را جمع‌آوری می‌کنند:

  • Cloud Logging: گزارش‌های دقیق از GKE Gateway، بارهای کاری GKE، و سرویس‌های دیگر، یک دنباله ممیزی از درخواست‌ها، ارزیابی‌های خط‌مشی، و نتایج ارائه می‌دهند.
  • Cloud Trace: ابزارگری OpenTelemetry پیکربندی‌شده در عامل و سرویس‌های زیرینه به شما امکان می‌دهد کل جریان تماس را از Gemini Enterprise ازطریق GKE Gateway به ابزارهای زیرینه تجسم کنید. این کار برای اشکال‌زدایی و درک چرخه حیات درخواست بسیار ارزشمند است.

مشاهده «ردگیری‌ها» برای جلسه‌هایتان:

  1. در کنسول Google Cloud، به صفحه Vertex AI Agent Engine بروید.
  2. به Agent Engine بروید. نمونه‌های Agent Engine که بخشی از پروژه انتخاب‌شده هستند در فهرست نشان داده می‌شوند. می‌توانید از فیلد «فیلتر» برای فیلتر کردن فهرست براساس ستون مشخص‌شده‌تان استفاده کنید.
  3. روی نام نمونه Agent Engine خود کلیک کنید.
  4. روی برگه «ردگیری‌ها» کلیک کنید.
  5. می‌توانید «نمای جلسه» یا «نمای بازه» را انتخاب کنید.
  6. روی یک جلسه یا بازه کلیک کنید تا جزئیات ردگیری را بررسی کنید، ازجمله نمودار غیرچرخه‌ای جهت‌دار (DAG) بازه‌ها، ورودی‌ها و خروجی‌ها، و ویژگی‌های فراداده.

‫۱۰. اختیاری: تراتبدیل REST API به MCP با Apigee

درحالی‌که سرویس درستی‌سنجی درآمد ما به‌طور بومی از «پروتکل بافتار مدل» پشتیبانی می‌کند، بسیاری از سیستم‌های قدیمی سازمانی فقط میاناهای برنامه‌سازی کاربردی RESTful ارائه می‌دهند. در این مرحله اختیاری، از Apigee MCP Discovery Proxy برای تراتبدیل نقطه پایان REST سرویس درستی‌سنجی درآمد به ابزار MCP استفاده خواهید کرد. این کار به شما امکان می‌دهد تا حاکمیت پیشرفته، محدودیت نرخ، و خط‌مشی‌های امنیتی Apigee را در ابزارهای قدیمی‌تان اعمال کنید.

برای اطلاعات بیشتر، نمای کلی Apigee MCP را ببینید.

پیش‌نیازها

قبل‌از ادامه دادن، مطمئن شوید که Apigee API Hub را تأمین و پیکربندی کرده‌اید. مراحل موجود در سند Provision API Hub را برای راه‌اندازی آن و پیوست کردن نمونه Apigee خود دنبال کنید.

مرحله ۱: ایجاد پیوست سرویس برای Apigee

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

  1. قانون بازارسال «دروازه GKE» داخلی را جستجو کنید:
    export RULE_URI=$(gcloud compute forwarding-rules list \
      --filter="loadBalancingScheme=INTERNAL_MANAGED AND target~targetHttpsProxies" \
      --format="value(selfLink.segment(6), region.basename(), name)" | \
      awk '{print "projects/" $1 "/regions/" $2 "/forwardingRules/" $3}')
    
  2. پیوست سرویس را ایجاد کنید:
    gcloud compute service-attachments create internal-gke-gateway-apigee \
        --region=${REGION} \
        --target-service=$RULE_URI \
        --connection-preference=ACCEPT_AUTOMATIC \
        --nat-subnets=gateway-psc-subnet
    

مرحله ۲: فعال کردن Apigee با Terraform

اکنون، پیکربندی زیرساخت خود را به‌روز کنید تا سازمان و نمونه Apigee را فراهم کنید.

  1. به فهرست راهنمای terraform بروید:
    cd terraform
    
  2. terraform.tfvars را ویرایش کنید و enable_apigee = true را تنظیم کنید.
  3. تغییرات را اعمال کنید:
    terraform apply
    

مرحله ۳: تعریف مشخصات OpenAPI

Apigee از تعاریف استاندارد OpenAPI (OAS) برای کشف و تراتبدیل ابزارها استفاده می‌کند. فایلی با نام income-verification-oas.yaml و محتوای زیر ایجاد کنید:

openapi: 3.0.0
info:
  title: Income Verification API
  description: Verify applicant income through third-party employer records.
  version: 1.0.0
servers:
  -   url: https://income-verification.internal.${DNS_PEERING_DOMAIN%%.}/api
paths:
  /income-verification/verify:
    post:
      summary: Verify applicant income
      operationId: verifyApplicant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
      responses:
        '200':
          description: Successful verification
          content:
            application/json:
              schema:
                type: object

مرحله ۴: استقرار Apigee MCP Discovery Proxy

‫MCP Discovery Proxy یک پراکسی Apigee تخصصی است که به‌عنوان سرور MCP عمل می‌کند.

  1. در میانای کاربر Apigee، به توسعه > پراکسی‌های API بروید.
  2. روی ایجاد جدید کلیک کنید و پراکسی کاوش MCP را انتخاب کنید.
  3. نام پراکسی income-verification-discovery را وارد کنید.
  4. در بخش OpenAPI Spec، فایل income-verification-oas.yaml را که ایجاد کرده‌اید بارگذاری کنید.
  5. گروه محیط را روی گروهی تنظیم کنید که درگاه داخلی‌تان در آن قابل‌دسترسی است.
  6. روی استقرار کلیک کنید.

(اختیاری) افزودن خط‌مشی امنیتی

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

مرحله ۵: تأیید دسترسی به ابزار تراتبدیل‌شده

پس‌از استقرار، Apigee به‌طور خودکار نقطه پایان POST /verify را به ابزار MCP verifyApplicant تراتبدیل می‌کند.

  1. ابزارهای دردسترس ازطریق نقطه پایان Apigee MCP را فهرست کنید:
    curl -X POST https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp \
      -H "Content-Type: application/json" \
      -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
      }'
    
  2. باید ابزار verifyApplicant را در پاسخ ببینید که از مشخصات REST شما تراتبدیل شده است. اکنون می‌توانید این ابزار را ازطریق Apigee فراخوانی کنید و Apigee ترجمه به سرویس REST زیربنایی را انجام می‌دهد و درعین‌حال هرگونه خط‌مشی امنیتی را که پیکربندی کرده‌اید اعمال می‌کند.

مرحله ۶: به‌روزرسانی Mortgage Agent برای استفاده از Apigee

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

  1. نشانی وب Apigee MCP خود را شناسایی کنید: نقطه پایانی شما باید از این الگو پیروی کند: https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp.
  2. دستورگان پیاده‌سازی را دوباره اجرا کنید: از پرچم --update به‌همراه --income-verification-url جدید استفاده کنید. این کار عامل موجود در «موتور عامل» را بدون نیاز به حذف کامل به‌روز می‌کند.
    cd src/mortgage-agent
    
    # Update the agent to route income verification through Apigee
    uv run python deploy_agent.py \
        --project=${PROJECT_ID} \
        --update \
        --agent-name=mortgage-agent \
        --dms-mcp-url=https://dms.${DNS_PEERING_DOMAIN%%.}/mcp \
        --income-verification-url=https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp \
        --email-mcp-url=https://email.${DNS_PEERING_DOMAIN%%.}/mcp \
        --network-attachment=projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/${PSC_ATTACHMENT} \
        --dns-peering-domain=${DNS_PEERING_DOMAIN} \
        --dns-peering-target-project=${PROJECT_ID} \
        --dns-peering-target-network=${VPC_NAME} \
        --ge-deploy \
        --app-id=${APP_ID} \
        --oauth-client-id=${OAUTH_CLIENT_ID}
    
  1. درستی‌سنجی تغییر: به میانای Gemini Enterprise برگردید و از عامل بخواهید درآمد متقاضی را درستی‌سنجی کند.
    "Can you verify the joint income for the Sterlings using the verification service?"
    
    در برگه «اشکال‌زدایی Apigee»، اکنون باید ببینید که درخواست JSON-RPC ورودی از «دروازه GKE» به درخواست REST POST استاندارد به سرویس GKE بااِند شما تبدیل می‌شود.

‫۱۱. مرتب‌سازی

برای جلوگیری از کسر هزینه از حساب Google Cloud شما بابت منابع ایجادشده در این codelab، پس‌از اتمام کار آن‌ها را حذف کنید.

  1. اگر پیوست سرویس به‌صورت دستی ایجاد شده است، آن را حذف کنید:
    gcloud compute service-attachments delete internal-gke-gateway \
        --region=${REGION} --quiet
    
  2. به دایرکتوری terraform بروید و همه منابع را ازبین ببرید:
    cd terraform
    terraform destroy
    
  3. درصورت تمایل، پروژه Google Cloud را به‌طور کامل حذف کنید:
    gcloud projects delete ${PROJECT_ID}
    

‫۱۲. تبریک می‌گوییم

این codelab را تکمیل کردید و یاد گرفتید که چگونه استقرارهای سازمانی عامل‌گرای بین‌ابری را ایمن کنید.

آنچه پوشش دادید

  • مستقر کردن عامل دستیار وام مسکن ADK در Agent Engine با ابزار دقیق OpenTelemetry
  • سرورهای MCP پس‌بخش را در GKE پشت یک «دروازه» داخلی مستقر کرد
  • Agent Engine را بااستفاده از «میانای PSC» و همتای DNS به VPC پروژه متصل کرد
  • GKE Gateway پیکربندی‌شده برای خروج عامل تحت نظارت با ویرایش DLP و مجوز MCP
  • اعمال کردن حفاظ‌های هوش مصنوعی با Model Armor برای غربال کردن پیام‌واره و پاسخ
  • به‌طور اختیاری، REST APIها را بااستفاده از Apigee MCP Discovery Proxy به MCP تراتبدیل کرد

مراحل بعدی