Configure semantic governance policies

Configure Semantic governance policies and the policy engine

This section covers the transition from infrastructure readiness to policy authoring.

Prerequisites

Before you configure Semantic governance policies, complete the following steps.

Enable required APIs

Before you begin, enable the APIs required for Semantic governance policy and its networking components:

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

Agent eligibility requirements

To appear in a Semantic governance policy's agent selector in the Google Cloud console, an agent's reasoning engine must have been deployed with both identity_type=AGENT_IDENTITY and agent_gateway_config set. If either is missing, the Google Cloud console filters the agent out of the selector. The API and gcloud return an explicit error instead.

To deploy an agent that meets these requirements, follow Route Agent Runtime traffic through Agent Gateway. Both fields are immutable on an existing reasoning engine, so an agent deployed without them must be redeployed — patching will not work.

To verify an existing agent is eligible, confirm that its reasoning engine's spec.effectiveIdentity starts with 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"

Supported locations

The Semantic governance policy engine and Semantic governance policies are supported in the following regional locations:

Provisioning and enablement

Enable the Semantic governance policy engine. This provisions the necessary runtime environment. Provisioning usually takes approximately 2 to 3 minutes to complete. However, when demand is high or the warmup pool is refilling, provisioning can take up to 20 minutes. Choose one of the following options for provisioning:

• Google-managed binding: Google creates the underlying network resources in your Google Cloud project and manages their lifecycle automatically.
• Self-managed binding: You create and manage the necessary network resources (network, subnetwork, and dnsZoneName) directly in your Google Cloud project.

After you complete the provisioning, you must connect the policy engine to Agent Gateway.

Google-managed binding

curl -X PATCH \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/semanticGovernancePolicyEngine?updateMask=SemanticGovernancePolicyEngine" \
    -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"

Replace the following:

• GATEWAY_NAME with a unique gateway name.
• DNS_NAME with the name of the private DNS zone to use.
• PROJECT_ID with your Google Cloud project ID (projects/PROJECT_ID/global/networks/default). If you use a custom network and subnet, replace the complete network and subnetwork resource paths accordingly.

Self-managed binding

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

This command returns a long-running operation. You can poll the operation status by replacing OPERATION with the name value from the response:

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

Alternatively, check the overall engine status until the state field returns 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"

Configuring the network

After the policy engine is provisioned, configure the networking components required for Agent Gateway to communicate with the policy engine.

1. Provision VPC network and subnet

In this step, you create a VPC network, a subnet, and a proxy-only subnet for agentic traffic. The IP ranges shown (10.11.12.0/24 and 10.11.13.0/24) are examples. You can use any RFC 1918 private range that fits your network design.

1. Create the VPC network:

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

   Replace NETWORK_NAME with the name for your VPC network (for example, agent-network).

2. Create the subnet:

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

   Replace SUBNET_NAME with the name for your subnet (for example, agent-subnet).

3. Create the proxy-only subnet (required for managed load balancers):

   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
   

   Replace PROXY_SUBNET_NAME with the name for your proxy-only subnet (for example, agent-proxy-subnet).

2. Provision private DNS zone

Create a private DNS zone to allow Agent Gateway to resolve the policy engine's hostname:

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: the name for your DNS zone (for example, my-private-zone).
• internal.example.com.: the DNS name for your zone, including the trailing dot.

3. Create network attachment

Create a network attachment to allow Agent Gateway to connect to resources in your VPC. The connection preference must be set to 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: the name for your network attachment (for example, sgp-nw-attachment).
• SUBNET_NAME: the subnet you created in step 1.

4. Create static IP, PSC endpoint, and DNS record

Reserve a static IP address, create a Private Service Connect (PSC) endpoint pointing to the policy engine's service attachment, and create a DNS record to make it reachable.

# 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

Replace the following:

• STATIC_IP_NAME: the name for your reserved IP address (for example, sgp-psc-ip).
• PSC_ENDPOINT_NAME: the name for your PSC endpoint (for example, sgp-psc-endpoint).
• PSC_SERVICE_ATTACHMENT: the pscServiceAttachment value saved from the provisioning response.
• SGP_DNS_HOSTNAME: a hostname under your private DNS zone, in the format LOCATION.DNS_ZONE_SUFFIX, where DNS_ZONE_SUFFIX is the DNS name you specified when creating your private DNS zone. For example, if your location is us-west1 and your DNS zone suffix is internal.example.com, use us-west1.internal.example.com.

5. Configure VPC connectivity on Agent Gateway

After creating the network resources, you must register the network attachment and DNS peering on your Agent Gateway so that it can reach the policy engine over the private network.

For detailed instructions, see Configure VPC connectivity in the Agent Gateway setup guide. At a minimum, you must:

• Register the network attachment created in step 3 with your Agent Gateway egress configuration.
• Register DNS peering so the gateway can resolve the private DNS hostname created in step 4.

Connect the policy engine to Agent Gateway

After the network is configured, you must create an authorization extension and an authorization policy so that Agent Gateway can forward traffic to the policy engine for evaluation.

1. Create the authorization extension: Create an authorization extension that points to the policy engine's DNS hostname. Use the same SGP_DNS_HOSTNAME that you created a DNS record for in Configuring the network (step 4). This is the mechanism by which Agent Gateway sends traffic to the policy engine for evaluation.

   gcloud

   Define the extension configuration in a YAML file (authz-ext.yaml) and import it:

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

   Replace SGP_DNS_HOSTNAME with the DNS hostname for which you created an A record in Configuring the network (step 4).

   This command returns a long-running operation. Wait for the operation to complete before proceeding.

2. Create the authorization policy: Create an authorization policy that binds the extension to your Agent Gateway. This tells Agent Gateway to send traffic through the policy engine for evaluation.

   gcloud

   Define the authorization policy configuration in a YAML file (authz-policy.yaml) and import it:

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

   This command returns a long-running operation. Wait for the operation to complete before proceeding.

Create a policy

Once the policy engine is active, you can define the technical and behavioral guardrails for your agents.

1. Define the scope: Determine if the policy applies to all actions taken by an agent or targets a specific tool.
2. Author the constraints: Provide your business rules in plain English.

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=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 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=AGENT_ID \
    --mcp-tools="mcp-server=MCP_SERVER,tools=TOOL_NAME" \
    --natural-language-constraint="NLC_TEXT" \
    --project=PROJECT_ID

Enabling dry run mode

You can enable dry run mode (DRY_RUN). Dry run is an audit-only or simulation mode that lets you evaluate policies without enforcing them. In this mode, the policy engine evaluates all tool calls against your constraints and logs verdicts, but never blocks actions. This lets you test and validate your constraints before enabling enforcement.

To enable dry run mode, add sgpEnforcementMode: DRY_RUN to the metadata of your authorization extension:

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 dry run mode:

• All tool calls are allowed regardless of the verdict.
• Verdicts and rationales are logged for review.
• You can review the logs to identify which actions would have been blocked and refine your constraints before switching to enforcement mode.

To switch back to normal enforcement mode, remove sgpEnforcementMode from the metadata:

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

View policy evaluation logs

The policy engine writes a structured log entry for each evaluation to Cloud Logging in your project. The entry records an overall verdict and an evaluations array with a verdict and rationale for each tool or action.

1. From the Console: On the Policies page, select a policy.
2. In the Details panel, in the Observability section, click Cloud Logging > View details.

3. In Logs Explorer: type semantic-governance-policy in the query box or use the following explicit filter:

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

The following example is a sample log entry:

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

Key fields:

• verdict: Overall decision, either ALLOW or DENY.
• evaluations[].rationale: The rationale as to why the policy engine reached a particular verdict for each tool or action.
• token_usage: The number of model tokens the evaluation consumed.

Enable request tracing

The policy engine exports a trace for each request it evaluates to Cloud Trace in your project, so you can inspect per-request latency and policy enforcement. To receive these traces, enable the Cloud Trace API and grant the Vertex AI service account (P4SA) permission to write traces.

1. Enable the Cloud Trace API:

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

2. Grant the Cloud Trace Agent role (roles/cloudtrace.agent) to the Vertex AI service account. This role grants only the trace-write permission (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.iam.gserviceaccount.com" \
       --role="roles/cloudtrace.agent"
   

After both are configured, send a request through your agent and view the traces in Trace explorer for your project.

Manage policy configuration

After Semantic governance policy is running, you can delete individual policies or disconnect the engine from your Agent Gateway.

Delete a policy

To remove an individual policy without affecting the overall Semantic governance policy integration:

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

Alternatively, use the following curl command:

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

De-provision a 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

Disconnect the policy engine from Agent Gateway

You can disconnect the policy engine from your Agent Gateway to stop tool calls from being evaluated against your constraints.

Delete the authorization policy that binds Semantic governance policy enforcement to your Agent Gateway:

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

To reconnect the policy engine later, recreate the authorization policy as described in Connect the policy engine to Agent Gateway.

(Optional) Delete the authorization extension

Delete the authorization extension created during setup.

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

(Optional) Clean up customer-managed resources

Deprovisioning the engine only tears down the Google-managed backing resources. You must manually delete the resources you created in your own project during setup if they are no longer needed.

Remove the private DNS zone

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

Remove the subnet and VPC

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

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

(Optional) Remove the IAM bindings

If you granted permissions to the Vertex AI service account (P4SA), you can remove them:

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

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

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

(Optional) Disable the Cloud Trace API

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

(Optional) Disable the Agent Platform API

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

Debug policy enforcement

To debug an unexpected verdict:

1. Check the verdict and rationale in policy evaluation logs.
2. Trace the request -- see Enable request tracing.
3. Validate changes safely with dry run mode.
4. Confirm deployment -- engine state is ACTIVE and the gateway binding is established.

Error catalog

The following table lists errors that you might encounter when managing Semantic Governance Policies, along with steps to resolve them:

What's next

• Learn more about Vertex AI gcloud CLI commands.
• Monitor policy verdicts in Log Explorer.