配置语义治理政策

配置语义治理政策和政策引擎

本部分介绍了从基础设施准备到政策撰写的过渡。

前提条件

在配置语义治理政策之前，请完成以下步骤。

启用必需的 API

在开始之前，请启用语义治理政策及其网络组件所需的 API：

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

代理资格要求

如需在Google Cloud 控制台中的语义治理政策的代理选择器中显示代理，必须在部署代理的推理引擎时设置 identity_type=AGENT_IDENTITY 和 agent_gateway_config。如果缺少任一信息， Google Cloud 控制台会从选择器中过滤掉该代理。 API 和 gcloud 会返回明确的错误。

如需部署满足这些要求的 Agent，请参阅通过 Agent Gateway 路由 Agent Runtime 流量。这两个字段在现有推理引擎上都是不可变的，因此如果部署的代理没有这两个字段，则必须重新部署，修补将不起作用。

如需验证现有代理是否符合条件，请确认其推理引擎的 spec.effectiveIdentity 是否以 agents.global. 开头：

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

支持的位置

以下区域位置支持语义治理政策引擎和语义治理政策：

配置和启用

启用语义治理政策引擎。这会配置必要的运行时环境。 预配通常需要大约 2 到 3 分钟才能完成。不过，在需求旺盛或预热池正在重新填充时，预配可能需要长达 20 分钟。选择以下预配选项之一：

• Google 管理的绑定：Google 会在您的 Google Cloud 项目中创建底层网络资源，并自动管理其生命周期。
• 自行管理的绑定：您直接在 Google Cloud 项目中创建和管理必要的网络资源（network、subnetwork 和 dnsZoneName）。

完成配置后，您必须将政策引擎连接到 Agent Gateway。

Google 管理的绑定

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"

替换以下内容：

• 将 GATEWAY_NAME 替换为唯一的网关名称。
• 将 DNS_NAME 替换为要使用的专用 DNS 区域的名称。
• PROJECT_ID 替换为您的 Google Cloud 项目 ID (projects/PROJECT_ID/global/networks/default)。如果您使用自定义网络和子网，请相应地替换完整的 network 和 subnetwork 资源路径。

自行管理的绑定

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

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

此命令会返回一个长时间运行的操作。您可以通过将 OPERATION 替换为响应中的 name 值来轮询操作状态：

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

或者，检查整个引擎的状态，直到 state 字段返回 ACTIVE：

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

配置网络

预配政策引擎后，配置 Agent Gateway 与政策引擎通信所需的网络组件。

1. 预配 VPC 网络和子网

在此步骤中，您将创建一个 VPC 网络、一个子网和一个代理专用子网，用于代理流量。显示的 IP 范围（10.11.12.0/24 和 10.11.13.0/24）是示例。您可以使用符合网络设计的任何 RFC 1918 专用范围。

1. 创建 VPC 网络：

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

   将 NETWORK_NAME 替换为您的 VPC 网络的名称（例如 agent-network）。

2. 创建子网：

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

   将 SUBNET_NAME 替换为您的子网名称（例如 agent-subnet）。

3. 创建代理专用子网（托管式负载平衡器必需）：

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

   将 PROXY_SUBNET_NAME 替换为代理专用子网的名称（例如 agent-proxy-subnet）。

2. 预配专用 DNS 区域

创建专用 DNS 区域，以允许 Agent Gateway 解析政策引擎的主机名：

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

Replace the following:

• DNS_ZONE_NAME：DNS 区域的名称（例如 my-private-zone）。
• internal.example.com.：您所在地区的 DNS 名称，包括结尾句点。

3. 创建网络连接

创建网络连接，以允许 Agent Gateway 连接到 VPC 中的资源。连接偏好设置必须设置为 ACCEPT_AUTOMATIC。

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

Replace the following:

• NETWORK_ATTACHMENT_NAME：网络连接的名称（例如 sgp-nw-attachment）。
• SUBNET_NAME：您在第 1 步中创建的子网。

4. 创建静态 IP、PSC 端点和 DNS 记录

预留静态 IP 地址，创建指向政策引擎的服务连接的 Private Service Connect (PSC) 端点，并创建 DNS 记录以使其可访问。

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

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

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

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

替换以下内容：

• STATIC_IP_NAME：预留的 IP 地址的名称（例如 sgp-psc-ip）。
• PSC_ENDPOINT_NAME：PSC 端点的名称（例如 sgp-psc-endpoint）。
• PSC_SERVICE_ATTACHMENT：从配置响应中保存的 pscServiceAttachment 值。
• SGP_DNS_HOSTNAME：专用 DNS 区域下的主机名，格式为 LOCATION.DNS_ZONE_SUFFIX，其中 DNS_ZONE_SUFFIX 是您在创建专用 DNS 区域时指定的 DNS 名称。例如，如果您的位置是 us-west1，并且您的 DNS 区域后缀是 internal.example.com，请使用 us-west1.internal.example.com。

5. 在 Agent Gateway 上配置 VPC 连接

创建网络资源后，您必须在 Agent Gateway 上注册网络连接和 DNS 对等互连，以便 Agent Gateway 可以通过专用网络访问政策引擎。

如需了解详细说明，请参阅 Agent Gateway 设置指南中的配置 VPC 连接。您必须至少执行以下操作：

• 将第 3 步中创建的网络连接注册到您的 Agent Gateway 出站流量配置。
• 注册 DNS 对等互连，以便网关可以解析在第 4 步中创建的专用 DNS 主机名。

将政策引擎连接到 Agent Gateway

配置网络后，您必须创建授权扩展程序和授权政策，以便 Agent Gateway 可以将流量转发到政策引擎进行评估。

1. 创建授权扩展程序：创建指向政策引擎 DNS 主机名的授权扩展程序。使用您在配置网络（第 4 步）中为其创建 DNS 记录的同一 SGP_DNS_HOSTNAME。这是 Agent Gateway 将流量发送到政策引擎以进行评估的机制。

   gcloud

   在 YAML 文件 (authz-ext.yaml) 中定义扩展程序配置并导入：

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

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

   REST

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

   将 SGP_DNS_HOSTNAME 替换为您在配置网络（第 4 步）中为其创建 A 记录的 DNS 主机名。

   此命令会返回一个长时间运行的操作。等待操作完成后再继续。

2. 创建授权政策：创建将扩展程序绑定到 Agent Gateway 的授权政策。这会告知 Agent Gateway 将流量发送到政策引擎以进行评估。

   gcloud

   在 YAML 文件 (authz-policy.yaml) 中定义授权政策配置并导入：

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

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

   REST

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

   此命令会返回一个长时间运行的操作。等待操作完成后再继续。

创建政策

政策引擎处于有效状态后，您就可以为代理定义技术和行为方面的安全措施。

1. 定义范围：确定政策是适用于代理执行的所有操作，还是仅适用于特定工具。
2. 撰写限制条件：以纯英文提供业务规则。

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

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

gcloud beta ai semantic-governance-policies create POLICY_ID \
    --location=LOCATION \
    --display-name="Semantic governance policy for ShippingAgent-1" \
    --description="Applies to all tool calls from the Cymbal shipping assistant agent" \
    --agent=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

启用试运行模式

您可以启用试运行模式 (DRY_RUN)。试运行是一种仅审核或模拟模式，可让您评估政策，而无需强制执行这些政策。在此模式下，政策引擎会根据您的限制条件评估所有工具调用并记录判定结果，但绝不会阻止任何操作。这样，您就可以在启用强制执行之前测试和验证限制条件。

如需启用试运行模式，请将 sgpEnforcementMode: DRY_RUN 添加到授权扩展程序的元数据中：

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

在试运行模式下：

• 无论判决结果如何，所有工具调用都允许。
• 系统会记录判决和理由以供审核。
• 您可以查看日志，确定哪些操作会被阻止，并在切换到强制执行模式之前优化限制条件。

如需切换回正常强制执行模式，请从元数据中移除 sgpEnforcementMode：

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

查看政策评估日志

政策引擎会针对每次评估向您项目中的 Cloud Logging 写入结构化日志条目。该条目记录了总体 verdict 以及一个 evaluations 数组，其中包含每个工具或操作的 verdict 和 rationale。

1. 在控制台中：在政策页面上，选择一项政策。
2. 在详细信息面板的可观测性部分中，依次点击 Cloud Logging > 查看详细信息。

3. 在 Logs Explorer 中：在查询框中输入 semantic-governance-policy，或使用以下明确的过滤条件：

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

以下示例是一个日志条目示例：

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

关键字段：

• verdict：总体决策，可以是 ALLOW 或 DENY。
• evaluations[].rationale：政策引擎针对每种工具或操作得出特定判定的理由。
• token_usage：评估消耗的模型 token 数量。

启用请求跟踪

政策引擎会针对其评估的每个请求向您项目中的 Cloud Trace 导出跟踪记录，以便您检查每个请求的延迟时间和政策执行情况。如需接收这些轨迹，请启用 Cloud Trace API 并授予 Vertex AI 服务账号 (P4SA) 写入轨迹的权限。

1. 启用 Cloud Trace API：

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

2. 向 Vertex AI 服务账号授予 Cloud Trace Agent 角色 (roles/cloudtrace.agent)。此角色仅授予轨迹写入权限 (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"
   

在配置好两者后，通过代理发送请求，然后在项目的跟踪记录浏览器中查看跟踪记录。

管理政策配置

语义治理政策运行后，您可以删除单个政策，也可以断开引擎与 Agent Gateway 的连接。

删除政策

如需移除单个政策，而不影响整体语义治理政策集成，请执行以下操作：

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

或者，使用以下 curl 命令：

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

取消配置政策引擎

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

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

断开政策引擎与 Agent Gateway 的连接

您可以断开政策引擎与 Agent Gateway 的连接，以停止根据限制条件评估工具调用。

删除将语义治理政策强制执行绑定到代理网关的授权政策：

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

如需稍后重新连接政策引擎，请按照将政策引擎连接到 Agent Gateway 中的说明重新创建授权政策。

（可选）删除授权扩展服务

删除在设置期间创建的授权扩展程序。

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

（可选）清理客户管理的资源

取消配置引擎只会拆除 Google 管理的后端资源。如果您不再需要设置期间在自己的项目中创建的资源，则必须手动将其删除。

移除专用 DNS 区域

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

移除子网和 VPC

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

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

（可选）移除 IAM 绑定

如果您向 Vertex AI 服务账号 (P4SA) 授予了权限，可以移除这些权限：

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

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.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"

（可选）停用 Cloud Trace API

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

（可选）停用 Agent Platform API

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

调试政策执行情况

如需调试意外的判决结果，请执行以下操作：

1. 在政策评估日志中查看判决和理由。
2. 跟踪请求 - 请参阅启用请求跟踪。
3. 使用试运行模式安全地验证更改。
4. 确认部署 - 引擎状态为 ACTIVE，并且已建立网关绑定。

错误目录

下表列出了您在管理语义治理政策时可能会遇到的错误，以及解决这些错误的步骤：

后续步骤

• 详细了解 Vertex AI gcloud CLI 命令。
• 在 Log Explorer 中监控政策判定结果。