Mengelola Agent Gateway

Dokumen ini menjelaskan tugas pemeliharaan pasca-deployment untuk resource Agent Gateway. Jika Anda belum membuat gateway, lihat Menyiapkan Gateway Agen.

Sebelum memulai

Sebelum Anda mengelola resource Agent Gateway, verifikasi prasyarat berikut:

Melihat dan memeriksa gateway

Anda dapat mencantumkan resource Agent Gateway dalam project Google Cloud dan memeriksa konfigurasi gateway, ekstensi yang dilampirkan, dan metadata khusus output.

Konsol

  1. Di konsol Google Cloud , buka halaman Gateways.

    Buka Gateways

  2. Lihat daftar gateway di project yang Anda pilih.

  3. Klik nama gateway untuk membuka halaman detailnya:

    • Di tab Details, tinjau bagian Overview, Access authorization, AI Security, Service Extensions, dan VPC configuration.
    • Di tab Observability, tinjau metrik kebijakan dan traffic gateway. Untuk mengetahui informasi selengkapnya, lihat Memantau traffic Agent Gateway.

gcloud

  • Mencantumkan semua gateway di region tertentu:

    gcloud network-services agent-gateways list \
  --location=LOCATION \
  --project=PROJECT_ID

    Ganti kode berikut:

    • LOCATION: region tempat gateway Anda di-deploy, seperti us-central1.
    • PROJECT_ID: ID project Google Cloud yang menghosting gateway.

  • Periksa konfigurasi gateway tertentu:

    gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID

    Ganti AGENT_GATEWAY_NAME dengan nama resource Agent Gateway.

Setelan yang tidak dapat diubah

Sebagian besar konfigurasi Agent Gateway seperti instance Agent Registry terkait serta kebijakan keamanan dan tata kelola dapat diubah langsung seperti yang dijelaskan dalam Mengupdate Agent Gateway. Namun, konfigurasi inti tertentu tidak dapat diubah dan mengharuskan Anda men-deploy gateway pengganti. Periksa tabel berikut sebelum mengubah gateway:

Setelan Mutabilitas Persyaratan atau batasan
Nama dan region gateway Tidak dapat diubah Untuk mengubah nama atau region, deploy gateway pengganti.

Jalur akses yang diatur

(AGENT_TO_ANYWHERE atau CLIENT_TO_AGENT)

 Tidak dapat diubah Dikonfigurasi saat pembuatan di googleManaged.governedAccessPath. Tidak dapat diubah di tempat.

Lampiran jaringan Private Service Connect

(networkAttachment)

 Tidak dapat diubah setelah ditetapkan Setelah Anda mengaitkan lampiran jaringan dengan gateway, lampiran tersebut tidak dapat diubah atau dihapus.

Template konektivitas agen dan peering Cloud DNS, konfigurasi kepercayaan TLS, dan setelan egress VPC terkait

 Dapat diubah secara bersyarat Anda dapat memperbarui konfigurasi gateway untuk merujuk ke template konektivitas yang berbeda dengan setelan baru, asalkan template baru masih merujuk ke networkAttachment yang sama.

Mengganti gateway untuk mengubah setelan yang tidak dapat diubah

Jika Anda perlu mengubah setelan yang tidak dapat diubah, seperti lampiran jaringan PSC yang terkait dengan gateway, Anda harus men-deploy gateway pengganti dan memigrasikan workload ke gateway baru:

  1. Buat Gateway Agen pengganti dan konfigurasikan kebijakan Identity and Access Management (IAM) dan otorisasi. Untuk mengetahui petunjuknya, lihat Menyiapkan Gateway Agen.

  2. Perbarui workload Anda untuk menggunakan gateway pengganti:

    • Aplikasi Gemini Enterprise: Perbarui nama resource gateway di setelan Security > Configuration aplikasi. Lihat Merutekan traffic Gemini Enterprise melalui Agent Gateway.
    • Agen Agent Runtime: Dalam satu project dan region, semua agen Agent Runtime harus terikat ke gateway yang sama. Update langsung di tempat dari satu gateway ke gateway lain tidak didukung. Untuk memigrasikan agen Anda:
      1. Pastikan setiap agen terikat merutekan 100% traffic ke revisi terbarunya (trafficConfig.trafficSplitAlwaysLatest).
      2. Batalkan pengaitan semua agen dalam project dan region dari gateway sebelumnya dengan menetapkan spec.deploymentSpec.agentGatewayConfig ke {} menggunakan reasoningEngines.patch, dan tunggu hingga setiap operasi update selesai.
      3. Panggil reasoningEngines.patch di setiap agen untuk menetapkan spec.deploymentSpec.agentGatewayConfig ke nama resource gateway pengganti. Untuk contoh permintaan, lihat Merutekan traffic Agent Runtime melalui Agent Gateway.

  3. Setelah semua workload berhenti mereferensikan gateway sebelumnya, ikuti langkah-langkah di bagian Menghapus Gateway Agen untuk menghapus gateway sebelumnya.

Mengupdate Agent Gateway

Anda dapat memperbarui konfigurasi Agent Gateway tertentu langsung di konsol Google Cloud atau menggunakan gcloud CLI untuk mengekspor konfigurasi gateway ke file YAML, membuat perubahan, dan mengimpor ulang file.

Mengupdate Agent Registry

Anda dapat memperbarui Agent Registry terkait di konsolGoogle Cloud atau gcloud CLI. Gateway Anda harus mereferensikan satu registry regional yang sesuai dengan region gateway. Jika gateway ditautkan ke aplikasi Gemini Enterprise, gateway harus menyimpan satu registry yang cocok dengan lokasi aplikasi tersebut.

Konsol

  1. Di konsol Google Cloud , buka halaman Gateways.

    Buka Gateways

  2. Klik nama gateway yang ingin Anda perbarui.

  3. Di tab Details, di bagian Overview, klik Edit registries.

  4. Pilih Agent Registry regional yang cocok dengan region tempat gateway Anda di-deploy, lalu klik Save.

gcloud

Ekspor konfigurasi gateway ke agent-gateway.yaml menggunakan gcloud network-services agent-gateways export, edit registries, description, atau labels (menghapus kolom khusus output seperti createTime, updateTime, agentGatewayCard, dan selfLink), lalu impor ulang file menggunakan gcloud network-services agent-gateways import seperti yang ditunjukkan dalam Memperbarui template konektivitas gateway.

Memperbarui template konektivitas

Anda dapat memperbarui template konektivitas resource Agent Gateway menggunakan gcloud CLI.

gcloud

  1. Buat AgentConnectivityTemplate baru dengan setelan konektivitas yang telah diperbarui, dan pastikan gateway tersebut menggunakan networkAttachment yang sama dengan gateway yang ada. Untuk mengetahui petunjuk konfigurasi dan sintaksis template yang mendetail, lihat Menyiapkan Gateway Agen dengan konektivitas VPC.

  2. Ekspor konfigurasi gateway yang ada ke file YAML:

    gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \
 --destination="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

    Ganti kode berikut:

    • AGENT_GATEWAY_NAME: nama gateway yang akan diupdate.
    • LOCATION: region tempat gateway di-deploy.
    • PROJECT_ID: project ID tempat gateway di-deploy.

  3. Dalam file agent-gateway.yaml yang diekspor, biarkan kolom protocols, registries, description, dan labels yang ada tetap utuh, hapus kolom khusus output (createTime, updateTime, agentGatewayCard, selfLink), dan perbarui agentConnectivityTemplate untuk mereferensikan template baru:

    name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION
agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME

    Ganti kode berikut:

    • PROJECT_NUMBER: nomor project numerik tempat gateway di-deploy (agentConnectivityTemplate memerlukan nomor project, bukan project ID).
    • LOCATION: region gateway.
    • AGENT_GATEWAY_NAME: nama gateway.
    • NEW_TEMPLATE_NAME: nama template konektivitas pengganti.

  4. Impor ulang file YAML yang telah diperbarui untuk menerapkan perubahan Anda:

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

  5. Opsional: Hapus template konektivitas sebelumnya setelah update gateway selesai:

    gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

Mengubah setelan IAP atau template Model Armor

Anda dapat mengubah setelan penerapan IAP dan template Model Armor dengan memperbarui ekstensi otorisasi yang dilampirkan ke gateway Anda.

Konsol

  1. Di konsol Google Cloud , buka halaman Gateways.

    Buka Gateways

  2. Klik nama gateway yang ingin Anda perbarui.

  3. Di tab Details, perbarui ekstensi keamanan yang dilampirkan:

    • Mengubah mode penerapan IAP: Di bagian Access authorization, di samping Access authorization, klik Edit access authorization. Pilih Audit-only (mode uji coba) atau Enforce policies, lalu klik Save.

    • Mengubah template Model Armor: Di bagian AI Security, klik Edit request template di samping Template for requests atau Edit response template di samping Template for responses. Pilih template pengganti, lalu klik Simpan.

gcloud

  1. Cantumkan ekstensi otorisasi di region gateway untuk mengidentifikasi nama ekstensi:

    gcloud service-extensions authz-extensions list \
 --location=LOCATION \
 --project=PROJECT_ID

    Ganti LOCATION dengan region gateway dan PROJECT_ID dengan project ID Anda.

  2. Periksa konfigurasi ekstensi saat ini:

    gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \
 --location=LOCATION \
 --project=PROJECT_ID \
 --format=yaml

    Ganti AUTHZ_EXTENSION_NAME dengan nama resource AuthzExtension IAP atau Model Armor Anda.

  3. Simpan spesifikasi ekstensi yang telah diupdate ke authz-extension.yaml, dengan menghilangkan kolom khusus output seperti createTime dan updateTime:

    • Untuk ekstensi IAP: Sertakan iamEnforcementMode: "DRY_RUN" untuk mode khusus audit, atau hapus iamEnforcementMode untuk menerapkan kebijakan:

      name: AUTHZ_EXTENSION_NAME
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policies

    • Untuk ekstensi Model Armor: Perbarui request_template_id dan response_template_id di metadata.model_armor_settings:

      name: AUTHZ_EXTENSION_NAME
service: modelarmor.LOCATION.rep.googleapis.com
failOpen: false
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
      "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
    }
  ]'

      Ganti kode berikut:

      • AUTHZ_EXTENSION_NAME: nama resource AuthzExtension Model Armor Anda.
      • LOCATION: region gateway.
      • MODEL_ARMOR_PROJECT_ID: project ID yang menghosting template Model Armor Anda.
      • REQUEST_TEMPLATE_ID dan RESPONSE_TEMPLATE_ID: ID template permintaan dan respons Anda.

      Pastikan akun layanan gateway (agentGatewayCard.serviceExtensionsServiceAccount) memiliki roles/modelarmor.user pada project template yang baru direferensikan, serta roles/modelarmor.calloutUser dan roles/serviceusage.serviceUsageConsumer pada project gateway (lihat Mendelegasikan otorisasi).

  4. Impor file YAML ekstensi yang telah diperbarui:

    gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \
 --source="authz-extension.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

Untuk melampirkan kebijakan otorisasi baru atau mengubah aturan pencocokan traffic pada AuthzPolicy yang ada, lihat Mendelegasikan otorisasi.

Membatalkan pengaitan workload dari Agent Gateway

Sebelum dapat menghapus Gateway Agen, Anda harus membatalkan pengaitan setiap aplikasi Gemini Enterprise dan agen Runtime Agen yang merujuk ke gateway.

Membatalkan pengaitan aplikasi Gemini Enterprise

Anda dapat membatalkan tautan Gateway Agen dari aplikasi Gemini Enterprise di konsol Google Cloud :

  1. Di konsol Google Cloud , buka halaman Gemini Enterprise.

    Buka Gemini Enterprise

  2. Klik nama aplikasi yang terkait dengan gateway.

  3. Klik Keamanan.

  4. Di tab Configuration, di bagian Agent Gateway configuration, hapus kolom Agent Gateway resource name.

  5. Klik Simpan.

Membatalkan pengaitan Agent Gateway akan menghentikan perutean traffic keluar aplikasi melalui gateway. Agen dan server Model Context Protocol (MCP) yang diimpor tetap terdaftar di Agent Registry, tetapi aplikasi tidak dapat mengaksesnya hingga Anda menautkan gateway lagi. Perhatikan bahwa gateway baru harus merujuk ke Agent Registry yang sama.

Membatalkan pengaitan agen Agent Runtime

Konsol Google Cloud dan gcloud CLI tidak mendukung pengubahan binding gateway Agent Runtime. Untuk memisahkan Gateway Agen dari agen Agent Runtime yang di-deploy sambil tetap menjalankan agen, Anda dapat memanggil metode REST API reasoningEngines.patch untuk menghapus spec.deploymentSpec.agentGatewayConfig:

  1. Pastikan agen merutekan semua traffic ke revisi terbaru (trafficConfig.trafficSplitAlwaysLatest ditetapkan ke true, atau tidak ada pemisahan trafficConfig manual yang dikonfigurasi). Menghapus atau mengubah binding gateway akan gagal jika pemisahan traffic revisi manual aktif dan mengarsipkan semua revisi sebelumnya secara permanen. Untuk mengetahui detailnya, lihat Agent Gateway dan revisi.

  2. Kirim permintaan PATCH ke mesin penalaran dengan updateMask=spec.deploymentSpec.agentGatewayConfig dan objek agentGatewayConfig kosong ({}):

    curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -d '{
   "spec": {
     "deploymentSpec": {
       "agentGatewayConfig": {}
     }
   }
 }' \
 "https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

    Ganti kode berikut:

    • REGION: region tempat agen di-deploy.
    • PROJECT_ID: project ID tempat agen di-deploy.
    • RESOURCE_ID: ID resource agen.

Menghapus Gateway Agen

Agent Gateway menerapkan pelacakan referensi yang ketat untuk mencegah kebijakan keamanan yang tidak terhubung dan jalur traffic agen yang rusak. Penghapusan gateway gagal, dan tombol Delete di konsol Google Cloud tetap tidak tersedia, jika salah satu kondisi berikut berlaku:

  • Satu atau beberapa agen Agent Runtime atau aplikasi Gemini Enterprise masih mereferensikan gateway.
  • Setiap AuthzPolicy (untuk IAP, Model Armor, atau penyedia kustom) atau TelemetryPolicy masih menargetkan gateway.
  • Operasi update konfigurasi VPC masih berjalan di gateway.

Selesaikan langkah-langkah berikut secara berurutan untuk menghapus Agent Gateway dan membersihkan resource terkait:

Konsol

  1. Pastikan tidak ada aplikasi Gemini Enterprise atau agen Agent Runtime yang merujuk ke gateway. Ikuti petunjuk di Membatalkan pengaitan workload dari Agent Gateway.

  2. Di konsol Google Cloud , buka halaman Gateways.

    Buka Gateways

  3. Klik nama gateway yang ingin Anda hapus.

  4. Di tab Details, hapus semua pengaitan kebijakan yang menargetkan gateway:

    • Jika bagian Access authorization muncul, klik Remove, lalu konfirmasi penghapusan. Tindakan ini akan menghapus AuthzPolicy IAP dan AuthzExtension-nya.
    • Jika bagian AI Security muncul, klik Remove, lalu konfirmasi penghapusan. Tindakan ini akan menghapus Model Armor AuthzPolicy dan AuthzExtension-nya.
    • Periksa tabel Service Extensions. Jika masih ada resource AuthzPolicy kustom yang terpasang, gunakan tab gcloud dalam prosedur ini untuk menghapusnya sebelum melanjutkan.

  5. Setelah semua pengaitan kebijakan dihapus dan tidak ada update VPC yang sedang berlangsung, klik Delete, lalu konfirmasi penghapusan.

  6. Pastikan gateway tidak lagi muncul dalam daftar Gateways untuk project Anda.

  7. Opsional: Bersihkan resource konektivitas yang tidak digunakan jika tidak ada gateway lain yang menggunakannya. Gunakan tab gcloud untuk menghapus AgentConnectivityTemplate, dan hapus lampiran jaringan.

gcloud

  1. Pastikan tidak ada aplikasi Gemini Enterprise atau agen Agent Runtime yang merujuk ke gateway. Ikuti petunjuk di Membatalkan pengaitan workload dari Agent Gateway.

  2. Hapus kebijakan otorisasi dan ekstensi otorisasi:

    1. Cantumkan kebijakan otorisasi di region gateway untuk menemukan kebijakan yang kolom target.resources-nya merujuk ke gateway Anda, dan catat authzExtensions yang dirujuk:

      gcloud network-security authz-policies list \
  --location=LOCATION \
  --project=PROJECT_ID \
  --format="yaml(name,target.resources,customProvider.authzExtension.resources)"

      Ganti LOCATION dengan region gateway dan PROJECT_ID dengan project ID Anda.

    2. Hapus setiap AuthzPolicy yang menargetkan gateway:

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

      Ganti AUTHZ_POLICY_NAME dengan ID setiap kebijakan otorisasi yang menargetkan gateway (misalnya, AGENT_GATEWAY_NAME-iap-authzpolicy atau AGENT_GATEWAY_NAME-aisecurity-authzpolicy untuk kebijakan yang dibuat konsol).

    3. Opsional: Setelah Anda menghapus resource AuthzPolicy yang mereferensikan, hapus resource AuthzExtension yang tidak digunakan oleh kebijakan lain:

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

      Ganti AUTHZ_EXTENSION_NAME dengan ID ekstensi otorisasi yang tidak digunakan.

  3. Hapus Gateway Agen:

    gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Ganti AGENT_GATEWAY_NAME dengan nama gateway yang akan dihapus.

  4. Pastikan gateway tidak lagi muncul dalam daftar gateway regional:

    gcloud network-services agent-gateways list \
 --location=LOCATION \
 --project=PROJECT_ID

  5. Opsional: Anda tidak dapat menghapus AgentConnectivityTemplate saat Gateway Agen mereferensikannya. Setelah Anda menghapus gateway, hapus template konektivitas yang tidak digunakan:

    gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

    Ganti CONNECTIVITY_TEMPLATE_NAME dengan nama template konektivitas yang tidak digunakan. Jika Anda tidak lagi memerlukan lampiran jaringan Private Service Connect, zona DNS pribadi Cloud DNS, atau resource TrustConfig Certificate Manager yang mendasarinya, lihat Menghapus lampiran jaringan.

Langkah berikutnya

Panduan

Pelajari cara mendelegasikan otorisasi untuk Agent Gateway ke IAP, Model Armor, atau layanan otorisasi kustom Anda sendiri.

Panduan

Pelajari cara memantau Agent Gateway.

Panduan

Pelajari cara menyiapkan Gateway Agen.

Pemecahan masalah

Pelajari cara memecahkan masalah konektivitas Agent Gateway.