שליטה בעומסי עבודה אג'נטיים באמצעות Agent Gateway בפלטפורמת הסוכנים של Gemini Enterprise

1. מבוא

‫Gemini Enterprise Agent Platform היא פלטפורמה פתוחה ליצירה, להרחבה, לניהול ולאופטימיזציה של סוכני AI ברמה שמתאימה לארגונים, שמבוססים על הנתונים שלכם.

‫Agent Runtime מספק סביבת ביצוע מנוהלת להרצת סוכנים, כמו אלה שנבנו באמצעות הערכה לפיתוח סוכנים (ADK) בקוד פתוח, בצורה מאובטחת ב-Google Cloud.

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

מידע על Agent Gateway

‫Agent Gateway הוא רכיב הרשת של חבילת Agent Governance בפלטפורמה. הוא משמש כנקודת הכניסה והיציאה של הרשת לכל האינטראקציות עם הסוכנים, ומאפשר לאדמינים של אבטחה לאכוף ניהול מרכזי בלי לדרוש מהמפתחים לנהל פרימיטיבים מורכבים של רשתות.

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

  • לקוח לסוכן (כניסה): מאבטח את התקשורת בין לקוחות חיצוניים (כמו Cursor או Gemini CLI) לבין הסוכנים שלכם.
  • Agent-to-Anywhere (יציאה): מאבטח את התקשורת בין סוכנים שפועלים ב-Google Cloud לבין שרתים, כלים או ממשקי API שפועלים בכל מקום.

ב-Codelab הזה נתמקד במצב Agent-to-Anywhere (יציאה).

בקרת גישה באמצעות Agent Gateway

כדי לאכוף מדיניות אבטחה, Agent Gateway משולב באופן הדוק עם שאר המערכת האקולוגית:

  • Agent Registry: ספרייה מרכזית של סוכנים וכלים מאושרים (כולל שרתי MCP של צד שלישי).
  • זהות הסוכן: לכל סוכן יש פרסונה ייחודית שאפשר לעקוב אחריה, והיא מאובטחת אוטומטית באמצעות mTLS מקצה לקצה.
  • ‫Identity-Aware Proxy (IAP) & IAM: שכבת האכיפה שמוגדרת כברירת מחדל ומאמתת את זהות הסוכן מול הרשאות IAM מפורטות לפני שהיא מאפשרת לבצע קריאות לכלים ספציפיים.
  • הגנה מוגברת על המודל: אמצעי הגנה מבוסס-AI שמשולב באמצעות Service Extensions כדי לבצע סניטציה של התוכן ולהגן מפני מתקפות שבהן מחדירים הנחיות או מפני דליפת נתונים.

מצבי פריסה (רשת ציבורית לעומת רשת פרטית ב-Cloud Run)

כדי להפוך את שיעור ה-Codelab הזה לנגיש, אתם יכולים לבחור בין שני נתיבי רשת לכלים הפנימיים (שרתי MCP) שפרסתם ב-Cloud Run:

  1. ברירת מחדל (כניסה ציבורית): שרתי ה-MCP נפרסים ב-Cloud Run עם שמות מארחים ציבוריים (ingress=all). התעבורה מנותבת מהסוכן אל הכלים באמצעות כתובות URL רגילות של *.run.app. לא נדרשים דומיינים של DNS בהתאמה אישית, וזו הדרך הכי מהירה ללמוד את מושגי השליטה.
  2. מאובטח (רשת פרטית): ארכיטקטורה אופציונלית ופרטית לחלוטין. הגישה לשרתי ה-MCP מוגבלת (ingress=internal-and-cloud-load-balancing) והם נחשפים דרך מאזן עומסים פנימי של אפליקציות עם Serverless NEG. כדי להקצות אישור שמנוהל על ידי Google, צריך להיות בבעלותכם דומיין DNS ציבורי.

תצטרכו לבחור את הנתיב המועדף כשמגדירים את Terraform.

כדי לקבל מידע נוסף על תעבורת נתונים נכנסת של נקודות קצה ברשת ל-Cloud Run, קראו את המסמכים שלנו.

הפעולות שתבצעו:

  • הקצאת משאבים של מחסנית תשתית הליבה באמצעות Terraform
  • פיתוח ופריסה של כלים פנימיים כשרתי MCP ב-Cloud Run
  • פריסת סוכן ADK ל-Agent Runtime באמצעות יציאה מממשק PSC
  • הגדרת תוספים לשירות Agent Gateway לגישה מבוססת-זהות (IAM) ולסינון תוכן (Model Armor)
  • מעקב אחר הביצוע המאובטח מקצה לקצה של הסוכן ואימותו

הדרישות

  • דפדפן אינטרנט כמו Chrome
  • פרויקט ב-Google Cloud שהחיוב בו מופעל ושיש לו גישת בעלים
  • הרשאות IAM ברמת הארגון (ה-codelab מעניק תפקידים בהיקף הארגון)
  • דומיין שאתם שולטים בו שהוקצה ל-Cloud DNS (לצורך אישור מנוהל ציבורי)
  • היכרות עם Terraform,‏ gcloud ועם רשתות בסיסיות ב-Google Cloud

טופולוגיית Codelab

ארכיטקטורה מקצה לקצה: Gemini Enterprise ל-Agent Runtime ל-Agent Gateway לשרתי MCP ב-Cloud Run

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

תתחילו בהקצאת משאבים של רישות בסיסי, כולל VPC ומאזן עומסים של אפליקציות (ALB) פנימי שהוגדר כ-Agent Gateway. לאחר מכן, תפרסו שלושה שרתי Model Context Protocol‏ (MCP) ב-Cloud Run. השרתים האלה פועלים ככלים פנימיים קנייניים:

  • ניהול מסמכים (legacy-dms)
  • כתובת אימייל ארגונית (corporate-email)
  • אימות הכנסה (income-verification)

אחרי שתגדירו את הכלים, תפרסו את העוזר למשכנתאות (mortgage-agent) שנבנה באמצעות ADK ל-Agent Runtime. תגדירו את הסוכן הזה כך שישתמש בממשק PSC לתעבורת נתונים יוצאת פרטית ותפעילו גילוי כלים בזמן ריצה באמצעות Agent Registry.

כדי לאבטח את התהליך, תצטרכו להגדיר את Agent Gateway עם שתי תוספים לשירות. קודם כול, תוסף REQUEST_AUTHZ יאמת את זהות הסוכן מול מדיניות IAM לכל כלי, כדי לוודא שהסוכן ניגש רק לכלים מורשים. בשלב השני, תוסף CONTENT_AUTHZ שמשתמש ב-הגנה מוגברת על המודל יסנן את ההנחיות והתשובות של הסוכן.

לבסוף, תרשמו את הסוכן ב-Gemini Enterprise, תפעילו משימת חיתום משכנתא כמשתמשי קצה ותאמתו את הביצוע המאובטח והמנוהל באמצעות Cloud Trace.

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

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

יצירת פרויקט ואימות

יוצרים פרויקט חדש ב-GCP (או משתמשים בפרויקט קיים) עם חיוב מופעל, ואז מאמתים את Cloud Shell או את המחשב המקומי:

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

הפעלת ממשקי API של bootstrap

מודול הבסיס של Terraform מאפשר להשתמש ב-30 ממשקי API בערך בהפעלה הראשונה, אבל נדרש סט קטן של אתחול ל-terraform init ולמאגר המידע של GCS:

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,‏ Python 3.12+‎ ו-Google Cloud SDK ‏ (gcloud).

הגדרה של משתני סביבה

בהמשך ה-codelab מניחים שהקבצים האלה מיוצאים למעטפת.

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

3. שכפול המאגר 

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

4. יצירת קטגוריית אחסון של מצב Terraform והגדרת הקצה העורפי

יוצרים קטגוריה ב-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"

5. (אופציונלי) יצירת תחום ציבורי ב-Cloud DNS

כברירת מחדל, במעבדה הזו, הגדרת הכניסה של Cloud Run מוגדרת ל-all, ו-Agent Registry רושם כל שרת MCP בכתובת ה-URL הציבורית שלו *.run.app – לא נדרשים DNS, אישורים או איזון עומסים נוספים. אם רוצים לעבור לרשת פרטית (Cloud Run עם ingress = internal-and-cloud-load-balancing מאחורי איזון עומסים פנימי של אפליקציות), צריך גם תחום DNS ציבורי של Cloud DNS כדי ש-Certificate Manager יוכל לאמת את אישור איזון העומסים.

תרשים זרימה ברמה גבוהה של רשת פרטית

תרשים זרימה ברמה גבוהה של אפשרות רשת פרטית

כדי להשתמש בגישה לרשת פרטית:

  1. יוצרים את תחום ה-DNS הציבורי ב-Cloud DNS –‏ Certificate Manager מאמת את האישור האזורי המנוהל על ידי כתיבת רשומות CNAME לתוכו:
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

אזור פרטי תואם ל-mcp.${DOMAIN_NAME} (בשימוש על ידי איזון העומסים הפנימי של MCP וחיבור ה-DNS מ-Agent Runtime) נוצר אוטומטית על ידי Terraform – אין צורך ליצור אותו באופן ידני. אם הרשת הפרטית מושבתת, לא מוקצה אזור ציבורי ולא מוקצה אזור פרטי.

6. הגדרת משתני Terraform

מעתיקים את הקובץ לדוגמה tfvars ועורכים אותו:

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

  • מאזן עומסים פנימי של אפליקציות (ALB)
  • אישור שמנוהל על ידי Google
  • ‫Cloud Run עם ingress = internal-and-cloud-load-balancing
  • קישור DNS בין רשתות שכנות (peering) של 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"

7. פריסת תשתית באמצעות Terraform

אתחול, בדיקה והחלה:

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

‫terraform apply מספקת כ-40 משאבים בנתיב ברירת המחדל, והתהליך נמשך 8-10 דקות בפרויקט חדש (כ-60 משאבים / 15-20 דקות כש-enable_cloud_run_private_networking = true). היא יוצרת:

  • הבסיס של הפרויקט (ממשקי API, זהויות שירות, מכסות)
  • VPC, רשתות משנה (primary, proxy-only, PSC, PSC-Interface, Agent Gateway co-location), ‏ Cloud NAT, כללי חומת אש
  • מאגר Artifact Registry לתמונות Cloud Run
  • שלושה שירותי Cloud Run + חשבונות שירות של זמן ריצה לכל שירות (תעבורת כניסה = all כברירת מחדל; internal-and-cloud-load-balancing כשמופעלת רשת פרטית)
  • תבנית של הגנה מוגברת על המודל + IAM
  • ‫Agent Gateway, ‏ PSC-I network attachment, ‏ IAP ו-Model Armor extensions, ‏ both authorization policies, והרשאת הגישה roles/iap.egressor ברמת הפרויקט
  • נקודות קצה של Agent Registry ‏ (Vertex AI, ‏ IAP, ‏ Discovery Engine וכו') בתוספת שלושת שרתי ה-MCP (רשומים ב-*.run.app/mcp כברירת מחדל, וב-./mcp כשהרשת הפרטית מופעלת)

רק כשenable_cloud_run_private_networking = true:

  • מאזן עומסים אזורי פנימי של אפליקציות עם NEG ללא שרת (ניתוב של מיסוך כתובות URL) + רשומות DNS פרטיות מסוג A
  • תחום DNS פרטי של MCP‏ (mcp..) שמצורף ל-VPC
  • מודול של תחום DNS ציבורי (הרשאות DNS של Certificate Manager) + אישור אזורי בניהול Google
  • תחום DNS של ממשק PSC (יתום כשאין שמות מארחים פרטיים לפתרון, ולכן הוא גם מוגבל על ידי דגל הראשי)
  • קישור DNS בין רשתות שכנות (peering) של Agent Gateway עבור mcp.. (נוסף אוטומטית בתחילת השורה)

8. בדיקת נקודות הקצה של מאגר הנציגים

‫Agent Registry הוא קטלוג של שירותים (ממשקי Google API ושרתי MCP משלכם) שסוכן מגלה בזמן הריצה. הקטלוג הזה הוא ספציפי לכל פרויקט. סוכן המשכנתאות קורא את הקובץ הזה בהפעלה ומקשר כלים באופן דינמי – כתובות ה-URL של MCP לא מוטמעות בקוד של הסוכן או בפקודת הפריסה שלו.

נקודות קצה

מה ש-Terraform הפעיל בשמכם – לכל Google 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

9. בדיקת ההגדרות של Agent Gateway

Agent Gateway הוא מישור ניהול שמנוהל על ידי Google בין Agent Runtime לבין הכלים שלכם. במצב AGENT_TO_ANYWHERE הוא קשור ל-Agent Registry של הפרויקט, והתעבורה היוצאת שלו עוברת דרך ממשק 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}

10. בדיקת הרשאות ב-IAP וב-הגנה מוגברת על המודל

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

  • ‫REQUEST_AUTHZ – מוערך פעם אחת לכל בקשה בשלב הכותרות. הפרמטר הזה משמש לקריאה ל-IAP, שבודק אם לזהות של הסוכן המבצע את הקריאה יש roles/iap.egressor בשרת היעד של MCP.
  • ‫CONTENT_AUTHZ – מעביר אירועים של גוף הזרם לתוסף לצורך ניקוי תוכן. משמש כאן לקריאה ל-הגנה מוגברת על המודל, שבודק אם יש החדרה של הנחיות, פריצות, הפרות של RAI ו(אופציונלית) פרטים אישיים מזהים (PII) באמצעות Sensitive Data Protection (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}

מקשרים אותו ל-Agent Gateway באמצעות מדיניות REQUEST_AUTHZ:

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

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 של Model Armor משתמש ברשימה מובנית של סוגי מידע. כדי לקבל שליטה מדויקת יותר (סוגי מידע בהתאמה אישית, מיסוך חלקי, החלפה בסורוגט, צנזורה לפי סבירות), אפשר להפנות את Model Armor לתבניות בדיקה וביטול הזיהוי של 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": {} }
          }]
        }
      }
    }
  }'

לאחר מכן מצביעים על זוג המפתחות באמצעות sdpSettings.advancedConfig בתצורת התגובה של תבנית Model Armor (כאן מודול 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"
      }
    }
  }
}

IAP egressor IAM (לכל שרת MCP בלבד)

‫Terraform לא יוצרת קשירת roles/iap.egressor ברמת הפרויקט במאגר הסוכנים המרומז של IAP. הבקשה REQUEST_AUTHZ של IAP שמוערכת בפועל היא לכל שרת MCP ולכל מנוע נימוקים, והיא ניתנת אחרי שהסוכן נפרס ואחרי שמזהים את מזהה הסוכן. השלב Grant the agent per-MCP-server egress (הענקת גישה ליציאה לסוכן לכל שרת MCP) מפעיל את scripts/grant_agent_mcp_egress.sh לשם כך.

11. פיתוח ופריסה של שרתי 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:

מייצאים את הגדרת ה-ingress של Cloud Run.

  • all
  • internal-and-cloud-load-balancing (בשימוש בגישה של רשת פרטית)
export MCP_INGRESS=all

חוזרים לספריית ההדגמה הראשית:

cd ..

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

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 פועל כחשבון שירות של זמן ריצה שנוצר על ידי Terraform (לדוגמה, mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). כדי לפרוס כחשבונות השירות האלה, צריך roles/iam.serviceAccountUser על עצמכם:

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

פיתוח באמצעות Cloud Build ופריסה באמצעות Skaffold:

skaffold run

‫Skaffold יוצר שלוש תמונות (legacy-dms, ‏corporate-email, ‏income-verification-api) במאגר Artifact Registry ומעדכן כל שירות Cloud Run כך שיצביע על ה-digest החדש.

אימות:

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

שלושת השירותים צריכים להופיע עם הסטטוס ACTIVE.

12. פריסת סוכן המשכנתאות ל-Agent Runtime

צריך להעניק לכל הסוכנים את התפקיד IAP Egressor בכל נקודות הקצה שרשמנו במאגר. הסוכן צריך גישה לנקודות הקצה האלה כי כשהוא נפרס, הוא צריך להגיע אל github.com כדי להוריד חבילות, ואז להגיע אל ממשקי Google API השונים שנדרשים לפריסה.

./scripts/grant_agent_mcp_egress.sh --bind-all-agents --endpoints

מתקינים את יחסי התלות של הסוכן ומבצעים פריסה:

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 \
  --mcp-invoker-sa=$(terraform -chdir=../../terraform output -raw agent_mcp_invoker_email) \
  --model-endpoint-location=global

כשהסקריפט מסתיים, מעתיקים את הערך המודפס reasoningEngines/ אל המעטפת (לדוגמה, 4262292559201566720):

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

13. הענקת גישה ליציאה (egress) לסוכן לכל שרת MCP

תוסף ה-IAP REQUEST_AUTHZ מאשר כל קריאה לכלי על ידי בדיקת roles/iap.egressor של הסוכן בשרת MCP ספציפי או בנקודת קצה שאליה הוא קורא. מידע נוסף זמין במאמר בנושא יצירת מדיניות יציאה מסוכן לשרת MCP.

הסקריפט (scripts/grant_agent_mcp_egress.sh) מונה את שרתי ה-MCP ב-Agent Registry בקטע projects/${PROJECT_ID}/locations/${REGION} וממזג את הקישור roles/iap.egressor עבור חשבון המשתמש של הסוכן לתוך מדיניות ה-IAM של כל שרת (שיקוף של הסמנטיקה של gcloud add-iam-policy-binding).

תרחיש שימוש 1 – הענקת הרשאה ללא תנאי בהיקף של שרתי MCP ספציפיים

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

תרחיש שימוש 2 – הענקת הרשאה מותנית (CEL) בהיקף של שרת MCP ספציפי

כדי להגביל את הסוכן לקבוצת משנה של כלים בשרת MCP יחיד, צריך לצרף תנאי IAM. Agent Gateway מפרסם מאפיינים לכל כלי ש-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 || api.getAttribute('iap.googleapis.com/mcp.toolName', '') == ''" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

אחרי שהפעולה הזו תרוץ, כלי כתיבה ב-corporate-email יחזירו 403 PermissionDenied מ-IAP REQUEST_AUTHZ; כלי קריאה בלבד ימשיכו לפעול.

אימות הקישורים

עוברים אל הכרטיסייה Policies ורואים את רשימת הכללים שנוצרו עבור נקודות הקצה ושרתי ה-MCP.

תרחישים נוספים לדוגמה:

הענקת הרשאה ללא תנאי בכל שרת MCP, בהיקף של סוכן אחד

מריצים את הפקודה הזו אחרי כל פריסה מחדש של סוכן. בלי מסנן ובלי תנאי, הסוכן שצוין מקבל roles/iap.egressor בכל שרת MCP ברשומות:

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

14. בדיקת הנציג במסוף Agent Platform

המסוף של Agent Platform כולל סביבת ניסויים שמאפשרת לכם לשוחח בצ'אט ישירות עם הסוכן שפרסתם. זו הדרך הכי מהירה לבצע בדיקת עשן של קריאות לכלים ולבדוק עקבות לפני שמחברים את הסוכן ל-Gemini Enterprise.

  1. פותחים את הדף Agent Platform Deployments במסוף Google Cloud.
  2. אם רוצים לצמצם את רשימת זמני הריצה, משתמשים בשדה Filter ואז לוחצים על זמן הריצה 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?

אמורה להתקבל תשובה מהכלי לניהול מסמכים ומהכלי לאימות הכנסות, וגם מספרים של כרטיסי ביטוח לאומי צריכים להיות מוסתרים בתשובה הזו. 5. מקלידים שאילתת המשך:

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

הסוכן יוכל לשלוח את האימייל בהצלחה, כי המדיניות המותנית לא נאכפת בגלל שהתוסף IAP נמצא במצב הרצת בדיקה.

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

  • ‫Trace – מעקב מלא של השיחה, כולל Agent Gateway,‏ IAP REQUEST_AUTHZ ו-Model Armor CONTENT_AUTHZ
  • אירוע – תרשים של הכלים שהופעלו ופרטי האירוע של התור הנוכחי
  • State – מצב הסשן של הסוכן והקלט/פלט של הכלי
  • סשנים – כל סשן שהתחלתם בזמן הריצה הזה

15. אכיפת הרשאה של 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. אם רוצים לצמצם את רשימת זמני הריצה, משתמשים בשדה Filter ואז לוחצים על זמן הריצה 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?

אמורה להתקבל תשובה מהכלי לניהול מסמכים ומהכלי לאימות הכנסות, וגם מספרים של כרטיסי ביטוח לאומי צריכים להיות מוסתרים בתשובה הזו. 5. מקלידים שאילתת המשך:

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

אם הכל הוגדר בצורה נכונה, הסוכן אמור להשיב שהוא לא יכול לשלוח את האימייל בגלל מדיניות ההרשאות.

16. הגדרה ובדיקה של Gemini Enterprise

הגדרה של Gemini Enterprise

פועלים לפי המדריך לתחילת העבודה עם Gemini Enterprise.

רישום סוכן ADK ב-Gemini Enterprise

כדי לרשום את הסוכן שלנו ב-Gemini Enterprise, אפשר לפעול לפי השלבים האלה.

  1. במסוף Google Cloud, עוברים לדף Gemini Enterprise.
  2. בוחרים את אפליקציית Gemini Enterprise שבה הסוכן רשום.
  3. פותחים את כתובת ה-URL שמופיעה בקטע Your Gemini Enterprise webapp is ready (אפליקציית האינטרנט של Gemini Enterprise מוכנה).
  4. בתפריט הימני, לוחצים על הכרטיסייה סוכן כדי לפתוח את גלריית הסוכנים.
  5. בוחרים באפשרות Mortgage Assistant Agent ומתחילים בצ'אט.

אפשר לנסות את אותן הנחיות ב-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.

17. לוח בקרה של ניראות (observability)

מרכז הבקרה לניפוי באגים בהרשאות מספק תצוגה יחידה של תעבורת הנתונים היוצאת (egress) של סוכני Agent Runtime.

לוח בקרה של ניראות (observability)

בלוח הבקרה מוצגים הנתונים הבאים:

  • סוכן ➔ נקודת קצה (דחיות 403)
  • סוכן ➔ שרת MCP (דחיות 403)
  • סוכן ➔ סוכן (דחיות 403)
  • חסימות של אימיילים יוצאים שלא נרשמו
  • סקירה כללית של תנועה ומצב אכיפה של רכישות מתוך האפליקציה
  • GCP API IAM Denials

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

  • חסימות של תנועה יוצאת שלא רשומה – בווידג'ט הזה מבודדים את התנועה ש-Agent Gateway חסם כי שם המארח של היעד לא קיים במרשם הסוכנים. מכיוון ששרת ה-proxy של השער חוסם את הבקשות האלה לפני שהן מגיעות ל-IAP, אין רשומות של הבקשות האלה ביומני הביקורת של IAP.
  • סקירה כללית של התנועה ומצב האכיפה של IAP – בווידג'ט הזה מוצגת טבלה עם כל דפוסי התנועה. חשוב לציין שהיא כוללת את הסטטוס של ההרצה היבשה של IAP, כך שהמשתמשים יכולים לראות אם מדיניות IAP חוסמת תנועה באופן פעיל או רק עוקבת אחריה.
  • GCP API IAM Denials – הווידג'ט הזה מחפש ביומני ביקורת רגילים של Cloud ‏ (cloudaudit.googleapis.com) כדי לזהות שגיאות הרשאה ב-Google Cloud API שקשורות לסוכנים.

לוח הבקרה הזה נמצא ב-Cloud Console: Monitoring > Dashboards > Agent Platform: Authorization Debugging

18. פתרון בעיות ותיקונים נפוצים

ניפוי באגים בעזרת AI באמצעות Gemini CLI

אתם יכולים להשתמש במיומנות agent-platform-debugger ב-Gemini CLI כדי לפתור בעיות. חבילת המיומנות הזו כוללת ידע מיוחד לניפוי באגים בעזרת AI. מכיוון ש-Gemini CLI מתייחס ל-agent-platform-debugger כאל כינוי ברמה גבוהה ל-.gemini/skills/ בהיקף של Workspace, אתם יכולים להשתמש במיומנויות ישירות. כדי להשתמש במיומנות הזו מתוך מאגר Codelab:.agents/skills/

עוברים לספריית המאגר ומפעילים את Gemini CLI:

cd /path/to/cloud-networking-solutions/demos/agent-gateway
gemini

כשתופיע בקשה, צריך לאשר את סביבת העבודה (מיומנויות בהיקף סביבת העבודה נטענות רק מתיקיות מהימנות). מאשרים שהמיומנות נטענה:

/skills list

agent-platform-debugger אמור להופיע ברשימה. אם היא חסרה, צריך לטעון מחדש את המיומנויות:

/skills reload

טיפים לפתרון בעיות

  • ‫terraform apply נכשל ב-Agent Gateway עם השגיאה 'resource is being created and therefore can not be updated' – פרויקט הדייר של השער נדרש להמתין כ-30 שניות לפני שאפשר לצרף מדיניות הרשאות. מודול 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}
    אמורות להופיע שלוש רשומות (אחת לכל שירות MCP של Cloud Run). אם הרשימה ריקה, צריך לוודא שאפשר להגיע לשירותי ה-MCP מתוך ה-VPC, וש-Agent Gateway מילא את הרישום (הוא עושה זאת באופן עצלני ברשימת הכלים הראשונה שמועברת דרך ה-proxy).
  • הפעלות של כלים מחזירות את השגיאה 403 PermissionDenied – מריצים מחדש את scripts/grant_agent_mcp_egress.sh. הסיבה הכי נפוצה היא ששוכחים להעניק מחדש הרשאות אחרי פריסה מחדש של הסוכן (הערך של reasoningEngines/ משתנה בכל פריסה).
  • ‫skaffold run נכשל עם ההודעה "permission denied on service account" (ההרשאה נדחתה בחשבון השירות) — חסרה לכם ההרשאה roles/iam.serviceAccountUser. מריצים מחדש את ההרשאה העצמית בשלב הקודם.
  • שגיאות בחיבור DNS מ-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.

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

מנוע הנימוקים לא מנוהל על ידי Terraform (הוא נוצר על ידי ADK SDK). מחיקה ידנית:

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

20. מזל טוב

מעולה! הטמעתם בהצלחה ניהול מקיף של סוכנים בסוכן ADK מרובה-כלים באמצעות Agent Gateway. בתור מישור בקרה מרכזי ברשת, Agent Gateway מאפשר לכם ליצור נתיב יציאה מאובטח לכלים פרטיים, לאכוף מדיניות IAM מפורטת שמבוססת על זהויות באמצעות שרת proxy לאימות זהויות (IAP), ולבצע סניטציה של אינטראקציות עם תוכן באמצעות אמצעי הגנה משולבים של Model Armor.

מה למדתם

  • איך פורסים ומגדירים את Agent Gateway כשכבת הבקרה המרכזית לתעבורת נתונים יוצאת (egress) מ-Agent-to-Anywhere.
  • איך משלבים את Agent Registry כדי לגלות כלים דינמיים בזמן ריצה, בהתאם לכללים.
  • איך לכתוב ולאכוף מדיניות IAM לכל כלי ומדיניות מבוססת-תנאים כדי לשלוט באופן קפדני בנתיבי ההפעלה של הסוכן.
  • איך למנף את Service Extensions של Agent Gateway כדי להחיל מדיניות הגנה מוגברת על המודל, וליירט ולצנזר באופן אוטומטי תעבורת נתונים רגישה של סוכנים.

מסמכים לדוגמה