ניהול Agent Gateway

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

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

לפני שאתם מנהלים את המשאבים של Agent Gateway, ודאו שאתם עומדים בדרישות המוקדמות הבאות:

הצגה ובדיקה של שערים

אתם יכולים להציג את רשימת המשאבים של Agent Gateway בפרויקט ב- Google Cloud, ולבדוק את ההגדרות של השער, את התוספים שמצורפים אליו ואת המטא-נתונים לפלט בלבד.

המסוף

  1. נכנסים לדף Gateways במסוף Google Cloud .

    כניסה לדף Gateways

  2. צפייה ברשימת השערים בפרויקט שנבחר.

  3. לוחצים על שם השער כדי לפתוח את דף הפרטים שלו:

    • בכרטיסייה Details, בודקים את הקטעים Overview,‏ Access authorization,‏ AI Security,‏ Service Extensions ו-VPC configuration.
    • בכרטיסייה Observability, בודקים את מדדי התנועה והמדיניות של השער. איך עוקבים אחרי התנועה ב-Agent Gateway

gcloud

  • הצגת רשימה של כל השערים באזור ספציפי:

    gcloud network-services agent-gateways list \
      --location=LOCATION \
      --project=PROJECT_ID
    

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

    • ‫LOCATION: האזור שבו נפרסו השערים, למשל us-central1.
    • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloudשמארח את השערים.
  • בודקים את ההגדרות של שער ספציפי:

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

    מחליפים את AGENT_GATEWAY_NAME בשם של המשאב Agent Gateway.

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

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

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

נתיב גישה מנוהל

(AGENT_TO_ANYWHERE או CLIENT_TO_AGENT)

לא ניתן לשינוי מוגדר בזמן היצירה ב-googleManaged.governedAccessPath. אי אפשר לשנות את המיקום.

מחבר רשת של Private Service Connect

(networkAttachment)

אי אפשר לשנות את השדה אחרי שמגדירים אותו אחרי שמשייכים חיבור לרשת לשער, אי אפשר לשנות או להסיר אותו.

תבנית הקישוריות של הנציג והגדרות ה-VPC, ה-TLS וה-DNS המשויכות אליה

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

החלפת שער כדי לשנות הגדרות שלא ניתנות לשינוי

אם אתם צריכים לשנות הגדרה שלא ניתנת לשינוי, כמו מחבר הרשת של PSC שמשויך לשער, אתם צריכים לפרוס שער חלופי ולהעביר את עומסי העבודה לשער החדש:

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

    • אפליקציות Gemini Enterprise: מעדכנים את שם המשאב של השער בהגדרות אבטחה > הגדרה של האפליקציה. ניתוב התנועה של Gemini Enterprise דרך Agent Gateway
    • סוכני Agent Runtime: בפרויקט ובאזור אחד, כל סוכני Agent Runtime חייבים להיות מקושרים לאותו שער. אי אפשר לעדכן ישירות שער אחד לשער אחר. כדי להעביר את הנציגים:
      1. מוודאים שכל סוכן מקושר מנתב 100% מהתנועה לגרסה האחרונה שלו (trafficConfig.trafficSplitAlwaysLatest).
      2. מבטלים את השיוך של כל הסוכנים בפרויקט ובאזור לשער הקודם, על ידי הגדרת spec.deploymentSpec.agentGatewayConfig ל-{} באמצעות reasoningEngines.patch, וממתינים עד שכל פעולת עדכון תסתיים.
      3. מפעילים את reasoningEngines.patch בכל סוכן כדי להגדיר את spec.deploymentSpec.agentGatewayConfig לשם המשאב של שער ההחלפה. במאמר ניתוב תנועה של Agent Runtime דרך Agent Gateway מופיעות דוגמאות לבקשות.
  3. אחרי שכל עומסי העבודה מפסיקים להפנות לשער הקודם, פועלים לפי השלבים שמפורטים בקטע מחיקת Agent Gateway כדי להסיר את השער הקודם.

עדכון של Agent Gateway

אתם יכולים לעדכן הגדרות מסוימות של Agent Gateway ישירות במסוף Google Cloud , או להשתמש ב-CLI של gcloud כדי לייצא את הגדרות השער לקובץ YAML, לבצע את השינויים ולייבא מחדש את הקובץ.

עדכון מרשם הסוכנים

אפשר לעדכן את Agent Registry שמשויך במסוףGoogle Cloud או ב-CLI של gcloud. השער צריך להפנות למרשם האזורי היחיד שתואם לאזור של השער. אם השער מקושר לאפליקציית Gemini Enterprise, השער צריך לכלול מרשם אחד שתואם למיקום של האפליקציה.

המסוף

  1. נכנסים לדף Gateways במסוף Google Cloud .

    כניסה לדף Gateways

  2. לוחצים על השם של השער שרוצים לעדכן.

  3. בכרטיסייה Details, בקטע Overview לוחצים על Edit registries.

  4. בוחרים את ה-Agent Registry האזורי שתואם לאזור שבו השער פרוס, ולוחצים על Save.

gcloud

מייצאים את הגדרות השער אל agent-gateway.yaml באמצעות gcloud network-services agent-gateways export, עורכים את registries, description או labels (מסירים שדות פלט בלבד כמו createTime, updateTime, agentGatewayCard ו-selfLink) ומייבאים מחדש את הקובץ באמצעות gcloud network-services agent-gateways import, כמו שמוסבר בקטע עדכון תבנית הקישוריות של השער.

עדכון תבנית הקישוריות

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

gcloud

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

  2. מייצאים את הגדרת השער הקיימת לקובץ YAML:

    gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \
     --destination="agent-gateway.yaml" \
     --location=LOCATION \
     --project=PROJECT_ID
    

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

    • ‫AGENT_GATEWAY_NAME: שם השער שרוצים לעדכן.
    • ‫LOCATION: האזור שבו נפרס שער הגישה.
    • ‫PROJECT_ID: מזהה הפרויקט שבו נפרס שער הגישה.
  3. בקובץ agent-gateway.yaml שיוצא, משאירים את השדות protocols,‏ registries,‏ description ו-labels כמו שהם, מסירים את השדות לפלט בלבד (createTime,‏ updateTime,‏ agentGatewayCard,‏ selfLink) ומעדכנים את agentConnectivityTemplate כך שיפנה לתבנית החדשה:

    name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
    protocols:
      - MCP
    googleManaged:
      governedAccessPath: AGENT_TO_ANYWHERE
    registries:
      - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION
    agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME
    

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

    • ‫PROJECT_NUMBER: מספר הפרויקט שבו השער נפרס (ב-agentConnectivityTemplate צריך להזין את מספר הפרויקט ולא את מזהה הפרויקט).
    • ‫LOCATION: האזור של השער.
    • ‫AGENT_GATEWAY_NAME: שם השער.
    • ‫NEW_TEMPLATE_NAME: השם של תבנית הקישוריות החלופית.
  4. מייבאים מחדש את קובץ ה-YAML המעודכן כדי להחיל את השינויים:

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
     --source="agent-gateway.yaml" \
     --location=LOCATION \
     --project=PROJECT_ID
    
  5. אופציונלי: מוחקים את תבנית הקישוריות הקודמת אחרי שעדכון השער מסתיים:

    gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \
     --location=LOCATION \
     --project=PROJECT_ID
    

לשנות את הגדרות ה-IAP או את התבניות של Model Armor

כדי לשנות את הגדרות האכיפה של IAP ואת התבניות של Model Armor, אתם יכולים לעדכן את התוספים שמפנים לבדיקת הרשאות שמצורפים לשער.

המסוף

  1. נכנסים לדף Gateways במסוף Google Cloud .

    כניסה לדף Gateways

  2. לוחצים על השם של השער שרוצים לעדכן.

  3. בכרטיסייה פרטים, מעדכנים את תוספי האבטחה המצורפים:

    • שינוי מצב האכיפה של IAP: בקטע Access authorization, לצד Access authorization, לוחצים על Edit access authorization. בוחרים באפשרות ביקורת בלבד (מצב פרימטר לבדיקות) או אכיפת כללי מדיניות, ואז לוחצים על שמירה.

    • שינוי התבניות של Model Armor: בקטע AI Security, לוחצים על Edit request template ליד Template for requests או על Edit response template ליד Template for responses. בוחרים את התבנית החלופית ולוחצים על שמירה.

gcloud

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

    gcloud service-extensions authz-extensions list \
     --location=LOCATION \
     --project=PROJECT_ID
    

    מחליפים את LOCATION באזור של השער ואת PROJECT_ID במזהה הפרויקט.

  2. בודקים את ההגדרות הנוכחיות של התוסף:

    gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \
     --location=LOCATION \
     --project=PROJECT_ID \
     --format=yaml
    

    מחליפים את AUTHZ_EXTENSION_NAME בשם של המשאב ב-IAP או ב-Model Armor AuthzExtension.

  3. שומרים את מפרט התוסף המעודכן ב-authz-extension.yaml, ומשמיטים שדות פלט בלבד כמו createTime ו-updateTime:

    • בתוסף IAP: מוסיפים את iamEnforcementMode: "DRY_RUN" למצב ביקורת בלבד, או מסירים את iamEnforcementMode כדי לאכוף את כללי המדיניות:

      name: AUTHZ_EXTENSION_NAME
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
        iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policies
      
    • בתוסף Model Armor: מעדכנים את request_template_id ו-response_template_id ב-metadata.model_armor_settings:

      name: AUTHZ_EXTENSION_NAME
      service: modelarmor.LOCATION.rep.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        model_armor_settings: '[
          {
            "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
            "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
          }
        ]'
      

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

      • ‫AUTHZ_EXTENSION_NAME: השם של המשאב AuthzExtension ב-Model Armor.
      • ‫LOCATION: האזור של השער.
      • ‫MODEL_ARMOR_PROJECT_ID: מזהה הפרויקט שמארח את התבניות של Model Armor.
      • ‫REQUEST_TEMPLATE_ID ו-RESPONSE_TEMPLATE_ID: המזהים של תבניות הבקשה והתשובה.

      מוודאים שלחשבון השירות של השער (agentGatewayCard.serviceExtensionsServiceAccount) יש את התפקיד roles/modelarmor.user בכל פרויקט תבנית חדש שמפנים אליו, וגם את התפקידים roles/modelarmor.calloutUser ו-roles/serviceusage.serviceUsageConsumer בפרויקט השער (ראו הקצאת הרשאות).

  4. מייבאים את קובץ ה-YAML המעודכן של התוסף:

    gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \
     --source="authz-extension.yaml" \
     --location=LOCATION \
     --project=PROJECT_ID
    

כדי לצרף כללי מדיניות הרשאה חדשים או לשנות את הכללים להתאמת תנועה ב-AuthzPolicy קיים, קראו את המאמר הקצאת הרשאות.

ביטול השיוך של עומסי עבודה ל-Agent Gateway

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

ביטול השיוך של אפליקציית Gemini Enterprise

אפשר לבטל את הקישור של Agent Gateway לאפליקציית Gemini Enterprise במסוף Google Cloud :

  1. נכנסים לדף Gemini Enterprise במסוף Google Cloud .

    אל Gemini Enterprise

  2. לוחצים על השם של האפליקציה שמשויכת לשער.

  3. לוחצים על אבטחה.

  4. בכרטיסייה Configuration, בקטע Agent Gateway configuration, מוחקים את השדה Agent Gateway resource name.

  5. לוחצים על Save.

אם מבטלים את השיוך של Agent Gateway, התנועה היוצאת של האפליקציה מפסיקה לעבור דרך השער. הסוכנים והשרתים של Model Context Protocol‏ (MCP) שיובאו נשארים רשומים ב-Agent Registry, אבל לאפליקציה אין גישה אליהם עד שמקשרים שוב שער. חשוב לזכור שהשער החדש צריך להפנות לאותו מרשם סוכנים.

ביטול השיוך של סוכן Agent Runtime

אי אפשר לשנות את הקישורים של שער Agent Runtime במסוף Google Cloud וב-CLI של gcloud. כדי לבטל את השיוך של Agent Gateway לסוכן Agent Runtime פרוס, בלי להפסיק את הפעולה של הסוכן, אתם יכולים להפעיל את ה-method של ה-API בארכיטקטורת REST‏ reasoningEngines.patch כדי למחוק את spec.deploymentSpec.agentGatewayConfig:

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

  2. שולחים בקשת PATCH למנוע החשיבה הרציונלית עם updateMask=spec.deploymentSpec.agentGatewayConfig ואובייקט agentGatewayConfig ריק ({}):

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

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

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

מחיקת Agent Gateway

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

  • יש לפחות סוכן אחד של Agent Runtime או אפליקציה אחת של Gemini Enterprise שעדיין מפנים לשער.
  • כל AuthzPolicy (ל-IAP, להגנה מוגברת על המודל או לספק בהתאמה אישית) או TelemetryPolicy עדיין מטרגטים את השער.
  • פעולת עדכון של הגדרת VPC עדיין פועלת בשער.

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

המסוף

  1. מוודאים שאין אפליקציות של Gemini Enterprise או סוכנים של Agent Runtime שמפנים לשער. פועלים לפי ההוראות במאמר ביטול השיוך של עומסי עבודה ל-Agent Gateway.
  2. נכנסים לדף Gateways במסוף Google Cloud .

    כניסה לדף Gateways

  3. לוחצים על שם השער שרוצים למחוק.

  4. בכרטיסייה Details, מסירים את כל שיוכי המדיניות שמטרגטים את השער:

    • אם מופיע הקטע Access authorization, לוחצים על Remove ומאשרים את המחיקה. הפעולה הזו מוחקת גם את AuthzPolicy של ה-IAP וגם את AuthzExtension שלו.
    • אם מופיע הקטע AI Security, לוחצים על Remove ומאשרים את המחיקה. הפעולה הזו מוחקת גם את AuthzPolicy של Model Armor וגם את AuthzExtension שלו.
    • בודקים את הטבלה Service Extensions. אם נשארו משאבי AuthzPolicy מותאמים אישית, צריך להשתמש בכרטיסייה gcloud בתהליך הזה כדי למחוק אותם לפני שממשיכים.
  5. אחרי שמסירים את כל שיוכי המדיניות ואין עדכון VPC בתהליך, לוחצים על Delete ומאשרים את המחיקה.

  6. מוודאים שהשער לא מופיע יותר ברשימה Gateways של הפרויקט.

  7. אופציונלי: אם אין שער אחר שמשתמש במשאבי הקישוריות, אפשר לנקות אותם. בכרטיסייה gcloud, מוחקים את AgentConnectivityTemplate ומוחקים את חיבור הרשת.

gcloud

  1. מוודאים שאין אפליקציות של Gemini Enterprise או סוכנים של Agent Runtime שמפנים לשער. פועלים לפי ההוראות במאמר ביטול השיוך של עומסי עבודה ל-Agent Gateway.
  2. מסירים את כללי מדיניות ההרשאות ואת התוספים שמפנים לבדיקת הרשאות:

    1. מציגים את מדיניות ההרשאות באזור של השער כדי למצוא כללי מדיניות שהשדה target.resources שלהם מפנה לשער, ורושמים את כל הערכים של authzExtensions שאליהם מפנים:

      gcloud network-security authz-policies list \
        --location=LOCATION \
        --project=PROJECT_ID \
        --format="yaml(name,target.resources,customProvider.authzExtension.resources)"
      

      מחליפים את LOCATION באזור של השער ואת PROJECT_ID במזהה הפרויקט.

    2. מוחקים כל AuthzPolicy שמטרגט את השער:

      gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \
        --location=LOCATION \
        --project=PROJECT_ID
      

      מחליפים את AUTHZ_POLICY_NAME במזהה של כל מדיניות הרשאה שמטרגטת את השער (לדוגמה, AGENT_GATEWAY_NAME-iap-authzpolicy או AGENT_GATEWAY_NAME-aisecurity-authzpolicy למדיניות שנוצרה במסוף).

    3. אופציונלי: אחרי שמוחקים את המשאבים של AuthzPolicy שמפנים למשאבים של , מוחקים את המשאבים של AuthzExtension שלא נמצאים בשימוש של כללי מדיניות אחרים:

      gcloud service-extensions authz-extensions delete AUTHZ_EXTENSION_NAME \
        --location=LOCATION \
        --project=PROJECT_ID
      

      מחליפים את AUTHZ_EXTENSION_NAME במזהה של תוסף שמפנה לבדיקת הרשאות שלא בשימוש.

  3. מוחקים את Agent Gateway:

    gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \
     --location=LOCATION \
     --project=PROJECT_ID
    

    מחליפים את AGENT_GATEWAY_NAME בשם של השער שרוצים למחוק.

  4. מוודאים ששער הגישה לא מופיע יותר ברשימת שערי הגישה האזוריים:

    gcloud network-services agent-gateways list \
     --location=LOCATION \
     --project=PROJECT_ID
    
  5. אופציונלי: אי אפשר למחוק AgentConnectivityTemplate אם Agent Gateway מפנה אליו. אחרי שמוחקים את השער, מוחקים את כל תבניות הקישוריות שלא בשימוש:

    gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \
     --location=LOCATION \
     --project=PROJECT_ID
    

    מחליפים את CONNECTIVITY_TEMPLATE_NAME בשם של תבנית הקישוריות שלא בשימוש. אם אתם לא צריכים יותר את המשאבים הבסיסיים של Private Service Connect (מחבר הרשת, אזורי Cloud DNS פרטיים או משאבי TrustConfig של Certificate Manager), קראו את המאמר מחיקת מחברי רשת.

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

מדריך

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

מדריך

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

מדריך

איך מגדירים Agent Gateway.

פתרון בעיות

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