配置语义治理政策和政策引擎
本部分介绍了从基础设施准备到政策撰写的过渡。
前提条件
在配置语义治理政策之前,请完成以下步骤。
启用必需的 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 专用范围。
创建 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_UNSPECIFIEDgcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \ --source=authz-ext.yaml \ --location=LOCATION \ --project=PROJECT_IDREST
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.endsWith(':generateContent') || request.path.endsWith(':streamGenerateContent'))" action: CUSTOM policyProfile: CONTENT_AUTHZ customProvider: authzExtension: resources: - projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHZ_EXTENSION_NAMEgcloud network-security authz-policies import AUTHZ_POLICY_NAME \ --source=authz-policy.yaml \ --location=LOCATION \ --project=PROJECT_IDREST
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"] } } }'此命令会返回一个长时间运行的操作。请等待操作完成后再继续。
创建政策
政策引擎处于有效状态后,您可以为代理定义技术和行为准则。
- 定义范围:确定政策是适用于智能体执行的所有操作,还是针对特定工具。
- 撰写限制条件:以纯英文提供业务规则。
控制台
- 在 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)。将此值用于完全限定的代理名称(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。
- 在控制台中:在政策页面上,选择一项政策。
- 在详细信息面板的可观测性部分中,点击 Cloud Logging > 查看详细信息。
在 Logs Explorer 中:在查询框中输入
semantic-governance-policy,或使用以下明确的过滤条件:logName="projects/PROJECT_ID/logs/semantic-governance-policy"
以下示例是一个日志条目示例:
{
"jsonPayload": {
"token_usage": 1859,
"verdict": "ALLOW"