העברת תנועה של Agent Runtime דרך Agent Gateway

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

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

  • חשוב לוודא שאתם יודעים איך פורסים סוכנים ב-Agent Runtime.

  • מידע על Agent Gateway אתם יכולים להשתמש ב-Agent Gateway במצב Agent-to-Anywhere (יציאה) כדי לאבטח ולנהל את כל התקשורת היוצאת עם תנועה יוצאת לכלים, למודלים, לממשקי API ולנציגים אחרים. אתם משתמשים בשער במצב Client-to-Agent (ingress) כדי לקבוע אילו לקוחות יכולים לגשת לסוכנים שלכם. השער מאפשר לכם לבחור אילו מדיניות בנושא רכישות מתוך האפליקציה ותבניות של Model Armor יחולו על האינטראקציות האלה.

    מופע יחיד של זמן ריצה יכול להיות משויך בו-זמנית גם לשער Agent-to-Anywhere (יציאה) וגם לשער Client-to-Agent (כניסה).

מגבלות

  • אי אפשר לקשר שער סוכן למנועי ניתוח בזמן ריצה שנוצרו לפני 29 באפריל 2026.

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

    לדוגמה, אם פרויקט ואזור מכילים את egress-gateway-X ואת egress-gateway-Y, כל הסוכנים בפרויקט ובאזור האלה צריכים להיות מוגדרים לשימוש באותו שער ליציאה. כלומר, כל הסוכנים משתמשים ב-egress-gateway-X או שכל הסוכנים משתמשים ב-egress-gateway-Y. אי אפשר להגדיר את agent-A לשימוש ב-egress-gateway-X ואת agent-B לשימוש ב-egress-gateway-Y.

    אותו כלל של צירוף חל גם על שערים של תעבורת נכנסת בתוך פרויקט ואזור.

  • שירות זיהוי האיומים של Agent Engine ב-Security Command Center לא זמין כש-Agent Gateway מופעל עבור סוכן.

  • במצב Client-to-Agent (כניסה), Agent Gateway יכול לשלוט רק בשיטות query ו-streamQuery של Agent Runtime. כדי להגן על שיטות אחרות שלא נתמכות (כמו asyncQuery), אפשר להחיל תבניות של Model Armor ישירות מהאפליקציה או מהסוכן. אפשר לעיין במאמר בנושא ניקוי הנחיות ותשובות או ב-codelab בנושא יצירת מערכת סוכנים מאובטחת באמצעות הגנה מוגברת על המודל.

העברת תנועה של Agent Runtime דרך Agent Gateway

כדי לנתב תנועה בזמן ריצה של סוכן דרך Agent Gateway, מבצעים את השלבים הבאים:

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

    מוודאים שהשער מוגדר בהתאם לצרכים של הפריסה. לדוגמה, אם הסוכן שלכם דורש גישה ל-LLM, צריך להגדיר את השער כך שיאפשר את הגישה הזו כדי למנוע כשלים פוטנציאליים בפריסת Agent Runtime.

  2. מגדירים את הסוכן לניתוב תנועה דרך Agent Gateway.

    • לנציגים חדשים

      מציינים את משאב השער בזמן פריסת הסוכן. לדוגמה, כדי לפרוס את הסוכן ב-Agent Runtime, משתמשים ב-client.agent_engines.create כדי להעביר את האובייקט local_agent יחד עם הגדרות אופציונליות.

      אם רוצים להשתמש בתכונות של פלטפורמת השער כמו Model Armor או Semantic Governance Policies עם הסוכן הזה, צריך להגדיר גם את agent_gateway_config וגם את identity_type=AGENT_IDENTITY בקריאת היצירה, כמו בדוגמה הזו. בלי identity_type=AGENT_IDENTITY, המופע של Runtime effectiveIdentity חוזר לחשבון השירות שמוגדר כברירת מחדל ב-Vertex AI, ומדיניות השליטה הסמנטית מסננת את הסוכן מהבורר של יצירת המדיניות בלי להציג הודעה.

      remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
      },
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      # Other optional configuration ...
      # "requirements": requirements,
      # "gcs_dir_name": gcs_dir_name,
      # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
      "env_vars": {
        "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
      }
  },
)

      מחליפים את AGENT_GATEWAY_TO_ANYWHERE_NAME בשם של שער הסוכן שיצרתם במצב Agent-to-Anywhere (יציאה).

      אם יצרתם שער במצב Client-to-Agent (כניסה), צריך להשתמש בשדה client_to_agent_config במקום בשדה AGENT_GATEWAY_CLIENT_TO_AGENT_NAME ולהחליף את AGENT_GATEWAY_CLIENT_TO_AGENT_NAME בשם של שער הסוכן שיצרתם לכניסה.

    • לסוכנים קיימים

      Agent-to-Anywhere

      משתמשים בבקשת ה-API ל-REST הבאה כדי לשייך סוכן קיים לשער Agent-to-Anywhere ליציאה.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "spec": {
    "deploymentSpec": {
      "agentGatewayConfig": {
        "agentToAnywhereConfig": {
          "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

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

      • ‫PROJECT_ID: מזהה הפרויקט
      • ‫REGION: האזור שבו הסוכן נפרס
      • ‫AGENT_GATEWAY_TO_ANYWHERE_NAME: השם של Agent Gateway שיצרתם במצב Agent-to-Anywhere (יציאה)
      • ‫RESOURCE_ID: מזהה המשאב של הסוכן

      Client-to-Agent

      משתמשים בבקשת REST API הבאה כדי לשייך סוכן קיים לשער Client-to-Agent לצורך תעבורה נכנסת.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "spec": {
    "deploymentSpec": {
      "agentGatewayConfig": {
        "clientToAgentConfig": {
          "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

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

      • ‫PROJECT_ID: מזהה הפרויקט
      • ‫REGION: האזור שבו הסוכן נפרס
      • ‫AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: השם של Agent Gateway שיצרתם ב-Client-to-Agent (ingress)
      • ‫RESOURCE_ID: מזהה המשאב של הסוכן

  3. נרשמים במופע של Agent Registry באותו פרויקט ואזור כמו הסוכן והשער.

    gcloud agent-registry services create SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \
  --format="value(registryResource)"

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

    • ‫SERVICE_NAME: השם שרוצים לתת למשאב, למשל allow-aiplatform-region-eu3.
    • ‫PROJECT_ID: מזהה הפרויקט.
    • ‫REGION: האזור של המאגר.
    • ‫DISPLAY_NAME: השם של נקודת הקצה שקריא לאנשים.

    מידע נוסף מופיע במאמר בנושא רישום סוכן.

  4. יוצרים קשירת מדיניות IAM מסוכן למאגר עבור הסוכן.

    gcloud iap web add-iam-policy-binding \
  --resource-type=agent-registry \
  --endpoint=ENDPOINT_ID \
  --region=REGION \
  --project=PROJECT_ID \
  --member=MEMBER \
  --role=roles/iap.egressor

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

    • ‫ENDPOINT_ID: המזהה של נקודת הקצה של השירות של הסוכן הרשום. הנתון הזה מופיע בפלט של השלב הקודם.

    • ‫MEMBER: חשבון הראשי של זהות הסוכן שרוצים להקצות לו את התפקיד. הפורמט הוא בדרך כלל: principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.

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

    • אם Cloud Trace מופעל, Agent Gateway צריך לאפשר תנועה לנקודת הקצה https://telemetry.googleapis.com/.

      אם משתני הסביבה GOOGLE_API_USE_CLIENT_CERTIFICATE ו-GOOGLE_API_USE_MTLS_ENDPOINT מוגדרים, צריך לוודא שהתעבורה אל https://telemetry.mtls.googleapis.com/ מותרת גם כן.

    • אם Cloud Logging מופעל, Agent Gateway צריך לאפשר תנועה לנקודת הקצה https://logging.googleapis.com/.

      אם משתני הסביבה GOOGLE_API_USE_CLIENT_CERTIFICATE ו-GOOGLE_API_USE_MTLS_ENDPOINT מוגדרים, צריך לוודא שהתעבורה אל https://logging.mtls.googleapis.com/ מותרת גם כן.

    בנוסף, אם הסוכנים שלכם מתקשרים עם מודלים גדולים של שפה (LLM) או משתמשים בתכונות כמו Sessions ו-Memory Bank, אתם צריכים לוודא שהסוכנים יכולים לתקשר עם נקודות הקצה שבהן השירותים האלה משתמשים. לדוגמה:

    • לסשנים: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions
    • ב-Memory Bank: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

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

    • https://REGION-aiplatform.googleapis.com
    • https://REGION-aiplatform.mtls.googleapis.com
    • https://aiplatform.REGION.rep.googleapis.com

    מידע נוסף על רישום נקודות קצה זמין במאמר רישום נקודות קצה. צריך גם לוודא שלסוכן יש את תפקיד IAP Egressor עבור נקודות הקצה האלה. הוראות מפורטות מופיעות במאמר בנושא יצירת מדיניות ליציאת נתונים מסוכן לנקודת קצה.

  6. בודקים את הגדרות הנציג.

    המסוף

    1. נכנסים לדף Deployments של Agent Platform במסוף Google Cloud .

      מעבר לדף Deployments

    2. לוחצים על השם של נציג התמיכה שהטמעתם.

    3. לוחצים על הגדרת שירות. החלונית Observability של הסוכן תיפתח.

    4. לוחצים על פרטי הפריסה. ההגדרות של כניסה ויציאה של Agent Gateway זמינות בשדה Deployment spec.

    gcloud

    כדי לוודא שהסוכן משויך עכשיו לשער, משתמשים בבקשת REST API הבאה. אם הפלט שמוחזר הוא null, המשמעות היא ש-Runtime לא הצליח להתחבר לשער.

    curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
  | jq '.spec.deploymentSpec.agentGatewayConfig'

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

    • ‫PROJECT_ID: מזהה הפרויקט
    • ‫REGION: האזור שבו הסוכן נפרס
    • ‫RESOURCE_ID: מזהה המשאב של הסוכן

הגבלת הגישה ל-Agent Runtime לשערי סוכנים שאושרו

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

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

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

Agent-to-Anywhere

  1. כדי להגדיר אילוץ מותאם אישית למצב Agent-to-Anywhere (יציאה), יוצרים קובץ בשם constraint-agent-gateway-egress.yaml.

    בדוגמה הבאה, השדה condition מציין שהפעולה מותרת רק אם צוין משאב של Agent Gateway (השדה קיים ולא ריק) ואם השער שצוין נמצא ברשימה שאושרה מראש.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

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

    • ‫ORGANIZATION_ID: מזהה הארגון.
    • AGENT_PROJECT_ID: מזהה הפרויקט.
    • ‫REGION: האזור שבו נוצר שער.
    • ‫AGENT_GATEWAY_ID: מזהה השער.

  2. החלת האילוץ המותאם אישית.

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

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

  3. יוצרים את מדיניות הארגון כדי לאכוף את האילוץ. כדי להגדיר את מדיניות הארגון, יוצרים קובץ YAML של מדיניות בשם policy-agent-gateway-egress.yaml. בדוגמה הזו אנחנו אוכפים את האילוץ הזה ברמת הפרויקט, אבל אפשר גם להגדיר אותו ברמת הארגון או התיקייה.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    מחליפים את AGENT_PROJECT_ID במזהה הפרויקט.

  4. אוכפים את מדיניות הארגון.

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    מחליפים את EGRESS_POLICY_PATH בנתיב המלא לקובץ ה-YAML של מדיניות הארגון שנוצר בשלב הקודם. יכול להיות שיחלפו עד 15 דקות לפני שהמדיניות תיכנס לתוקף.

Client-to-Agent

  1. כדי להגדיר אילוץ מותאם אישית למצב 'לקוח לסוכן' (ingress), יוצרים קובץ בשם constraint-agent-gateway-ingress.yaml.

    בדוגמה הבאה, השדה condition מציין שהפעולה מותרת רק אם צוין משאב של Agent Gateway (השדה קיים ולא ריק) ואם השער שצוין נמצא ברשימה שאושרה מראש.

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

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

    • ‫ORGANIZATION_ID: מזהה הארגון.
    • AGENT_PROJECT_ID: מזהה הפרויקט.
    • ‫REGION: האזור שבו נוצר שער.
    • ‫AGENT_GATEWAY_ID: מזהה השער.

  2. החלת האילוץ המותאם אישית.

    gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

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

  3. יוצרים את מדיניות הארגון כדי לאכוף את האילוץ. כדי להגדיר את מדיניות הארגון, יוצרים קובץ YAML של מדיניות בשם policy-agent-gateway-ingress.yaml. בדוגמה הזו אנחנו אוכפים את האילוץ הזה ברמת הפרויקט, אבל אפשר גם להגדיר אותו ברמת הארגון או התיקייה.

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    מחליפים את AGENT_PROJECT_ID במזהה הפרויקט.

  4. אוכפים את מדיניות הארגון.

    gcloud org-policies set-policy INGRESS_POLICY_PATH

    מחליפים את INGRESS_POLICY_PATH בנתיב המלא לקובץ ה-YAML של מדיניות הארגון שנוצר בשלב הקודם. יכול להיות שיחלפו עד 15 דקות לפני שהמדיניות תיכנס לתוקף.

מידע נוסף על שימוש באילוצים מותאמים אישית של מדיניות הארגון זמין במאמר יצירת אילוצים מותאמים אישית.

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

Codelab

איך שולטים בעומסי עבודה אקטיביים באמצעות Agent Gateway ב-Gemini Enterprise Agent Platform.

מדריך

כאן מוסבר איך להקצות הרשאה ל-Agent Gateway ל-IAP, ל-Model Armor או לשירות הרשאות מותאם אישית משלכם.

מדריך

איך עוקבים אחרי Agent Gateway

פתרון בעיות

כאן אפשר לקרוא על פתרון בעיות בקישוריות של Agent Gateway.