אבטחה של פריסות של סוכנים חוצי-ענן בארגונים

1. מבוא

ב-Codelab הזה נסביר איך פורסים פריסה מאובטחת של סוכן יחיד עם כמה כלים באמצעות הערכה לפיתוח סוכנים (ADK),‏ Agent Engine ו-Google Kubernetes Engine. תלמדו איך סוכן AI שהופעל על ידי משתמש ב-Gemini Enterprise מנווט בצורה מאובטחת ב-Google Cloud, תוך הסתמכות על GKE Gateway עם Service Extensions כדי לצנזר מידע אישי רגיש בתשובות של כלי MCP.

מה לומדים

פריסת סוכן ADK לטיפול במשכנתאות ב-Agent Engine באמצעות אינסטרומנטציה של OpenTelemetry
פריסת שרתי MCP של קצה עורפי ב-Google Kubernetes Engine ‏ (GKE) מאחורי שער פנימי
קישור של Agent Engine ל-VPC של פרויקט באמצעות ממשק PSC וקישור בין רשתות שכנות (peering) ב-DNS
חשיפת ממשקי REST API ככלים של MCP באמצעות Apigee MCP Discovery Proxy
הגדרת GKE Gateway ליציאת סוכנים מבוקרת עם Service Extensions לצורך צנזורה של DLP והרשאה של MCP
החלת אמצעי הגנה מבוססי-AI באמצעות הגנה מוגברת על המודל לסינון הנחיות ותשובות

מה צריך

דפדפן אינטרנט כמו Chrome
פרויקט ב-Google Cloud שהחיוב בו מופעל
היכרות בסיסית עם Terraform,‏ Kubernetes ו-Python

ה-Codelab הזה מיועד למפתחים ולמומחי אבטחה שרוצים לפרוס ולאבטח תהליכי עבודה אקטיביים בסביבות ארגוניות.

‫2. לפני שמתחילים

יוצרים פרויקט בענן ב-Google Cloud ומפעילים את ממשקי ה-API הנדרשים.

במסוף Google Cloud, בדף לבחירת הפרויקט בוחרים פרויקט בענן או לוחצים על Create a Google Cloud project .
הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט.

התפקידים שצריך ב-IAM

ב-Codelab הזה אנחנו מניחים שיש לכם את התפקיד בעלי הפרויקט בפרויקט שלכם ב-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 (מנהל החבילות של 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}

יצירת תחום DNS ציבורי

כדי להשתמש ב-Codelab הזה, צריך לוודא שקיים בפרויקט תחום DNS ציבורי לפני שמחילים את ההגדרות של Terraform. האזור הזה נדרש להקצאת שרת שמות, כדי שההגדרה תוכל ליצור באופן אוטומטי את הרשומות הנדרשות עבור 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}"

3. שיבוט מאגר GitHub

בטרמינל במחשב המקומי, משכפלים את מאגר cloud-networking-solutions:
```
git clone https://github.com/googleCloudPlatform/cloud-networking-solutions.git
```

עוברים לספרייה של המאגר שהורדתם:

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

4. פריסת תשתית באמצעות 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 ומחליפים את הערכים הזמניים לשמירת מקום (placeholder). מחליפים את הערכים הבאים:
- ‫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

מפעילים את Terraform ומחילים את ההגדרות:

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

5. פריסת עומסי עבודה לדוגמה באמצעות 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/
```

6. החלת אמצעי הגנה מבוססי-AI באמצעות הגנה מוגברת על המודל

אתם יכולים להאציל את ההחלטות בנוגע לאבטחת תוכן, כמו הסרת הנחיות מזיקות או מניעת דליפות נתונים, אל הגנה מוגברת על המודל.

דרישות מוקדמות: מתן תפקידים ב-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

יצירת תוסף הרשאה של הגנה מוגברת על המודל

מגדירים תוסף שמפנה לשירות הגנה מוגברת על המודל באזור שלכם. שומרים את ההגדרה הזו בשם 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

יצירת מדיניות הרשאות של הגנה מוגברת על המודל

יוצרים מדיניות שמשייכת את תוסף הגנה מוגברת על המודל ל-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

7. הגדרה של 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

החלת סינון של הגנה מוגברת על המודל על העוזר הדיגיטלי של Gemini Enterprise כדי לסנן את ההנחיות של המשתמשים ואת התשובות של המודל. אפליקציות גלובליות של Gemini Enterprise דורשות תבנית הגנה מוגברת על המודל באזור us במספר אזורים, ולכן Terraform פורס תבנית נפרדת למטרה הזו.

מאחזרים את שם התבנית מהפלט של Terraform:

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

מאחזרים את מזהה האפליקציה של מופע Gemini Enterprise:

במסוף Google Cloud, עוברים לדף Gemini Enterprise.
בתפריט הניווט, לוחצים על 'אפליקציות'.
העתקת המזהה של מכונת Gemini Enterprise

מייצאים את המזהה כמשתנה סביבה.

export APP_ID=<PASTE_APP_ID>

מטמיעים תיקון ב-Assistant כדי להפעיל את הגנה מוגברת על המודל:

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 כדי לאפשר לבקשות לעבור כש-הגנה מוגברת על המודל לא זמין, או ל-FAIL_CLOSED כדי לחסום אותן.

8. פריסת סוכן והוספת סוכן ב-Gemini Enterprise

קבלת פרטי הרשאה

כדי לקבל את פרטי ההרשאה, פועלים לפי השלבים הבאים.

במסוף Google Cloud, בדף APIs & Services, עוברים לדף Credentials.
עוברים אל Credentials (פרטי כניסה).
לוחצים על Create credentials (יצירת פרטי כניסה) ובוחרים באפשרות OAuth client ID (מזהה לקוח OAuth).
בקטע Application type (סוג אפליקציה), בוחרים באפשרות Web application (אפליקציית אינטרנט).
בקטע Authorized redirect URIs (כתובות URI מורשות להפניה אוטומטית), מוסיפים את כתובות ה-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 (אופציונלי). במאמר רישום וניהול של סוכן A2A מוסבר על תהליך הרישום של Gemini Enterprise.

ייצוא משתנים מפריסת 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`	(חובה)	כתובת ה-URL של שרת ה-MCP של DMS
`--income-verification-url`	(חובה)	כתובת ה-URL הבסיסית של Income Verification API;‏ `/mcp` מצורפת באופן אוטומטי
`--email-mcp-url`	(חובה)	כתובת ה-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
`--dns-peering-target-network`	(אופציונלי)	שם רשת ה-VPC לקישור DNS
`--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, אפשר לעיין במאמר בנושא הוספה או שינוי של משתמשים וההרשאות שלהם.

9. בדיקת הסוכן

אחרי שפורסים ומגדירים את הסוכן, את GKE Gateway ואת כל שירותי ה-Backend, צריך לבדוק את התהליך מקצה לקצה כדי לוודא שכללי האבטחה פועלים כמצופה. תקיימו אינטראקציה עם 'סוכן משכנתאות' בממשק של Gemini Enterprise.

גישה לסוכן

עוברים לדף Gemini Enterprise במסוף Google Cloud.
בוחרים את אפליקציית Gemini Enterprise שהגדרתם קודם, שבה רשום הסוכן למשכנתאות.
בכרטיסייה 'סקירה כללית', עוברים לכתובת ה-URL שמוצגת בקטע 'אפליקציית האינטרנט של Gemini Enterprise מוכנה'.
בתפריט הימני, לוחצים על הכרטיסייה 'סוכן' שנקראת גלריית הסוכנים.
עכשיו אמורה להיות לך אפשרות לצ'אט עם "העוזר הווירטואלי בנושא משכנתאות".

תרחיש בדיקה 1: התרחיש האופטימלי – סיכום נתונים עם הסרת פרטים אישיים מזהים

בבדיקה הזו מוודאים שלסוכן יש גישה למערכות עורפיות דרך שער הסוכן, ושהמדיניות למניעת אובדן נתונים (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), מנתוני החזרי המס לפני שהם מגיעים לסוכן.
התוצאה הצפויה: הסוכן יחזיר סיכום של דוחות מס וסטטוס אימות הכנסה. חשוב לבדוק את הסיכום שהסוכן מספק. אפשר לראות שמידע רגיש, כמו מזהי משלמי מס (מספרי ביטוח לאומי), הוחלף ב-placeholder (למשל, [REDACTED]). זה מאשר את ההפעלה של מדיניות ה-DLP דרך השער.

ניראות וביקורת

במהלך הבדיקות האלה, פלטפורמת הסוכן והשירותים המשויכים אוספים נתוני טלמטריה:

‫Cloud Logging: יומנים מפורטים מ-GKE Gateway, מעומסי עבודה של GKE וממשקי שירות אחרים מספקים נתיב ביקורת של בקשות, הערכות מדיניות ותוצאות.
Cloud Trace: אינסטרומנטציית OpenTelemetry שהוגדרה בסוכן ובשירותי הקצה העורפי מאפשרת לכם לראות את כל זרימת השיחות, מ-Gemini Enterprise דרך GKE Gateway ועד לכלי הקצה העורפי. המידע הזה חשוב מאוד לניפוי באגים ולהבנת מחזור החיים של הבקשה.

כדי לראות את הנתונים של Traces בסשנים:

במסוף Google Cloud, עוברים לדף Vertex AI Agent Engine.
עוברים אל Agent Engine. מופעים של Agent Engine שהם חלק מהפרויקט שנבחר יופיעו ברשימה. אפשר להשתמש בשדה Filter (סינון) כדי לסנן את הרשימה לפי העמודה שצוינה.
לוחצים על השם של מופע Agent Engine.
לוחצים על הכרטיסייה 'עקבות'.
אפשר לבחור בתצוגת סשן או בתצוגת טווח.
לוחצים על סשן או על טווח כדי לבדוק את פרטי העקבות, כולל גרף אציקלי מכוון (DAG) של הטווחים, הקלט והפלט שלו ומאפייני המטא-נתונים.

10. אופציונלי: המרת ממשקי API של REST ל-MCP באמצעות Apigee

שירות אימות ההכנסות שלנו תומך באופן מובנה בפרוטוקול Model Context‏ (MCP), אבל הרבה מערכות מדור קודם של ארגונים מספקות רק ממשקי RESTful API. בשלב האופציונלי הזה, משתמשים ב-Apigee MCP Discovery Proxy כדי לשנות את הקידוד של נקודת הקצה של שירות אימות ההכנסות לפורמט של כלי MCP. כך תוכלו להחיל על הכלים הקודמים שלכם את מדיניות האבטחה, הגבלת קצב של יצירת בקשות והניהול המתקדמים של Apigee.

מידע נוסף זמין במאמר סקירה כללית על Apigee MCP.

דרישות מוקדמות

לפני שממשיכים, צריך לוודא שהקצאתם והגדרתם את Apigee API Hub. פועלים לפי השלבים שמפורטים בתיעוד בנושא הקצאת API Hub כדי להגדיר אותו ולצרף את מופע Apigee.

שלב 1: יצירת קובץ מצורף לשירות עבור Apigee

כדי לאפשר ל-Apigee להגיע לשירותים הפנימיים שלכם שפועלים ב-GKE, צריך ליצור קובץ מצורף לשירות.

מחפשים את כלל ההעברה הפנימי של GKE Gateway:

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

שלב 2: הפעלת 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: פריסת ה-Discovery Proxy של Apigee MCP

ה-MCP Discovery Proxy הוא שרת proxy ייעודי של Apigee שפועל כשרת MCP.

בממשק המשתמש של Apigee, עוברים אל Develop > API Proxies.
לוחצים על Create New (יצירת חדש) ובוחרים באפשרות MCP Discovery Proxy (שרת proxy של MCP Discovery).
נותנים ל-proxy את השם income-verification-discovery.
בקטע OpenAPI Spec (מפרט OpenAPI), מעלים את קובץ income-verification-oas.yaml שיצרתם.
מגדירים את קבוצת הסביבות לקבוצה שבה השער הפנימי נגיש.
לוחצים על פריסה.

(אופציונלי) הוספה של מדיניות אבטחה

לפני שמפעילים או משתפים את ה-Proxy, צריך לאבטח אותו. אתם יכולים להוסיף כללי מדיניות כדי לאכוף דרישות אבטחה, כמו טוקנים של OAuth או מפתחות API. הוראות להוספת מדיניות אבטחה מופיעות במסמכי Apigee בנושא אבטחת ממשקי API.

שלב 5: אימות הגישה לכלי הקידוד מחדש

אחרי הפריסה, Apigee מתעתק באופן אוטומטי את נקודת הקצה POST /verify לכלי MCP verifyApplicant.

מפרטים את הכלים שזמינים דרך נקודת הקצה של 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 הבסיסי תוך החלת מדיניות האבטחה שהגדרתם.

שלב 6: מעדכנים את Mortgage Agent כדי להשתמש ב-Apigee

עכשיו, אחרי ש-Apigee ביצע בהצלחה טרנסקוד של API בארכיטקטורת REST לכלי שתואם ל-MCP, צריך לעדכן את הגדרות הפריסה של הסוכן. אם מצביעים על הסוכן לנקודת הקצה של Apigee, כל בקשות האימות של ההכנסות ייהנו עכשיו מהאבטחה, מהרישום ביומן ומניהול התנועה ברמה הארגונית של Apigee.

מזהים את כתובת ה-URL של 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 בקצה העורפי.

11. הסרת המשאבים

כדי להימנע מחיובים בחשבון 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}
```

12. מזל טוב

השלמתם את ה-Codelab הזה ולמדתם איך לאבטח פריסות של סוכנים חוצי-ענן בארגונים.

מה כיסיתם

פריסת סוכן ADK לסיוע במשכנתאות ב-Agent Engine באמצעות OpenTelemetry
פריסת שרתי MCP בקצה העורפי ב-GKE מאחורי שער פנימי
חיבור של Agent Engine ל-VPC של פרויקט באמצעות ממשק PSC וקישור בין רשתות שכנות (peering) ב-DNS
הגדרת GKE Gateway ליציאת סוכנים מבוקרת עם צנזורה של DLP והרשאה של MCP
אמצעי הגנה מבוססי-AI עם הגנה מוגברת על המודל לסינון הנחיות ותשובות
אופציונלי: קידוד מחדש של ממשקי API ל-REST ל-MCP באמצעות Apigee MCP Discovery Proxy