ניהול סוכנים באמצעות Agent Gateway

באמצעות Agent Gateway אתם יכולים לנהל את התנועה היוצאת מסוכני ה-AI שאתם יוצרים ומארחים ב-Cloud Run. אם תנתבו את התנועה היוצאת משירות Cloud Run דרך Agent Gateway בניהול עצמי שפועל ב-Secure Web Proxy, תוכלו לאכוף כללי מדיניות גישה ריכוזיים, לבדוק את המטען הייעודי (payload) כדי לוודא שהתוכן בטוח ולאסוף נתוני טלמטריה של ניראות בעומסי העבודה של הסוכנים.

במאמר הזה מוסבר איך להגדיר ארכיטקטורה ריכוזית ל-Agent Gateway ב-Cloud Run, ואיך לבצע את הפעולות הבאות:

ארכיטקטורה

בפריסה ריכוזית בניהול עצמי, Secure Web Proxy פועל כנקודת אכיפת המדיניות ופועל בתוך רשת ה-VPC שלכם. הקונטיינר המשני (sidecar) של Ambient Networking מיירט את תעבורת הנתונים היוצאת מסוכן Cloud Run ומנתב אותה דרך Direct VPC egress למכונה של Secure Web Proxy. ‫Secure Web Proxy אוכף כללי גישה ותוכן מנקודות החלטה לגבי מדיניות, כמו שרת proxy לאימות זהויות (IAP) והגנה מוגברת על המודל.

דיאגרמת ארכיטקטורה שמראה שירות Cloud Run עם קונטיינר של סוכן וקונטיינר של קובץ עזר חיצוני (sidecar proxy) סביבתי, שמנתבים את תעבורת הנתונים דרך Direct VPC egress אל Agent Gateway בניהול עצמי שמגובה על ידי Secure Web Proxy בתוך רשת VPC.
תרשים 1. ארכיטקטורה של Agent Gateway בניהול עצמי לסוכן Cloud Run.

כדי לנתב את התנועה ולנהל אותה בארכיטקטורה הזו, צריך להגדיר את הרכיבים הבאים:

  • Direct VPC egress ו-Ambient Networking: שירות Cloud Run מתחבר לרשת ה-VPC באמצעות --vpc-egress=all ו---ambient-networking, שמשתמשים בהיקף האזורי כברירת מחדל ומנתבים את כל תעבורת הנתונים היוצאת לרשת ה-VPC.
  • ‫Agent Gateway בניהול עצמי: משאב Agent Gateway לוגי במצב ניהול עצמי, שמפנה למכונה של Secure Web Proxy ברשת ה-VPC שלכם.
  • מדיניות ניתוב של תעבורת נתונים יוצאת (egress): מדיניות של Network Services API EgressRouting שמפנה את תעבורת הנתונים היוצאת מהשירות ב-Cloud Run למכונה של Secure Web Proxy.

לפני שמתחילים

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloudליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. מפעילים את ממשקי ה-API הבאים, אם הם עדיין לא מופעלים: Cloud Run Admin API,‏ Network Services API,‏ Network Security API,‏ Service Extensions API,‏ Model Armor API,‏ Certificate Authority Service API,‏ Certificate Manager API,‏ Cloud Resource Manager API,‏ App Hub API,‏ Identity and Access Management API,‏ Identity-Aware Proxy API,‏ Compute Engine API,‏ Traffic Director API,‏ Cloud DNS API,‏ Network Connectivity API ו-Agent Registry API.

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם אתם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, אתם יכולים לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

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

  13. יוצרים רשת VPC ותת-רשת, ומפעילים בתת-רשת את גישה פרטית ל-Google.
  14. מגדירים את Agent Registry בפרויקט או בארגון.
  15. התקן ואתחל את ממשק שורת הפקודה (CLI) של גוגל קלאוד.
  16. מעדכנים את הרכיבים של ה-CLI של gcloud: 
    gcloud components update

התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות להגדרת Agent Gateway ל-Cloud Run, בקשו מהאדמין להקצות לכם את התפקידים הבאים ב-IAM בפרויקט:

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

אם אתם מגדירים פריסה בכמה פרויקטים עם VPC משותף, בקשו מהאדמין להקצות לכם את התפקיד roles/compute.xpnAdmin ברמת הארגון או התיקייה.

יצירת Agent Gateway בניהול עצמי

לפני שיוצרים את המשאב של Agent Gateway, צריך לפרוס ולהגדיר מכונה של Secure Web Proxy ברשת ה-VPC, כמו שמתואר במאמר פריסת Secure Web Proxy בתור Agent Gateway:

  1. מגדירים בדיקת TLS ויוצרים מדיניות אבטחה של שער שמצרפת את TlsInspectionPolicy. אתם לא צריכים כללים של מדיניות אבטחה או רשימות של כתובות URL ב-Secure Web Proxy.
  2. יצירת משאב ServerTlsPolicy באמצעות allowOpen: false ו-mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT. אל תגדירו את clientValidationTrustConfig.
  3. פורסים מכונה של Secure Web Proxy במצב ניתוב מפורש של שרת proxy, עם addresses,‏ ports,‏ certificateUrls,‏ gatewaySecurityPolicy ו-serverTlsPolicy שמוגדרים כשיוצרים את השער, כדי ש-Cloud Run יעביר את Workload Identity של הסוכן ל-Secure Web Proxy ול-IAP דרך mTLS.

אחרי שהמכונה של Secure Web Proxy מוכנה, יוצרים משאב של Agent Gateway בניהול עצמי שמפנה למכונה של Secure Web Proxy:

  1. יוצרים קובץ תצורה בפורמט YAML בשם my-agent-gateway.yaml:

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫AGENT_GATEWAY_NAME: השם שרוצים לתת למשאב של Agent Gateway.
    • ‫PROJECT_ID: מזהה הפרויקט שמארח את המכונה של Secure Web Proxy.
    • ‫REGION: האזור של מכונת Secure Web Proxy, למשל us-central1.
    • ‫SWP_NAME: השם של מכונת Secure Web Proxy.

  2. מייבאים את ההגדרות של Agent Gateway:

    gcloud beta network-services agent-gateways import AGENT_GATEWAY_NAME \
   --source="my-agent-gateway.yaml" \
   --location=REGION \
   --project=PROJECT_ID

  3. מאמתים את המשאב של Agent Gateway:

    gcloud beta network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID

    לפני שממשיכים לחלק הבא, מוודאים שהפלט מציג את ההגדרות של selfManaged ואת ה-URI של המשאב של המכונה של Secure Web Proxy.

הגדרת Ambient Networking ב-Cloud Run כדי לגשת ל-Traffic Director API

כשמגדירים שירות Cloud Run עם Direct VPC egress ו---vpc-egress=all, כל החיבורים היוצאים ממכונת הקונטיינר מנותבים דרך רשת ה-VPC. זה כולל את החיבור של Envoy sidecar ל-trafficdirector.REGION.rep.googleapis.com.

כדי לאפשר ל-sidecar לזהות את Traffic Director API ולהגיע אליו, צריך להגדיר אזור פרטי ב-Cloud DNS ברשת ה-VPC, בהתאם לשימוש של הסביבה ב-VPC Service Controls:

בלי VPC Service Controls

אם בפרויקט לא משתמשים ב-VPC Service Controls, יוצרים תחום Cloud DNS פרטי שמנתב בקשות ל-trafficdirector.REGION.rep.googleapis.com אל כתובת ה-IP של שער Secure Web Proxy, כדי ש-Secure Web Proxy יאפשר לתנועה לעבור:

  1. מאחזרים את כתובת ה-IP הפנימית של שער Secure Web Proxy:

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫SWP_NAME: השם של מכונת Secure Web Proxy.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫REGION: האזור של הפריסה.

  2. יוצרים אזור מנוהל פרטי ב-Cloud DNS בשביל Traffic Director API:

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    מחליפים את VPC_NETWORK_NAME בשם של רשת ה-VPC.

  3. מוסיפים רשומת A שמפנה את הדומיין האזורי של Traffic Director API לכתובת ה-IP של Secure Web Proxy:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. מוודאים שקבוצת רשומות ה-DNS פעילה באזור הפרטי:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    מוודאים שרשומת A של trafficdirector.REGION.rep.googleapis.com. מפנה לכתובת ה-IP של Secure Web Proxy.

עם VPC Service Controls

בסביבות של VPC Service Controls, מקצים נקודת קצה אזורית של Private Service Connect שמטרגטת את Traffic Director API האזורי בתוך רשת המשנה של ה-VPC, וממפים את הדומיין באמצעות תחום Cloud DNS פרטי:

  1. יוצרים נקודת קצה אזורית של Private Service Connect שמטרגטת את Traffic Director API האזורי:

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫REGION: האזור של הפריסה.
    • ‫VPC_NETWORK_NAME: השם של רשת ה-VPC
    • ‫VPC_SUBNET_NAME: השם של רשת המשנה של ה-VPC.

  2. מאחזרים את כתובת ה-IP הפנימית של נקודת הקצה האזורית:

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. יוצרים אזור מנוהל פרטי ב-Cloud DNS בשביל Traffic Director API:

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. מוסיפים רשומת A שמפנה את הדומיין האזורי של Traffic Director API לכתובת ה-IP של נקודת הקצה האזורית:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. מאמתים את נקודת הקצה האזורית ואת קבוצת רשומות ה-DNS:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    מוודאים שרשומת A של trafficdirector.REGION.rep.googleapis.com. מפנה לכתובת ה-IP של נקודת הקצה האזורית.

פריסה או עדכון של שירות Cloud Run עם Ambient Networking ו-Direct VPC egress

כדי לחבר את סוכן Cloud Run למכונה של Secure Web Proxy ברשת ה-VPC, מפעילים את Direct VPC egress ואת Ambient Networking האזורית, ומגדירים את השירות עם Agent Identity. כשפורסים באמצעות --functional-type=agent ו---identity-type=agent-identity, Cloud Run מעניק את התפקיד roles/run.agentDefaultAccess, שכולל את ההרשאות roles/trafficdirector.client ו-roles/cloudtrace.agent:

  1. פורסים שירות חדש של סוכן Cloud Run או מעדכנים שירות קיים כדי להפעיל רשתות מקומיות אזוריות, תעבורת נתונים יוצאת ישירה של VPC לכל התנועה היוצאת ו-Agent Identity:

    שירות חדש

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    שירות קיים

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫SERVICE_NAME: השם של שירות הסוכן ב-Cloud Run.
    • ‫IMAGE_URL: הפניה לקובץ האימג' של הקונטיינר, לדוגמה us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, המאגר REPO_NAME כבר צריך להיות קיים. הפורמט של כתובת ה-URL הוא LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • ‫VPC_NETWORK_NAME: השם של רשת ה-VPC שמארחת את המכונה של Secure Web Proxy. מידע נוסף על יצירת רשת VPC ורשת משנה זמין במאמר יצירה וניהול של רשתות VPC.
    • ‫VPC_SUBNET_NAME: השם של תת-הרשת של ה-VPC שבה אפשר לגשת למכונה של Secure Web Proxy.
    • ‫REGION: האזור של השירות.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

  2. מוודאים ששירות Cloud Run משתמש ב-Ambient Networking, בתעבורת נתונים יוצאת ישירה של VPC וב-Agent Identity:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    מוודאים שבפלט מוצגים רשת המשנה של התעבורה היוצאת של Direct VPC, התעבורה היוצאת של all-traffic, הרשת הסביבתית האזורית וחשבון המשתמש שהוקצה לזהות הסוכן.

הגדרת הסוכן ב-Cloud Run כך שיסמוך על Agent Gateway

כדי ש-Secure Web Proxy יוכל לבדוק את המטענים הייעודיים (payloads) של HTTPS ולאכוף כללי מדיניות, הוא צריך לסיים סשנים יוצאים של TLS מהסוכן. מאגר הסוכנים של Cloud Run צריך לתת אמון באישור של רשות האישורים (CA) הראשית או המשנית שמשויכת למדיניות בדיקת ה-TLS של Secure Web Proxy בשירות CA או ב-PKI הפרטי של הארגון:

  1. מייצאים את אישור ה-CA בקידוד PEM ממאגר שירות ה-CA למכונה של Secure Web Proxy:

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫CA_POOL_NAME: השם של מאגר ה-CA שמשויך למדיניות בדיקת ה-TLS של Secure Web Proxy.
    • ‫REGION: האזור של מאגר ה-CA.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

  2. מעדכנים את שירות Cloud Run כדי להעביר את תוכן האישור במשתנה סביבה:

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫SERVICE_NAME: השם של שירות הסוכן ב-Cloud Run.
    • ‫REGION: האזור של השירות.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .

    לדוגמה, הסקריפט הבא של נקודת הכניסה של מאגר Debian או Ubuntu,‏ entrypoint.sh, מתקין את AGENT_GATEWAY_ROOT_CERT במאגר האישורים של המערכת ומייצא את נתיבי חבילת ה-CA ללקוחות Python ו-gRPC לפני הפעלת האפליקציה:

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. מוודאים שהשירות מגדיר את משתנה הסביבה AGENT_GATEWAY_ROOT_CERT:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

ניתוב תעבורת נתונים יוצאת אל Agent Gateway

אחרי שמגדירים את שירות Cloud Run ואת Agent Gateway, יוצרים מדיניות EgressRouting של Network Services API כדי להפנות את התנועה היוצאת משירות Cloud Run לשער של Secure Web Proxy:

  1. יוצרים את המשאב EgressRouting:

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫REGION: האזור של שירות Cloud Run והשער.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫SWP_NAME: השם של משאב ה-Secure Web Proxy Gateway הבסיסי, ולא של משאב ה-AgentGateway.
    • ‫SERVICE_NAME: השם של שירות הסוכן ב-Cloud Run. כדי לנתב את כל שירותי Cloud Run בפרויקט דרך השער באמצעות מדיניות אחת, מגדירים את workloadUri לערך //run.googleapis.com/projects/PROJECT_ID או //run.googleapis.com/projects/PROJECT_NUMBER.

    אחרי שההגדרה EgressRouting נכנסת לתוקף, כל התנועה היוצאת משירות Cloud Run מנותבת דרך Secure Web Proxy. בקטע הבא מוסבר איך להגדיר כללי מדיניות כדי לאפשר בקשות יוצאות ולנהל אותן.

  2. מוודאים שהמשאב EgressRouting פעיל:

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    מוודאים שבשדה sources מופיע ה-URI של עומס העבודה ב-Cloud Run, ובשדה gateway מופיע משאב השער של Secure Web Proxy.

הגדרת כללי מדיניות ב-Agent Gateway

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

  • סינון תנועה בסיסית וכלים של MCP: מאפשרים נקודות קצה של מודלים ושיטות וכלים מאושרים של Model Context Protocol‏ (MCP) באמצעות ALLOW מדיניות הרשאה.
  • בקרת גישה מבוססת-זהות: מקשרים את IAP למשאב ExtensionBinding ומגדירים מדיניות גישה מאוחדת של IAM כדי לקבוע אילו נציגים יכולים לקרוא לשרתי MCP, לכלים או לנקודות קצה ספציפיים.
  • אבטחת תוכן: מקשרים את Model Armor למשאב ExtensionBinding כדי לבדוק ולנקות פרומפטים ותשובות, וכך למנוע החדרת פרומפטים, דליפת מידע רגיש או הפרות מדיניות.

המערכת מתעלמת מכללי מדיניות ההרשאה או מכללי מדיניות האבטחה של השער שמצורפים למשאב Gateway הבסיסי של Secure Web Proxy. אחרי שיוצרים או מעדכנים משאב ExtensionBinding, יכול להיות שיעברו עד חמש דקות עד שהשינויים יתעדכנו בשער. כדי לראות את רצף הערכת הכללים בכללי הרשת, בדיקת TLS, קישורי תוספים וכללי HTTP, עיינו בקטע סדר ההערכה של כללי ההרשאה.

אישור תעבורת נתונים בסיסית יוצאת ותעבורת נתונים של MCP

כברירת מחדל, Secure Web Proxy דוחה את כל תעבורת הנתונים היוצאת עם שגיאות 403 Forbidden, עד שALLOW AuthzPolicy במשאב Agent Gateway מאפשר זאת.

מכיוון שהשירות של Cloud Run משתמש ב---vpc-egress=all, כל תעבורת הנתונים היוצאת של הקונטיינר, כולל קריאות API לכלי MCP ובקשות ל-LLM, מנותבת דרך השער. מצרפים ALLOW כללי מדיניות הרשאה למשאב Agent Gateway לשני סוגי התנועה:

הגדרת כללי מדיניות של תעבורת נתונים יוצאת (egress) ב-IAP

‫Agent Gateway משתמש ב-IAP כמנוע לקבלת החלטות לגבי מדיניות, כדי להעריך את כללי המדיניות של IAM Unified Access Policies. כדי לאכוף את כללי המדיניות של זהות הסוכן, מגדירים את כללי הגישה במדיניות גישה מאוחדת (UAP) ב-IAM ומקשרים את IAP לשער:

  1. יוצרים מערכת גישה מאוחדת לכללי מדיניות (UAP) של IAM באמצעות ישות מורשית Agent Identity של שירות Cloud Run, ‏principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME, ומקשרים את המדיניות לפרויקט או לשער לפי ההוראות במאמרים יצירת מדיניות גישה של IAM וקישור מדיניות גישה מאוחדת לפרויקט.
  2. מקשרים את IAP,‏ iap.googleapis.com, ל-Agent Gateway באמצעות ExtensionBinding, לפי ההוראות במאמר קישור של IAP ל-Agent Gateway.

‫--vpc-egress=all שולח קריאות למודל כמו REGION-aiplatform.googleapis.com דרך השער, לכן צריך להגדיר את ההיקף matchConditions ב-IAP ExtensionBinding ל-prefix: "urn:mcp" כדי שהקריאות למודל יעקפו את ההערכה של IAP. כדי לנהל גם את התנועה בין הסוכנים, צריך להוסיף את prefix: "urn:agent". אם קישור התוסף תואם למארחים אחרים, צריך להוסיף כלל הרשאה לכל מארח במדיניות הגישה המאוחדת (UAP) של IAM, למשל destination.unregistered.host == 'REGION-aiplatform.googleapis.com'. לדוגמה, ראו יצירת מדיניות לנקודת קצה לא רשומה של נציג.

הגדרת כללי מדיניות של Model Armor

כדי לבדוק את ההנחיות והתשובות שעוברות דרך Agent Gateway ולהסיר מהן תוכן זדוני או רגיש, צריך ליצור תבניות של Model Armor ולקשר אותן לשער:

  1. יוצרים תבניות אזוריות של בקשות ותגובות להגנה מוגברת על המודל, ומקצים את התפקידים הנדרשים לסוכן השירות של Service Extensions לפי ההוראות במאמר הגדרת הגנה מוגברת על המודל בשער.
  2. מצרפים את התבניות ל-Agent Gateway באמצעות ExtensionBinding, לפי ההוראות במאמר קישור של Model Armor להסרת תוכן זדוני או רגיש מהנחיות ומתשובות.

הגדרת פריסה מרכזית בכמה פרויקטים באמצעות VPC משותף

בארגון עם כמה פרויקטים, אתם יכולים לפרוס את הסוכנים של Cloud Run בפרויקט שירות אחד או יותר, ולארח את Agent Gateway, מכונה של Secure Web Proxy ו-Agent Registry בפרויקט מארח ייעודי של רשתות באמצעות VPC משותף:

  • פרויקט א', פרויקט שירות של סוכן: מארח את שירות הסוכן של Cloud Run ואת המדיניות המקומית של EgressRouting.
  • פרויקט ב', פרויקט מארח של שער ורשתות: משמש כפרויקט המארח של ה-VPC המשותף, וצריך לארח את Agent Gateway, מכונה של Secure Web Proxy, ‏Agent Registry, משאבי ExtensionBinding וקישורי מדיניות IAM.
דיאגרמת ארכיטקטורה של פרויקטים שונים, שבה פרויקט א' מארח שירות Cloud Run ומדיניות ניתוב של תעבורת נתונים יוצאת, ומחובר דרך רשת VPC משותפת לפרויקט ב' שמארח את Agent Gateway, ‏Secure Web Proxy ו-Agent Registry.
איור 2. פריסת Agent Gateway בפרויקטים שונים באמצעות VPC משותף.

לפני שמתחילים את השלבים האלה, צריך להפעיל את run.googleapis.com,‏ compute.googleapis.com,‏ networkservices.googleapis.com ו-trafficdirector.googleapis.com בפרויקט א', ואת aiplatform.googleapis.com אם הנציג שלכם קורא ל-Vertex AI. בפרויקט ב', פורסים את המכונה של Secure Web Proxy ואת המשאב של Agent Gateway ברשת ה-VPC המשותפת, כמו שמתואר במאמר יצירת Agent Gateway בניהול עצמי, ומגדירים את הניתוב של DNS או של Private Service Connect כמו שמתואר במאמר הגדרת Ambient Networking ב-Cloud Run כדי לגשת ל-Traffic Director API, כדי שרכיבי ה-sidecar הסביבתיים בפרויקט א' יוכלו לגשת ל-Traffic Director API.

כדי להגדיר פריסה בכמה פרויקטים:

  1. מגדירים את פרויקט ב' כפרויקט מארח של VPC משותף, מצרפים את פרויקט א' כפרויקט שירות ומשתפים את תת-הרשת שמארחת את המכונה של Secure Web Proxy. כדי להפעיל VPC משותף ולצרף פרויקטים של שירות, צריך את ההרשאה roles/compute.xpnAdmin ברמת הארגון או התיקייה. הוראות מפורטות זמינות במאמרים שליחת תנועה לרשת VPC משותפת באמצעות תנועה יוצאת של Direct VPC והקצאת VPC משותף.

  2. בפרויקט ב', מקצים את התפקיד roles/compute.networkUser בתת-הרשת המשותפת לסוכן השירות של Cloud Run מפרויקט א':

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
   --role="roles/compute.networkUser"

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫SHARED_SUBNET_NAME: השם של רשת המשנה המשותפת בפרויקט ב'.
    • ‫PROJECT_B_ID: מזהה הפרויקט של פרויקט B, שהוא הפרויקט המארח של השער ושל ה-VPC המשותף.
    • ‫REGION: האזור של רשת המשנה המשותפת.
    • ‫PROJECT_A_NUMBER: מספר הפרויקט של פרויקט א', פרויקט השירות של הסוכן.

  3. פורסים את שירות הסוכן של Cloud Run בפרויקט א' ומפנים אותו לרשת המשנה המשותפת בפרויקט ב':

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫SERVICE_NAME: השם של שירות הסוכן של Cloud Run בפרויקט א'.
    • ‫PROJECT_A_ID: מזהה הפרויקט של פרויקט A, פרויקט השירות של הסוכן.
    • ‫IMAGE_URL: הפניה לקובץ האימג' של הקונטיינר, לדוגמה us-docker.pkg.dev/cloudrun/container/hello:latest. אם אתם משתמשים ב-Artifact Registry, המאגר REPO_NAME כבר צריך להיות קיים. הפורמט של כתובת ה-URL הוא LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

    אחרי פריסת השירות, מגדירים את הסוכן בפרויקט א' כך שיסמוך על אישור ה-CA הבסיסי של מכונת ה-Secure Web Proxy בפרויקט ב', לפי השלבים שמפורטים בקטע הגדרת סוכן Cloud Run כך שיסמוך על Agent Gateway.

  4. יוצרים מדיניות EgressRouting בפרויקט א' שמפנה לשער Secure Web Proxy בפרויקט ב'. בפרויקט א' צריכה להיות לכם ההרשאה roles/networkservices.admin:

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    מחליפים את CENTRAL_SWP_NAME בשם של שער Secure Web Proxy בפרויקט ב'. כדי לנתב את כל שירותי Cloud Run בפרויקט א' דרך השער של פרויקט ב', מגדירים את workloadUri לערך //run.googleapis.com/projects/PROJECT_A_ID או //run.googleapis.com/projects/PROJECT_A_NUMBER.

  5. מוודאים שהמשאב EgressRouting בפרויקט A פעיל:

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. מגדירים מדיניות בסיסית ריכוזית, מדיניות IAP ומדיניות הגנה מוגברת על המודל במשאב Agent Gateway בפרויקט ב', כמו שמתואר בקטע הגדרת כללי מדיניות ב-Agent Gateway:

    • מאפשרים תעבורת נתונים בסיסית של MCP ומודלים במשאב Agent Gateway בפרויקט ב', לפי ההוראות במאמר איך מאפשרים תעבורת נתונים בסיסית של MCP ותעבורת נתונים יוצאת.
    • כדי לתת לסוכן בפרויקט א' הרשאה לשלוח קריאות לשרתי MCP שרשומים בפרויקט ב', יוצרים מדיניות גישה מאוחדת של IAM בפרויקט ב' שרשימת ה-principals שלה מפנה למספר הפרויקט של פרויקט א', principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME, מקשרים את המדיניות לפרויקט ב' או למשאב Agent Gateway שלו, ומצרפים את ה-ExtensionBinding של IAP בפרויקט ב'.
    • כדי להחיל את מעקות הבטיחות המרוכזים של Model Armor בפרויקט ב', צריך ליצור את התבניות האזוריות של Model Armor, להקצות את התפקידים הנדרשים לסוכן השירות של Service Extensions בפרויקט ב' ולצרף את ExtensionBinding של Model Armor למשאב Agent Gateway בפרויקט ב'.

הצגת יומנים ומעקבים

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

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

אזורים נתמכים

אתם יכולים להשתמש ב-Agent Gateway ב-Cloud Run באזורים הבאים:

  • europe-west1
  • us-central1

מגבלות

בנוסף למגבלות של Ambient Networking ולשיקולים לגבי Secure Web Proxy שמפורטים במאמר פריסת Secure Web Proxy בתור Agent Gateway, כשמשתמשים ב-Agent Gateway עם Cloud Run חלות המגבלות הבאות:

  • בקשות של סוכנים יוצאים שמנותבות דרך מכונה של Secure Web Proxy לבדיקת TLS לנקודות קצה (endpoints) של *.mtls.googleapis.com ו-*.mtls.run.app נכשלות עם שגיאות 503, כי Secure Web Proxy מסיים ומפעיל מחדש סשנים של TLS בלי להעביר את אישור הלקוח.
  • כל Agent Gateway אזורי בניהול עצמי תומך לכל היותר ב-Agent Registry אזורי אחד ברשימת registries שלו.
  • כברירת מחדל, כל פרויקט תומך בעד 10 משאבי AgentGateway אזוריים ו-10 משאבי EgressRouting אזוריים לכל אזור. בפרויקטים חדשים, המגבלה יכולה להתחיל ב-2 לכל אזור. כדי לבקש להגדיל את המכסה, פנו לצוות ניהול החשבון.
  • אתם צריכים לייצא את אישור הבסיס או האישור המשני ממאגר שירות ה-CA או מה-PKI הפרטי של הארגון, ולהגדיר את מאגר ה-Agent כך שיסמוך עליו.

המאמרים הבאים