הגדרה של כללי מדיניות סמנטיים לניהול גישה

הגדרה של מדיניות פיקוח בשפה טבעית ומנוע המדיניות

בקטע הזה מוסבר על המעבר ממוכנות התשתית לכתיבת מדיניות.

דרישות מוקדמות

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

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

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

gcloud services enable \
    aiplatform.googleapis.com \
    agentregistry.googleapis.com \
    networkservices.googleapis.com \
    networksecurity.googleapis.com \
    compute.googleapis.com \
    dns.googleapis.com \
    --project=PROJECT_ID

הענקת הרשאות IAM לחשבון השירות של Vertex AI (רק לקישור בניהול Google)

אם משתמשים באפשרות Google-managed binding במהלך ההקצאה, צריך להעניק לחשבון השירות של Vertex AI ‏ (P4SA) את התפקידים הדרושים ליצירת נקודת הקצה של Private Service Connect ‏ (PSC) ‏(roles/compute.networkAdmin) ושל קבוצת רשומות ה-DNS ‏ (roles/dns.admin) בפרויקט. אם אתם משתמשים באפשרות Self-managed binding, אתם יכולים לדלג על השלב הזה כי אתם יוצרים את משאבי הרשת בעצמכם.

יוצרים את זהות השירות (אידמפוטנטית) ומקצים את התפקידים:

export PROJECT_NUM=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud beta services identity create \
    --service=aiplatform.googleapis.com \
    --project=PROJECT_ID

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/compute.networkAdmin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/dns.admin"

פקודות ההסרה המתאימות מופיעות בקטע הסרת הקישורים של IAM בקטע 'ניקוי'.

דרישות הסף לסוכנים

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

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

כדי לוודא שסוכן קיים עומד בדרישות, צריך לבדוק שמנוע הנימוקים שלו spec.effectiveIdentity מתחיל ב-agents.global.:

gcloud ai reasoning-engines describe REASONING_ENGINE_ID \
    --region=LOCATION \
    --project=PROJECT_ID \
    --format='value(spec.effectiveIdentity)' \
    | grep -q '^agents.global.' \
    && echo "Eligible" || echo "Not eligible"

מיקומים נתמכים

מנוע מדיניות הפיקוח הסמנטי ומדיניות הפיקוח הסמנטי נתמכים במיקומים האזוריים הבאים:

הקצאת הרשאות והפעלה

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

• קישור בניהול Google:‏ Google יוצרת את משאבי הרשת הבסיסיים בפרויקט Cloud de Confiance by S3NS שלכם ומנהלת את מחזור החיים שלהם באופן אוטומטי.
• קישור בניהול עצמי: אתם יוצרים ומנהלים את משאבי הרשת הנדרשים (network,‏ subnetwork ו-dnsZoneName) ישירות בפרויקט Cloud de Confiance by S3NS .

אחרי שמשלימים את הקצאת ההרשאות, צריך לקשר את Policy Engine ל-Agent Gateway.

קישור שמנוהל על ידי Google

curl -X PATCH \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine?updateMask=gatewayConfigs" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{ "gatewayConfigs": {
        "GATEWAY_NAME": {
          "network": "NETWORK_NAME",
            "subnetwork": "SUBNETWORK_NAME",
            "dnsZoneName": "DNS_NAME" }
        }
      }'

gcloud beta ai semantic-governance-policy-engine update \
--location=LOCATION \
--project=PROJECT_ID \
--gateway-config="name='GATEWAY_NAME',network=NETWORK_NAME,subnetwork=SUBNETWORK_NAME,dns-zone-name=DNS_NAME"

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

• GATEWAY_NAME בשם ייחודי של שער.
• ‫DNS_NAME עם השם של תחום ה-DNS הפרטי שבו רוצים להשתמש.
• ‫PROJECT_ID עם Cloud de Confiance by S3NS מזהה הפרויקט (projects/PROJECT_ID/global/networks/default). אם משתמשים ברשת וברשת משנה בהתאמה אישית, צריך להחליף את נתיבי המשאבים המלאים network ו-subnetwork בהתאם.

אחזור שם המארח של ה-DNS שנוצר באופן אוטומטי

כשמקצים את המנוע עם קישור בניהול Google, ‏ Google יוצרת באופן אוטומטי נקודת קצה (endpoint) של Private Service Connect ‏(PSC) ורושמת רשומת DNS מסוג A בתחום ה-DNS הפרטי. ה-FQDN של הרשומה הזו משמש כ-SGP_DNS_HOSTNAME ומאוכלס בשדה dnsRecord של תצורת השער, שהוא שדה פלט בלבד.

כדי לאחזר את שם המארח של ה-DNS שנוצר באופן אוטומטי:

gcloud beta ai semantic-governance-policy-engine describe \
    --location=LOCATION \
    --project=PROJECT_ID

curl "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

בתשובה, מאתרים את השדה dnsRecord מתחת ל-gatewayConfigs.GATEWAY_NAME.dnsRecord. שומרים את ה-FQDN הזה – תצטרכו אותו כ-SGP_DNS_HOSTNAME כשמחברים את מנוע המדיניות ל-Agent Gateway.

קישור בניהול עצמי

curl  -X PATCH "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine"
    }'

gcloud beta ai semantic-governance-policy-engine update \
    --location=LOCATION \
    --project=PROJECT_ID

הפקודה הזו מחזירה פעולה ממושכת. כדי לבדוק את סטטוס הפעולה, מחליפים את OPERATION בערך של name מהתשובה:

curl "https://LOCATION-aiplatform.googleapis.com/v1beta1/OPERATION" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json"

אפשר גם לבדוק את הסטטוס הכללי של המנוע עד שהשדה state מחזיר: ACTIVE

curl "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json"

הגדרת הרשת (בניהול עצמי בלבד)

אחרי הקצאת מנוע המדיניות, צריך להגדיר את רכיבי הרשת שנדרשים כדי ש-Agent Gateway יוכל לתקשר עם מנוע המדיניות.

בנתיב בניהול Google, נקודת הקצה של PSC נוצרת אוטומטית בפרויקט של דייר בניהול Google. בנתיב בניהול עצמי, צריך ליצור ולנהל את נקודת הקצה של PSC באופן ידני בפרויקט שלכם ב- Cloud de Confiance by S3NS .

1. הקצאת רשת VPC ותת-רשת

בשלב הזה יוצרים רשת VPC, רשת משנה ורשת משנה לשרת proxy בלבד לתעבורת נתונים של סוכנים. טווחי ה-IP שמוצגים (10.11.12.0/24 ו-10.11.13.0/24) הם דוגמאות. אפשר להשתמש בכל טווח פרטי של RFC 1918 שמתאים לעיצוב הרשת.

1. יוצרים את רשת ה-VPC:

   gcloud compute networks create NETWORK_NAME \
       --subnet-mode=auto \
       --project=PROJECT_ID
   

   מחליפים את NETWORK_NAME בשם של רשת ה-VPC (לדוגמה, agent-network).

2. יוצרים את רשת המשנה:

   gcloud compute networks subnets create SUBNET_NAME \
       --network=NETWORK_NAME \
       --region=LOCATION \
       --range=10.11.12.0/24 \
       --project=PROJECT_ID
   

   מחליפים את SUBNET_NAME בשם של תת-הרשת (לדוגמה, agent-subnet).

3. יוצרים את רשת המשנה של ה-proxy בלבד (נדרש למאזני עומסים מנוהלים):

   gcloud compute networks subnets create PROXY_SUBNET_NAME \
       --network=NETWORK_NAME \
       --region=LOCATION \
       --range=10.11.13.0/24 \
       --purpose=REGIONAL_MANAGED_PROXY --role=ACTIVE \
       --project=PROJECT_ID
   

   מחליפים את PROXY_SUBNET_NAME בשם של תת-הרשת של ה-proxy בלבד (לדוגמה, agent-proxy-subnet).

2. הקצאת תחום DNS פרטי

יוצרים תחום DNS פרטי כדי לאפשר ל-Agent Gateway לזהות את שם המארח של Policy Engine:

gcloud dns managed-zones create DNS_ZONE_NAME \
    --description="Private zone for my internal agentic VPC services" \
    --dns-name="internal.example.com." \
    --visibility=private \
    --networks=NETWORK_NAME \
    --project=PROJECT_ID

Replace the following:

• DNS_ZONE_NAME: השם של תחום ה-DNS (לדוגמה, my-private-zone).
• ‫internal.example.com.: שם ה-DNS של האזור, כולל הנקודה בסוף.

3. יצירת קובץ מצורף לרשת

יוצרים חיבור לרשת כדי לאפשר ל-Agent Gateway להתחבר למשאבים ב-VPC. ההגדרה של העדפת החיבור חייבת להיות ACCEPT_AUTOMATIC.

gcloud compute network-attachments create NETWORK_ATTACHMENT_NAME \
    --region=LOCATION \
    --subnets=SUBNET_NAME \
    --connection-preference=ACCEPT_AUTOMATIC \
    --project=PROJECT_ID

Replace the following:

• ‫NETWORK_ATTACHMENT_NAME: השם של חיבור הרשת (לדוגמה, sgp-nw-attachment).
• ‫SUBNET_NAME: רשת המשנה שיצרתם בשלב 1.

4. יצירת כתובת IP סטטית, נקודת קצה (endpoint) מסוג PSC ורשומת DNS

שומרים כתובת IP סטטית, יוצרים נקודת קצה (endpoint) של Private Service Connect ‏(PSC) שמפנה לקובץ המצורף לשירות של מנוע המדיניות, ויוצרים רשומת DNS כדי לאפשר גישה אליה.

# Reserve a static IP address
gcloud compute addresses create STATIC_IP_NAME \
    --region=LOCATION \
    --subnet=SUBNET_NAME \
    --purpose=GCE_ENDPOINT \
    --project=PROJECT_ID

# Capture the reserved IP address
IP=$(gcloud compute addresses describe STATIC_IP_NAME \
    --region=LOCATION \
    --project=PROJECT_ID \
    --format=value(address))

# Create the PSC endpoint
gcloud compute forwarding-rules create PSC_ENDPOINT_NAME \
    --region=LOCATION \
    --network=NETWORK_NAME \
    --address=STATIC_IP_NAME \
    --target-service-attachment=PSC_SERVICE_ATTACHMENT \
    --project=PROJECT_ID

# Create a DNS A record for the policy engine
gcloud dns record-sets create SGP_DNS_HOSTNAME \
    --zone=DNS_ZONE_NAME \
    --type=A \
    --ttl=300 \
    --rrdatas=$IP \
    --project=PROJECT_ID

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

• ‫STATIC_IP_NAME: השם של כתובת ה-IP השמורה (לדוגמה, sgp-psc-ip).
• ‫PSC_ENDPOINT_NAME: השם של נקודת הקצה של PSC (לדוגמה, sgp-psc-endpoint).
• ‫PSC_SERVICE_ATTACHMENT: הערך של pscServiceAttachment שנשמר מהתגובה להקצאת ה-SIM.
• ‫SGP_DNS_HOSTNAME: שם מארח בתחום ה-DNS הפרטי, בפורמט ‫LOCATION.DNS_ZONE_SUFFIX, כאשר DNS_ZONE_SUFFIX הוא שם ה-DNS שציינתם כשיצרתם את תחום ה-DNS הפרטי. לדוגמה, אם המיקום שלכם הוא us-west1 והסיומת של תחום ה-DNS היא internal.example.com, צריך להשתמש ב-us-west1.internal.example.com.

5. הגדרת קישוריות ל-VPC ב-Agent Gateway

אחרי שיוצרים את משאבי הרשת, צריך לרשום את מחבר הרשת ואת הקישור בין רשתות שכנות (peering) ב-DNS ב-Agent Gateway כדי שהוא יוכל להגיע ל-Policy Engine דרך הרשת הפרטית.

הוראות מפורטות זמינות במאמר בנושא הגדרת קישוריות ל-VPC במדריך להגדרת Agent Gateway. לפחות את הפעולות הבאות:

• רושמים את מחבר הרשת שנוצר בשלב 3 בהגדרת תעבורת הנתונים היוצאת של Agent Gateway.
• רושמים DNS peering כדי שהשער יוכל לפענח את שם המארח של ה-DNS הפרטי שנוצר בשלב 4.

חיבור מנוע המדיניות ל-Agent Gateway

אחרי שמגדירים את הרשת, צריך ליצור תוסף הרשאה ומדיניות הרשאה כדי ש-Agent Gateway יוכל להעביר תנועה למנוע המדיניות לצורך הערכה.

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

   gcloud

   מגדירים את תצורת התוסף בקובץ YAML ‏ (authz-ext.yaml) ומייבאים אותו:

   name: AUTHZ_EXTENSION_NAME
   service: SGP_DNS_HOSTNAME
   authority: SGP_DNS_HOSTNAME
   failOpen: false
   loadBalancingScheme: LOAD_BALANCING_SCHEME_UNSPECIFIED
   

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

   REST

   curl -X POST \
       "https://networkservices.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/authzExtensions?authzExtensionId=AUTHZ_EXTENSION_NAME" \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json" \
       -d '{
         "service": "SGP_DNS_HOSTNAME",
         "authority": "SGP_DNS_HOSTNAME",
         "failOpen": false,
         "loadBalancingScheme": "LOAD_BALANCING_SCHEME_UNSPECIFIED"
       }'
   

   מחליפים את SGP_DNS_HOSTNAME בשם המארח של ה-DNS שעבורו יצרתם רשומת A בהגדרת הרשת (שלב 4).

   הפקודה הזו מחזירה פעולה ממושכת. ממתינים לסיום הפעולה לפני שממשיכים.

2. יוצרים את מדיניות ההרשאות: יוצרים מדיניות הרשאות שמקשרת את התוסף ל-Agent Gateway. ההגדרה הזו אומרת ל-Agent Gateway לשלוח תנועה דרך מנוע המדיניות לצורך הערכה.

   gcloud

   מגדירים את התצורה של מדיניות ההרשאות בקובץ YAML ‏ (authz-policy.yaml) ומייבאים אותו:

   name: AUTHZ_POLICY_NAME
   target:
     loadBalancingScheme: LOAD_BALANCING_SCHEME_UNSPECIFIED
     resources:
     - projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
   httpRules:
   - to:
       operations:
       - paths:
         - prefix: /
     when: "!request.headers['content-type'].startsWith('application/grpc') && (request.path.endsWith(':generateContent') || request.path.endsWith(':streamGenerateContent'))"
   action: CUSTOM
   policyProfile: CONTENT_AUTHZ
   customProvider:
     authzExtension:
       resources:
       - projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME
   

   gcloud network-security authz-policies import AUTHZ_POLICY_NAME \
       --source=authz-policy.yaml \
       --location=LOCATION \
       --project=PROJECT_ID
   

   REST

   curl -X POST \
       "https://networksecurity.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/authzPolicies?authzPolicyId=AUTHZ_POLICY_NAME" \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json" \
       -d '{
         "target": {
           "loadBalancingScheme": "LOAD_BALANCING_SCHEME_UNSPECIFIED",
           "resources": ["projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"]
         },
         "httpRules": [{
           "to": {
             "operations": [{"paths": [{"prefix": "/"}]}]
           },
           "when": "!request.headers['"'"'content-type'"'"'].startsWith('"'"'application/grpc'"'"') && (request.path.endsWith('"'"':generateContent'"'"') || request.path.endsWith('"'"':streamGenerateContent'"'"'))"
         }],
         "action": "CUSTOM",
         "policyProfile": "CONTENT_AUTHZ",
         "customProvider": {
           "authzExtension": {
             "resources": ["projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME"]
           }
         }
       }'
   

   הפקודה הזו מחזירה פעולה ממושכת. ממתינים לסיום הפעולה לפני שממשיכים.

הוספה של כלל מדיניות

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

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

gcloud alpha agent-registry agents list \
    --project=PROJECT_ID \
    --location=LOCATION

gcloud config set api_endpoint_overrides/aiplatform \
    https://LOCATION-aiplatform.googleapis.com/

gcloud beta ai semantic-governance-policies create POLICY_ID \
    --location=LOCATION \
    --display-name="Semantic governance policy for ShippingAgent-1" \
    --description="Applies to all tool calls from the Cymbal shipping assistant agent" \
    --agent=projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID \
    --natural-language-constraint="Always use UPS as the shipping provider for shipments within the USA. Always use DHL as the shipping provider for shipments within the EU." \
    --project=PROJECT_ID

gcloud beta ai semantic-governance-policies create POLICY_ID \
    --location=LOCATION \
    --display-name="Semantic governance policy for ShippingAgent-1" \
    --agent=projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID \
    --natural-language-constraint="Always use UPS as the shipping provider for shipments within the USA. Always use DHL as the shipping provider for shipments within the EU." \
    --agent-response-denial-message="Sorry, I can only book shipments through the approved carriers for your region." \
    --project=PROJECT_ID

gcloud alpha agent-registry mcp-servers list \
    --project=PROJECT_ID \
    --location=LOCATION

gcloud beta ai semantic-governance-policies create POLICY_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --agent=projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID \
    --mcp-tools="mcp-server=MCP_SERVER,tools=TOOL_NAME" \
    --natural-language-constraint="NLC_TEXT" \
    --project=PROJECT_ID

הודעות דחייה עם כמה כללי מדיניות

כשבקשה אחת מפעילה דחיות מכמה כללי מדיניות, מנוע המדיניות משלב את הודעות הדחייה שהוגדרו בכללי המדיניות האלה לפני שהוא מחזיר את התגובה למשתמש. ההתנהגות הבאה חלה:

• הודעות הדחייה מכל מדיניות עם פסיקת דחייה מוצגות יחד, מופרדות על ידי שורות ריקות.
• הודעות כפולות מוצגות פעם אחת.
• אם בחלק ממדיניות ההפעלה מוגדרת הודעת דחייה ובחלק לא, המערכת מוסיפה שורה כללית "הבקשה הזו נדחתה בגלל מדיניות עסקית אחרת" כדי לכסות את המדיניות שבה לא מוגדרת הודעה.
• בכל בקשה מוצגות עד 5 הודעות דחייה. השאר מושמטות.

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

אתם יכולים להפעיל מצב פרימטר לבדיקות (DRY_RUN). מצב פרימטר לבדיקות הוא מצב של ביקורת בלבד או סימולציה, שמאפשר לכם להעריך את כללי המדיניות בלי לאכוף אותם. במצב הזה, Policy Engine מעריך את כל הקריאות לפונקציות בהתאם למגבלות שלכם ומתעד את ההחלטות, אבל אף פעם לא חוסם פעולות. כך תוכלו לבדוק ולאמת את האילוצים לפני שתפעילו את האכיפה.

כדי להפעיל את מצב ההרצה היבשה, מוסיפים את sgpEnforcementMode: DRY_RUN למטא-נתונים של תוסף ההרשאה:

curl -X PATCH \
    "https://networkservices.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME?updateMask=metadata" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {
        "sgpEnforcementMode": "DRY_RUN"
      }
    }'

במצב פרימטר לבדיקות:

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

כדי לחזור למצב אכיפה רגיל, מסירים את sgpEnforcementMode מהמטא-נתונים:

curl -X PATCH \
    "https://networkservices.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME?updateMask=metadata" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "metadata": {}
    }'

צפייה ביומני הערכת מדיניות

מנוע המדיניות כותב רשומה מובנית ביומן לכל הערכה ב-Cloud Logging בפרויקט שלכם. הרשומה מכילה מערך verdict ומערך evaluations עם verdict ו-rationale לכל כלי או פעולה.

1. מהמסוף: בדף Policies, בוחרים מדיניות.
2. בחלונית פרטים, בקטע יכולת צפייה, לוחצים על Cloud Logging > הצגת פרטים.

3. ב-Logs Explorer: מקלידים semantic-governance-policy בתיבת השאילתה או משתמשים במסנן המפורש הבא:

   logName="projects/PROJECT_ID/logs/semantic-governance-policy"

דוגמה לרשומה ביומן:

{
  "jsonPayload": {
    "token_usage": 1859,
    "verdict": "ALLOW",
    "token_usage_breakdown": {"output": 43, "thinking": 0, "input": 1816, "total": 1859},
    "evaluations": [
      {
        "toolName": "process_refund",
        "verdict": "ALLOW",
        "actionName": "process_refund",
        "rationale": "The action is aligned with the user's request to process a refund and complies with the constraints regarding order ID length."
      }
    ]
  },
  "resource": {"type": "global", "labels": {"project_id": "PROJECT_NUMBER"}},
  "logName": "projects/PROJECT_ID/logs/semantic-governance-policy"
}

שדות עיקריים:

• ‫verdict: ההחלטה הכוללת, ALLOW או DENY.
• ‫evaluations[].rationale: ההסבר למה מנוע המדיניות הגיע לפסיקה מסוימת לגבי כל כלי או פעולה.
• ‫token_usage: מספר הטוקנים של המודל שההערכה צרכה.

הפעלת מעקב אחר בקשות

מנוע המדיניות מייצא עקבות לכל בקשה שהוא מעריך ל-Cloud Trace בפרויקט שלכם, כך שתוכלו לבדוק את זמן האחזור לכל בקשה ואת אכיפת המדיניות. כדי לקבל את המעקבים האלה, צריך להפעיל את Cloud Trace API ולתת לחשבון השירות של Vertex AI ‏ (P4SA) הרשאה לכתוב מעקבים.

1. מפעילים את Cloud Trace API:

   gcloud services enable cloudtrace.googleapis.com \
       --project=PROJECT_ID
   

2. מקצים את התפקיד Cloud Trace Agent ‏ (roles/cloudtrace.agent) לחשבון השירות של Vertex AI. התפקיד הזה מעניק רק את הרשאת הכתיבה של המעקב (cloudtrace.traces.patch):

   export PROJECT_NUM=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   
   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
       --role="roles/cloudtrace.agent"
   

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

ניהול הגדרת המדיניות

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

מחיקת מדיניות

כדי להסיר מדיניות ספציפית בלי להשפיע על השילוב הכולל של מדיניות הפיקוח בשפה טבעית:

gcloud beta ai semantic-governance-policies delete POLICY_ID \
    --location=LOCATION \
    --project=PROJECT_ID

אפשר גם להשתמש בפקודה curl הבאה:

curl -X DELETE \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicies/POLICY_ID" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

ביטול ההקצאה של Policy Engine

curl  -X POST "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine:deprovision" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

gcloud beta ai semantic-governance-policy-engine deprovision \
    --location=LOCATION \
    --project=PROJECT_ID

ניתוק מנוע המדיניות מ-Agent Gateway

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

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

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

כדי לחבר מחדש את מנוע המדיניות בהמשך, צריך ליצור מחדש את מדיניות ההרשאות כמו שמתואר במאמר חיבור מנוע המדיניות ל-Agent Gateway.

(אופציונלי) מחיקה של תוסף ההרשאה

מוחקים את תוסף ההרשאה שנוצר במהלך ההגדרה.

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

(אופציונלי) הסרת המשאבים שמנוהלים על ידי הלקוח

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

הסרת תחום ה-DNS הפרטי

gcloud dns managed-zones delete DNS_ZONE_NAME \
    --project=PROJECT_ID

הסרת תת-הרשת ורשת ה-VPC

gcloud compute networks subnets delete SUBNET_NAME \
    --region=LOCATION \
    --project=PROJECT_ID

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

(אופציונלי) הסרת קישורי IAM

אם הענקתם הרשאות לחשבון השירות של Vertex AI‏ (P4SA), תוכלו להסיר אותן:

export PROJECT_NUM=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/compute.networkAdmin"

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/dns.admin"

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

(אופציונלי) השבתה של Cloud Trace API

gcloud services disable cloudtrace.googleapis.com --project=PROJECT_ID

(אופציונלי) השבתה של Agent Platform API

gcloud services disable aiplatform.googleapis.com --project=PROJECT_ID

ניפוי באגים באכיפת המדיניות

כדי לנפות באגים בפסק דין לא צפוי:

1. בודקים את פסק הדין וההסבר ביומני הערכת המדיניות.
2. מעקב אחרי הבקשה – ראו הפעלת מעקב אחרי בקשות.
3. אימות שינויים באופן בטוח באמצעות מצב פרימטר לבדיקות.
4. אישור הפריסה – מצב המנוע הוא ACTIVE והקישור לשער הגישה נוצר.

קטלוג שגיאות

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

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

• מידע נוסף על פקודות ה-CLI של gcloud ב-Vertex AI
• מעקב אחרי תוצאות של בדיקות מדיניות ב-Log Explorer.