配置语义治理政策

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

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

前提条件

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

启用必需的 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

向 Vertex AI 服务账号授予 IAM 权限(仅限 Google 管理的绑定)

如果您在预配期间使用 Google 管理的绑定选项,请向 Vertex AI 服务账号 (P4SA) 授予在项目中创建 Private Service Connect (PSC) 端点 (roles/compute.networkAdmin) 和 DNS 记录集 (roles/dns.admin) 所需的角色。如果您使用自行管理的绑定选项,则可以跳过此步骤,因为您需要自行创建这些网络资源。

创建服务身份(幂等)并授予角色:

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"

相应的移除命令位于清理部分下的移除 IAM 绑定中。

代理资格要求

如需在Google Cloud 控制台的语义治理政策智能体选择器中显示,智能体的推理引擎必须在部署时同时设置 identity_type=AGENT_IDENTITY 和 agent_gateway_config。如果缺少其中任何一项, Google Cloud 控制台会从选择器中滤除该代理。API 和 gcloud 会返回明确的错误。

如需部署满足这些要求的智能体,请参阅通过 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"

支持的位置

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

地理位置 可用区域
美洲 us-central1、us-east1、us-east4、us-west1
欧洲 europe-southwest1、europe-west1、europe-west4、europe-west8

预配和启用

启用语义治理政策引擎。这会配置必要的运行时环境。 预配通常需要大约 2 到 3 分钟才能完成。不过,当需求较高或预热池正在重新填充时,预配最多可能需要 20 分钟。选择以下某个预配选项:

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

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

Google 管理的绑定

REST

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

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 资源路径。
检索自动生成的 DNS 主机名

当您使用 Google 管理的绑定预配引擎时,Google 会自动创建 Private Service Connect (PSC) 端点,并在您的专用 DNS 区域中注册 DNS A 记录。相应记录的 FQDN 用作 SGP_DNS_HOSTNAME,并填充到网关配置的 dnsRecord(仅输出)字段中。

如需检索自动生成的 DNS 主机名,请执行以下操作:

gcloud

运行以下命令以描述政策引擎配置:

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

REST

发送 GET 请求以检索引擎资源:

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

在响应中,找到 gatewayConfigs.GATEWAY_NAME.dnsRecord 下的 dnsRecord 字段。保存此 FQDN,在将政策引擎连接到 Agent Gateway 时,您需要将其用作 SGP_DNS_HOSTNAME。

自行管理的绑定

REST

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

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 与政策引擎通信所需的网络组件。

虽然 Google 会在 Google 管理的租户项目中自动创建 PSC 端点以用于 Google 管理的路径,但对于自行管理的路径,您必须在自己的 Google Cloud 项目中手动创建和管理 PSC 端点。

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 可以通过专用网络访问政策引擎。

如需了解详细说明,请参阅代理网关设置指南中的配置 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. 撰写限制条件:以纯英文提供业务规则。

控制台

  1. 在 Google Cloud 控制台中,前往语义治理政策页面。

    前往“语义治理政策”页面

  2. 点击 + 添加政策。
  3. 在添加政策侧边栏中,配置以下各项:
    • 名称:输入政策的唯一 ID。该名称只能包含小写字母、数字和连字符。
    • 说明:(可选)输入政策用途的简要说明。
    • 代理选择:选择此规则适用的特定代理或所有代理。如果选择器为空或缺少您预期的代理,请参阅代理资格要求。
    • 访问目标:
      • 如需将限制条件应用于每项操作,请选中将限制条件应用于所有工具复选框。
      • 如需指定特定资源,请从下拉菜单中选择 MCP 服务器和各个工具。
    • 限制条件:以自然语言输入您的业务规则(最多 5,000 个字符)。
    • 拒绝消息:(可选)输入一条消息(最多 1,000 个字符),以便在此政策拒绝请求时向用户显示,而不是显示政策理由。在 REST API 中,此设置会映射到政策资源中的 agentResponseCustomization.denialMessage;在 Google Cloud CLI 中,请在 gcloud beta ai semantic-governance-policies create 或 gcloud beta ai semantic-governance-policies update 上使用 --agent-response-denial-message(请参阅下方的 gcloud 标签页)。请参阅信息泄露风险和包含多项政策的拒绝消息。
  4. 点击创建。

gcloud

您可以使用 gcloud beta ai semantic-governance-policies create 命令在代理范围(适用于所有工具)或工具范围配置限制条件。

查找您的代理 ID

如需创建政策,您需要从 Agent Registry 获取智能体的唯一 ID。列出项目中的代理,以查找 ID:

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

代理 ID 是 name 字段的最后一部分(例如 agentregistry-00000000-0000-0000-abcd-012345678901)。将此值用于完全限定的代理名称(projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID)的 AGENT_ID 部分,以下命令会将该名称传递给 --agent。

在运行语义治理政策命令之前,请设置区域级 API 端点替换项:

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

如需配置拒绝消息(请参阅控制台标签页下的拒绝消息项目符号,以及包含多项政策的拒绝消息),请添加 --agent-response-denial-message:

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 beta ai semantic-governance-policies update 在现有政策中添加或更新 --agent-response-denial-message。

查找 MCP 服务器
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

包含多项政策的拒绝消息

如果单个请求触发了多项政策的拒绝,政策引擎会在向用户返回响应之前,合并这些政策中配置的拒绝消息。以下行为适用:

  • 每个判决为“拒绝”的政策的拒绝消息会一起显示,并以空白行分隔。
  • 重复的消息仅显示一次。
  • 如果部分触发政策配置了拒绝消息,而其他政策没有,系统会附加一条通用消息“此请求因违反其他业务政策而被拒绝。”,以涵盖未配置拒绝消息的政策。
  • 每个请求最多显示 5 条拒绝消息;其他消息会被省略。

启用试运行模式

您可以启用试运行模式 (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"