設定語意管理政策

設定語意管理政策和政策引擎

本節說明如何從基礎架構準備階段過渡到政策撰寫階段。

必要條件

設定語意管理政策前，請先完成下列步驟。

啟用必要的 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 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. 佈建虛擬私有雲網路和子網路

在這個步驟中，您將建立虛擬私有雲網路、子網路，以及僅限 Proxy 的子網路，用於代理程式流量。顯示的 IP 範圍 (10.11.12.0/24 和 10.11.13.0/24) 僅為範例。您可以根據網路設計使用任何 RFC 1918 私人範圍。

1. 建立虛擬私有雲網路：

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

   將 NETWORK_NAME 替換為虛擬私有雲網路的名稱 (例如 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. 建立僅限 Proxy 的子網路 (管理型負載平衡器必須使用)：

   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 替換為僅限 Proxy 子網路的名稱 (例如 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 連線至虛擬私有雲中的資源。連線偏好設定必須設為 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 的虛擬私有雲連線

建立網路資源後，您必須在 Agent Gateway 上註冊網路連結和 DNS 對等互連，才能透過私人網路連線至政策引擎。

如需詳細操作說明，請參閱 Agent Gateway 設定指南中的「設定 VPC 連線」。您至少必須：

• 使用 Agent Gateway 輸出設定，註冊步驟 3 中建立的網路連結。
• 註冊 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，以及每個工具或動作的 verdict 和 rationale 陣列。evaluations

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：評估作業消耗的模型權杖數量。

啟用要求追蹤

政策引擎會將評估的每項要求追蹤記錄匯出至專案的 Cloud Trace，方便您檢查每項要求的延遲時間和政策執行情況。如要接收這些追蹤記錄，請啟用 Cloud Trace API，並授予 Vertex AI 服務帳戶 (P4SA) 寫入追蹤記錄的權限。

1. 啟用 Cloud Trace API：

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

2. 將 Cloud Trace 代理程式角色 (roles/cloudtrace.agent) 授予 Vertex AI 服務帳戶。這個角色只會授予追蹤寫入權限 (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

移除子網路和虛擬私有雲

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 中監控政策判定結果。