Configurer des règles de gouvernance sémantique

Configurer les règles de gouvernance sémantique et le moteur de stratégies

Cette section explique comment passer de la préparation de l'infrastructure à la création de règles.

Prérequis

Avant de configurer des règles de gouvernance sémantique, procédez comme suit.

Activer les API requises

Avant de commencer, activez les API requises pour la règle de gouvernance sémantique et ses composants réseau :

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

Accorder des autorisations IAM au compte de service Vertex AI (liaison gérée par Google uniquement)

Si vous utilisez l'option Liaison gérée par Google lors du provisionnement, accordez au compte de service Vertex AI (P4SA) les rôles dont il a besoin pour créer le point de terminaison Private Service Connect (PSC) (roles/compute.networkAdmin) et l'ensemble d'enregistrements DNS (roles/dns.admin) dans votre projet. Si vous utilisez l'option Liaison autogérée, vous pouvez ignorer cette étape, car vous créez vous-même ces ressources réseau.

Créez l'identité de service (idempotente) et accordez les rôles :

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." \
    --role="roles/compute.networkAdmin"

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

Les commandes de suppression correspondantes se trouvent dans Supprimer les liaisons IAM, dans la section sur le nettoyage.

Critères d'éligibilité des agents

Pour qu'un moteur de raisonnement d'agent apparaisse dans le sélecteur d'agents d'une règle de gouvernance sémantique dans la consoleGoogle Cloud , il doit avoir été déployé avec les paramètres identity_type=AGENT_IDENTITY et agent_gateway_config définis. Si l'un ou l'autre manque, la console Google Cloud filtre l'agent hors du sélecteur. L'API et gcloud renvoient une erreur explicite à la place.

Pour déployer un agent qui répond à ces exigences, suivez les instructions de la section Acheminer le trafic d'Agent Runtime via Agent Gateway. Ces deux champs sont immuables sur un moteur de raisonnement existant. Par conséquent, un agent déployé sans ces champs doit être redéployé. L'application de correctifs ne fonctionnera pas.

Pour vérifier qu'un agent existant est éligible, assurez-vous que le spec.effectiveIdentity de son moteur de raisonnement commence par 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"

Pays acceptés

Le moteur de stratégies de gouvernance sémantique et les règles de gouvernance sémantique sont disponibles dans les emplacements régionaux suivants :

Provisionnement et activation

Activez le moteur de stratégies de gouvernance sémantique. L'environnement d'exécution nécessaire est alors provisionné. Le provisionnement prend généralement deux à trois minutes. Toutefois, lorsque la demande est élevée ou que le pool de préchauffage est en cours de réapprovisionnement, le provisionnement peut prendre jusqu'à 20 minutes. Choisissez l'une des options de provisionnement suivantes :

• Liaison gérée par Google : Google crée les ressources réseau sous-jacentes dans votre projet Google Cloud et gère automatiquement leur cycle de vie.
• Liaison autogérée : vous créez et gérez les ressources réseau nécessaires (network, subnetwork et dnsZoneName) directement dans votre projet Google Cloud .

Une fois le provisionnement terminé, vous devez connecter le moteur de stratégies à Agent Gateway.

Liaison gérée par 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"

Remplacez les éléments suivants :

• GATEWAY_NAME par un nom de passerelle unique.
• DNS_NAME par le nom de la zone DNS privée à utiliser.
• PROJECT_ID par l'ID de votre projet Google Cloud (projects/PROJECT_ID/global/networks/default). Si vous utilisez un réseau et un sous-réseau personnalisés, remplacez les chemins d'accès complets aux ressources network et subnetwork en conséquence.

Récupérer le nom d'hôte DNS généré automatiquement

Lorsque vous provisionnez le moteur avec une liaison gérée par Google, Google crée automatiquement un point de terminaison Private Service Connect (PSC) et enregistre un enregistrement DNS A dans votre zone DNS privée. Le nom de domaine complet de cet enregistrement sert de SGP_DNS_HOSTNAME et est renseigné dans le champ dnsRecord en sortie seule de la configuration de votre passerelle.

Pour récupérer le nom d'hôte DNS généré automatiquement :

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

Dans la réponse, recherchez le champ dnsRecord sous gatewayConfigs.GATEWAY_NAME.dnsRecord. Enregistrez ce nom de domaine complet, car vous en aurez besoin comme SGP_DNS_HOSTNAME lorsque vous connecterez le moteur de stratégies à Agent Gateway.

Liaison autogérée

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

Cette commande renvoie une opération de longue durée. Vous pouvez interroger l'état de l'opération en remplaçant OPERATION par la valeur name de la réponse :

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

Vous pouvez également vérifier l'état général du moteur jusqu'à ce que le champ state renvoie 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"

Configurer le réseau (autogéré uniquement)

Une fois le moteur de stratégies provisionné, configurez les composants réseau requis pour qu'Agent Gateway communique avec le moteur de stratégies.

Alors que Google crée automatiquement le point de terminaison PSC dans un projet de locataire géré par Google pour le chemin géré par Google, vous devez créer et gérer manuellement le point de terminaison PSC dans votre propre projet Google Cloud pour le chemin autogéré.

1. Provisionner un réseau et un sous-réseau VPC

Au cours de cette étape, vous allez créer un réseau VPC, un sous-réseau et un sous-réseau proxy réservé pour le trafic agentique. Les plages d'adresses IP affichées (10.11.12.0/24 et 10.11.13.0/24) sont des exemples. Vous pouvez utiliser n'importe quelle plage privée RFC 1918 adaptée à la conception de votre réseau.

1. Créez le réseau VPC :

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

   Remplacez NETWORK_NAME par le nom de votre réseau VPC (par exemple, agent-network).

2. Créez le sous-réseau :

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

   Remplacez SUBNET_NAME par le nom de votre sous-réseau (par exemple, agent-subnet).

3. Créez le sous-réseau proxy réservé (obligatoire pour les équilibreurs de charge gérés) :

   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
   

   Remplacez PROXY_SUBNET_NAME par le nom de votre sous-réseau proxy réservé (par exemple, agent-proxy-subnet).

2. Provisionner une zone DNS privée

Créez une zone DNS privée pour permettre à Agent Gateway de résoudre le nom d'hôte du moteur de stratégies :

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 : nom de votre zone DNS (par exemple, my-private-zone).
• internal.example.com. : nom DNS de votre zone, y compris le point final.

3. Créer un rattachement de réseau

Créez un rattachement de réseau pour permettre à Agent Gateway de se connecter aux ressources de votre VPC. La préférence de connexion doit être définie sur 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 : nom de votre rattachement de réseau (par exemple, sgp-nw-attachment).
• SUBNET_NAME : sous-réseau que vous avez créé à l'étape 1.

4. Créer une adresse IP statique, un point de terminaison PSC et un enregistrement DNS

Réservez une adresse IP statique, créez un point de terminaison Private Service Connect (PSC) pointant vers le rattachement de service du moteur de stratégies et créez un enregistrement DNS pour le rendre accessible.

# 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

Remplacez les éléments suivants :

• STATIC_IP_NAME : nom de votre adresse IP réservée (par exemple, sgp-psc-ip).
• PSC_ENDPOINT_NAME : nom de votre point de terminaison PSC (par exemple, sgp-psc-endpoint).
• PSC_SERVICE_ATTACHMENT : valeur pscServiceAttachment enregistrée à partir de la réponse de provisionnement.
• SGP_DNS_HOSTNAME : nom d'hôte sous votre zone DNS privée, au format LOCATION.DNS_ZONE_SUFFIX, où DNS_ZONE_SUFFIX correspond au nom DNS que vous avez spécifié lors de la création de votre zone DNS privée. Par exemple, si votre emplacement est us-west1 et que le suffixe de votre zone DNS est internal.example.com, utilisez us-west1.internal.example.com.

5. Configurer la connectivité VPC sur Agent Gateway

Après avoir créé les ressources réseau, vous devez enregistrer le rattachement de réseau et l'appairage DNS sur votre Agent Gateway afin qu'il puisse accéder au moteur de stratégies via le réseau privé.

Pour obtenir des instructions détaillées, consultez Configurer la connectivité VPC dans le guide de configuration d'Agent Gateway. Vous devez au minimum :

• Enregistrez le rattachement de réseau créé à l'étape 3 avec la configuration de sortie de votre passerelle Agent Gateway.
• Enregistrez l'appairage DNS afin que la passerelle puisse résoudre le nom d'hôte DNS privé créé à l'étape 4.

Connecter le moteur de stratégies à Agent Gateway

Une fois le réseau configuré, vous devez créer une extension d'autorisation et une règle d'autorisation pour que l'Agent Gateway puisse transférer le trafic au moteur de stratégies pour évaluation.

1. Créez l'extension d'autorisation : créez une extension d'autorisation qui pointe vers le nom d'hôte DNS du moteur de stratégies. Utilisez le même SGP_DNS_HOSTNAME pour lequel vous avez créé un enregistrement DNS dans Configurer le réseau (étape 4). Il s'agit du mécanisme par lequel la passerelle d'agent envoie le trafic au moteur de règles pour évaluation.

   gcloud

   Définissez la configuration de l'extension dans un fichier YAML (authz-ext.yaml) et importez-la :

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

   Remplacez SGP_DNS_HOSTNAME par le nom d'hôte DNS pour lequel vous avez créé un enregistrement A dans Configurer le réseau (étape 4).

   Cette commande renvoie une opération de longue durée. Attendez la fin de l'opération avant de continuer.

2. Créer la règle d'autorisation : créez une règle d'autorisation qui lie l'extension à votre Agent Gateway. Cela indique à Agent Gateway d'envoyer le trafic au moteur de stratégies pour évaluation.

   gcloud

   Définissez la configuration de la règle d'autorisation dans un fichier YAML (authz-policy.yaml) et importez-le :

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

   Cette commande renvoie une opération de longue durée. Attendez la fin de l'opération avant de continuer.

Créer une règle

Une fois le moteur de stratégies actif, vous pouvez définir les limites techniques et comportementales de vos agents.

1. Définissez le champ d'application : déterminez si la règle s'applique à toutes les actions effectuées par un agent ou si elle cible un outil spécifique.
2. Rédigez les contraintes : fournissez vos règles métier en langage clair.

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

Messages de refus avec plusieurs règles

Lorsqu'une seule requête déclenche des refus de plusieurs règles, le moteur de règles combine les messages de refus configurés sur ces règles avant de renvoyer la réponse à l'utilisateur. Le comportement suivant s'applique :

• Les messages de refus de chaque règle avec un verdict de refus sont affichés ensemble, séparés par des lignes vides.
• Les messages en double ne s'affichent qu'une seule fois.
• Si certaines règles de déclenchement ont un message de refus configuré et d'autres non, la ligne générique Cette demande a été refusée en raison d'une autre règle commerciale. est ajoutée pour couvrir les règles sans message.
• Au maximum cinq messages de refus sont affichés par requête. Les autres sont omis.

Activer le mode de simulation

Vous pouvez activer le mode dry run (DRY_RUN). Le mode dry run est un mode d'audit uniquement ou de simulation qui vous permet d'évaluer des règles sans les appliquer. Dans ce mode, le moteur de stratégies évalue tous les appels d'outils par rapport à vos contraintes et enregistre les verdicts, mais ne bloque jamais les actions. Cela vous permet de tester et de valider vos contraintes avant d'activer l'application.

Pour activer le mode de simulation, ajoutez sgpEnforcementMode: DRY_RUN aux métadonnées de votre extension d'autorisation :

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

En mode de simulation :

• Tous les appels d'outils sont autorisés, quel que soit le verdict.
• Les verdicts et les justifications sont enregistrés pour examen.
• Vous pouvez consulter les journaux pour identifier les actions qui auraient été bloquées et affiner vos contraintes avant de passer en mode d'application.

Pour revenir au mode d'application normal, supprimez sgpEnforcementMode des métadonnées :

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

Afficher les journaux d'évaluation des règles

Le moteur de règles écrit une entrée de journal structurée pour chaque évaluation dans Cloud Logging dans votre projet. L'entrée enregistre un verdict global et un tableau evaluations avec un verdict et un rationale pour chaque outil ou action.

1. Dans la console : sur la page Règles, sélectionnez une règle.
2. Dans le panneau Détails, dans la section Observabilité, cliquez sur Cloud Logging > Afficher les détails.

3. Dans l'explorateur de journaux, saisissez semantic-governance-policy dans le champ de requête ou utilisez le filtre explicite suivant :

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

Voici un exemple d'entrée de journal :

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

Champs clés :

• verdict : décision globale, ALLOW ou DENY.
• evaluations[].rationale : justification de la décision du moteur de stratégies pour chaque outil ou action.
• token_usage : nombre de jetons de modèle consommés par l'évaluation.

Activer le traçage des requêtes

Le moteur de règles exporte une trace pour chaque requête qu'il évalue vers Cloud Trace dans votre projet. Vous pouvez ainsi inspecter la latence et l'application des règles par requête. Pour recevoir ces traces, activez l'API Cloud Trace et accordez au compte de service Vertex AI (P4SA) l'autorisation d'écrire des traces.

1. Activez l'API Cloud Trace :

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

2. Attribuez le rôle d'agent Cloud Trace (roles/cloudtrace.agent) au compte de service Vertex AI. Ce rôle n'accorde que l'autorisation trace-write (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." \
       --role="roles/cloudtrace.agent"
   

Une fois les deux configurés, envoyez une requête via votre agent et affichez les traces dans l'explorateur de traces de votre projet.

Gérer la configuration des règles

Une fois la règle de gouvernance sémantique en cours d'exécution, vous pouvez supprimer des règles individuelles ou déconnecter le moteur de votre Agent Gateway.

Supprimer une stratégie

Pour supprimer une règle individuelle sans affecter l'intégration globale de la règle de gouvernance sémantique :

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

Vous pouvez également utiliser la commande curl suivante :

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

Désactiver un moteur de stratégies

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

Déconnecter le moteur de stratégies d'Agent Gateway

Vous pouvez déconnecter le moteur de stratégies de votre Agent Gateway pour que les appels d'outils ne soient plus évalués par rapport à vos contraintes.

Supprimez la règle d'autorisation qui lie l'application de la règle de gouvernance sémantique à votre passerelle d'agent :

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

Pour reconnecter le moteur de stratégies ultérieurement, recréez la règle d'autorisation comme décrit dans Connecter le moteur de stratégies à Agent Gateway.

(Facultatif) Supprimer l'extension d'autorisation

Supprimez l'extension d'autorisation créée lors de la configuration.

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

(Facultatif) Nettoyer les ressources gérées par le client

La suppression du moteur ne fait que supprimer les ressources de sauvegarde gérées par Google. Vous devez supprimer manuellement les ressources que vous avez créées dans votre propre projet lors de la configuration si vous n'en avez plus besoin.

Supprimer la zone DNS privée

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

Supprimer le sous-réseau et le VPC

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

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

(Facultatif) Supprimer les liaisons IAM

Si vous avez accordé des autorisations au compte de service Vertex AI (P4SA), vous pouvez les supprimer :

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." \
    --role="roles/compute.networkAdmin"

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

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

(Facultatif) Désactiver l'API Cloud Trace

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

(Facultatif) Désactiver l'API Agent Platform

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

Déboguer l'application des règles

Pour déboguer un verdict inattendu :

1. Consultez le verdict et la justification dans les journaux d'évaluation des règles.
2. Suivez la requête : consultez Activer le traçage des requêtes.
3. Validez les modifications de manière sécurisée avec le mode de simulation.
4. Confirmer le déploiement : l'état du moteur est ACTIVE et la liaison de la passerelle est établie.

Catalogue d'erreurs

Le tableau suivant liste les erreurs que vous pouvez rencontrer lors de la gestion des règles de gouvernance sémantique, ainsi que les étapes à suivre pour les résoudre :

Étapes suivantes

• En savoir plus sur les commandes gcloud CLI Vertex AI
• Surveillez les verdicts concernant les règles dans l'explorateur de journaux.