יציאה מ-Agent Gateway מ-Agent Runtime אל Google MCP

1. מבוא

בשיעור Codelab הזה נסביר על ניהול תעבורת נתונים יוצאת (egress) של Agent Gateway לסוכני AI שמתחברים לשרתים מרוחקים של Model Context Protocol‏ (MCP) ב-Google Cloud.

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

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

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

מה תפַתחו

• Agent Gateway ביציאה (מצב agent-to-anywhere)
• תוסף הרשאות של שרת proxy לאימות זהויות (IAP)
• סוכן ADK של Agent Runtime עם זהות סוכן
• Agent Registry עם Google API ונקודות קצה של MCP
• כללי מדיניות של הרשאות עם בקרת גישה של IAM
• מערך נתונים ב-BigQuery לשליחת שאילתות באמצעות MCP

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

מה לומדים

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

מה צריך

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

2. מושגים

רצף הפריסה

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

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

• התחלה במצב הרצה יבשה: אם זמן הריצה של הסוכן מוגדר לניתוב שיחות יוצאות לשער לפני שהשער הוקצה במלואו, עומס העבודה לא יאותחל. הגדרת תוסף הרשאת השער במצב DRY_RUN קודם לכן מבטיחה שכשתנועת הסוכן תגיע לשער, לא יושמטו בקשות.
• רישום כל השירותים: כל הסוכנים, שרתי ה-MCP ונקודות הקצה שמשתמשים ב-Agent Gateway צריכים להיות רשומים ב-Agent Registry. בקשות ממקורות או ליעדים לא רשומים יידחו. סוכנים שנפרסו ב-Agent Runtime ובשרתי Google MCP נרשמים באופן אוטומטי. צריך לרשום באופן ידני כל נקודת קצה ל-API של Google או שרת MCP בהתאמה אישית.
• החלת מדיניות הרשאות: מדיניות הרשאות משמשת כדי לאפשר לסוכנים רשומים גישה לרכיבים של סוכנים על ידי הקצאת התפקיד roles/iap.egressor לחשבון המשתמש של זהות הסוכן וקישורו למשאב של מאגר היעד. להעריך את התנהגות הסוכן באמצעות מצב הרצה יבשה, ואז להגדיר כללי מדיניות כדי לאפשר לתעבורת היציאה שנבחרה לעבור דרך השער. אחרי שמגדירים את המדיניות, עוברים למצב ENFORCED כדי להפעיל את השער ולאכוף באופן פעיל את מדיניות השליטה.

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

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

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

כשעומס עבודה של אפליקציית AI או של סוכן מנסה להפעיל כלי חיצוני או API, בקשת היציאה נחסמת על ידי Agent Gateway ונבדקת בהתאם למדיניות השליטה לפני שהיא מנותבת ליעד שלה:

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

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

המיקוד של שיעור Codelab הזה הוא בתעבורה יוצאת מסוכן מותאם אישית ב-Agent Runtime שמכוונת לנקודת הקצה של שרת Google MCP מרוחק עבור BigQuery.

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
BigQuery	roles/bigquery.admin	הגדרת סכימות ובדיקה של מערכי נתונים
Cloud Storage	roles/storage.admin	ניהול של קטגוריות אחסון של פריסות בשלב ההכנה
יומנים וביקורת	roles/logging.viewer	בדיקת עקבות ויומני ביקורת

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

גישה לפרויקט

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

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

• ‫Cloud Shell בכתובת shell.cloud.google.com, או
• מסוף מקומי עם gcloud CLI מותקן

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

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)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# 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-dj"
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}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

הפעלת שירותי 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 \
  discoveryengine.googleapis.com

הערה: יכול להיות שחלק מהתכונות משתמשות בפקודות של gcloud beta. אם הוא לא מותקן, מריצים את הפקודה gcloud components install beta כדי להפעיל אותו.

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

4. שער

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

במקרה הזה, Agent Gateway משתמש במאגר אזורי כדי לתמוך במשאבי Agent Runtime אזוריים.

יצירת שער

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

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

5. אישור

תוסף ההרשאה של 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.

תוסף הרשאה

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

# 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 (verify extension state)
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 (verify dry run mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

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

6. בסיס קוד

קוד הסוכן, מערך הנתונים של BigQuery וסקריפט ההרשמה שמשמשים בשיעור 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_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

יצירת מערך נתונים ב-BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

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

# 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 (מאגר).

7. מרשם

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

כדי לאתחל את הסביבה ולתמוך בסוכנים באמצעות Google APIs ושירותים שונים, נעשה שימוש בסקריפט כדי לרשום במהירות קבוצה משותפת של נקודות קצה של API באמצעות שמות מארחים ומיקומים מ-endpoints/googleapis.txt.

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

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

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

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

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

8. זמן ריצה

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

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

פריסת הסוכן

# deploy agent runtime workload
uv --directory agent-dj 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 dj contact info" \
  --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 AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

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

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

הערה: פריסת הסוכן ב-Agent Runtime יוצרת באופן אוטומטי קישור למאגר (RuntimeReference), חושפת את חשבון המשתמש של זהות הסוכן שמשמש למדיניות יציאה של IAP (RuntimeIdentity), ומציגה גילוי דינמי של נקודת קצה (protocols.interfaces).

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

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

# verify agent gateway routing specification
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}'

‫VERIFY: מוודאים שב-agentGateway מוצג ה-URI של משאב השער...
"agentGateway": "projects/PROJ_ID/locations/REGION/agentGateways/agw-SLUG-REGION-ata"

הענקת תפקידי IAM לסוכנים עבור משאבים

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

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# 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 של סוכן למשאבים

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

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

9. מדיניות

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

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

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

NOTE: בפריסת ייצור, אפשר להטמיע מדיניות מפורטת יותר כדי להגביל את התעבורה היוצאת מסוכנים ספציפיים לנקודות קצה ספציפיות. בסדנאות קוד עתידיות נסביר על אמצעי בקרה מפורטים ועל מדיניות של אישור מותנה.

הגדרת מדיניות IAM של רישום אזורי ב-IAP

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

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

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

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

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

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

10. ביקורת

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

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

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

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

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

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

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

• How many DJs do we have on file?
• What is the phone number of DJ Cosmopup?

מוודאים שהשאילתות מחזירות תשובות תקינות (למשל, יש 12 תקליטנים בקובץ).

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

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

# query gateway logs for dry run
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
  )"

אימות: בודקים שהתוצאה IAP_AUTHZ מציגה ALLOWED.

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

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

11. אכוף

הסוכן הצליח לשלוח בקשות דרך השער במצב 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 DJ Fishfry's credit card number?

שימו לב שבקשות הסוכן למודל הבסיסי של Gemini ‏ (${REGION}-aiplatform.googleapis.com/...) ולנקודת הקצה של שרת ה-MCP ‏ (bigquery.googleapis.com/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
  )"

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

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

# delete agent
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

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "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 storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# delete gateway resources
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}

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

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

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

13. סיכום

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

Cosmopup thinks Codelabs are tops!

מה השלב הבא?

• במסמכי Gemini Enterprise Agent Platform אפשר למצוא מידע על תכונות מתקדמות ומדריכים
• הגדרת אמצעי הגנה של Model Armor ב-Agent Gateway לשיפור הבטיחות והאבטחה של ה-AI
• כדאי לעיין במדיניות בנושא ניהול סמנטי כדי לאכוף כללים עסקיים ותאימות לשאילתות בשפה טבעית

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

תודה!