Mengonfigurasi kebijakan tata kelola semantik

Mengonfigurasi kebijakan tata kelola Semantik dan Policy Engine

Bagian ini membahas transisi dari kesiapan infrastruktur ke penulisan kebijakan.

Prasyarat

Sebelum mengonfigurasi kebijakan tata kelola semantik, selesaikan langkah-langkah berikut.

Aktifkan API yang diperlukan

Sebelum memulai, aktifkan API yang diperlukan untuk Kebijakan tata kelola semantik dan komponen jaringannya:

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

Memberikan izin IAM ke akun layanan Vertex AI (khusus binding yang dikelola Google)

Jika Anda menggunakan opsi binding yang dikelola Google selama penyediaan, berikan peran yang diperlukan akun layanan Vertex AI (P4SA) untuk membuat endpoint Private Service Connect (PSC) (roles/compute.networkAdmin) dan set data DNS (roles/dns.admin) di project Anda. Jika menggunakan opsi Binding yang dikelola sendiri, Anda dapat melewati langkah ini karena Anda membuat resource jaringan tersebut sendiri.

Buat identitas layanan (idempotensi) dan berikan peran:

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.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/compute.networkAdmin"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/dns.admin"

Perintah penghapusan yang sesuai ada di Hapus binding IAM di bagian pembersihan.

Persyaratan kelayakan agen

Agar muncul di pemilih agen kebijakan tata kelola Semantik di konsol Cloud de Confiance , mesin penalaran agen harus telah di-deploy dengan setelan identity_type=AGENT_IDENTITY dan agent_gateway_config. Jika salah satunya tidak ada, konsol Cloud de Confiance akan memfilter agen dari pemilih. API dan gcloud akan menampilkan error eksplisit.

Untuk men-deploy agen yang memenuhi persyaratan ini, ikuti langkah-langkah di bagian Merutekan traffic Agent Runtime melalui Agent Gateway. Kedua kolom tidak dapat diubah pada mesin penalaran yang ada, sehingga agen yang di-deploy tanpa kolom tersebut harus di-deploy ulang — patching tidak akan berfungsi.

Untuk memverifikasi bahwa agen yang ada memenuhi syarat, konfirmasi bahwa mesin penalaran spec.effectiveIdentity-nya dimulai dengan 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"

Lokasi yang didukung

Policy Engine Tata kelola semantik dan Kebijakan tata kelola semantik didukung di lokasi regional berikut:

Penyediaan dan pemberdayaan

Aktifkan Policy Engine tata kelola semantik. Tindakan ini menyediakan lingkungan runtime yang diperlukan. Proses penyediaan biasanya memerlukan waktu sekitar 2 hingga 3 menit. Namun, saat permintaan tinggi atau pool warmup sedang diisi ulang, penyediaan dapat memerlukan waktu hingga 20 menit. Pilih salah satu opsi penyediaan berikut:

• Binding yang dikelola Google: Google membuat resource jaringan yang mendasarinya di project Cloud de Confiance by S3NS Anda dan mengelola siklus prosesnya secara otomatis.
• Pengikatan yang dikelola sendiri: Anda membuat dan mengelola resource jaringan yang diperlukan (network, subnetwork, dan dnsZoneName) langsung di project Cloud de Confiance by S3NS Anda.

Setelah menyelesaikan penyediaan, Anda harus menghubungkan Policy Engine ke Agent Gateway.

Binding yang dikelola Google

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 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"

Ganti kode berikut:

• GATEWAY_NAME dengan nama gateway yang unik.
• DNS_NAME dengan nama zona DNS pribadi yang akan digunakan.
• PROJECT_ID dengan project ID Cloud de Confiance by S3NS Anda (projects/PROJECT_ID/global/networks/default). Jika Anda menggunakan jaringan dan subnet kustom, ganti jalur resource network dan subnetwork lengkap sebagaimana mestinya.

Mengambil nama host DNS yang dibuat secara otomatis

Saat Anda menyediakan mesin dengan binding yang dikelola Google, Google akan otomatis membuat endpoint Private Service Connect (PSC) dan mendaftarkan data A DNS di zona DNS pribadi Anda. FQDN data ini berfungsi sebagai SGP_DNS_HOSTNAME dan diisi di kolom khusus output dnsRecord pada konfigurasi gateway Anda.

Untuk mengambil nama host DNS yang dibuat secara otomatis:

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

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

Dalam respons, temukan kolom dnsRecord di bagian gatewayConfigs.GATEWAY_NAME.dnsRecord. Simpan FQDN ini—Anda akan memerlukannya sebagai SGP_DNS_HOSTNAME saat menghubungkan Policy Engine ke Agent Gateway.

Binding yang dikelola sendiri

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

Perintah ini menampilkan operasi yang berjalan lama. Anda dapat melakukan polling status operasi dengan mengganti OPERATION dengan nilai name dari respons:

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

Atau, periksa status mesin secara keseluruhan hingga kolom state menampilkan 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"

Mengonfigurasi jaringan (khusus yang dikelola sendiri)

Setelah Policy Engine disediakan, konfigurasi komponen jaringan yang diperlukan agar Agent Gateway dapat berkomunikasi dengan Policy Engine.

Meskipun Google otomatis membuat endpoint PSC di project tenant yang dikelola Google untuk jalur yang dikelola Google, untuk jalur yang dikelola sendiri, Anda harus membuat dan mengelola endpoint PSC secara manual di project Anda sendiri Cloud de Confiance by S3NS .

1. Menyediakan jaringan VPC dan subnet

Pada langkah ini, Anda akan membuat jaringan VPC, subnet, dan subnet khusus proxy untuk traffic agen. Rentang IP yang ditampilkan (10.11.12.0/24 dan 10.11.13.0/24) adalah contoh. Anda dapat menggunakan rentang pribadi RFC 1918 apa pun yang sesuai dengan desain jaringan Anda.

1. Buat jaringan VPC:

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

   Ganti NETWORK_NAME dengan nama untuk jaringan VPC Anda (misalnya, agent-network).

2. Buat subnet:

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

   Ganti SUBNET_NAME dengan nama untuk subnet Anda (misalnya, agent-subnet).

3. Buat subnet khusus proxy (diperlukan untuk load balancer terkelola):

   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
   

   Ganti PROXY_SUBNET_NAME dengan nama untuk subnet khusus proxy Anda (misalnya, agent-proxy-subnet).

2. Menyediakan zona DNS pribadi

Buat zona DNS pribadi agar Agent Gateway dapat me-resolve nama host Policy Engine:

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: nama untuk zona DNS Anda (misalnya, my-private-zone).
• internal.example.com.: nama DNS untuk zona Anda, termasuk titik di bagian akhir.

3. Buat network attachment

Buat lampiran jaringan untuk mengizinkan Agent Gateway terhubung ke resource di VPC Anda. Preferensi koneksi harus ditetapkan ke 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: nama untuk lampiran jaringan Anda (misalnya, sgp-nw-attachment).
• SUBNET_NAME: subnet yang Anda buat di langkah 1.

4. Buat IP statis, endpoint PSC, dan data DNS

Cadangkan alamat IP statis, buat endpoint Private Service Connect (PSC) yang mengarah ke lampiran layanan Policy Engine, dan buat catatan DNS agar dapat dijangkau.

# 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

Ganti kode berikut:

• STATIC_IP_NAME: nama untuk alamat IP yang dipesan (misalnya, sgp-psc-ip).
• PSC_ENDPOINT_NAME: nama untuk endpoint PSC Anda (misalnya, sgp-psc-endpoint).
• PSC_SERVICE_ATTACHMENT: nilai pscServiceAttachment yang disimpan dari respons penyediaan.
• SGP_DNS_HOSTNAME: nama host di zona DNS pribadi Anda, dalam format LOCATION.DNS_ZONE_SUFFIX, dengan DNS_ZONE_SUFFIX adalah nama DNS yang Anda tentukan saat membuat zona DNS pribadi. Misalnya, jika lokasi Anda adalah us-west1 dan akhiran zona DNS Anda adalah internal.example.com, gunakan us-west1.internal.example.com.

5. Mengonfigurasi konektivitas VPC di Agent Gateway

Setelah membuat resource jaringan, Anda harus mendaftarkan network attachment dan peering DNS di Agent Gateway agar dapat menjangkau Policy Engine melalui jaringan pribadi.

Untuk petunjuk mendetail, lihat Mengonfigurasi konektivitas VPC di panduan penyiapan Gateway Agen. Setidaknya, Anda harus:

• Daftarkan network attachment yang dibuat pada langkah 3 dengan konfigurasi egress Agent Gateway Anda.
• Daftarkan peering DNS agar gateway dapat me-resolve nama host DNS pribadi yang dibuat di langkah 4.

Menghubungkan mesin kebijakan ke Agent Gateway

Setelah jaringan dikonfigurasi, Anda harus membuat ekstensi otorisasi dan kebijakan otorisasi agar Agent Gateway dapat meneruskan traffic ke Policy Engine untuk dievaluasi.

1. Buat ekstensi otorisasi: Buat ekstensi otorisasi yang mengarah ke nama host DNS Policy Engine. Gunakan SGP_DNS_HOSTNAME yang sama dengan yang Anda buat data DNS-nya di Mengonfigurasi jaringan (langkah 4). Ini adalah mekanisme yang digunakan Agent Gateway untuk mengirim traffic ke mesin kebijakan untuk dievaluasi.

   gcloud

   Tentukan konfigurasi ekstensi dalam file YAML (authz-ext.yaml) dan impor:

   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"
       }'
   

   Ganti SGP_DNS_HOSTNAME dengan nama host DNS yang data A-nya Anda buat di Mengonfigurasi jaringan (langkah 4).

   Perintah ini menampilkan operasi yang berjalan lama. Tunggu hingga operasi selesai sebelum melanjutkan.

2. Buat kebijakan otorisasi: Buat kebijakan otorisasi yang mengikat ekstensi ke Agent Gateway Anda. Tindakan ini akan memberi tahu Agent Gateway untuk mengirim traffic melalui Policy Engine untuk dievaluasi.

   gcloud

   Tentukan konfigurasi kebijakan otorisasi dalam file YAML (authz-policy.yaml) dan impor:

   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"]
           }
         }
       }'
   

   Perintah ini menampilkan operasi yang berjalan lama. Tunggu hingga operasi selesai sebelum melanjutkan.

Buat kebijakan

Setelah Policy Engine aktif, Anda dapat menentukan batas aman teknis dan perilaku untuk agen Anda.

1. Tentukan cakupan: Tentukan apakah kebijakan berlaku untuk semua tindakan yang dilakukan oleh agen atau menargetkan alat tertentu.
2. Tulis batasan: Berikan aturan bisnis Anda dalam bahasa Inggris yang jelas.

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=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

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

Pesan penolakan dengan beberapa kebijakan

Jika satu permintaan memicu penolakan dari beberapa kebijakan, mesin kebijakan akan menggabungkan pesan penolakan yang dikonfigurasi pada kebijakan tersebut sebelum mengembalikan respons kepada pengguna. Perilaku berikut berlaku:

• Pesan penolakan dari setiap kebijakan dengan hasil penolakan ditampilkan bersama, dipisahkan oleh baris kosong.
• Pesan duplikat ditampilkan satu kali.
• Jika beberapa kebijakan penyiapan memiliki pesan penolakan yang dikonfigurasi dan yang lainnya tidak, baris umum "Permintaan ini ditolak karena kebijakan bisnis lainnya." ditambahkan untuk mencakup kebijakan yang tidak memiliki pesan penolakan.
• Maksimal 5 pesan penolakan ditampilkan per permintaan; pesan tambahan tidak ditampilkan.

Mengaktifkan mode uji coba

Anda dapat mengaktifkan mode uji coba (DRY_RUN). Uji coba adalah mode khusus audit atau simulasi yang memungkinkan Anda mengevaluasi kebijakan tanpa menerapkannya. Dalam mode ini, Policy Engine mengevaluasi semua panggilan alat berdasarkan batasan Anda dan mencatat keputusan, tetapi tidak pernah memblokir tindakan. Dengan begitu, Anda dapat menguji dan memvalidasi batasan sebelum mengaktifkan penerapan.

Untuk mengaktifkan mode uji coba, tambahkan sgpEnforcementMode: DRY_RUN ke metadata ekstensi otorisasi Anda:

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"
      }
    }'

Dalam mode uji coba:

• Semua panggilan alat diizinkan terlepas dari hasilnya.
• Putusan dan alasan dicatat untuk ditinjau.
• Anda dapat meninjau log untuk mengidentifikasi tindakan mana yang akan diblokir dan menyempurnakan batasan sebelum beralih ke mode diterapkan.

Untuk beralih kembali ke mode penegakan normal, hapus sgpEnforcementMode dari metadata:

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

Melihat log evaluasi kebijakan

Policy Engine menulis entri log terstruktur untuk setiap evaluasi ke Cloud Logging di project Anda. Entri mencatat verdict keseluruhan dan array evaluations dengan verdict dan rationale untuk setiap alat atau tindakan.

1. Dari Konsol: Di halaman Kebijakan, pilih kebijakan.
2. Di panel Details, di bagian Observability, klik Cloud Logging > View details.

3. Di Logs Explorer: ketik semantic-governance-policy di kotak kueri atau gunakan filter eksplisit berikut:

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

Contoh berikut adalah contoh entri log:

{
  "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"
}

Kolom utama:

• verdict: Keputusan keseluruhan, baik ALLOW maupun DENY.
• evaluations[].rationale: Alasan mengapa Policy Engine mencapai putusan tertentu untuk setiap alat atau tindakan.
• token_usage: Jumlah token model yang digunakan evaluasi.

Mengaktifkan pelacakan permintaan

Policy Engine mengekspor trace untuk setiap permintaan yang dievaluasinya ke Cloud Trace di project Anda, sehingga Anda dapat memeriksa latensi per permintaan dan penegakan kebijakan. Untuk menerima rekaman aktivitas ini, aktifkan Cloud Trace API dan berikan izin akun layanan Vertex AI (P4SA) untuk menulis rekaman aktivitas.

1. Aktifkan Cloud Trace API:

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

2. Berikan peran Cloud Trace Agent (roles/cloudtrace.agent) ke akun layanan Vertex AI. Peran ini hanya memberikan izin trace-write (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.s3ns-system.iam.gserviceaccount.com" \
       --role="roles/cloudtrace.agent"
   

Setelah keduanya dikonfigurasi, kirim permintaan melalui agen Anda dan lihat rekaman aktivitas di Trace explorer untuk project Anda.

Mengelola konfigurasi kebijakan

Setelah Kebijakan tata kelola semantik berjalan, Anda dapat menghapus kebijakan satu per satu atau memutuskan hubungan mesin dari Agent Gateway.

Menghapus kebijakan

Untuk menghapus kebijakan satu per satu tanpa memengaruhi integrasi Kebijakan tata kelola semantik secara keseluruhan:

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

Atau, gunakan perintah curl berikut:

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)"

Membatalkan penyediaan Policy Engine

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

Memutuskan hubungan Policy Engine dari Agent Gateway

Anda dapat memutuskan hubungan Policy Engine dari Agent Gateway untuk menghentikan evaluasi panggilan alat terhadap batasan Anda.

Hapus kebijakan otorisasi yang mengikat penerapan kebijakan tata kelola Semantik ke Agent Gateway Anda:

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

Untuk menghubungkan kembali mesin kebijakan nanti, buat ulang kebijakan otorisasi seperti yang dijelaskan dalam Menghubungkan mesin kebijakan ke Agent Gateway.

(Opsional) Menghapus ekstensi otorisasi

Hapus ekstensi otorisasi yang dibuat selama penyiapan.

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

(Opsional) Membersihkan resource yang dikelola pelanggan

Membatalkan penyediaan mesin hanya akan menghapus resource pendukung yang dikelola Google. Anda harus menghapus resource yang Anda buat di project Anda sendiri secara manual selama penyiapan jika tidak lagi diperlukan.

Hapus zona DNS pribadi

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

Hapus subnet dan VPC

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

gcloud compute networks delete NETWORK_NAME \
    --project=PROJECT_ID

(Opsional) Menghapus binding IAM

Jika Anda memberikan izin ke akun layanan Vertex AI (P4SA), Anda dapat menghapusnya:

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.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/compute.networkAdmin"

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/dns.admin"

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-${PROJECT_NUM}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

(Opsional) Nonaktifkan Cloud Trace API

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

(Opsional) Menonaktifkan Agent Platform API

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

Men-debug penegakan kebijakan

Untuk men-debug keputusan yang tidak terduga:

1. Periksa hasil dan alasan di log evaluasi kebijakan.
2. Lacak permintaan -- lihat Mengaktifkan pelacakan permintaan.
3. Validasi perubahan dengan aman menggunakan mode uji coba.
4. Konfirmasi deployment -- status mesin adalah ACTIVE dan binding gateway telah dibuat.

Katalog error

Tabel berikut mencantumkan error yang mungkin Anda alami saat mengelola Kebijakan Tata Kelola Semantik, beserta langkah-langkah untuk mengatasinya:

Langkah berikutnya

• Pelajari lebih lanjut perintah gcloud CLI Vertex AI.
• Pantau keputusan kebijakan di Log Explorer.