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

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

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

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

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

  1. יצירת Agent Gateway

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

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

    הוראות מפורטות מופיעות במאמר הגדרת Agent Gateway.

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

  2. אופציונלי: הגדרת גישה לשער יציאה בין פרויקטים

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

    1. יוצרים תפקיד IAM בהתאמה אישית בפרויקט של Agent Gateway:

      gcloud iam roles create ar_agw_cross_project_sa \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --title="Runtime Agent Gateway Cross-Project SA" \
  --description="Custom role for the cross-project service agent to access Agent Gateway" \
  --permissions="networkservices.agentGateways.get,networkservices.operations.get"

      מחליפים את AGENT_GATEWAY_PROJECT_ID במזהה הפרויקט שבו נפרס Agent Gateway.

    2. מקצים את התפקיד בהתאמה אישית בפרויקט השער לסוכן השירות של Agent Runtime בפרויקט הסוכן:

      gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
  --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

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

  3. הגדרת הסוכן לניתוב תנועה דרך Agent Gateway

    בהתאם לפריסה של סוכן חדש או להגדרה של סוכן קיים, בוחרים באחת מהאפשרויות הבאות:

    • לנציגים חדשים שמשתמשים ב-Python SDK

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

      אם רוצים להשתמש בתכונות של הפלטפורמה בתיווך שער כמו הגנה מוגברת על המודל או מדיניות פיקוח בשפה טבעית עם הסוכן הזה, צריך להגדיר גם את agent_gateway_config וגם את identity_type=AGENT_IDENTITY בקריאת היצירה, כמו בדוגמה הזו. ה-backend אוכף את identity_type = "AGENT_IDENTITY" ברמת ה-API בכל פעם שצוין agent_gateway_config, וכתוצאה מכך אימות הפריסה נכשל אם הזהות של מכונת זמן הריצה הושמטה או הוגדרה באופן שגוי.

      נציג לכל מקום 

      remote_agent = client.runtimes.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_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_PROJECT_ID: מזהה הפרויקט שבו נפרס Agent Gateway
      • ‫REGION: האזור שבו הסוכן והשער נפרסים
      • ‫AGENT_GATEWAY_TO_ANYWHERE_NAME: השם של Agent Gateway שיצרתם במצב Agent-to-Anywhere (יציאה)

      לקוח לנציג 

      remote_agent = client.runtimes.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "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,
      }
  },
)

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

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

    • לסוכנים חדשים שמשתמשים ב-Terraform

      כשמקצים את הסוכן באמצעות Terraform, משתמשים בספק google-beta ומגדירים את הבלוק agent_gateway_config בתוך המשאב google_vertex_ai_reasoning_engine. פרטים על הגדרת Terraform זמינים במאמר הקצאת סוכנים באמצעות Terraform.

      מסוכן לכל מקום

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

      resource "google_vertex_ai_reasoning_engine" "agent" {
provider = google-beta

project      = "AGENT_RUNTIME_PROJECT_ID"
region       = "REGION"
display_name = "AGENT_DISPLAY_NAME"
description  = "AGENT_DESCRIPTION"

spec {
  identity_type = "AGENT_IDENTITY"

  container_spec {
    image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
  }

  deployment_spec {
    agent_gateway_config {
      agent_to_anywhere_config {
        agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
      }
    }
  }
}
}

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

      • ‫AGENT_RUNTIME_PROJECT_ID: מזהה הפרויקט שבו סוכן Cloud Build נפרס
      • ‫REGION: האזור שבו הסוכן והשער נפרסים
      • ‫AGENT_DISPLAY_NAME: השם המוצג של הנציג
      • ‫AGENT_DESCRIPTION: תיאור של הסוכן
      • ‫REPOSITORY: מאגר Artifact Registry שמכיל את קובץ האימג' של הקונטיינר
      • ‫IMAGE: השם של קובץ האימג' של הקונטיינר
      • ‫TAG: התג של קובץ האימג' של הקונטיינר
      • ‫AGENT_GATEWAY_PROJECT_ID: מזהה הפרויקט שבו נפרס Agent Gateway
      • ‫AGENT_GATEWAY_TO_ANYWHERE_NAME: השם של Agent Gateway שיצרתם במצב Agent-to-Anywhere (יציאה)

      לקוח לנציג

      כדי לשייך סוכן לשער Client-to-Agent לתעבורת נתונים נכנסת, משתמשים בהגדרות הבאות של Terraform.

      resource "google_vertex_ai_reasoning_engine" "agent" {
provider = google-beta

project      = "PROJECT_ID"
region       = "REGION"
display_name = "AGENT_DISPLAY_NAME"
description  = "AGENT_DESCRIPTION"

spec {
  identity_type = "AGENT_IDENTITY"

  container_spec {
    image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
  }

  deployment_spec {
    agent_gateway_config {
      client_to_agent_config {
        agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
      }
    }
  }
}
}

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

      • ‫PROJECT_ID: מזהה הפרויקט שבו נפרסו הסוכן והשער
      • ‫REGION: האזור שבו נפרסים הסוכן והשער
      • ‫AGENT_DISPLAY_NAME: השם המוצג של הנציג
      • ‫AGENT_DESCRIPTION: תיאור של הסוכן
      • ‫REPOSITORY: מאגר Artifact Registry שמכיל את קובץ האימג' של הקונטיינר
      • ‫IMAGE: השם של קובץ האימג' של הקונטיינר
      • ‫TAG: התג של קובץ האימג' של הקונטיינר
      • ‫AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: השם של Agent Gateway שיצרתם במצב Client-to-Agent (תעבורת נתונים נכנסת)

    • לסוכנים קיימים שמשתמשים ב-API בארכיטקטורת REST

      נציג לכל מקום

      משתמשים בבקשת 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/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

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

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

      מלקוח לנציג

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

      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/v1/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: מזהה המשאב של הסוכן

  4. רישום הסוכן ב-Agent Registry

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

    gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --location=REGION \
  --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
  --format="value(registryResource)"

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

    • ‫RUNTIME_AGENT_SERVICE_NAME: השם שרוצים לתת לרשומה של הסוכן במאגר
    • ‫AGENT_GATEWAY_PROJECT_ID: מזהה הפרויקט שבו שער הגישה פרוס
    • ‫REGION: האזור שבו הסוכן והשער נפרסים
    • ‫RUNTIME_AGENT_DISPLAY_NAME: השם המוצג של רשומת הסוכן במרשם, שקריא לאנשים
    • ‫RUNTIME_AGENT_PROJECT_NUMBER: מספר הפרויקט שבו סוכן זמן הריצה פרוס
    • ‫ENGINE_ID: מזהה המשאב של הסוכן

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

  5. יצירת קישור של מדיניות IAM מסוכן למאגר

    מבצעים את השלב הזה באותו פרויקט ובאותו אזור כמו Agent Gateway.

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

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

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

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

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

      • כדי לתת גישה לכל הנציגים בפרויקט: principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
      • כדי לתת גישה לכל הסוכנים בארגון: principalSet://TRUST_DOMAIN/*

      במחרוזות העיקריות האלה, TRUST_DOMAIN הוא בדרך כלל agents.global.org-ORGANIZATION_ID.system.id.goog.

  6. הוספת ממשקי API חיוניים לרשימת ההיתרים לפעולות של זמן ריצה

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

    ההתאמה של שם המארח ב-Agent Gateway היא מדויקת. אין תמיכה בתווים כלליים לחיפוש, כמו *.googleapis.com, או בקידומות. אתם צריכים לרשום כל וריאנט של שם מארח רגיל, אזורי ומאובטח (mTLS) שאפליקציית הלקוח או ה-SDK של הנציג פותרים.

    כדי להפעיל פונקציות מסוימות של Agent Platform ולהבטיח הפעלה מוצלחת וטלמטריה, צריך לאפשר תנועה לנקודות הקצה הבאות ב-Agent Registry:

    נקודות קצה חיוניות בפלטפורמה

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

    שם השירות שם מארח סטנדרטי שם המארח של mTLS וריאציות אזוריות ואחרות
    Agent Registry agentregistry.googleapis.com — —
    Cloud Logging logging.googleapis.com logging.mtls.googleapis.com —
    Cloud Trace / Telemetry telemetry.googleapis.com telemetry.mtls.googleapis.com —
    ‫Trace API cloudtrace.googleapis.com cloudtrace.mtls.googleapis.com —
    Cloud Monitoring monitoring.googleapis.com monitoring.mtls.googleapis.com —
    Secret Manager secretmanager.googleapis.com secretmanager.mtls.googleapis.com —
    מנהל המשאבים cloudresourcemanager.googleapis.com cloudresourcemanager.mtls.googleapis.com —
    IAM credentials iamcredentials.googleapis.com iamcredentials.mtls.googleapis.com —
    פלטפורמת סוכנים (aiplatform) aiplatform.googleapis.com aiplatform.mtls.googleapis.com REGION-aiplatform.googleapis.com
    REGION-aiplatform.mtls.googleapis.com
    aiplatform.REGION.rep.googleapis.com

    נקודות קצה (endpoint) ספציפיות לתכונות

    בנוסף, אם הסוכנים שלכם משתמשים בתכונות כמו 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

    במאמר רישום נקודות קצה מוסבר איך לרשום נקודות קצה. אם יש לכם הגדרה של כמה פרויקטים, אתם יכולים לרשום כמה נקודות קצה ל-API של ליבת Google בשירות יחיד של Agent Registry. מידע נוסף זמין במאמר בנושא הרשמה לנקודת קצה מורכבת של Google APIs. אתם גם צריכים לוודא שלנציג יש את ההרשאה iap.resources.egressViaIAP לנקודות הקצה האלה. הוראות מפורטות מופיעות במאמר בנושא יצירת מדיניות יציאה של סוכן לנקודת קצה.

  7. אימות ההגדרות של הנציג

    המסוף

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

      מעבר לדף Deployments

    2. לוחצים על השם של הסוכן שפרסתם.

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

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

    gcloud

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

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

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

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

הגדרת סוכנים של קונטיינר בהתאמה אישית (BYOC) ל-Agent Gateway

אם אתם רוצים לנתב תנועה יוצאת דרך Agent Gateway מסוג Agent-to-Anywhere (תעבורת נתונים יוצאת (egress)) לסוכן שנפרס עם קובץ אימג' של קונטיינר בהתאמה אישית (Bring Your Own Container / BYOC), אתם צריכים להטמיע את אישור רשות אישורי הבסיס (CA) של השער במאגר אישורים של קובץ האימג' של הקונטיינר בהתאמה אישית.

מכיוון ש-Agent Gateway מבצע פענוח ובדיקה של TLS בתקשורת של סוכנים יוצאים, פריסות של סוכנים שאינן BYOC (מבוססות מקור) מזריקות אוטומטית את האישור של רשות האישורים במהלך יצירת התמונה. אם אתם משתמשים בקובצי אימג' של קונטיינרים בהתאמה אישית, אתם צריכים לאחזר באופן מפורש את אישור ה-CA של השער, להתקין אותו במאגר האישורים המהימנים של ה-CA במערכת בתוך Dockerfile, ולהגדיר את משתני הסביבה של חבילת האישורים שנדרשים על ידי ערכות ה-SDK של Python, ספריות הלקוח של HTTP ו-gRPC.

כדי להגדיר קובץ אימג' של קונטיינר BYOC לתעבורת נתונים יוצאת של Agent Gateway:

  1. מאחזרים את אישורי הבסיס מהמשאב של Agent Gateway.

    מייצאים את מחרוזת ה-PEM של אישור הבסיס של ה-CA ישירות מהשדה agentGatewayCard.rootCertificates של משאב Agent Gateway:

    export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")

    לחלופין, אפשר להשתמש ב-API בארכיטקטורת REST כדי לאחזר את משאב השער:

    curl -s -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://networkservices.googleapis.com/v1/projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
   | jq -r '.agentGatewayCard.rootCertificates[]'

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

    • ‫AGENT_GATEWAY_NAME: השם של Agent Gateway ליציאה
    • ‫REGION: האזור שבו השער נפרס
    • ‫AGENT_GATEWAY_PROJECT_ID: מזהה הפרויקט שבו נפרס שער ה-API

  2. מעדכנים את Dockerfile כדי לתת אמון באישור ה-CA.

    מוסיפים את AGENT_GATEWAY_ROOT_CERTIFICATES build argument אל Dockerfile. פקודות ה-build מפצלות את האישורים לקבצים נפרדים, מתקינות אותם באמצעות update-ca-certificates ומגדירות משתני סביבה כך ש-OpenSSL, ספריות לקוח של HTTP ב-Python ‏ (requests, httpx) ו-gRPC יזהו את רשות האישורים המותאמת אישית:

    # Install root certificates under root user
USER root

ARG AGENT_GATEWAY_ROOT_CERTIFICATES
RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \
     echo "Installing Agent Gateway root certificates..."; \
     printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \
     update-ca-certificates; \
   fi

# Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC
ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}

# Switch back to application execution user
USER 1000

  3. יוצרים את קובץ האימג' של הקונטיינר באמצעות Cloud Build.

    יוצרים קובץ cloudbuild.yaml כדי להעביר את מחרוזת אישור הבסיס ל-Cloud Build באמצעות החלפות:

    steps:
- name: 'gcr.io/cloud-builders/docker'
  args:
  - 'build'
  - '--build-arg'
  - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}'
  - '-t'
  - '$_IMAGE_URI'
  - '.'

images:
- '$_IMAGE_URI'

    שולחים את יצירת קובץ האימג' של הקונטיינר ל-Cloud Build:

    export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest"

gcloud builds submit \
   --project=PROJECT_ID \
   --region=REGION \
   --config=cloudbuild.yaml \
   --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \
   .

    מחליפים את REPOSITORY_NAME ואת IMAGE_NAME בשמות המאגר והאימג' שלכם ב-Artifact Registry.

  4. פריסת הסוכן שמופעל באמצעות קונטיינר.

    מציינים את ה-URI של קובץ האימג' של הקונטיינר שנוצר יחד עם ההגדרה של Agent Gateway בבקשת הפריסה (באמצעות agent_gateway_config בקטע spec.deploymentSpec או באמצעות קריאות לפריסת SDK).

הגבלת Agent Runtime ל-Agent Gateways מאושרים

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

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

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

נציג לכל מקום

  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 דקות עד שהמדיניות תיכנס לתוקף.

לקוח לנציג

  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 דקות עד שהמדיניות תיכנס לתוקף.

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

מגבלות

  • אלה המגבלות של ניהול משתמשים בכמה פרויקטים:

    • קישורים בין פרויקטים בין סוכנים לשערים נתמכים רק במצב "סוכן לכל מקום" (תעבורת נתונים יוצאת). במצב Client-to-Agent (ingress), הנציג ו-Agent Gateway צריכים להיות באותו פרויקט.
    • כדי להגדיר ניהול מקצה לקצה בין פרויקטים, צריך להשתמש ב-API בארכיטקטורת REST או ב-gcloud. במסוף Google Cloud Google Cloud אי אפשר ליצור קישורי מדיניות IAM או רשומות ב-Agent Registry בין פרויקטים.

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

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

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

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

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

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

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

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

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

Codelab

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

מדריך

איך להעביר את הרשאת הגישה ל-Agent Gateway ל-IAP, ל-Model Armor או לשירות הרשאות בהתאמה אישית.

מדריך

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

פתרון בעיות

איך פותרים בעיות בקישוריות של Agent Gateway