Merutekan traffic Agent Runtime melalui Agent Gateway

Halaman ini menjelaskan cara merutekan traffic Agent Runtime melalui Agent Gateway. Agent Gateway adalah komponen jaringan dan keamanan pusat dari ekosistem Gemini Enterprise Agent Platform. Agent Gateway menyediakan konektivitas yang aman dan dikelola untuk semua interaksi agentic, baik yang terjadi antara pengguna dan agen, agen dan alat, atau antar-agen itu sendiri.

Sebelum memulai

• Pastikan Anda memahami cara men-deploy agen di Agent Runtime.

• Pelajari Agent Gateway. Anda dapat menggunakan Agent Gateway dalam mode Agent-to-Anywhere (keluar) untuk mengamankan dan mengatur semua komunikasi keluar dengan traffic keluar ke alat, model, API, dan agen lainnya. Anda menggunakan gateway dalam mode Client-to-Agent (masuk) untuk mengontrol klien mana yang dapat mengakses agen Anda. Gateway ini memungkinkan Anda memilih kebijakan IAP dan template Model Armor mana yang harus diterapkan pada interaksi ini.

  Satu instance Runtime dapat terikat ke gateway Agent-to-Anywhere (keluar) dan gateway Client-to-Agent (masuk) secara bersamaan.

Batasan

• Agent Gateway tidak dapat terikat ke Runtime Reasoning Engine yang dibuat sebelum 29 April 2026.

• Meskipun satu project dan region dapat menghosting beberapa instance Agent Gateway Agent-to-Anywhere (keluar) dan Client-to-Agent (masuk), semua agen Agent Runtime yang di-deploy dalam project dan region yang sama harus terikat ke instance Agent Gateway keluar dan masuk tertentu yang sama.

  Misalnya, jika project dan region berisi egress-gateway-X dan egress-gateway-Y, semua agen dalam project dan region tersebut harus dikonfigurasi untuk menggunakan gateway yang sama untuk keluar. Artinya, semua agen menggunakan egress-gateway-X atau semua agen menggunakan egress-gateway-Y. Anda tidak dapat mengonfigurasi agent-A untuk menggunakan egress-gateway-X dan agent-B untuk menggunakan egress-gateway-Y.

  Aturan binding yang sama ini juga berlaku untuk gateway masuk dalam project dan region.

• Layanan Security Command Center Agent Engine Threat Detection tidak tersedia saat Agent Gateway diaktifkan untuk agen.

• Dalam mode Client-to-Agent (masuk), Agent Gateway hanya dapat mengatur metode query dan streamQuery Agent Runtime. Untuk melindungi metode lain yang tidak didukung (seperti asyncQuery), Anda dapat menerapkan template Model Armor langsung dari aplikasi atau agen. Lihat Membersihkan perintah dan respons atau codelab ini tentang Membangun sistem agen yang aman dengan Model Armor.

Merutekan traffic Agent Runtime melalui Agent Gateway

Untuk merutekan traffic Agent Runtime melalui Agent Gateway, lakukan langkah-langkah berikut:

1. Buat resource Agent Gateway dan lampirkan kebijakan otorisasi sesuai kebutuhan. Anda dapat membuat gateway dalam mode Agent-to-Anywhere (keluar) atau mode Client-to-Agent (masuk). Perhatikan bahwa agen dan gateway harus dibuat dalam project dan region yang sama. Untuk mengetahui petunjuknya, lihat Menyiapkan Agent Gateway.

   Pastikan gateway dikonfigurasi untuk memenuhi kebutuhan deployment Anda. Misalnya, jika agen Anda memerlukan akses LLM, konfigurasi gateway untuk mengizinkan akses ini guna mencegah potensi kegagalan deployment Agent Runtime.

2. Konfigurasi agen Anda untuk merutekan traffic melalui Agent Gateway.

   • Untuk agen baru

     Tentukan resource gateway saat men-deploy agen Anda. Misalnya, untuk men-deploy agen di Agent Runtime, gunakan client.agent_engines.create untuk meneruskan objek local_agent beserta konfigurasi opsional.

     Jika Anda ingin menggunakan fitur platform yang dimediasi gateway seperti Model Armor atau Kebijakan Tata Kelola Semantik dengan agen ini, tetapkan agent_gateway_config dan identity_type=AGENT_IDENTITY dalam panggilan pembuatan, seperti yang ditunjukkan dalam contoh ini. Tanpa identity_type=AGENT_IDENTITY, effectiveIdentity instance Runtime akan kembali ke akun layanan Vertex AI default, dan Kebijakan Tata Kelola Semantik akan memfilter agen secara diam-diam dari pemilih pembuatan kebijakan.

     remote_agent = client.agent_engines.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME},
             # "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
           },
           "identity_type": types.IdentityType.AGENT_IDENTITY,
           # Other optional configuration ...
           # "requirements": requirements,
           # "gcs_dir_name": gcs_dir_name,
           # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
           "env_vars": {
             "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
           }
       },
     )

     Ganti AGENT_GATEWAY_TO_ANYWHERE_NAME dengan nama Agent Gateway yang Anda buat dalam mode Agent-to-Anywhere (keluar).

     Jika Anda membuat gateway dalam mode Client-to-Agent (masuk), gunakan kolom client_to_agent_config dan ganti AGENT_GATEWAY_CLIENT_TO_AGENT_NAME dengan nama Agent Gateway yang Anda buat untuk masuk.

   • Untuk agen yang ada

     Catatan: Memperbarui mesin penalaran yang ada untuk menetapkan agentGatewayConfig tidak mengubah identity_type-nya. Jika mesin awalnya dibuat tanpa identity_type=AGENT_IDENTITY, Anda tidak dapat membuatnya memenuhi syarat untuk Kebijakan Tata Kelola Semantik secara retrospektif dengan menambalnya. Anda harus men-deploy ulang mesin penalaran baru dengan agent_gateway_config dan identity_type=AGENT_IDENTITY yang ditetapkan pada waktu pembuatan agen.

     Agent-to-Anywhere

     Gunakan permintaan REST API berikut untuk mengaitkan agen yang ada dengan gateway Agent-to-Anywhere untuk keluar.

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

     Ganti kode berikut:

     • PROJECT_ID: project ID
     • REGION: region tempat agen di-deploy
     • AGENT_GATEWAY_TO_ANYWHERE_NAME: nama Agent Gateway yang Anda buat dalam mode Agent-to-Anywhere (keluar)
     • RESOURCE_ID: ID resource agen

     Client-to-Agent

     Gunakan permintaan REST API berikut untuk mengaitkan agen yang ada dengan gateway Client-to-Agent untuk masuk.

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

     Ganti kode berikut:

     • PROJECT_ID: project ID
     • REGION: region tempat agen di-deploy
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: nama Agent Gateway yang Anda buat dalam mode Client-to-Agent (masuk)
     • RESOURCE_ID: ID resource agen

3. Daftar ke instance Agent Registry di project dan region yang sama dengan agen dan gateway.

   gcloud agent-registry services create SERVICE_NAME \
     --project=PROJECT_ID \
     --location=REGION \
     --display-name="DISPLAY_NAME" \
     --endpoint-spec-type=no-spec \
     --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \
     --format="value(registryResource)"
   

   Ganti kode berikut:

   • SERVICE_NAME: Nama yang ingin Anda berikan ke resource, misalnya, allow-aiplatform-region-eu3.
   • PROJECT_ID: Project ID.
   • REGION: Region registry.
   • DISPLAY_NAME: Nama endpoint yang dapat dibaca manusia.

   Untuk mengetahui informasi selengkapnya, lihat Mendaftarkan agen.

4. Buat binding kebijakan IAM agent-to-registry untuk agen.

   gcloud iap web add-iam-policy-binding \
     --resource-type=agent-registry \
     --endpoint=ENDPOINT_ID \
     --region=REGION \
     --project=PROJECT_ID \
     --member=MEMBER \
     --role=roles/iap.egressor
   

   Ganti kode berikut:

   • ENDPOINT_ID: ID endpoint layanan agen terdaftar. Anda akan mendapatkannya dari output langkah sebelumnya.

   • MEMBER: Principal identitas agen yang akan diberi peran. Formatnya biasanya: principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID.

     Catatan: Jika Anda ingin mengikat semua agen dalam project ke registry (termasuk semua agen Runtime, agen Gemini Enterprise, dan agen lain yang dibuat di masa mendatang), Anda dapat mengikat kebijakan IAM ke principal://TRUST_DOMAIN/attribute.container/projects/PROJECT_ID.

5. Pada tahap ini, traffic agen Anda akan diarahkan melalui Agent Gateway. Namun, Agent Gateway mengadopsi kebijakan penolakan default. Untuk mengaktifkan fungsi Agent Platform tertentu, Anda harus memastikan bahwa agen dapat berkomunikasi dengan endpoint berikut:

   • Jika Cloud Trace diaktifkan, Agent Gateway harus mengizinkan traffic ke endpoint https://telemetry.googleapis.com/.

     Jika variabel lingkungan GOOGLE_API_USE_CLIENT_CERTIFICATE dan GOOGLE_API_USE_MTLS_ENDPOINT ditetapkan, pastikan traffic ke https://telemetry.mtls.googleapis.com/ juga diizinkan.

   • Jika Cloud Logging diaktifkan, Agent Gateway harus mengizinkan traffic ke endpoint https://logging.googleapis.com/.

     Jika variabel lingkungan GOOGLE_API_USE_CLIENT_CERTIFICATE dan GOOGLE_API_USE_MTLS_ENDPOINT ditetapkan, pastikan traffic ke https://logging.mtls.googleapis.com/ juga diizinkan.

   Selain itu, jika agen Anda memanggil LLM, atau menggunakan fitur seperti Sesi dan Bank Memori, Anda harus memastikan bahwa agen dapat berkomunikasi dengan endpoint yang digunakan oleh layanan ini. Contoh:

   • Untuk Sesi: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions
   • Untuk Bank Memori: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

   Demi alasan keamanan, sebaiknya daftarkan dan izinkan hanya URI tertentu yang diakses agen. Karena gateway mencocokkan nama host secara langsung, Anda harus memastikan bahwa Anda mendaftarkan semua varian yang digunakan SDK agen. Misalnya, bergantung pada versi SDK, konfigurasi klien regional, atau penggunaan mTLS, Google API dapat diselesaikan melalui nama host endpoint berikut:

   • https://REGION-aiplatform.googleapis.com
   • https://REGION-aiplatform.mtls.googleapis.com
   • https://aiplatform.REGION.rep.googleapis.com
   Perhatian: Meskipun Anda dapat mendaftarkan URI dasar (seperti https://REGION-aiplatform.googleapis.com/) untuk kemudahan, tindakan ini akan memberikan kebijakan akses yang luas yang memungkinkan agen mengakses layanan apa pun di domain tersebut. Perhatikan bahwa meskipun Anda mendaftarkan URI dasar, Anda tetap harus mendaftarkan semua varian regional dan mTLS-nya.

   Untuk mempelajari cara mendaftarkan endpoint, lihat Mendaftarkan endpoint. Anda juga harus memastikan bahwa agen memiliki peran IAP Egressor untuk endpoint ini. Untuk mengetahui petunjuknya, lihat Membuat kebijakan keluar agent-to-endpoint policy.

6. Verifikasi konfigurasi agen Anda.

   Konsol

   1. Di Google Cloud konsol, buka halaman Deployment Agent Platform.
      

      Buka Deployment

   2. Klik nama agen yang Anda deploy.

   3. Klik Konfigurasi layanan. Panel Kemampuan observasi untuk agen akan terbuka.

   4. Klik Detail deployment. Konfigurasi masuk dan keluar Agent Gateway tersedia di kolom Spesifikasi deployment.

   gcloud

   Gunakan permintaan REST API berikut untuk memvalidasi bahwa agen kini dikaitkan dengan gateway. Jika output yang ditampilkan adalah null, artinya Runtime gagal terikat ke gateway.

   curl -s -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
     | jq '.spec.deploymentSpec.agentGatewayConfig'

   Ganti kode berikut:

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

Membatasi Agent Runtime ke Agent Gateway yang disetujui

Anda dapat membuat batasan kebijakan organisasi kustom untuk menentukan kumpulan resource Agent Gateway yang memenuhi syarat dan dapat digunakan saat men-deploy agen.

Catatan: Kontrol Layanan VPC tidak didukung dengan Agent Gateway. Namun, jika Kontrol Layanan VPC diterapkan pada project, kebijakan organisasi ini diperlukan untuk memastikan bahwa agen hanya menggunakan jalur keluar yang disetujui, sehingga mencegah eksfiltrasi data melalui gateway yang tidak sah.

Membuat batasan kebijakan organisasi kustom

Contoh ini membuat batasan kustom yang hanya mengizinkan traffic ke dan dari daftar gateway yang telah disetujui sebelumnya.

Agent-to-Anywhere

1. Untuk menentukan batasan kustom untuk mode Agent-to-Anywhere (keluar), buat file bernama constraint-agent-gateway-egress.yaml.

   Dalam contoh berikut, kolom condition menentukan bahwa operasi hanya diizinkan jika resource Agent Gateway ditentukan (kolom ada dan tidak kosong) dan jika gateway yang ditentukan ada dalam daftar yang telah disetujui sebelumnya.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
   resource_types:
   - aiplatform.googleapis.com/ReasoningEngine
   condition: >-
   has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
   resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
   (resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
     'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
     'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
   ])
   method_types:
   - CREATE
   - UPDATE
   action_type: ALLOW
   display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
   description: Reasoning Engines can only be bound to a pre-approved list of
   Agent Gateway instances. Binding to any other gateway is denied.
   

   Ganti kode berikut:

   • ORGANIZATION_ID: ID organisasi Anda.
   • AGENT_PROJECT_ID: project ID Anda.
   • REGION: region tempat gateway dibuat.
   • AGENT_GATEWAY_ID: ID gateway Anda.

2. Terapkan batasan kustom.

   gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH
   

   Ganti EGRESS_CONSTRAINT_PATH dengan jalur lengkap ke file batasan kustom yang dibuat pada langkah sebelumnya.

3. Buat kebijakan organisasi untuk menerapkan batasan. Untuk menentukan kebijakan organisasi, buat file YAML kebijakan bernama policy-agent-gateway-egress.yaml. Dalam contoh ini, kami menerapkan batasan ini di level project, tetapi Anda juga dapat menetapkannya di level organisasi atau folder.

   name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   Ganti AGENT_PROJECT_ID dengan project ID Anda.

4. Terapkan kebijakan organisasi.

   gcloud org-policies set-policy EGRESS_POLICY_PATH
   

   Ganti EGRESS_POLICY_PATH dengan jalur lengkap ke file YAML kebijakan organisasi yang dibuat pada langkah sebelumnya. Kebijakan ini memerlukan waktu hingga 15 menit untuk diterapkan.

Client-to-Agent

1. Untuk menentukan batasan kustom untuk mode Client-to-Agent (masuk), buat file bernama constraint-agent-gateway-ingress.yaml.

   Dalam contoh berikut, kolom condition menentukan bahwa operasi hanya diizinkan jika resource Agent Gateway ditentukan (kolom ada dan tidak kosong) dan jika gateway yang ditentukan ada dalam daftar yang telah disetujui sebelumnya.

   name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
   resource_types:
   - aiplatform.googleapis.com/ReasoningEngine
   condition: >-
   has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
   resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
   (resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
     'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
     'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
   ])
   method_types:
   - CREATE
   - UPDATE
   action_type: ALLOW
   display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
   description: Reasoning Engines can only be bound to a pre-approved list of
   Agent Gateway instances. Binding to any other gateway is denied.
   

   Ganti kode berikut:

   • ORGANIZATION_ID: ID organisasi Anda.
   • AGENT_PROJECT_ID: project ID Anda.
   • REGION: region tempat gateway dibuat.
   • AGENT_GATEWAY_ID: ID gateway Anda.

2. Terapkan batasan kustom.

   gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH
   

   Ganti INGRESS_CONSTRAINT_PATH dengan jalur lengkap ke file batasan kustom yang dibuat pada langkah sebelumnya.

3. Buat kebijakan organisasi untuk menerapkan batasan. Untuk menentukan kebijakan organisasi, buat file YAML kebijakan bernama policy-agent-gateway-ingress.yaml. Dalam contoh ini, kami menerapkan batasan ini di level project, tetapi Anda juga dapat menetapkannya di level organisasi atau folder.

   name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
   spec:
     rules:
     - enforce: true
   

   Ganti AGENT_PROJECT_ID dengan project ID Anda.

4. Terapkan kebijakan organisasi.

   gcloud org-policies set-policy INGRESS_POLICY_PATH
   

   Ganti INGRESS_POLICY_PATH dengan jalur lengkap ke file YAML kebijakan organisasi yang dibuat pada langkah sebelumnya. Kebijakan ini memerlukan waktu hingga 15 menit untuk diterapkan.

Untuk mengetahui informasi selengkapnya tentang cara menggunakan batasan kebijakan organisasi kustom, lihat Membuat batasan kustom.

Langkah berikutnya

Codelab

Codelab: Mengatur workload agentic dengan Agent Platform

Pelajari cara mengatur workload agentic dengan Agent Gateway di Gemini Enterprise Agent Platform.

Panduan

Mendelegasikan otorisasi untuk Agent Gateway

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

Panduan

Memantau Agent Gateway

Pelajari cara memantau Agent Gateway.

Pemecahan masalah

Memecahkan masalah Agent Gateway

Pelajari cara memecahkan masalah konektivitas Agent Gateway.