Richtlinien für semantische Governance konfigurieren

Richtlinien für die semantische Governance und die Policy Engine konfigurieren

In diesem Abschnitt wird der Übergang von der Infrastrukturvorbereitung zur Richtlinienerstellung behandelt.

Vorbereitung

Führen Sie die folgenden Schritte aus, bevor Sie Richtlinien für die semantische Governance konfigurieren.

Erforderliche APIs aktivieren

Aktivieren Sie zuerst die APIs, die für die semantische Governance-Richtlinie und ihre Netzwerkkomponenten erforderlich sind:

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

Dem Vertex AI-Dienstkonto IAM-Berechtigungen gewähren (nur von Google verwaltete Bindung)

Wenn Sie während der Bereitstellung die Option Von Google verwaltete Bindung verwenden, weisen Sie dem Vertex AI-Dienstkonto (P4SA) die Rollen zu, die es zum Erstellen des Private Service Connect-Endpunkts (PSC) (roles/compute.networkAdmin) und des DNS-Eintragssatzes (roles/dns.admin) in Ihrem Projekt benötigt. Wenn Sie die Option Selbstverwaltete Bindung verwenden, können Sie diesen Schritt überspringen, da Sie diese Netzwerkressourcen selbst erstellen.

Erstellen Sie die Dienstidentität (idempotent) und weisen Sie die Rollen zu:

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"

Die entsprechenden Befehle zum Entfernen finden Sie im Abschnitt „Bereinigen“ unter IAM-Bindungen entfernen.

Teilnahmevoraussetzungen für Agenten

Damit ein KI-Agent in derCloud de Confiance Console in der Agent-Auswahl einer semantischen Governance-Richtlinie angezeigt wird, muss die Reasoning Engine des KI-Agenten mit sowohl identity_type=AGENT_IDENTITY als auch agent_gateway_config bereitgestellt worden sein. Wenn eines der beiden fehlt, wird der Agent in der Cloud de Confiance -Konsole aus der Auswahl herausgefiltert. Die API und gcloud geben stattdessen einen expliziten Fehler zurück.

Wenn Sie einen Agenten bereitstellen möchten, der diese Anforderungen erfüllt, folgen Sie der Anleitung unter Agent Runtime-Traffic über Agent Gateway weiterleiten. Beide Felder sind in einer vorhandenen Reasoning Engine unveränderlich. Daher muss ein Agent, der ohne sie bereitgestellt wird, neu bereitgestellt werden. Patchen ist nicht möglich.

So prüfen Sie, ob ein vorhandener Agent infrage kommt: Die Reasoning Engine des Agents (spec.effectiveIdentity) muss mit agents.global. beginnen:

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"

Unterstützte Standorte

Die Policy Engine für semantische Governance und semantische Governance-Richtlinien werden an den folgenden regionalen Standorten unterstützt:

Bereitstellung und Aktivierung

Aktivieren Sie die Policy Engine für semantische Governance. Dadurch wird die erforderliche Laufzeitumgebung bereitgestellt. Die Bereitstellung dauert in der Regel etwa 2 bis 3 Minuten. Bei hoher Nachfrage oder wenn der Warmup-Pool wieder aufgefüllt wird, kann die Bereitstellung jedoch bis zu 20 Minuten dauern. Wählen Sie eine der folgenden Optionen für die Bereitstellung aus:

• Von Google verwaltete Bindung:Google erstellt die zugrunde liegenden Netzwerkressourcen in Ihrem Cloud de Confiance by S3NS -Projekt und verwaltet ihren Lebenszyklus automatisch.
• Selbstverwaltete Bindung:Sie erstellen und verwalten die erforderlichen Netzwerkressourcen (network, subnetwork und dnsZoneName) direkt in Ihrem Cloud de Confiance by S3NS -Projekt.

Nachdem Sie die Bereitstellung abgeschlossen haben, müssen Sie die Policy Engine mit dem Agent Gateway verbinden.

Von Google verwaltete Bindung

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"

Ersetzen Sie Folgendes:

• GATEWAY_NAME durch einen eindeutigen Gateway-Namen.
• Ersetzen Sie DNS_NAME durch den Namen der zu verwendenden privaten DNS-Zone.
• PROJECT_ID durch Ihre Projekt-ID in Cloud de Confiance by S3NS (projects/PROJECT_ID/global/networks/default). Wenn Sie ein benutzerdefiniertes Netzwerk und Subnetz verwenden, ersetzen Sie die vollständigen Ressourcenpfade network und subnetwork entsprechend.

Automatisch generierten DNS-Hostnamen abrufen

Wenn Sie die Engine mit einer von Google verwalteten Bindung bereitstellen, erstellt Google automatisch einen Private Service Connect-Endpunkt (PSC) und registriert einen DNS-A-Eintrag in Ihrer privaten DNS-Zone. Der FQDN dieses Eintrags dient als SGP_DNS_HOSTNAME und wird im schreibgeschützten Feld dnsRecord Ihrer Gateway-Konfiguration ausgefüllt.

So rufen Sie den automatisch generierten DNS-Hostnamen ab:

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)"

Suchen Sie in der Antwort unter gatewayConfigs.GATEWAY_NAME.dnsRecord nach dem Feld dnsRecord. Speichern Sie diesen FQDN. Sie benötigen ihn als SGP_DNS_HOSTNAME, wenn Sie die Policy Engine mit dem Agent Gateway verbinden.

Selbstverwaltete Bindung

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

Dieser Befehl gibt einen Vorgang mit langer Ausführungszeit zurück. Sie können den Status des Vorgangs abfragen, indem Sie OPERATION durch den Wert name aus der Antwort ersetzen:

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

Alternativ können Sie den Gesamtstatus der Engine prüfen, bis das Feld state den Wert ACTIVE zurückgibt:

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"

Netzwerk konfigurieren (nur selbstverwaltet)

Nachdem die Policy Engine bereitgestellt wurde, konfigurieren Sie die Netzwerkkomponenten, die für die Kommunikation des Agent Gateway mit der Policy Engine erforderlich sind.

Während Google den PSC-Endpunkt im von Google verwalteten Mandantenprojekt für den von Google verwalteten Pfad automatisch erstellt, müssen Sie ihn für den selbstverwalteten Pfad manuell in Ihrem eigenen Cloud de Confiance by S3NS Projekt erstellen und verwalten.

1. VPC-Netzwerk und ‑Subnetz bereitstellen

In diesem Schritt erstellen Sie ein VPC-Netzwerk, ein Subnetz und ein Nur-Proxy-Subnetz für Agent-Traffic. Die angezeigten IP-Bereiche (10.11.12.0/24 und 10.11.13.0/24) sind Beispiele. Sie können einen beliebigen privaten RFC 1918-Bereich verwenden, der zu Ihrem Netzwerkdesign passt.

1. VPC-Netzwerk erstellen:

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

   Ersetzen Sie NETWORK_NAME durch den Namen Ihres VPC-Netzwerk (z. B. agent-network).

2. Erstellen Sie das Subnetz:

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

   Ersetzen Sie SUBNET_NAME durch den Namen Ihres Subnetzes (z. B. agent-subnet).

3. Erstellen Sie das Nur-Proxy-Subnetz (erforderlich für verwaltete Load Balancer):

   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
   

   Ersetzen Sie PROXY_SUBNET_NAME durch den Namen Ihres Nur-Proxy-Subnetzes, z. B. agent-proxy-subnet.

2. Private DNS-Zone bereitstellen

Erstellen Sie eine private DNS-Zone, damit Agent Gateway den Hostnamen der Policy Engine auflösen kann:

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: der Name Ihrer DNS-Zone, z. B. my-private-zone.
• internal.example.com.: der DNS-Name für Ihre Zone, einschließlich des abschließenden Punkts.

3. Netzwerkanhang erstellen

Erstellen Sie einen Netzwerkanhang, damit Agent Gateway eine Verbindung zu Ressourcen in Ihrer VPC herstellen kann. Die Verbindungseinstellung muss auf ACCEPT_AUTOMATIC festgelegt sein.

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: Der Name des Netzwerkanhangs, z. B. sgp-nw-attachment.
• SUBNET_NAME: Das Subnetz, das Sie in Schritt 1 erstellt haben.

4. Statische IP-Adresse, PSC-Endpunkt und DNS-Eintrag erstellen

Reservieren Sie eine statische IP-Adresse, erstellen Sie einen Private Service Connect-Endpunkt (PSC), der auf den Dienstanhang der Policy Engine verweist, und erstellen Sie einen DNS-Eintrag, damit er erreichbar ist.

# 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

Ersetzen Sie Folgendes:

• STATIC_IP_NAME: der Name Ihrer reservierten IP-Adresse, z. B. sgp-psc-ip.
• PSC_ENDPOINT_NAME: der Name für Ihren PSC-Endpunkt (z. B. sgp-psc-endpoint).
• PSC_SERVICE_ATTACHMENT: Der pscServiceAttachment-Wert, der in der Bereitstellungsantwort gespeichert wurde.
• SGP_DNS_HOSTNAME: ein Hostname in Ihrer privaten DNS-Zone im Format LOCATION.DNS_ZONE_SUFFIX, wobei DNS_ZONE_SUFFIX der DNS-Name ist, den Sie beim Erstellen Ihrer privaten DNS-Zone angegeben haben. Wenn Ihr Standort beispielsweise us-west1 und Ihr DNS-Zonensuffix internal.example.com ist, verwenden Sie us-west1.internal.example.com.

5. VPC-Verbindung im KI-Agenten-Gateway konfigurieren

Nachdem Sie die Netzwerkressourcen erstellt haben, müssen Sie die Netzwerkverbindung und das DNS-Peering in Ihrem Agent Gateway registrieren, damit die Policy Engine über das private Netzwerk erreicht werden kann.

Eine ausführliche Anleitung finden Sie im Einrichtungsleitfaden für das Agent Gateway unter VPC-Verbindung konfigurieren. Sie müssen mindestens Folgendes tun:

• Registrieren Sie den in Schritt 3 erstellten Netzwerkanhang mit der Egress-Konfiguration Ihres Agent Gateways.
• Registrieren Sie DNS-Peering, damit das Gateway den privaten DNS-Hostnamen auflösen kann, der in Schritt 4 erstellt wurde.

Policy Engine mit Agent Gateway verbinden

Nachdem das Netzwerk konfiguriert wurde, müssen Sie eine Autorisierungserweiterung und eine Autorisierungsrichtlinie erstellen, damit das Agent Gateway Traffic zur Auswertung an die Policy Engine weiterleiten kann.

1. Autorisierungserweiterung erstellen: Erstellen Sie eine Autorisierungserweiterung, die auf den DNS-Hostnamen der Policy Engine verweist. Verwenden Sie dieselbe SGP_DNS_HOSTNAME, für die Sie in Netzwerk konfigurieren (Schritt 4) einen DNS-Eintrag erstellt haben. Über diesen Mechanismus sendet Agent Gateway Traffic zur Auswertung an die Richtlinien-Engine.

   gcloud

   Definieren Sie die Erweiterungskonfiguration in einer YAML-Datei (authz-ext.yaml) und importieren Sie sie:

   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"
       }'
   

   Ersetzen Sie SGP_DNS_HOSTNAME durch den DNS-Hostnamen, für den Sie in Netzwerk konfigurieren (Schritt 4) einen A-Eintrag erstellt haben.

   Dieser Befehl gibt einen Vorgang mit langer Ausführungszeit zurück. Warten Sie, bis der Vorgang abgeschlossen ist, bevor Sie fortfahren.

2. Autorisierungsrichtlinie erstellen: Erstellen Sie eine Autorisierungsrichtlinie, die die Erweiterung an Ihr Agent Gateway bindet. Dadurch wird Agent Gateway angewiesen, Traffic zur Bewertung über die Policy Engine zu senden.

   gcloud

   Definieren Sie die Konfiguration der Autorisierungsrichtlinie in einer YAML-Datei (authz-policy.yaml) und importieren Sie sie:

   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"]
           }
         }
       }'
   

   Dieser Befehl gibt einen Vorgang mit langer Ausführungszeit zurück. Warten Sie, bis der Vorgang abgeschlossen ist, bevor Sie fortfahren.

Richtlinie erstellen

Sobald die Policy Engine aktiv ist, können Sie die technischen und verhaltensbezogenen Schutzmaßnahmen für Ihre Agenten definieren.

1. Bereich definieren: Legen Sie fest, ob die Richtlinie für alle Aktionen eines KI-Agents oder für ein bestimmtes Tool gilt.
2. Beschränkungen erstellen: Geben Sie Ihre Geschäftsregeln in einfachem Deutsch an.

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

Ablehnungsnachrichten mit mehreren Richtlinien

Wenn durch eine einzelne Anfrage Ablehnungen aufgrund mehrerer Richtlinien ausgelöst werden, kombiniert die Richtlinien-Engine die in diesen Richtlinien konfigurierten Ablehnungsmitteilungen, bevor sie die Antwort an den Nutzer zurückgibt. Das folgende Verhalten gilt:

• Ablehnungsnachrichten aus jeder Richtlinie mit einem Ablehnungsurteil werden zusammen angezeigt und durch Leerzeilen getrennt.
• Doppelte Nachrichten werden nur einmal angezeigt.
• Wenn für einige Auslösungsrichtlinien eine Ablehnungsnachricht konfiguriert ist und für andere nicht, wird eine allgemeine Zeile „Diese Anfrage wurde aufgrund einer anderen Unternehmensrichtlinie abgelehnt.“ angehängt, um die Richtlinien ohne Ablehnungsnachricht abzudecken.
• Pro Anfrage werden maximal fünf Ablehnungsmeldungen angezeigt. Weitere Meldungen werden ausgelassen.

Probelaufmodus aktivieren

Sie können den Probelaufmodus (DRY_RUN) aktivieren. Der Probelauf ist ein reiner Prüf- oder Simulationsmodus, mit dem Sie Richtlinien auswerten können, ohne sie zu erzwingen. In diesem Modus wertet die Policy Engine alle Tool-Aufrufe anhand Ihrer Einschränkungen aus und protokolliert Ergebnisse, blockiert aber niemals Aktionen. So können Sie Ihre Einschränkungen testen und validieren, bevor Sie die Erzwingung aktivieren.

Wenn Sie den Probelaufmodus aktivieren möchten, fügen Sie den Metadaten Ihrer Autorisierungserweiterung sgpEnforcementMode: DRY_RUN hinzu:

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"
      }
    }'

Im Probelaufmodus:

• Alle Tool-Aufrufe sind zulässig, unabhängig vom Ergebnis.
• Entscheidungen und Begründungen werden zur Überprüfung protokolliert.
• Sie können die Logs prüfen, um herauszufinden, welche Aktionen blockiert worden wären, und Ihre Einschränkungen anpassen, bevor Sie in den erzwungenen Modus wechseln.

Wenn Sie wieder zum normalen erzwungenen Modus zurückkehren möchten, entfernen Sie sgpEnforcementMode aus den Metadaten:

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": {}
    }'

Logs zur Richtlinienbewertung ansehen

Die Richtlinien-Engine schreibt für jede Bewertung einen strukturierten Logeintrag in Cloud Logging in Ihrem Projekt. Der Eintrag enthält einen allgemeinen verdict und ein evaluations-Array mit einem verdict und rationale für jedes Tool oder jede Aktion.

1. Über die Konsole:Wählen Sie auf der Seite Richtlinien eine Richtlinie aus.
2. Klicken Sie im Bereich Details im Abschnitt Beobachtbarkeit auf Cloud Logging > Details ansehen.

3. Im Log-Explorer: Geben Sie semantic-governance-policy in das Abfragefeld ein oder verwenden Sie den folgenden expliziten Filter:

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

Das folgende Beispiel zeigt einen Logeintrag:

{
  "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"
}

Wichtigste Felder:

• verdict: Gesamte Entscheidung, entweder ALLOW oder DENY.
• evaluations[].rationale: Die Begründung dafür, warum die Policy Engine für jedes Tool oder jede Aktion ein bestimmtes Ergebnis erzielt hat.
• token_usage: Die Anzahl der Modell-Tokens, die für die Bewertung verwendet wurden.

Anfrage-Tracing aktivieren

Die Richtlinien-Engine exportiert für jede Anfrage, die sie auswertet, einen Trace nach Cloud Trace in Ihrem Projekt. So können Sie die Latenz pro Anfrage und die Richtliniendurchsetzung prüfen. Wenn Sie diese Traces erhalten möchten, aktivieren Sie die Cloud Trace API und gewähren Sie dem Vertex AI-Dienstkonto (P4SA) die Berechtigung zum Schreiben von Traces.

1. Cloud Trace API aktivieren:

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

2. Weisen Sie dem Vertex AI-Dienstkonto die Rolle „Cloud Trace Agent“ (roles/cloudtrace.agent) zu. Diese Rolle gewährt nur die Berechtigung zum Schreiben von Traces (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"
   

Nachdem Sie beide konfiguriert haben, senden Sie eine Anfrage über Ihren Agenten und sehen Sie sich die Traces in Trace Explorer für Ihr Projekt an.

Richtlinienkonfiguration verwalten

Nachdem die Richtlinie für semantische Governance ausgeführt wurde, können Sie einzelne Richtlinien löschen oder die Engine von Ihrem Agent Gateway trennen.

Richtlinie löschen

So entfernen Sie eine einzelne Richtlinie, ohne die Integration der Richtlinie für die semantische Governance insgesamt zu beeinträchtigen:

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

Alternativ können Sie den folgenden curl-Befehl verwenden:

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)"

Bereitstellung einer Policy Engine aufheben

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

Verbindung der Policy Engine zu Agent Gateway trennen

Sie können die Policy Engine von Ihrem Agent Gateway trennen, damit Tool-Aufrufe nicht mehr anhand Ihrer Einschränkungen ausgewertet werden.

Löschen Sie die Autorisierungsrichtlinie, mit der die Durchsetzung der Richtlinie für die semantische Governance an Ihr Agent Gateway gebunden ist:

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

Wenn Sie die Policy Engine später wieder verbinden möchten, erstellen Sie die Autorisierungsrichtlinie neu, wie unter Policy Engine mit Agent Gateway verbinden beschrieben.

(Optional) Autorisierungserweiterung löschen

Löschen Sie die Autorisierungserweiterung, die während der Einrichtung erstellt wurde.

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

(Optional) Kundenverwaltete Ressourcen bereinigen

Beim Aufheben der Bereitstellung der Engine werden nur die von Google verwalteten Sicherungsressourcen entfernt. Sie müssen die Ressourcen, die Sie während der Einrichtung in Ihrem eigenen Projekt erstellt haben, manuell löschen, wenn sie nicht mehr benötigt werden.

Private DNS-Zone entfernen

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

Subnetz und VPC entfernen

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

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

(Optional) IAM-Bindungen entfernen

Wenn Sie dem Vertex AI-Dienstkonto (P4SA) Berechtigungen erteilt haben, können Sie diese entfernen:

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"

(Optional) Cloud Trace API deaktivieren

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

(Optional) Agent Platform API deaktivieren

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

Durchsetzung von Richtlinien debuggen

So beheben Sie Fehler bei einem unerwarteten Urteil:

1. Prüfen Sie das Ergebnis und die Begründung in den Richtlinienauswertungsprotokollen.
2. Anfrage verfolgen – siehe Anfrage-Tracing aktivieren.
3. Änderungen im Probelaufmodus sicher validieren.
4. Bereitstellung bestätigen: Der Engine-Status ist ACTIVE und die Gateway-Bindung wurde hergestellt.

Fehlerkatalog

In der folgenden Tabelle sind Fehler aufgeführt, die bei der Verwaltung von Richtlinien für die semantische Governance auftreten können, sowie Schritte zur Behebung dieser Fehler:

Nächste Schritte

• Weitere Informationen zu den gcloud CLI-Befehlen für Vertex AI
• Richtlinienentscheidungen im Log-Explorer im Blick behalten.