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

1. מבוא

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

• מאגר סוכנים: ספרייה מרכזית של סוכנים וכלים מאושרים (כולל שרתי MCP של צד שלישי).
• זהות הסוכן: לכל סוכן יש פרסונה ייחודית שאפשר לעקוב אחריה, והיא מאובטחת באופן אוטומטי באמצעות mTLS מקצה לקצה.
• שרת 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.

במאמרי העזרה שלנו יש מידע נוסף על תעבורת נתונים נכנסת (ingress) של נקודת קצה (endpoint) ברישות עבור Cloud Run.

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

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

הדרישות

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

טופולוגיית Codelab

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

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

אם אתם מבצעים את הנתיב האופציונלי של רשת מאובטחת, צריך להגדיר את DOMAIN_NAME (למשל, agw.example.com). אחרת, אפשר להתעלם מההגדרה הזו.

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"

terraform/backend.conf מוחרג מ-Git. כל משתמש שומר עותק משלו.

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

אם משתמשים בנתיב ברירת המחדל, אפשר לדלג על השלב הזה. אם רוצים להשתמש בהגדרה הפשוטה ביותר עם כתובות URL ציבוריות של Cloud Run, אפשר לעבור ישירות לשלב הבא.

כברירת מחדל, הגדרת הכניסה של Cloud Run במעבדה הזו מוגדרת ל-all, ורשם הסוכנים רושם כל שרת 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 peering מ-Agent Runtime) נוצר באופן אוטומטי על ידי Terraform – אין צורך ליצור אותו באופן ידני. אם הרשת הפרטית מושבתת, לא מוקצה אזור ציבורי ולא מוקצה אזור פרטי.

למדריך מפורט יותר על תבנית ה-DNS של אופק מפוצל ציבורי ופרטי שבה נעשה שימוש בהדגמה הזו (הגדרת אזור מנוהל, קישור בין רשתות שכנות (peering) ב-DNS בין רשתות VPC, תהליך אימות אישורים), אפשר לעיין במדריך להגדרת DNS.

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

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

cp terraform/example.tfvars terraform/terraform.tfvars

יש שתי דרכים לצפות בהדגמה, והן מוגבלות על ידי enable_cloud_run_private_networking.

נתיב ברירת מחדל: Cloud Run עם תעבורת נתונים נכנסת (ingress) ציבורית

**ההגדרה הכי פשוטה.**בנתיב ברירת המחדל צריך לערוך רק שלושה ערכים ב-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:[e-mail]"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

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

רשת פרטית (אופציונלי)

מגדירים את enable_cloud_run_private_networking = true ומוסיפים את המשתנים הבאים כדי להקצות את מחסנית האבטחה המלאה:

• מאזן עומסים פנימי של אפליקציות (ALB)
• אישור שמנוהל על ידי Google
• ‫Cloud Run עם ingress = internal-and-cloud-load-balancing
• שירות Agent Gateway DNS peering.

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"

התמונות של Cloud Run שלמעלה מצביעות על פלייסולדר של Google. זה מכוון – Terraform יוצר את שירותי Cloud Run עם lifecycle { ignore_changes = [template[0].containers[0].image] }, כך שהפעלות skaffold run הבאות מחליפות את קובץ האימג' בלי ש-Terraform יתנגד להן.

הערך של agent_gateway_subnet_cidr צריך להיות לפחות /28, בהתאם ל-RFC 1918, ואסור שיהיה חפיפה בין agent_gateway_subnet_cidr לבין 10.0.0.0/24,‏ 10.0.1.0/24 או 10.0.2.0/24. הטווחים האלה שמורים ליציאה מ-Agent Gateway.

האיזון העומסים הפנימי של MCP משרת TLS עבור *.mcp.${DOMAIN_NAME} באמצעות אותו אישור אזורי בניהול Google. אל תגדירו את mcp_internal_dns_zone.domain לסיומת שלא ניתן לנתב כמו mcp-server.internal. בזמן שגם enable_agent_gateway = true וגם enable_cloud_run_private_networking = true.

נכון לעכשיו, Agent Gateway לא מאמת את אישור הגיבוי עם החתימה העצמית. ההגדרה הזו נאכפת על ידי בלוק check בהגדרות Terraform בזמן התכנון (היא מדלגת על זה כשמכבים את הרשת הפרטית, כי אין אישור של איזון עומסים לאימות).

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

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

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

‫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 והרחבות הגנה מוגברת על המודל, ‏ both authorization policies, ‏ וה-roles/iap.egressor grant ברמת הפרויקט
• נקודות קצה של Agent Registry‏ (Vertex AI, ‏ IAP, ‏ Discovery Engine וכו') בתוספת שלושת שרתי ה-MCP (רשומים ב-*.run.app/mcp כברירת מחדל, וב-./mcp כשהרשת הפרטית מופעלת)

רק כשenable_cloud_run_private_networking = true:

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

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

לעיון בלבד. הפקודות בקטע הזה כבר הופעלו בשבילכם על ידי המודול agent-registry-endpoints של Terraform. הן מוצגות כדי שתוכלו לראות בדיוק איך נראה רישום של נקודת קצה שאפשר לגלות באמצעות MCP.

מאגר הסוכנים הוא קטלוג של שירותים (ממשקי 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 הזה כבר יובא על ידי Terraform. קוד ה-YAML שבהמשך הוא המקבילה המדויקת של terraform/modules/agent-gateway/main.tf.

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}

בגרסה הנוכחית של terraform-provider-google-beta עדיין אין אפשרות להשתמש ב-network_config.dns_peering_config. ‫Terraform מחיל את ההגדרה באמצעות PATCH post-apply ב-networkservices.googleapis.com/v1beta1. הסכום יוצג בterraform_data.dns_peering במודול.

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

לעיון בלבד. ‫Terraform כבר יצר את שני התוספים ואת שני כללי המדיניות. הפקודות שבהמשך מגיעות ישירות מ-terraform/modules/agent-gateway/main.tf.

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

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

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

התוסף הגנה מוגברת על המודל CONTENT_AUTHZ שלמעלה יזהה אוטומטית את תבניות ההגדרה המתקדמות האלה בפעם הבאה שהוא יעריך תגובה – לא צריך לשנות את התוסף. מוודאים שלסוכן השירות של הגנה מוגברת על המודל (service-${PROJECT_NUMBER}@gcp-sa-modelarmor.iam.gserviceaccount.com) יש את התפקידים roles/dlp.user ו-roles/dlp.reader בפרויקט (מודול model-armor של Terraform כבר מעניק את התפקידים האלה).

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

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. פריסת סוכן המשכנתאות לזמן ריצה של סוכן

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

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 \
  --model-endpoint-location=global

הסוכן מגלה כלי MCP בזמן הריצה על ידי רישום mcpServers במאגר הסוכן בקטע projects/${PROJECT_ID}/locations/${REGION}.

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

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 במאגר סוכני ה-AI ב-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. שער הסוכן מפרסם מאפיינים לכל כלי ש-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" \
  --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 כוללת סביבת Sandbox שמאפשרת לכם לשוחח בצ'אט ישירות עם הסוכן שנפרס. זו הדרך הכי מהירה לבצע בדיקת עשן לקריאות לכלים ולבדוק עקבות לפני שמחברים את הסוכן ל-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 [e-mail]

הסוכן צריך לזהות שאין לו גישה לכלי send_email ולהגיב בהתאם.

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

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

ב-Playground אין אימות של Gemini Enterprise, ולכן זה המקום הכי מהיר לוודא שהתוסף IAP REQUEST_AUTHZ מעניק גישה לשימוש בכלים בצורה תקינה. אם כלי מחזיר כאן 403, מריצים מחדש את scripts/grant_agent_mcp_egress.sh לפני שמבצעים ניפוי באגים מעמיק יותר.

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

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

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 [e-mail]

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

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 (סוכן משכנתאות) ומתחילים בצ'אט.

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

ההנחיה הראשונית:

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 [e-mail]

אם חוזרים לקטע Agent Deployment במסוף, בוחרים את פריסת הסוכן ועוברים אל הכרטיסייה traces, עכשיו אפשר לראות את סוכן Gemini Assistant ביחידה הלוגית למעקב שבה מוצגת השיחה שמקורה ב-Gemini Enterprise.

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

• ‫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, וששער הסוכן מילא את הרישום (הוא עושה זאת באופן עצלני ברשימת הכלים הראשונה שמועברת דרך ה-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.

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

מנוע הנימוקים לא מנוהל על ידי 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

19. מזל טוב

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

מה למדתם

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

מסמכי עזר

• סקירה כללית של מדיניות ניהול הסוכנים
• מסמכי תיעוד של Agent Gateway
• מאמרים בנושא זהות הסוכן
• סקירה כללית של פלטפורמת הסוכנים של Gemini Enterprise