Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

配置语义治理政策

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

本部分介绍了从基础架构准备到政策编写的过渡。

前提条件

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

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

向 Gemini Enterprise Agent Platform 服务账号授予 IAM 权限（仅限 Google 管理的绑定）

如果您在预配期间使用 Google 管理的绑定选项，请向 Gemini Enterprise Agent Platform 服务账号 (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.iam.gserviceaccount.com" \
    --role="roles/compute.networkAdmin"

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

支持的模型提供商

您的代理必须通过某个受支持的模型提供方调用其模型，且不使用流式传输。请记下每个提供方的请求路径；您在将政策引擎连接到 Agent Gateway 中创建的授权政策必须与该路径匹配。

支持的位置

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

地理位置	可用区域
美洲	`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 会在 Google 管理的租户项目中自动创建 PSC 端点；而对于自行管理的路径，您必须在自己的 Google Cloud 项目中手动创建和管理 PSC 端点。

1. 预配 VPC 网络和子网

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

创建 VPC 网络：

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

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

创建子网：

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）。

创建代理专用子网（托管式负载均衡器需要）：

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 可以将流量转发到政策引擎进行评估。

创建授权扩展：创建指向政策引擎 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 主机名。

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

创建授权政策：创建一项授权政策，将扩展程序绑定到 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.contains(':generateContent') || request.path.contains(':rawPredict') || request.path.contains('/v1/messages') || request.path.contains('/chat/completions'))"
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.contains('"'"':generateContent'"'"') || request.path.contains('"'"':rawPredict'"'"') || request.path.contains('"'"'/v1/messages'"'"') || request.path.contains('"'"'/chat/completions'"'"'))"
      }],
      "action": "CUSTOM",
      "policyProfile": "CONTENT_AUTHZ",
      "customProvider": {
        "authzExtension": {
          "resources": ["projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAME"]
        }
      }
    }'

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

创建政策

启用政策引擎后，您就可以为智能体定义技术和行为护栏。

定义范围：确定政策是适用于代理执行的所有操作，还是针对特定工具。
编写限制条件：用通俗易懂的英语提供业务规则。

控制台

在 Google Cloud 控制台中，前往语义治理政策页面。
前往“语义治理政策”页面
点击 + 添加政策。
在添加政策侧边栏中，配置以下内容：
- 名称：输入政策的唯一 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 标签页）。请参阅信息泄露风险和具有多项政策的拒绝消息。
点击创建。

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）。将此值用于以下命令传递给 --agent 的完全限定智能体名称 projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID 的 AGENT_ID 部分。

在运行语义治理政策命令之前，请设置区域级 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 条拒绝消息；其他消息会被省略。

注意：由于 semantic governance policy 使用 LLM 将拒绝归因于特定触发政策，因此并非每个请求都能进行归因。如果相关政策配置了拒绝消息，但未归因于任何政策，则政策引擎会返回通用消息“此请求因其他业务政策而被拒绝。”如果 LLM 根据前几项政策确定应拒绝请求，则可能不会评估所有政策。

如果请求仅返回一般拒绝消息，请尝试以下问题排查步骤：

用户：重新提交请求。由于 LLM 具有不确定性，后续评估可能会将拒绝归因于特定政策，并返回该政策配置的拒绝消息。
政策管理员：查看请求的政策评估日志。每个日志条目都包含每项政策的判定结果和理由，因此即使未向最终用户显示归因，您也可以确定是哪项政策拒绝了请求。

启用试运行模式

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

控制用户意图匹配

默认情况下，政策引擎会检查每个提议的工具调用是否符合以下两项要求：

遵守限制条件：工具调用符合对智能体设置的限制条件。
用户意图匹配：工具调用与用户请求一致。

启用用户意图匹配后，即使工具调用未违反任何限制，或者代理没有任何限制，政策引擎也可以拒绝与用户请求不匹配的工具调用。如需仅根据您的限制条件做出判定，请关闭用户意图匹配。该设置适用于授权扩展程序发送到政策引擎的每个请求。

如需关闭用户意图匹配，请在授权扩展程序的 metadata 中将 sgpUserIntentMatching 设置为 DISABLED：

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

如需重新启用，请将值设置为 ENABLED 或移除该键。使用大写值。政策引擎会忽略任何其他值，并保持用户意图匹配功能处于开启状态。

更新是一项长时间运行的操作，新设置可能需要几分钟才能到达政策引擎。如需确认评估使用的模式，请查看政策评估日志中的 sgpUserIntentMatchingMode 字段。仅当设置了 sgpUserIntentMatching 时，该字段才会显示，并且具有以下值之一：

CONSTRAINTS_AND_INTENT：用户意图匹配功能已开启。
CONSTRAINTS_ONLY：用户意图匹配功能已关闭。
INTENT_ONLY：用户意图匹配功能已开启，并且工具调用不受任何限制。

用户意图匹配和试运行模式是相互独立的。例如，在试运行模式下保持用户意图匹配处于开启状态，以便在强制执行基于意图的拒绝之前，先在日志中查看这些拒绝。

查看政策评估日志

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

在控制台中：在政策页面上，选择一项政策。
在详细信息面板的可观测性部分中，点击 Cloud Logging > 查看详细信息。
在 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，并向 Gemini Enterprise Agent Platform 服务账号 (P4SA) 授予写入跟踪记录的权限。

启用 Cloud Trace API：

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

向 Gemini Enterprise Agent Platform 服务账号授予 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"

配置完成后，通过代理发送请求，并在项目的 Trace Explorer 中查看跟踪记录。

管理政策配置

语义治理政策运行后，您可以删除单个政策，也可以断开引擎与 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)"

取消预配政策引擎

REST

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

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

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

您可以将政策引擎与 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 绑定

如果您向 Gemini Enterprise Agent Platform 服务账号 (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

调试政策执行情况

症状	可能的原因	检查事项
允许工具调用，但预期会屏蔽	政策与范围和代理不匹配，或限制条件过于宽松	在评估日志中，确认政策匹配情况并查看判定结果；优化 NLC
工具调用被拒，但预期为允许	限制条件过于严格或规则冲突	读取日志中的 `rationale`；调整 NLC；在试运行模式下迭代
完全没有判定	引擎未处于活跃状态、网关未绑定，或请求路径与授权政策的 `when` 条件不匹配	验证引擎 `state` 是否为 `ACTIVE`，以及授权扩展和政策是否存在。在 Agent Gateway 请求日志中，检查 `serviceExtensionInfo` 是否列出了您的授权扩展。如果不包含，请将提供方的请求路径添加到 `when` 条件中。
流式模型调用未返回任何结论或返回错误	政策引擎不支持流式模型回答	将代理配置为以非流式方式调用其模型

如需调试意外判定，请执行以下操作：

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

错误目录

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

错误名称	说明	建议采取的措施
`SEMANTIC_GOVERNANCE_POLICY_ALREADY_EXISTS`	您指定的政策 ID 在此项目和位置中已存在。	请使用唯一的政策 ID，或使用 `PATCH` 请求更新现有政策。
`SEMANTIC_GOVERNANCE_POLICY_ETAG_MISMATCH`	请求中的 etag 与资源的当前版本不匹配。	在尝试更新之前，请检索政策的最新版本，以获取当前 etag。
`SEMANTIC_GOVERNANCE_POLICY_AGENT_REQUIRED`	请求中缺少 `agent` 字段。	指定此政策适用的智能体的资源名称。
`SEMANTIC_GOVERNANCE_POLICY_CONSTRAINT_REQUIRED`	缺少 `natural_language_constraint` 字段。	在约束条件字段中，用简单的英语提供您的业务规则。
`SEMANTIC_GOVERNANCE_POLICY_AGENT_INVALID_NAME`	代理资源名称格式不正确。	验证格式：`projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID`。
`SEMANTIC_GOVERNANCE_POLICY_AGENT_UNSUPPORTED_REGION`	Agent Registry 不支持为代理指定的区域。	使用 Agent Registry 和 semantic governance policy 均支持的区域。
`SEMANTIC_GOVERNANCE_POLICY_AGENT_NOT_FOUND`	找不到指定的智能体。	验证代理是否存在于指定项目和位置的代理注册表中。
`SEMANTIC_GOVERNANCE_POLICY_AGENT_NOT_CONFIGURED`	智能体缺少有效的 `RuntimeIdentity`。	请先为代理配置有效的运行时身份，然后再应用政策。
`SEMANTIC_GOVERNANCE_POLICY_MCP_SERVER_NOT_FOUND`	找不到指定的 MCP 服务器。	验证 MCP 服务器是否已在项目的 Agent Registry 中注册。
`SEMANTIC_GOVERNANCE_POLICY_MCP_SERVER_INVALID_NAME`	MCP 服务器资源名称格式不正确。	验证格式：`projects/PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID`。
`SEMANTIC_GOVERNANCE_POLICY_MCP_SERVER_UNSUPPORTED_REGION`	不支持为 MCP 服务器指定的区域。	为 MCP 服务器使用受支持的区域。
`SEMANTIC_GOVERNANCE_POLICY_REGISTRY_DENIED`	由于缺少权限，系统无法查询代理注册表。	启用 Agent Registry API，并确保您的账号具有 `agentregistry.viewer` 角色。
`SEMANTIC_GOVERNANCE_POLICY_ENGINE_NOT_ENABLED_IN_REGION`	政策引擎在所请求的区域中未处于活跃状态。	按照预配和启用中的步骤，在您所在的区域启用该引擎。
`SEMANTIC_GOVERNANCE_POLICY_ENGINE_SERVICE_NOT_AVAILABLE_IN_LOCATION`	语义治理政策引擎服务在请求的位置不可用。	使用语义治理政策引擎服务支持的位置之一。

后续步骤

详细了解 Gemini Enterprise Agent Platform gcloud CLI 命令。
在Logs Explorer中监控政策判定。

配置语义治理政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

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

前提条件

启用必需的 API

向 Gemini Enterprise Agent Platform 服务账号授予 IAM 权限（仅限 Google 管理的绑定）

代理资格要求

支持的模型提供商

支持的位置

配置和启用

Google 管理的绑定

REST

gcloud

检索自动生成的 DNS 主机名

gcloud

REST

自行管理的绑定

REST

gcloud

配置网络（仅限自行管理）

将政策引擎连接到 Agent Gateway

gcloud

REST

gcloud

REST

创建政策

控制台

gcloud

查找您的代理 ID

创建代理范围政策

查找 MCP 服务器

创建工具范围政策

包含多项政策的拒绝消息

启用试运行模式

控制用户意图匹配

查看政策评估日志

启用请求跟踪

管理政策配置

删除政策

取消预配政策引擎

REST

gcloud

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

（可选）删除授权扩展

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

移除专用 DNS 区域

移除子网和 VPC

（可选）移除 IAM 绑定

（可选）停用 Cloud Trace API

（可选）停用 Agent Platform API

调试政策执行情况

错误目录

后续步骤

配置语义治理政策