Configura le policy di governance semantica

Configura le norme di governance semantica e il Policy Engine

Questa sezione tratta la transizione dalla preparazione dell'infrastruttura alla creazione delle norme.

Prerequisiti

Prima di configurare le norme di governance semantica, completa i seguenti passaggi.

Abilita le API richieste

Prima di iniziare, abilita le API richieste per le norme di governance semantica e i relativi componenti di rete:

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

Concedi le autorizzazioni IAM al account di servizio Vertex AI (solo binding gestito da Google)

Se utilizzi l'opzione Associazione gestita da Google durante il provisioning, concedi al account di servizio Vertex AI (P4SA) i ruoli necessari per creare l'endpoint Private Service Connect (PSC) (roles/compute.networkAdmin) e il set di record DNS (roles/dns.admin) nel tuo progetto. Se utilizzi l'opzione Binding autogestito, puoi saltare questo passaggio perché crei tu stesso queste risorse di rete.

Crea l'identità di servizio (idempotente) e concedi i ruoli:

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"

I comandi di rimozione corrispondenti si trovano in Rimuovi le associazioni IAM nella sezione di pulizia.

Requisiti di idoneità per gli agenti

Per essere visualizzato nel selettore di agenti di una norma di governance semantica nella consoleCloud de Confiance , il motore di ragionamento di un agente deve essere stato implementato con entrambi identity_type=AGENT_IDENTITY e agent_gateway_config impostati. Se manca uno dei due, la console Cloud de Confiance filtra l'agente dal selettore. L'API e gcloud restituiscono invece un errore esplicito.

Per eseguire il deployment di un agente che soddisfi questi requisiti, segui le istruzioni riportate in Instradare il traffico di Agent Runtime tramite Agent Gateway. Entrambi i campi sono immutabili in un motore di ragionamento esistente, quindi un agente di cui è stato eseguito il deployment senza questi campi deve essere ridistribuito. L'applicazione di patch non funzionerà.

Per verificare l'idoneità di un agente esistente, conferma che il motore di ragionamento spec.effectiveIdentity inizia con 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"

Località supportate

Il motore delle policy di governance semantica e le norme di governance semantica sono supportati nelle seguenti località regionali:

Provisioning e abilitazione

Attiva il Policy Engine delle norme di governance semantica. In questo modo viene eseguito il provisioning dell'ambiente runtime necessario. In genere, il provisioning richiede circa 2-3 minuti. Tuttavia, quando la domanda è elevata o il pool di preriscaldamento si sta riempiendo, il provisioning può richiedere fino a 20 minuti. Scegli una delle seguenti opzioni di provisioning:

• Binding gestito da Google: Google crea le risorse di rete sottostanti nel tuo progetto Cloud de Confiance by S3NS e ne gestisce automaticamente il ciclo di vita.
• Binding autogestito: crei e gestisci le risorse di rete necessarie (network, subnetwork e dnsZoneName) direttamente nel tuo progetto Cloud de Confiance by S3NS .

Dopo aver completato il provisioning, devi collegare il motore dei criteri a Agent Gateway.

Associazione gestita da 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"

Sostituisci quanto segue:

• GATEWAY_NAME con un nome gateway univoco.
• DNS_NAME con il nome della zona DNS privata da utilizzare.
• PROJECT_ID con l'ID progetto Cloud de Confiance by S3NS (projects/PROJECT_ID/global/networks/default). Se utilizzi una rete e una subnet personalizzate, sostituisci i percorsi delle risorse network e subnetwork completi di conseguenza.

Recupera il nome host DNS generato automaticamente

Quando esegui il provisioning dell'engine con l'associazione gestita da Google, Google crea automaticamente un endpoint Private Service Connect (PSC) e registra un record DNS A nella tua zona DNS privata. L'FQDN di questo record funge da SGP_DNS_HOSTNAME e viene compilato nel campo di sola uscita dnsRecord della configurazione del gateway.

Per recuperare il nome host DNS generato automaticamente:

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

Nella risposta, individua il campo dnsRecord in gatewayConfigs.GATEWAY_NAME.dnsRecord. Salva questo FQDN, ti servirà come SGP_DNS_HOSTNAME quando connetti il Policy Engine ad Agent Gateway.

Binding autogestito

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

Questo comando restituisce un'operazione a lunga esecuzione. Puoi eseguire il polling dello stato dell'operazione sostituendo OPERATION con il valore name della risposta:

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

In alternativa, controlla lo stato generale dell'engine finché il campo state non restituisce 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"

Configurazione della rete (solo autogestita)

Dopo il provisioning del motore delle policy, configura i componenti di rete necessari per consentire ad Agent Gateway di comunicare con il motore delle policy.

Mentre Google crea automaticamente l'endpoint PSC in un progetto tenant gestito da Google per il percorso gestito da Google, per il percorso autogestito devi creare e gestire manualmente l'endpoint PSC nel tuo Cloud de Confiance by S3NS progetto.

1. Esegui il provisioning della rete VPC e della subnet

In questo passaggio, crei una rete VPC, una subnet e una subnet solo proxy per il traffico agentic. Gli intervalli IP mostrati (10.11.12.0/24 e 10.11.13.0/24) sono esempi. Puoi utilizzare qualsiasi intervallo privato RFC 1918 adatto alla progettazione della tua rete.

1. Crea la rete VPC:

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

   Sostituisci NETWORK_NAME con il nome della tua rete VPC (ad esempio, agent-network).

2. Crea la subnet:

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

   Sostituisci SUBNET_NAME con il nome della subnet (ad esempio, agent-subnet).

3. Crea la subnet solo proxy (obbligatoria per i bilanciatori del carico gestiti):

   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
   

   Sostituisci PROXY_SUBNET_NAME con il nome della subnet solo proxy (ad esempio, agent-proxy-subnet).

2. Esegui il provisioning della zona DNS privata

Crea una zona DNS privata per consentire ad Agent Gateway di risolvere il nome host del 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: il nome della zona DNS (ad esempio, my-private-zone).
• internal.example.com.: il nome DNS della zona, incluso il punto finale.

3. Crea collegamento di rete

Crea un collegamento di rete per consentire ad Agent Gateway di connettersi alle risorse nel tuo VPC. La preferenza di connessione deve essere impostata su 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: il nome del collegamento di rete (ad esempio sgp-nw-attachment).
• SUBNET_NAME: la subnet creata nel passaggio 1.

4. Crea IP statico, endpoint PSC e record DNS

Prenota un indirizzo IP statico, crea un endpoint Private Service Connect (PSC) che punta al service attachment del Policy Engine e crea un record DNS per renderlo raggiungibile.

# 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

Sostituisci quanto segue:

• STATIC_IP_NAME: il nome dell'indirizzo IP prenotato (ad esempio, sgp-psc-ip).
• PSC_ENDPOINT_NAME: il nome dell'endpoint PSC (ad esempio, sgp-psc-endpoint).
• PSC_SERVICE_ATTACHMENT: il valore pscServiceAttachment salvato dalla risposta di provisioning.
• SGP_DNS_HOSTNAME: un nome host nella tua zona DNS privata, nel formato LOCATION.DNS_ZONE_SUFFIX, dove DNS_ZONE_SUFFIX è il nome DNS che hai specificato durante la creazione della zona DNS privata. Ad esempio, se la tua posizione è us-west1 e il suffisso della zona DNS è internal.example.com, utilizza us-west1.internal.example.com.

5. Configura la connettività VPC su Agent Gateway

Dopo aver creato le risorse di rete, devi registrare il collegamento di rete e il peering DNS sul tuo Agent Gateway in modo che possa raggiungere il Policy Engine tramite la rete privata.

Per istruzioni dettagliate, consulta Configura la connettività VPC nella guida alla configurazione di Agent Gateway. Come minimo, devi:

• Registra il collegamento di rete creato nel passaggio 3 con la configurazione di uscita di Agent Gateway.
• Registra il peering DNS in modo che il gateway possa risolvere il nome host DNS privato creato nel passaggio 4.

Connetti il Policy Engine ad Agent Gateway

Dopo aver configurato la rete, devi creare un'estensione di autorizzazione e una policy di autorizzazione in modo che Agent Gateway possa inoltrare il traffico a Policy Engine per la valutazione.

1. Crea l'estensione dell'autorizzazione: crea un'estensione dell'autorizzazione che punta al nome host DNS del Policy Engine. Utilizza lo stesso SGP_DNS_HOSTNAME per cui hai creato un record DNS in Configurazione della rete (passaggio 4). Questo è il meccanismo con cui Agent Gateway invia il traffico al motore delle policy per la valutazione.

   gcloud

   Definisci la configurazione dell'estensione in un file YAML (authz-ext.yaml) e importala:

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

   Sostituisci SGP_DNS_HOSTNAME con il nome host DNS per cui hai creato un record A in Configurazione della rete (passaggio 4).

   Questo comando restituisce un'operazione a lunga esecuzione. Attendi il completamento dell'operazione prima di procedere.

2. Crea la policy di autorizzazione: crea una policy di autorizzazione che colleghi l'estensione all'Agent Gateway. In questo modo, Agent Gateway invia il traffico al motore delle policy per la valutazione.

   gcloud

   Definisci la configurazione della policy di autorizzazione in un file YAML (authz-policy.yaml) e importala:

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

   Questo comando restituisce un'operazione a lunga esecuzione. Attendi il completamento dell'operazione prima di procedere.

Crea un criterio

Una volta attivo il motore delle norme, puoi definire i guardrail tecnici e comportamentali per i tuoi agenti.

1. Definisci l'ambito: determina se la policy si applica a tutte le azioni intraprese da un agente o se ha come target uno strumento specifico.
2. Crea i vincoli: fornisci le regole aziendali in un linguaggio semplice.

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

Messaggi di rifiuto con più policy

Quando una singola richiesta attiva rifiuti da più policy, il motore delle policy combina i messaggi di rifiuto configurati in queste policy prima di restituire la risposta all'utente. Si applica dunque il seguente comportamento:

• I messaggi di rifiuto di ogni policy con un verdetto di rifiuto vengono mostrati insieme, separati da righe vuote.
• I messaggi duplicati vengono mostrati una sola volta.
• Se alcune norme di attivazione hanno un messaggio di rifiuto configurato e altre no, viene aggiunta una riga generica "Questa richiesta è stata rifiutata a causa di altre norme aziendali" per coprire le norme senza un messaggio.
• Per ogni richiesta vengono visualizzati al massimo 5 messaggi di rifiuto; gli altri vengono omessi.

Attivare la modalità dry run

Puoi attivare la modalità dry run (DRY_RUN). Dry run è una modalità di sola simulazione o controllo che ti consente di valutare le policy senza applicarle. In questa modalità, il Policy Engine valuta tutte le chiamate degli strumenti in base ai vincoli e registra i verdetti, ma non blocca mai le azioni. In questo modo puoi testare e convalidare i vincoli prima di attivare l'applicazione.

Per attivare la modalità dry run, aggiungi sgpEnforcementMode: DRY_RUN ai metadati dell'estensione di autorizzazione:

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

In modalità dry run:

• Tutte le chiamate di strumenti sono consentite indipendentemente dal verdetto.
• I verdetti e le motivazioni vengono registrati per la revisione.
• Puoi esaminare i log per identificare le azioni che sarebbero state bloccate e perfezionare i vincoli prima di passare alla modalità di applicazione forzata.

Per tornare alla modalità di applicazione normale, rimuovi sgpEnforcementMode dai metadati:

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

Visualizza i log di valutazione delle policy

Il motore delle policy scrive una voce di log strutturata per ogni valutazione in Cloud Logging nel tuo progetto. La voce registra un verdict complessivo e un array evaluations con un verdict e un rationale per ogni strumento o azione.

1. Dalla console:nella pagina Policy, seleziona una policy.
2. Nel riquadro Dettagli, nella sezione Osservabilità, fai clic su Cloud Logging > Visualizza dettagli.

3. In Esplora log, digita semantic-governance-policy nella casella della query o utilizza il seguente filtro esplicito:

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

Il seguente esempio è una voce di log di esempio:

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

Campi chiave:

• verdict: Decisione complessiva, ALLOW o DENY.
• evaluations[].rationale: La motivazione per cui il Policy Engine ha raggiunto un determinato verdetto per ogni strumento o azione.
• token_usage: il numero di token del modello utilizzati per la valutazione.

Abilita il tracciamento delle richieste

Il Policy Engine esporta una traccia per ogni richiesta che valuta in Cloud Trace nel tuo progetto, in modo da poter ispezionare la latenza per richiesta e l'applicazione delle policy. Per ricevere queste tracce, abilita l'Cloud Trace API e concedi al account di servizio Vertex AI (P4SA) l'autorizzazione per scrivere tracce.

1. Abilita l'Cloud Trace API:

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

2. Concedi il ruolo Cloud Trace Agent (roles/cloudtrace.agent) al account di servizio Vertex AI. Questo ruolo concede solo l'autorizzazione di scrittura delle tracce (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"
   

Una volta configurati entrambi, invia una richiesta tramite l'agente e visualizza le tracce in Esplora tracce per il tuo progetto.

Gestire la configurazione delle policy

Dopo l'esecuzione delle norme di governance semantica, puoi eliminare singole norme o scollegare il motore dall'Agent Gateway.

Eliminare una policy

Per rimuovere una singola policy senza influire sull'integrazione complessiva delle norme di governance semantica:

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

In alternativa, utilizza il seguente comando 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)"

Eseguire il deprovisioning di un motore delle policy

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

Scollega il motore delle policy da Agent Gateway

Puoi disconnettere il Policy Engine dal tuo Agent Gateway per impedire che le chiamate di strumenti vengano valutate in base ai tuoi vincoli.

Elimina il criterio di autorizzazione che associa l'applicazione della policy di governance semantica al tuo gateway dell'agente:

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

Per riconnettere il Policy Engine in un secondo momento, ricrea la policy di autorizzazione come descritto in Connettere il Policy Engine ad Agent Gateway.

(Facoltativo) Elimina l'estensione dell'autorizzazione

Elimina l'estensione dell'autorizzazione creata durante la configurazione.

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

(Facoltativo) Esegui la pulizia delle risorse gestite dal cliente

Il deprovisioning del motore elimina solo le risorse di backend gestite da Google. Se non sono più necessarie, devi eliminare manualmente le risorse create nel tuo progetto durante la configurazione.

Rimuovi la zona DNS privata

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

Rimuovi la subnet e il VPC

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

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

(Facoltativo) Rimuovi le associazioni IAM

Se hai concesso autorizzazioni al account di servizio Vertex AI (P4SA), puoi rimuoverle:

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"

(Facoltativo) Disabilita l'Cloud Trace API

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

(Facoltativo) Disabilita l'API Agent Platform

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

Esegui il debug dell'applicazione delle policy

Per eseguire il debug di un verdetto imprevisto:

1. Controlla l'esito e la motivazione nei log di valutazione delle policy.
2. Traccia la richiesta: consulta Attivare la tracciabilità delle richieste.
3. Convalida le modifiche in sicurezza con la modalità dry run.
4. Conferma l'implementazione: lo stato del motore è ACTIVE e l'associazione del gateway è stabilita.

Catalogo degli errori

La tabella seguente elenca gli errori che potresti riscontrare durante la gestione delle norme di governance semantica, insieme ai passaggi per risolverli:

Passaggi successivi

• Scopri di più sui comandi gcloud CLI di Vertex AI.
• Monitora i verdetti dei criteri in Esplora log.