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

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

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

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

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

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

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

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

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

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

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

    gcloud

    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.

    1. מקצים את התפקיד בהתאמה אישית בפרויקט של השער לסוכן השירות של Agent Runtime בפרויקט של הסוכן:
    gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
    --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform." \
    --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

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

    Terraform

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

    variable "runtime_project_numbers" {
  type        = set(string)
  description = "Project numbers hosting cross-project Agent Runtime workloads"
  default     = ["AGENT_RUNTIME_PROJECT_NUMBER"]
}

resource "google_project_iam_custom_role" "ar_agw_cross_project_sa" {
  project     = "AGENT_GATEWAY_PROJECT_ID"
  role_id     = "ar_agw_cross_project_sa"
  title       = "Runtime Agent Gateway Cross-Project SA"
  description = "Custom role for cross-project service agents to access Agent Gateway"
  permissions = [
    "networkservices.agentGateways.get",
    "networkservices.operations.get",
  ]
}

resource "google_project_iam_member" "ar_agw_cross_project_binding" {
  for_each = var.runtime_project_numbers

  project = "AGENT_GATEWAY_PROJECT_ID"
  role    = google_project_iam_custom_role.ar_agw_cross_project_sa.name
  member  = "serviceAccount:service-${each.value}@gcp-sa-aiplatform."
}

  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.

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

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

      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: מזהה הפרויקט שבו הנציג פרוס
      • ‫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

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

      כדי לשייך סוכן קיים לשער Agent-to-Anywhere לתעבורת נתונים יוצאת, משתמשים בבקשת 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": {
        "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 לתעבורת נתונים נכנסת, משתמשים בבקשת ה-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 (תעבורת נתונים נכנסת)
      • ‫RESOURCE_ID: מזהה המשאב של הנציג

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

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

    gcloud 

    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: מזהה המשאב של הנציג

    Terraform 

    resource "google_agent_registry_service" "runtime_agent_entry" {
  project      = "AGENT_GATEWAY_PROJECT_ID"
  location     = "REGION"
  service_id   = "RUNTIME_AGENT_SERVICE_NAME"
  display_name = "RUNTIME_AGENT_DISPLAY_NAME"

  endpoint_spec {
    no_spec {}
  }

  interfaces {
    url              = "https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID"
    protocol_binding = "jsonrpc"
  }
}

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

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

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

    gcloud 

    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

    Terraform 

    resource "google_iap_agent_registry_endpoint_iam_member" "egress_binding" {
  project     = "AGENT_GATEWAY_PROJECT_ID"
  location    = "REGION"
  endpoint_id = "AGENT_ENDPOINT_ID"
  role        = "roles/iap.egressor"
  member      = "MEMBER"
}

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

    • ‫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/*

      במחרוזות ה-principal האלה, 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 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 או Agent Platform 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. במסוף Google Cloud , נכנסים לדף Deployments ב-Agent Platform.

      מעבר אל Deployments

    2. לוחצים על השם של הנציג שפרסתם.

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

    4. לוחצים על Deployment details. הגדרות הכניסה והיציאה של 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 (תנועה יוצאת) לסוכן שנפרס עם קובץ אימג' של קונטיינר בהתאמה אישית (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: מזהה הפרויקט שבו השער פרוס

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

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

    # 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'

    שולחים את ה-build של קובץ האימג' של הקונטיינר ל-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 Gateway מאושרים

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

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

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

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

  1. כדי להגדיר אילוץ בהתאמה אישית למצב "סוכן לכל מקום" (תעבורת נתונים יוצאת), יוצרים קובץ בשם 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. כדי להגדיר אילוץ בהתאמה אישית למצב Client-to-Agent (כניסה), יוצרים קובץ בשם 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 דקות לכל היותר.

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

מגבלות

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

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

  • אי אפשר לקשר Agent Gateway למנועי חשיבה רציונלית של סביבת זמן ריצה שנוצרו לפני 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 Engine לא זמין כש-Agent Gateway מופעל לסוכן.

  • במצב "מלקוח לסוכן" (ingress),‏ 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.

פתרון בעיות

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