תעבורת יציאה מ-Agent Gateway מ-Agent Runtime לרשת VPC

1. מבוא

ב-Codelab הזה נסביר על ניהול תעבורת נתונים יוצאת (egress) של Agent Gateway עבור סוכני AI שניגשים לנקודות קצה מרוחקות דרך רשת VPC פרטית. Agent Gateway שפועל במצב יציאה (agent-to-anywhere) תומך בקישוריות פרטית לרשת VPC באמצעות ממשקי Private Service Connect ‏ (PSC). בתרחיש הזה, Agent Runtime משתמש ב-Agent Gateway כדי לגשת לשרת MCP מרוחק של HTTP עם אפשרות סטרימינג שמתארח ב-Cloud Run באמצעות נקודת קצה (endpoint) של Private Service Connect ‏(PSC) ל-Google APIs ברשת ה-VPC.

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

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

כש-Agent Gateway פועל במצב יציאה (agent-to-anywhere), הוא משמש כשרת proxy לכל הבקשות היוצאות מסוכנים שהוגדרו לשימוש בשער. כל בקשה לעומס עבודה של סוכן מאומתת באמצעות זהות הסוכן הייחודית ומקבלת הרשאה באמצעות כללי מדיניות של שרת proxy לאימות זהויות (IAP). השיחות עם כלי ה-MCP מפוענחות ונבדקות באופן דינמי לצורך אכיפת המדיניות. אדמינים של אבטחה יכולים לאכוף הרשאות ברמת פירוט גבוהה באופן מרכזי, כדי לוודא שהסוכנים יכולים להפעיל רק נקודות קצה ושיטות שאושרו.

מה תפַתחו

  • Agent Gateway ביציאה (במצב agent-to-anywhere)
  • תוסף הרשאות של שרת proxy לאימות זהויות (IAP)
  • סוכן Agent Runtime ADK עם זהות סוכן
  • שרת HTTP MCP שניתן להזרמה ב-Cloud Run
  • Agent Registry עם Google API ונקודות קצה מותאמות אישית של MCP
  • כללי מדיניות של הרשאות עם בקרת גישה של IAM
  • משאבי רשת VPC, אזור Cloud DNS ונקודת קצה (endpoint) של PSC עבור Google APIs
  • צירוף רשת PSC לתעבורה יוצאת (egress) של Agent Gateway
  • כללי מדיניות של חומת אש Cloud Next Generation Firewall (NGFW)

figure1

איור 1. ארכיטקטורת Codelab

מה לומדים

  • איך פורסים את Agent Gateway ברצף מובנה של הגדרות
  • איך מגדירים Agent Gateway עם קישוריות פרטית לרשת VPC
  • איך מעבירים כללי מדיניות הרשאה ממצב הרצת בדיקה למצב אכיפה
  • איך רושמים נקודות קצה של Google API ושרתי MCP ב-Agent Registry
  • איך בודקים את היומנים של Agent Gateway כדי לאמת את ניהול היציאה
  • איך מאמתים את תנועת היציאה של Agent Gateway באמצעות יומנים של Cloud NGFW

מה צריך

  • פרויקט ב-Google Cloud שהחיוב בו מופעל
  • הרשאות IAM להקצאת שירותי רשת, מערכי נתונים של BigQuery ומשאבים של Agent Platform
  • מעטפת תואמת POSIX‏ (bash או zsh) עם Google Cloud CLI (רכיבי gcloud ו-bq) מותקן
  • כלי שורת פקודה: git,‏ curl,‏ jq (מעבד JSON),‏ Python 3 ו-uv (מנהל חבילות Python)

2. מושגים

רצף הפריסה

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

ב-Codelab הזה נעשה שימוש ברצף הפריסה הבא:

  1. התחלה במצב DRY_RUN: מוודאים שהבקשות של הסוכן מגיעות לשער ועוברות דרכו (מצב ביקורת בלבד).
  2. רישום כל השירותים: רישום כל רכיבי הסוכן במרשם הסוכנים ואישור הגישה לכלי הסוכן. אפשר להשתמש ב-Cloud Logging ובלוח הבקרה של Agent Gateway כדי לראות את השאילתות שנשלחות אל Agent Registry.
  3. יצירת מדיניות הרשאות: יוצרים ומחילים מדיניות הרשאות כדי לאפשר תנועת יציאה מסוכנים לשרתים ולנקודות קצה של MCP.
  4. מעבר למצב ENFORCED: עדכון המדיניות של תוסף ההרשאה כדי לאכוף את המדיניות ולחסום תעבורת נתונים יוצאת לא מורשית.

figure2

איור 2. רצף הפריסה

טופולוגיית ניתוב של תעבורת נתונים יוצאת (egress)

יציאה (egress) מ-Agent Gateway‏ (agent-to-anywhere) פועלת כפרוקסי יוצא מרכזי עם גישת אפס אמון לעומסי עבודה של סוכנים. כשסוכן שולח בקשה לכלי חיצוני או ל-API, בקשת היציאה נחטפת על ידי Agent Gateway ונבדקת בהתאם למדיניות השליטה לפני שהיא מנותבת ליעד שלה. בארכיטקטורה של פלטפורמת סוכנים ב-Google Cloud, שער הסוכנים מספק קישוריות של מישור הנתונים אל:

  • רשתות פרטיות (VPC): תעבורה יוצאת שמיועדת לממשקי API פנימיים של ארגונים, למיקרו-שירותים, למסדי נתונים שמתארחים ב-VPC פרטי ולרשתות מקומיות או חוצות ענן שאפשר להגיע אליהן באמצעות קישוריות היברידית.
  • רשתות חיצוניות (אינטרנט): תעבורת נתונים יוצאת שמכוונת לשירותי אינטרנט של צד שלישי, לממשקי API של SaaS או לנקודות קצה ציבוריות.
  • שירותי AI ופלטפורמת סוכנים: תעבורה יוצאת שמכוונת לממשקי Google Cloud API מנוהלים, למודלים בסיסיים, לנקודות קצה של Google MCP (כמו BigQuery) ולשירותי ניהול פלטפורמה (מאגר סוכנים ומדיניות IAP).

figure3

איור 3. טופולוגיית ניתוב ליציאה של Agent Gateway

המיקוד של שיעור Codelab הזה הוא בתעבורה יוצאת מסוכן מותאם אישית ב-Agent Runtime שמכוונת לנקודת קצה של PSC for Google APIs שנפרסה ברשת VPC. הארכיטקטורה הזו מאפשרת גישה פרטית לשרת MCP שמתארח ב-Cloud Run באמצעות צירוף רשת PSC לתעבורת נתונים יוצאת (egress) של Agent Gateway.

קישוריות ל-VPC

יציאה של Agent Gateway (agent-to-anywhere) יכולה להתחבר לרשת VPC על ידי ציון networkConfig: egress: networkAttachment: [URI] בקובץ ההגדרות של פריסת ה-YAML. ההגדרה הזו קובעת כללי ניתוב ב-Agent Gateway לשליחת תעבורת נתונים שמנותבת לכתובות IP פרטיות דרך החיבור לרשת PSC אל רשת ה-VPC.

figure4

איור 4. קישוריות VPC של Agent Gateway

ה-Agent Gateway יכול לפתור שמות מארחים של DNS פרטי באמצעות קישור בין רשתות שכנות (peering) ב-Cloud DNS לפרויקט יעד ולרשת VPC שצוינו. כל התחומים הפרטיים שמופיעים בהגדרה של dnsPeeringConfig: domains: [NAME] ישתמשו ברשומות Cloud DNS בפרויקט היעד. כל שאילתת DNS אחרת תשתמש במקודד ה-DNS הציבורי של Cloud DNS ב-VPC כברירת מחדל.

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

3. הגדרה

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

כדי ליצור את המשאבים ב-Codelab הזה, צריך את התפקידים הבאים:

קטגוריה

תפקיד IAM נדרש (מזהה)

תיאור

ניהול API

roles/serviceusage.serviceUsageAdmin

הפעלת שירותי Google Cloud API

נטוורקינג ושער

roles/networkservices.admin

הקצאת Agent Gateway

תוספים לשירותים

roles/serviceextensions.admin

הגדרת תוספי ניתוב

אבטחת רשתות

roles/networksecurity.admin

פריסת מדיניות הרשאות

Agent Registry

roles/agentregistry.admin

מארחים מורשים בקטלוג

‫Vertex AI וסוכנים

roles/aiplatform.admin

פריסת עומסי עבודה של Agent Runtime

מדיניות לגבי תעבורת נתונים יוצאת (egress)

roles/iap.admin

החלת מדיניות roles/iap.egressor

Cloud Storage

roles/storage.admin

ניהול של קטגוריות אחסון של פריסות בשלב ההכנה

יומנים וביקורת

roles/logging.viewer

בדיקת עקבות ויומני ביקורת

Cloud Run Developer

roles/run.developer

פריסת שירותים ב-Cloud Run

קורא של Artifact Registry

roles/artifactregistry.reader

שליפת קובצי אימג' של קונטיינרים

אדמין של רשת מחשוב

roles/compute.networkAdmin

ניהול משאבי רשת VPC

אדמין DNS

roles/dns.admin

ניהול של תחומים ורשומות ב-Cloud DNS

אפשר גם להשתמש בתפקיד בסיסי רחב כמו roles/admin או בתפקיד מדור קודם כמו roles/owner.

גישה לפרויקט

בשיעור Codelab הזה משתמשים בפרויקט אחד ב-Google Cloud. בשלבי ההגדרה נעשה שימוש בפקודות של gcloud CLI ושל מעטפת Linux.

כדי להתחיל, ניגשים לשורת הפקודה של הפרויקט ב-Google Cloud:

הגדרת מזהה הפרויקט

gcloud config set project SET_YOUR_PROJECT_ID_HERE

אימות הסשן

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

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

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-weather"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

אם אתם מריצים התקנה בניהול עצמי של Google Cloud SDK (כלומר, מחוץ ל-Cloud Shell), אתם צריכים לעדכן את הרכיבים לגרסה האחרונה.

# update gcloud cli
gcloud components update

הפעלת שירותי API

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

כאן מסתיים החלק של ההגדרה... עכשיו עוברים לקטע רשת.

4. רשת

רשת ה-VPC נפרסת באמצעות מצב מותאם אישית כדי ליצור תת-רשתות רגילות שתומכות בחיבור הרשת של PSC ל-Agent Gateway ולתעבורת נתונים יוצאת (egress) ישירה של VPC ב-Cloud Run.

נקודת הקצה של PSC ל-Google APIs נפרסת באמצעות /32כתובת IPv4 פנימית גלובלית אחת כדי לתמוך בגישה פנימית פרטית ל-Cloud Run. כתובת ה-IP הזו לא מוקצית מאף רשת משנה אזורית.

יצירת רשתות

יוצרים רשת VPC גלובלית.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

יוצרים תת-רשתות לצירוף רשת PSC של Agent Gateway ולתעבורת נתונים יוצאת (egress) ישירה של Cloud Run VPC.

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

יצירת כללים לחומת האש

יוצרים מדיניות וכלל של חומת אש שמאפשרים את כל תעבורת הנתונים היוצאת עם הפעלת הרישום ביומן. השירות הזה ישמש למעקב אחר תנועת הנתונים שיוצאת מ-Agent Gateway לרשת ה-VPC.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

יצירת קובץ מצורף לרשת PSC

יוצרים רכיב רשת מסוג PSC שמוגדר לקבל אוטומטית חיבורים חדשים של ספקי שירותים.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

אימות של צירוף לרשת PSC

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

יצירת נקודת קצה של PSC

יוצרים שמירת כתובת IP לנקודת הקצה הגלובלית של PSC. הכתובת שבה משתמשים כאן לא יכולה להיות מתוך רשת משנה קיימת או לחפוף לה.

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

יוצרים נקודת קצה (endpoint) של PSC עבור Google APIs באמצעות חבילת all-apis, שכוללת את Cloud Run ‏(run.app).

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

אימות של נקודת קצה של PSC

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

יצירת תחום DNS ורשומות

יוצרים תחום מנוהל פרטי ב-Cloud DNS לדומיין run.app.

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

יוצרים רשומת DNS עם תו כללי A בשביל *.run.app. שמפנה לכתובת ה-IP של נקודת הקצה (endpoint) של PSC.

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

יוצרים מדיניות Cloud DNS כדי להפעיל רישום ביומן של שאילתות DNS.

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

יצירת Cloud NAT

יוצרים Cloud Router ו-Cloud NAT כדי לתמוך בתעבורת נתונים יוצאת (egress) ישירה של VPC ב-Cloud Run, וכך לאפשר לשרת MCP להגיע לנתוני מזג אוויר חיצוניים דרך רשת ה-VPC.

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}

# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

סיימנו את החלק שקשור לרשת... עכשיו נעבור לקטע Gateway.

5. שער

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

במקרה הזה, Agent Gateway משתמש במאגר אזורי כדי לתמוך במשאבי Agent Runtime אזוריים, ומציין את השדות networkConfig לחיבור רשת PSC של רשת ה-VPC ולהגדרת הקישור בין רשתות DNS שכנות (peering).

יצירת שער

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}-networkConfig.yaml" \
  --location=${REGION}

אימות השער

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

בודקים שיש נקודת קצה מקובלת לחיבור.

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

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

6. אישור

תוסף ההרשאה של Agent Gateway לשרת proxy לאימות זהויות (IAP) הוא סוג של תוסף שירות שמשמש להעברת החלטות הרשאה לכל התקשורת של Agent Platform.

  1. תהליך ההעברה: כשסוכן מנסה להפעיל נקודת קצה חיצונית או שרת MCP, הוא מנתב את הבקשה ל-Agent Gateway. במקום להעריך את הגישה באופן מקומי, שער הגישה משתמש בתוסף ההרשאות כדי לשלוח Callout לשירות ההערכה של IAP. ‫IAP מעריך את זהות הסוכן (מבוססת SPIFFE) בהשוואה למדיניות IAM של משאב היעד ב-Agent Registry. ‫IAP מחזיר החלטה ALLOW או DENY לשער, שמעביר את התנועה הלאה או חוסם אותה עם קוד סטטוס HTTP 403 Forbidden.
  2. מצבי אכיפה: במצב DRY_RUN, ‏ IAP מעריך בקשות ומתעד החלטות ב-Cloud Logging בלי לחסום תנועה. במצב ENFORCE, כל בקשה מסוכן לא מורשה או ליעד לא רשום נחסמת באופן מיידי.
  3. שכבת הקישור: תוסף השירות מקושר ל-Agent Gateway באמצעות מדיניות הרשאות שהוגדרה עם פרופיל REQUEST_AUTHZ.

תוסף הרשאה

תוסף הרשאות מציין את שירות ספק האבטחה עם הגדרות קישוריות ופרמטרים אחרים שמגדירים איך השירות יפעל ואיך הוא ישולב עם Agent Gateway.

יצירת תוסף הרשאה

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

ייבוא תוסף הרשאות

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

אימות תוסף ההרשאה

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

מדיניות הרשאה

מדיניות הרשאה מקשרת את ספק האבטחה (IAP) למשאב שער היעד ומציינת את פרופיל היירוט (REQUEST_AUTHZ).

יצירת מדיניות הרשאה

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

כריכת מדיניות הרשאות

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

אימות מדיניות ההרשאה

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

כאן מסתיים החלק של ההרשאה… עכשיו עוברים לקטע Codebase.

7. בסיס קוד

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

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

אחזור פריטי מידע שנוצרים בתהליך פיתוח (Artifact) מרחוק

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_vpc

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

יצירת קטגוריית אחסון זמנית

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

עד כאן החלק של בסיס הקוד... עכשיו נעבור לקטע Registry (מאגר מידע).

8. מרשם

‫Agent Registry הוא מלאי מרכזי של כל הסוכנים, שרתי ה-MCP ונקודות הקצה (ממשקי ה-API) בסביבת ה-AI העסקית. הוא גם קטלוג שאפשר להשתמש בו כדי לרשום, לחפש ולגלות כלים ושירותים רשומים אחרים לשימוש באפליקציות AI. ה-Agent Gateway משתמש במודל הנתונים של המרשם כבסיס למדיניות כדי לאכוף בקרת גישה ליציאה. ההרשאות של תפקידי IAM שניתנות לסוכני חשבונות משתמשים מתבצעות בהתאם למדיניות שקשורה למשאב המרכזי.

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

רישום נקודות קצה

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

אימות הרישום של נקודת קצה

# list registry regional endpoints
gcloud agent-registry endpoints list --location=${REGION} \
  --flatten="interfaces[]" \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces.url:label=URL)"

כאן מסתיים החלק שקשור לרישום... עכשיו נעבור לקטע שרת MCP.

9. שרת MCP

מתן הרשאות IAM לפריסה

נותנים הרשאות לחשבון השירות שמוגדר כברירת מחדל ב-Compute כדי לתמוך בפריסת שירותי Cloud Run מקוד מקור.

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

אימות הרשאות IAM

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

פריסת שרת MCP

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

מתן הרשאות IAM לתעבורת כניסה

קישור מדיניות לגישת משתמשים

מעניקים הרשאות לחשבון המשתמש (לעצמו) להפעלת שרת ה-MCP המתארח ב-Cloud Run. ההרשאה הזו נדרשת להרצת סקריפט ליצירת toolspec.

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

אימות הרשאות IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

יצירת SA בהתאמה אישית להפעלת MCP

יוצרים חשבון שירות בהתאמה אישית להפעלת שרת MCP שמתארח ב-Cloud Run. הסוכן ישתמש בחשבון השירות הזה כדי לאחזר אסימון מזהה OIDC חתום על ידי Google, כדי לגשת ל-Cloud Run.

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"

# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

קישור מדיניות לחשבון שירות

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

אימות הרשאות IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

מתן הרשאות IAM לאימות

מקצים תפקידים של התחזות לחשבון שירות לחשבון השירות של Compute שמוגדר כברירת מחדל. כך הסוכן, שפועל תחת Application Default Credentials ‏ (ADC), יוכל ליצור אסימונים מזהים מסוג OIDC שחתומים על ידי Google בשם חשבון השירות של שירות ההפעלה המותאם אישית, כדי לאמת קריאות ל-Cloud Run.

קישור מדיניות לאימות

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

אימות הרשאות IAM

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

יצירת MCP toolspec

כשרושמים שרת MCP באופן ידני, צריך לכלול קובץ מפרט של כלי. קובץ toolspec.json מפרט את כל הכלים שזמינים דרך שרת ה-MCP, ומאפשר למשתמשים אחרים לגלות אותם אחרי שהם נרשמים.

הסקריפט test_mcp.py, שכלול בבסיס הקוד mcp-weather/, יוצר קובץ toolspec.json על ידי התחברות לשרת ה-MCP של היעד (דרך SSE או HTTP) והפעלת list_tools() כדי לאחזר את כל הכלים הזמינים שהשרת חושף.

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)

# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

בפלט toolspec שנוצר אפשר לראות את מאפייני ה-MCP ש-Agent Gateway יכול להשתמש בהם להערכה ולאכיפה של מדיניות יציאה.

אימות של MCP toolspec

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' mcp-weather/toolspec.json

עדכון של תעבורת נתונים נכנסת (ingress) ב-Cloud Run

משנים את הגדרת הכניסה של שירות Cloud Run כך שהוא יקבל רק בקשות נכנסות מרשת ה-VPC. כך לא תהיה גישה ציבורית ישירה לנקודת הקצה של MCP, ורק משאבים פנימיים יוכלו לגשת אליה. תנועה שמיועדת לנקודת הקצה של PSC עבור ממשקי Google API ברשת ה-VPC תיחשב ככניסה פנימית ותאושר.

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

אימות של תעבורת נתונים נכנסת (ingress) ב-Cloud Run

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

רישום שרת MCP

עכשיו, כשיש לכם את toolspec, אתם צריכים לרשום את שרת ה-MCP ב-Agent Registry האזורי.

# register mcp server
gcloud agent-registry services create ${MCP_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for weather info" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=mcp-weather/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

אימות ההרשמה ל-MCP

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

בזה מסתיים הקטע בנושא שרת MCP... עכשיו נעבור לקטע בנושא סוכן ADK.

10. סוכן ADK

סוכן agent-weather ADK שנפרס ב-Agent Runtime מוגדר עם ההגדרות הבאות בסקריפט הפריסה כדי להשתלב עם Agent Platform:

  • ‫"identity_type": types.IdentityType.AGENT_IDENTITY כדי להקצות זהות ייחודית של חשבון ראשי מבוססת SPIFFE לסוכן
  • ‫"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } כדי להפנות את כל התנועה היוצאת שנוצרת על ידי סוכנים אל Agent Gateway לצורך הערכה ואכיפה של מדיניות

הסוכן מוגדר גם להשתמש בשרת MCP על ידי העברת כתובת ה-URL וחשבון השירות כדי לאחזר את אסימון המזהה של OIDC.

פריסת הסוכן

# deploy agent runtime workload
uv --directory agent-weather run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

אימות הפריסה

אחזור נתונים בסיסיים של פריסה

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

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

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

אימות הגדרות השער

# show agent config details (gateway config)
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

מתן הרשאות IAM לאימות

כשסוכן מוגדר להשתמש בזהות סוכן, הוא מקבל אסימון (בפורמט JWT-SVID) משירות אסימוני האבטחה (STS) המאוחד, שנחתם על ידי sts.googleapis.com (ספק הזהויות של SPIFFE).

עם זאת, בדיקת ה-IAM של Cloud Run שמוטמעת כברירת מחדל בודקת רק אסימונים מזהים רגילים של OIDC שחתומים על ידי מנפיק ה-OIDC הראשי של Google ‏ (accounts.google.com), וסומכת רק עליהם.

לכן, נעשה שימוש בחשבון שירות בהתאמה אישית כדי להחליף את אסימון ה-STS המאוחד (JWT-SVID) שהתקבל על ידי זהות הסוכן באסימון Google (OIDC) רגיל שהתקבל באמצעות התחזות לחשבון שירות בזמן ריצה.

יוצרים את קישורי התפקידים שנדרשים לחשבון השירות בהתאמה אישית.

קישור מדיניות לאימות (התחזות)

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

אימות הרשאות IAM

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

מתן הרשאות IAM בזמן ריצה

מתן הרשאות IAM בזמן ריצה מאפשר לסוכן לגשת לשירותי AI Platform ולממשקי API ולשירותים מרכזיים אחרים של Google באמצעות זהות הסוכן העיקרית שלו מבוססת SPIFFE. האכיפה של כללי המדיניות האלה מתבצעת באמצעות IAM ברמת המשאב.

יוצרים את הקישורים הנדרשים בין התפקידים לבין זהות הסוכן.

קישור מדיניות לגישה של סוכנים

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

אימות הרשאות IAM

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

עד כאן בנושא סוכן ADK... עכשיו נעבור לקטע מדיניות.

11. מדיניות

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

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

הקצאת תפקידי IAM ליציאה מ-Agent Gateway

ה-Agent Gateway בודק בקשות נכנסות כדי לוודא שלסוכן ששולח את הבקשה יש את ההרשאה iap.webServiceVersions.egressViaIAP (שניתנת על ידי התפקיד roles/iap.egressor) במשאב היעד.

הענקת ההרשאה roles/iap.egressor לזהות הסוכן או לקבוצת חשבונות המשתמשים של Agent Runtime במשאב היעד שנבחר מאפשרת את תנועת היציאה הזו. בשיעור Codelab הזה, התפקיד מוקצה לחשבון המשתמש agent, שנותן הרשאה לזהות הסוכן הספציפית של Agent Runtime.

מדיניות ה-IAM קשורה למשאבי היעד כפי שמוגדר במודל הנתונים של מאגר הסוכנים. המשאב iap_web/agentRegistry מייצג רמה של מאגר כולל בהיררכיית IAM. כאשר agentRegistry משמש כרכיב האב של משאבי הצאצא הנפרדים agents,‏ mcpServers ו-endpoints. ב-codelab הזה, מדיניות IAM קשורה לרמות mcpServer ו-endpoint, וההרשאה חלה על משאבי הצאצא הספציפיים.

הגדרת מדיניות של סוכן לשרת MCP

יצירת מדיניות לסוכן לשרת MCP

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

הערה: הפונקציה etag: צריכה להחזיר את ברירת המחדל ACAB כי עדיין לא הוגדרו מדיניות.

# create policy config file
cat > cfg/iap-policy-agent-to-mcp.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

איגוד מדיניות לסוכן לשרת MCP

# import policy file
gcloud beta iap web set-iam-policy cfg/iap-policy-agent-to-mcp.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

אימות הרשאות IAM

# show iap iam policy on mcp server for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

כאן מסתיים החלק בנושא מדיניות… עכשיו נעבור לקטע ביקורת.

12. ביקורת

תוסף ההרשאה של Agent Gateway פועל במצב DRY_RUN. המערכת עוקבת אחרי בקשות יוצאות ומתעדת אותן, אבל לא חוסמת אותן. ניתוח היומנים לפני המעבר למצב ENFORCED יאפשר לכם לוודא אילו כללי מדיניות צריך להגדיר כדי לאפשר את התנועה הרצויה.

בדיקת שאילתות של סוכנים

פותחים חלון דפדפן לממשק המשתמש של מסוף Google Cloud ועוברים אל:

  • Agent Platform → Agents → Deployments → agent-weather
  • לוחצים על הכרטיסייה סביבת משחקים.

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

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

שולחים כמה שאילתות לדוגמה…

  • What is the weather like in London?
  • How warm is it in New York?

מוודאים שהשאילתות מחזירות תשובות תקינות.

ניתוח של יומני ביקורת

צפייה ביומנים ובבדיקות של הערכות המדיניות.

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'

TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

הגדרת מדיניות של סוכן לנקודות קצה

ממשקי ה-API המרכזיים של Google ל-agent-weather נרשמו בשירות נקודות קצה קולקטיביות במאגר (gapi.core.services), ולכן נדרשת רק מדיניות אחת כדי להעניק הרשאות יציאה של סוכן לגישה לנקודת קצה.

יצירת מדיניות לסוכן לנקודת קצה

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

קישור מדיניות של סוכן לנקודת קצה

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-agent-to-ep.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

אימות הרשאות IAM

# show iap iam policy on endpoint for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID}

כאן מסתיים החלק של הביקורת… עכשיו נעבור לקטע החלת מדיניות.

13. אכוף

הסוכן הצליח לשלוח בקשות דרך השער במצב DRY_RUN. יומני הגישה ונקודות הקצה נותחו כדי ליצור קבוצה של מדיניות ניהול שמאפשרת את תעבורת היציאה הנדרשת מהסוכן. מעדכנים את מדיניות ההרשאה כדי להעביר את תוסף ההרשאה של Agent Gateway IAP למצב ENFORCE.

עדכון תוסף הרשאה

יצירת תוסף הרשאה

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

ייבוא תוסף הרשאות

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

אימות תוסף ההרשאה

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

עדכון מדיניות ההרשאות

יצירת מדיניות הרשאה

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

כריכת מדיניות הרשאות

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

אימות מדיניות ההרשאה

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

אימות האכיפה

חוזרים אל הסביבה הניסיונית של הסוכן בממשק המשתמש של המסוף.

  • לוחצים על הלחצן + סשן חדש כדי ליצור סשן צ'אט חדש.

שליחת שאילתת בדיקה נוספת…

  • What is the current temperature in Los Angeles?

שימו לב שבקשות הסוכן למודל הבסיסי של Gemini ‏ (${REGION}-aiplatform.googleapis.com/...) ולנקודת הקצה של שרת ה-MCP ‏ (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) מועברות עם קודי סטטוס HTTP ‏200 OK.

ניתוח יומנים של שערים

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

בודקים שאין בקשות שנחסמות. מחפשים ביומני הביקורת של השער ניסיונות יציאה שנחסמו עם קודי סטטוס HTTP‏ 403 Forbidden.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

צופים ביומנים של Agent Gateway MCP ורואים איך מטען היישום של MCP (JSON-RPC) נבדק כדי לחשוף את המטא-נתונים של הפרוטוקול, כולל הכלים שמופעלים.

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

ניתוח יומנים של חומת אש

הצגת יומנים של עדיפות כלל מדיניות חומת האש ברשת 1001.

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

שימו לב לתצוגה ברמת הרשת של נתיבי התנועה השונים:

  • שער הסוכן מתקשר עם משאבים פנימיים ברשת VPC באמצעות subnet-${REGION}-agw
  • שרת ה-MCP שמתארח ב-Cloud Run שולח קריאות לממשקי API חיצוניים של מזג האוויר באמצעות subnet-${REGION}-crun
TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

ניתוח של יומני DNS

צפייה ביומני שאילתות DNS לבקשות שנפתרו על ידי אזור ה-DNS הפרטי (priv-zone-run).

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

הערה: בדיקות DNS לשירות Cloud Run ‏ (mcp-weather...run.app) מתבצעות מרשת ה-VPC באמצעות שיתוף פעולה של DNS, והן נפתרות בהצלחה לנקודת הקצה הפנימית של PSC עבור ממשקי Google API ‏ (240.0.0.10).

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

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

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

# delete agent runtime
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete agent resources
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

for ROLE in \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next

# delete gateway resources (policy binding must be deleted synchronously first)
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION} --async

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION} --async

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION} --async

# next

# remove policies
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_REGISTRY_ID} \
  --region=${REGION}

# next

# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next

# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next

# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next

# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

כאן מסתיים החלק של הניקוי... ועכשיו עוברים אל הסיכום!

15. סיכום

מעולה! הצלחתם לפרוס את Agent Gateway ולנהל את התנועה של סוכני AI יוצאים!

cosmopup

Cosmopup thinks Codelabs are the cat's pajamas!

מה השלב הבא?

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

תודה!