این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ایمن‌سازی استقرارهای سازمانی عامل‌دار بین ابری

۱. مقدمه

در این آزمایشگاه کد، شما یک پیاده‌سازی تک‌عاملی/چندابزاری را به صورت ایمن با استفاده از کیت توسعه عامل (ADK)، موتور عامل و موتور کوبرنتیز گوگل مستقر خواهید کرد. شما یاد خواهید گرفت که چگونه یک عامل هوش مصنوعی که توسط یک کاربر در Gemini Enterprise راه‌اندازی شده است، با تکیه بر GKE Gateway به همراه افزونه‌های سرویس، به طور ایمن در Google Cloud پیمایش می‌کند تا داده‌های حساس را در حین پرواز از پاسخ‌های ابزار MCP ویرایش کند.

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

Deploy an ADK mortgage assistant agent to Agent Engine with OpenTelemetry instrumentation
سرورهای MCP بک‌اند را در موتور گوگل کوبرنتیز (GKE) پشت یک گیت‌وی داخلی مستقر کنید.
اتصال Agent Engine به یک VPC پروژه با استفاده از رابط PSC و DNS peering
نمایش APIهای REST به عنوان ابزارهای MCP با استفاده از Apigee MCP Discovery Proxy
پیکربندی GKE Gateway برای خروج عامل کنترل‌شده با افزونه‌های سرویس برای ویرایش DLP و مجوز MCP
برای غربالگری سریع و واکنشی، از گاردریل‌های هوش مصنوعی با Model Armor استفاده کنید.

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

یک مرورگر وب مانند کروم
یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
آشنایی اولیه با Terraform، Kubernetes و Python

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

۲. قبل از شروع

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

در کنسول گوگل کلود، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر.

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

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

فعال کردن APIها

در کنسول Google Cloud، روی Activate Cloud Shell کلیک کنید: اگر قبلاً از Cloud Shell استفاده نکرده‌اید، پنجره‌ای ظاهر می‌شود که به شما امکان می‌دهد Cloud Shell را در یک محیط قابل اعتماد با یا بدون بوست شروع کنید. اگر از شما خواسته شد Cloud Shell را تأیید کنید، روی Authorize کلیک کنید.

در Cloud Shell، تمام API های مورد نیاز را فعال کنید:

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 (مدیر بسته پایتون) و 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}

ایجاد یک منطقه DNS عمومی

این آزمایشگاه کد، قبل از اعمال پیکربندی Terraform، نیاز به یک منطقه DNS عمومی دارد که از قبل در پروژه شما وجود داشته باشد. این منطقه برای واگذاری نام سرور مورد نیاز است تا تنظیمات بتواند ایجاد رکوردهای مورد نیاز برای Certificate Manager را خودکار کند.

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

۳. کپی کردن یک مخزن گیت‌هاب

در یک ترمینال روی دستگاه محلی خود، مخزن cloud-networking-solutions را کپی کنید:
```
git clone https://github.com/googleCloudPlatform/cloud-networking-solutions.git
```

به دایرکتوری مخزن دانلود شده بروید:

cd cloud-networking-solutions/demos/service-extensions-gke-gateway

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

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

به دایرکتوری terraform در مخزن کلون شده بروید:
```
cd terraform
```
پیکربندی بخش مدیریت Terraform. یک فایل backend.conf برای پیکربندی جزئی بخش مدیریت ایجاد کنید. جایگزین کنید با یک نام سطل منحصر به فرد جهانی.
```
cat <<EOF > backend.conf
bucket = "<YOUR_TERRAFORM_STATE_BUCKET>"
prefix = "terraform"
EOF
```

فایل متغیر مثال را کپی کرده و آن را با مقادیر پروژه خود به‌روزرسانی کنید:
```
cp example.tfvars terraform.tfvars
```
فایل terraform.tfvars را ویرایش کنید و مقادیر جایگزین را جایگزین کنید. مقادیر زیر را جایگزین کنید:
- project_id : شناسه پروژه گوگل کلود شما.
- organization_id : شناسه سازمانی عددی GCP شما.
- dns_zone_domain : دامنه‌ای که شما کنترل می‌کنید (مثلاً demo.example.com. ). باید با نقطه (dot) تمام شود.
مطمئن شوید که feature flag های زیر فعال هستند (آنها از قبل در فایل مثال پیکربندی شده‌اند):
- enable_certificate_manager = true
- enable_model_armor = true
- enable_agent_engine = true
- enable_psc_interface = true

پیکربندی Terraform را مقداردهی اولیه و اعمال کنید:

terraform init -backend-config=backend.conf
terraform plan -out=tfplan
terraform apply "tfplan"

۵. استقرار بارهای کاری نمونه با Skaffold

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

به خوشه GKE ایجاد شده توسط Terraform متصل شوید:

gcloud container clusters get-credentials gateway-cluster \
    --region=${REGION} \
    --project=${PROJECT_ID}

به ریشه پروژه برگردید و قالب‌های مانیفست Kubernetes را پیکربندی کنید. پیکربندی نمونه را کپی کنید و شناسه پروژه و دامنه پایه خود را تنظیم کنید: BASE_DOMAIN را طوری تنظیم کنید که با محیط شما مطابقت داشته باشد. BASE_DOMAIN باید با متغیر dns_zone_domain Terraform شما (بدون نقطه انتهایی) مطابقت داشته باشد.
```
export BASE_DOMAIN=example.com
```
مانیفست‌های Kubernetes و skaffold.yaml را از قالب‌ها تولید کنید:
```
bash k8s/generate.sh
envsubst '${PROJECT_ID}' < skaffold.yaml.tmpl > skaffold.yaml
```

تمام سرویس‌های بک‌اند را پیاده‌سازی کنید:

skaffold run -m legacy-dms,income-verification-api,corporate-email,dlp-ext-proc

پیکربندی 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 در منطقه شما اشاره کند. این پیکربندی را با نام ma-content-authz-extension.yaml ذخیره کنید.

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

فعال کردن زره مدل در Gemini Enterprise

Apply Model Armor filtering to the Gemini Enterprise assistant to screen both user prompts and model responses. Global Gemini Enterprise apps require a Model Armor template in the us multi-region, so Terraform deploys a separate template for this purpose.

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

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

شناسه برنامه (APP ID) نمونه سازمانی Gemini خود را دریافت کنید:

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

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

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"
      }
    }
  }'

برای اینکه وقتی Model Armor در دسترس نیست، درخواست‌ها بتوانند عبور کنند، failureMode روی FAIL_OPEN تنظیم کنید، یا برای مسدود کردن آنها FAIL_CLOSED را تنظیم کنید.

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

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

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

در کنسول گوگل کلود، در صفحه APIها و خدمات، به صفحه اعتبارنامه‌ها بروید.
به اعتبارنامه‌ها بروید
روی ایجاد اعتبارنامه کلیک کنید و شناسه کلاینت OAuth را انتخاب کنید.
در قسمت نوع برنامه، برنامه وب را انتخاب کنید.
در بخش Authorized redirect URIs، URI های زیر را اضافه کنید:

https://vertexaisearch.cloud.google.com/oauth-redirect
https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

روی ایجاد کلیک کنید.
شناسه کلاینت و راز کلاینت را برای استقرار صادر کنید.

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

Agent را در 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`	(الزامی)	آدرس اینترنتی سرور DMS MCP
`--income-verification-url`	(الزامی)	آدرس اینترنتی پایه 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`	(اختیاری)	دامنه DNS برای اتصال PSC-I DNS (باید با نقطه تمام شود)
`--dns-peering-target-project`	(اختیاری)	پروژه میزبانی شبکه VPC هدف برای DNS peering
`--dns-peering-target-network`	(اختیاری)	نام شبکه VPC برای DNS peering
`--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`	نام مدل جمینی برای عامل
`--agent-name`	`mortgage-agent`	مجوز و نام نماینده Gemini Enterprise
`--ge-deploy-only`	(اختیاری)	ثبت یک موتور استدلال موجود در Gemini Enterprise بدون نیاز به استقرار مجدد (ارسال نام کامل منبع)

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

برای افزودن کاربران دارای مجوز به یک عامل ADK با استفاده از کنسول Google Cloud ، به بخش افزودن یا تغییر کاربران و مجوزهای آنها مراجعه کنید.

۹. کارگزار خود را آزمایش کنید

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

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

به صفحه Gemini Enterprise در کنسول Google Cloud بروید.
برنامه Gemini Enterprise را که قبلاً پیکربندی کرده‌اید، جایی که "عامل وام مسکن" ثبت شده است، انتخاب کنید.
در برگه «نمای کلی»، به نشانی اینترنتی نشان داده شده در بخش «اپلیکیشن وب Gemini Enterprise شما آماده است» بروید.
از منوی سمت چپ که گالری نمایندگان نام دارد، تب نمایندگان را انتخاب کنید.
اکنون باید بتوانید با «نماینده دستیار وام مسکن» چت کنید.

مورد آزمایشی ۱: «مسیر شاد» - خلاصه‌سازی داده‌ها با ویرایش PII

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

پیام زیر را برای نماینده دستیار وام مسکن ارسال کنید:

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?

پشت صحنه چه خبر است:
- نماینده در Gemini Enterprise درخواست‌ها را به ابزارهای لازم (مثلاً سیستم مدیریت اسناد (DMS) برای اظهارنامه مالیاتی، API تأیید درآمد) تنظیم می‌کند.
- مدل آرمور، درخواست‌ها و پاسخ‌های مخرب را برای یافتن تهدیدها بررسی می‌کند.
- «سیاست مجوز مبتنی بر محتوا» که پیکربندی کرده‌اید، افزونه‌ی DLP سفارشی ( dlp-content-authz-ext ) را فعال می‌کند. این افزونه داده‌های دریافتی از سیستم‌های backend را بررسی می‌کند.
- سرویس DLP هرگونه اطلاعات شخصی قابل شناسایی (PII)، مانند شماره‌های تأمین اجتماعی (SSN)، را قبل از رسیدن به نماینده، از داده‌های اظهارنامه مالیاتی حذف می‌کند.
نتیجه مورد انتظار: نماینده خلاصه‌ای از اظهارنامه‌های مالیاتی و وضعیت تأیید درآمد را ارائه می‌دهد. نکته مهم این است که خلاصه ارائه شده توسط نماینده را بررسی کنید. باید مشاهده کنید که اطلاعات حساس، مانند شناسه مالیات‌دهندگان (SSN)، با متغیرهایی جایگزین شده‌اند (مثلاً [REDACTED] ). این امر اجرای سیاست DLP را از طریق دروازه تأیید می‌کند.

قابلیت مشاهده و حسابرسی

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

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

مشاهده ردپاها برای جلسات شما:

در کنسول گوگل کلود، به صفحه Vertex AI Agent Engine بروید.
به Agent Engine بروید. نمونه‌های Agent Engine که بخشی از پروژه انتخاب شده هستند در لیست ظاهر می‌شوند. می‌توانید از فیلد Filter برای فیلتر کردن لیست بر اساس ستون مشخص شده خود استفاده کنید.
روی نام نمونه Agent Engine خود کلیک کنید.
روی برگه ردیابی‌ها کلیک کنید.
می‌توانید نمای جلسه (Session view) یا نمای دهانه (Span view) را انتخاب کنید.
برای بررسی جزئیات ردیابی، از جمله یک نمودار جهت‌دار غیرمدور (DAG) از محدوده‌ها، ورودی‌ها و خروجی‌های آن و ویژگی‌های فراداده، روی یک جلسه یا محدوده کلیک کنید.

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

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

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

پیش‌نیازها

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

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

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

قانون داخلی ارسال دروازه 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}')

پیوست سرویس را ایجاد کنید:

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 را آماده کنید.

به دایرکتوری terraform بروید:
```
cd terraform
```
فایل terraform.tfvars را ویرایش کنید و enable_apigee = true قرار دهید.
اعمال تغییرات:
```
terraform apply
```

مرحله 3: تعریف مشخصات 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

مرحله 4: پروکسی Apigee MCP Discovery را مستقر کنید

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

در رابط کاربری Apigee، به مسیر Develop > API Proxies بروید.
روی «ایجاد جدید» کلیک کنید و MCP Discovery Proxy را انتخاب کنید.
نام income-verification-discovery وکالتی را بنویسید.
در بخش OpenAPI Spec ، فایل income-verification-oas.yaml که ایجاد کرده‌اید را آپلود کنید.
گروه محیطی (Environment Group) را روی گروهی که دروازه داخلی شما به آن دسترسی دارد، تنظیم کنید.
روی استقرار کلیک کنید.

(اختیاری) افزودن یک سیاست امنیتی

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

مرحله ۵: دسترسی به ابزار Transcoded را تأیید کنید

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

ابزارهای موجود از طریق نقطه پایانی 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": {}
  }'

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

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

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

آدرس اینترنتی Apigee MCP خود را مشخص کنید: نقطه پایانی شما باید از الگوی زیر پیروی کند: https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp .

اسکریپت استقرار را دوباره اجرا کنید: از پرچم --update به همراه --income-verification-url جدید استفاده کنید. این کار عامل موجود در Agent Engine را بدون نیاز به حذف کامل به‌روزرسانی می‌کند.

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}

تأیید تغییر: به رابط کاربری Gemini Enterprise برگردید و از نماینده بخواهید درآمد متقاضی را تأیید کند.
```
"Can you verify the joint income for the Sterlings using the verification service?"
```
در تب Apigee Debug ، اکنون باید ببینید که درخواست JSON-RPC ورودی از GKE Gateway به یک درخواست استاندارد REST POST به سرویس GKE بک‌اند شما تبدیل می‌شود.

۱۱. تمیز کردن

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

اگر پیوست سرویس به صورت دستی ایجاد شده است، آن را حذف کنید:

gcloud compute service-attachments delete internal-gke-gateway \
    --region=${REGION} --quiet

به دایرکتوری terraform بروید و تمام منابع را نابود کنید:
```
cd terraform
terraform destroy
```
در صورت تمایل، پروژه Google Cloud را به طور کامل حذف کنید:
```
gcloud projects delete ${PROJECT_ID}
```

۱۲. تبریک

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

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

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

مراحل بعدی

زره مدل را کاوش کنید
درباره موتور عامل (Agent Engine) بخوانید
کاوش در شرکت جمینی