Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

ברירת מחדל (כניסה ציבורית): שרתי ה-MCP נפרסים ב-Cloud Run עם שמות מארחים ציבוריים (ingress=all). התעבורה מנותבת מהסוכן אל הכלים באמצעות כתובות URL רגילות של *.run.app. לא נדרשים דומיינים של DNS בהתאמה אישית, וזו הדרך הכי מהירה ללמוד את מושגי השליטה.
מאובטח (רשת פרטית): ארכיטקטורה אופציונלית ופרטית לחלוטין. הגישה לשרתי ה-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 יוכל לאמת את אישור איזון העומסים.

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

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

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

יוצרים את תחום ה-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 peering מ-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, רשתות משנה (ראשיות, 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, ‏ and the project-level roles/iap.egressor grant
נקודות קצה של 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 (יתום כשאין שמות מארחים פרטיים לפענוח, ולכן הוא מוגבל גם על ידי דגל האב)
Agent Gateway DNS peering for mcp.. (auto-prepended)

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

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

‫REQUEST_AUTHZ – מוערך פעם אחת לכל בקשה בשלב הכותרות. הפרמטר הזה משמש כאן כדי לקרוא ל-IAP, שבודק אם לזהות של הסוכן המבצע את הקריאה יש את ההרשאה roles/iap.egressor בשרת היעד של MCP.
‫CONTENT_AUTHZ – מעביר אירועים של גוף הזרם לתוסף לצורך ניקוי התוכן. הוא משמש כאן לקריאה ל-Model Armor, שמסנן החדרת הנחיות, פריצות, הפרות של 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 ולכל מנוע נימוקים, והיא ניתנת אחרי שהסוכן נפרס ואחרי שמזהים את מזהה הסוכן. השלב 'הענקת גישה ליציאה של הסוכן לכל שרת 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. הענקת גישה ליציאה לסוכן לכל שרת 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.

פותחים את הדף Agent Platform Deployments במסוף Google Cloud.
אם רוצים לצמצם את רשימת זמני הריצה, משתמשים בשדה Filter ואז לוחצים על זמן הריצה mortgage-agent.
פותחים את הכרטיסייה סביבת אימון.
כותבים הנחיה כדי לשוחח בצ'אט עם נציג תמיכה:

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

חוזרים אל המגרש ומנסים שוב לנהל את השיחה.

פותחים את הדף Agent Platform Deployments במסוף Google Cloud.
אם רוצים לצמצם את רשימת זמני הריצה, משתמשים בשדה Filter ואז לוחצים על זמן הריצה mortgage-agent.
פותחים את הכרטיסייה סביבת אימון.
כותבים הנחיה כדי לשוחח בצ'אט עם נציג תמיכה:

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

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

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

הגדרה של Gemini Enterprise

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

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

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

במסוף Google Cloud, עוברים לדף Gemini Enterprise.
בוחרים את אפליקציית Gemini Enterprise שבה הסוכן רשום.
פותחים את כתובת ה-URL שמופיעה בקטע Your Gemini Enterprise webapp is ready (אפליקציית האינטרנט של Gemini Enterprise מוכנה).
בתפריט הימני, לוחצים על הכרטיסייה סוכן כדי לפתוח את גלריית הסוכנים.
בוחרים באפשרות 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 כי שם המארח של היעד לא קיים במאגר Agent Registry. מכיוון ששרת ה-proxy של השער חוסם את הבקשות האלה לפני שהן מגיעות ל-IAP, אין רשומות ביומני הביקורת של IAP לגבי הערכים האלה.
סקירה כללית של התנועה ומצב אכיפה של IAP – בווידג'ט הזה מוצגת טבלה עם כל דפוסי התנועה. חשוב לציין שהיא כוללת את הסטטוס של ההרצה היבשה של IAP, כך שהמשתמשים יכולים לראות אם מדיניות IAP חוסמת תנועה באופן פעיל או רק בודקת אותה.
GCP API IAM Denials – הווידג'ט הזה מחפש ביומני ביקורת רגילים של Cloud ‏ (cloudaudit.googleapis.com) כדי לזהות שגיאות הרשאה ב-Google Cloud API שקשורות לסוכנים.

לוח הבקרה הזה נמצא בכרטיסייה Observability (יכולת תצפית) בקטע Agent Gateway instance (מופע של Agent Gateway): Agent Platform > Agents > Gateways > Specific Instance > Observability

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

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

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

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