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. Layanan ini menyediakan konektivitas yang aman dan diatur untuk semua interaksi berbasis agen, baik yang terjadi antara pengguna dan agen, agen dan alat, atau antar-agen.

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 (ingress) untuk mengontrol klien mana yang dapat mengakses agen Anda. Gateway memungkinkan Anda memilih kebijakan IAP dan template Model Armor 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.

  • Tinjau Batasan yang terkait dengan deployment Runtime yang terkait dengan Agent Gateway.

Merutekan traffic Agent Runtime melalui Agent Gateway

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

  1. Buat Gateway Agen

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

    • Untuk mode Client-to-Agent (ingress), agen dan gateway harus dibuat di project dan region yang sama.
    • Untuk mode Agent-to-Anywhere (keluar), gateway dapat dibuat di project yang berbeda dengan agen, tetapi harus dibuat di region yang sama. Perhatikan bahwa pendaftaran Agent Registry dan binding kebijakan IAM terkait harus dibuat di project yang sama dengan Agent Gateway.

    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. Opsional: Mengonfigurasi akses gateway keluar lintas project

    Jika gateway Agent-to-Anywhere (keluar) berada dalam project yang berbeda dengan agen Runtime, lakukan langkah-langkah berikut untuk memberikan akses agen layanan Runtime ke project gateway keluar:

    1. Buat peran IAM khusus di project Agent Gateway:

      gcloud iam roles create ar_agw_cross_project_sa \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --title="Runtime Agent Gateway Cross-Project SA" \
  --description="Custom role for the cross-project service agent to access Agent Gateway" \
  --permissions="networkservices.agentGateways.get,networkservices.operations.get"

      Ganti AGENT_GATEWAY_PROJECT_ID dengan project ID tempat Agent Gateway di-deploy.

    2. Tetapkan peran kustom di project gateway ke agen layanan Agent Runtime project agen:

      gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
  --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

      Ganti AGENT_RUNTIME_PROJECT_NUMBER dengan nomor project tempat agen Runtime di-deploy.

  3. Mengonfigurasi agen Anda untuk merutekan traffic melalui Agent Gateway

    Bergantung pada apakah Anda men-deploy agen baru atau mengonfigurasi agen yang sudah ada, pilih salah satu opsi berikut:

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

      Agent-to-Anywhere 

      remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_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 kode berikut:

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

      Klien ke Agen 

      remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "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 kode berikut:

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

    • Untuk agen lama

      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/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Ganti kode berikut:

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

      Klien ke Agen

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

      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/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      Ganti kode berikut:

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

  4. Mendaftarkan agen ke Agent Registry

    Pastikan agen terdaftar di instance Agent Registry dalam project dan region yang sama dengan Agent Gateway.

    gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --location=REGION \
  --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
  --format="value(registryResource)"

    Ganti kode berikut:

    • RUNTIME_AGENT_SERVICE_NAME: nama yang ingin Anda berikan ke entri agen di registry
    • AGENT_GATEWAY_PROJECT_ID: project ID tempat gateway di-deploy
    • REGION: region tempat agen dan gateway di-deploy
    • RUNTIME_AGENT_DISPLAY_NAME: nama tampilan yang dapat dibaca manusia dari entri agen dalam registri
    • RUNTIME_AGENT_PROJECT_NUMBER: nomor project dari project tempat agen Runtime di-deploy
    • ENGINE_ID: ID resource agen

    Untuk mengetahui informasi selengkapnya, lihat Mendaftarkan agen.

  5. Membuat binding kebijakan IAM agen-ke-registry

    Lakukan langkah ini di project dan region yang sama dengan Agent Gateway.

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

    Ganti kode berikut:

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

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

  6. Mengizinkan API penting untuk operasi Runtime

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

    • Untuk mengaktifkan penemuan otomatis agen, server MCP, dan endpoint, Agent Gateway harus mengizinkan traffic ke endpoint https://agentregistry.googleapis.com/.

    • 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 Memory Bank: https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

    Demi alasan keamanan, sebaiknya Anda mendaftarkan dan memasukkan hanya URI tertentu yang diakses oleh agen ke dalam daftar yang diizinkan. 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

    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 dari agen ke endpoint.

  7. Memverifikasi konfigurasi agen

    Konsol

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

      Buka Deployment

    2. Klik nama agen yang Anda deploy.

    3. Klik Konfigurasi layanan. Panel Observability untuk agen akan terbuka.

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

    gcloud

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

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

    Ganti kode berikut:

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

Mengonfigurasi agen container kustom (BYOC) untuk Agent Gateway

Jika Anda ingin merutekan traffic keluar melalui Agent Gateway Agent-to-Anywhere (egress) untuk agen yang di-deploy dengan image container kustom (Bring Your Own Container / BYOC), Anda harus memasukkan sertifikat root certificate authority (CA) gateway ke dalam trust store image container kustom.

Karena Agent Gateway melakukan dekripsi dan pemeriksaan TLS pada komunikasi agen keluar, deployment agen non-BYOC (berbasis sumber) secara otomatis menyuntikkan sertifikat CA selama pembuatan gambar. Untuk image container kustom, Anda harus mengambil sertifikat CA gateway secara eksplisit, menginstalnya ke penyimpanan tepercaya CA sistem di dalam Dockerfile, dan menetapkan variabel lingkungan paket sertifikat yang diperlukan oleh SDK Python, library klien HTTP, dan gRPC.

Untuk mengonfigurasi image container BYOC untuk keluar dari Agent Gateway, lakukan langkah-langkah berikut:

  1. Ambil sertifikat root dari resource Agent Gateway.

    Ekspor string PEM sertifikat root CA langsung dari kolom agentGatewayCard.rootCertificates resource Agent Gateway Anda:

    export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")

    Atau, Anda dapat menggunakan REST API untuk mengambil resource gateway:

    curl -s -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://networkservices.googleapis.com/v1/projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
   | jq -r '.agentGatewayCard.rootCertificates[]'

    Ganti kode berikut:

    • AGENT_GATEWAY_NAME: nama Egress Agent Gateway Anda
    • REGION: region tempat gateway di-deploy
    • AGENT_GATEWAY_PROJECT_ID: project ID tempat gateway di-deploy

  2. Perbarui Dockerfile Anda agar memercayai sertifikat CA.

    Tambahkan argumen build AGENT_GATEWAY_ROOT_CERTIFICATES ke Dockerfile Anda. Perintah build membagi sertifikat menjadi file terpisah, menginstalnya menggunakan update-ca-certificates, dan menetapkan variabel lingkungan sehingga OpenSSL, library klien HTTP Python (requests, httpx), dan gRPC mengenali CA kustom:

    # Install root certificates under root user
USER root

ARG AGENT_GATEWAY_ROOT_CERTIFICATES
RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \
     echo "Installing Agent Gateway root certificates..."; \
     printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \
     update-ca-certificates; \
   fi

# Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC
ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}

# Switch back to application execution user
USER 1000

  3. Bangun image container menggunakan Cloud Build.

    Buat file cloudbuild.yaml untuk meneruskan string root certificate ke Cloud Build menggunakan penggantian:

    steps:
- name: 'gcr.io/cloud-builders/docker'
  args:
  - 'build'
  - '--build-arg'
  - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}'
  - '-t'
  - '$_IMAGE_URI'
  - '.'

images:
- '$_IMAGE_URI'

    Kirim build image container ke Cloud Build:

    export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest"

gcloud builds submit \
   --project=PROJECT_ID \
   --region=REGION \
   --config=cloudbuild.yaml \
   --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \
   .

    Ganti REPOSITORY_NAME dan IMAGE_NAME dengan nama repositori dan image Artifact Registry Anda.

  4. Deploy agen dalam container Anda.

    Tentukan URI image container yang di-build bersama dengan konfigurasi Agent Gateway dalam permintaan deployment Anda (menggunakan agent_gateway_config di bagian spec.deploymentSpec atau menggunakan panggilan deployment SDK).

Membatasi Agent Runtime ke Agent Gateway yang disetujui

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

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 (traffic 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 khusus.

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    Ganti EGRESS_CONSTRAINT_PATH dengan jalur lengkap ke file batasan kustom yang dibuat di 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.

Klien ke Agen

  1. Untuk menentukan batasan kustom untuk mode Client-to-Agent (ingress), 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 khusus.

    gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    Ganti INGRESS_CONSTRAINT_PATH dengan jalur lengkap ke file batasan kustom yang dibuat di 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.

Batasan

  • Tata kelola lintas project memiliki batasan berikut:

    • Binding lintas project antara agen dan gateway hanya didukung dalam mode Agent-to-Anywhere (keluar). Dalam mode Client-to-Agent (ingress), agen dan Agent Gateway harus berada dalam project yang sama.
    • Anda harus menggunakan REST API atau gcloud untuk mengonfigurasi tata kelola lintas project end-to-end. Konsol Google Cloud Google Cloud tidak mendukung pembuatan binding kebijakan IAM lintas project atau entri Agent Registry.

  • Agent Gateway tidak dapat terikat ke Mesin Inferensi Runtime yang dibuat sebelum 29 April 2026.

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

    Misalnya, jika project dan region berisi egress-gateway-X dan egress-gateway-Y, semua agen di project dan region tersebut harus dikonfigurasi untuk menggunakan gateway yang sama untuk egress. 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 pengikatan yang sama ini juga berlaku untuk gateway ingress dalam project dan region.

  • Layanan Deteksi Ancaman Mesin Agen Security Command Center tidak tersedia saat Agent Gateway diaktifkan untuk agen.

  • Dalam mode Client-to-Agent (ingress), 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 Anda. Lihat Membersihkan perintah dan respons atau codelab ini tentang Membangun sistem agen yang aman dengan Model Armor.

  • Kontrol Layanan VPC tidak didukung dengan Agent Gateway.

  • Agent Gateway tidak didukung untuk agen Agent Runtime yang menggunakan revisi. Anda tidak akan dapat menggunakan fitur terkait pembuatan versi seperti konfigurasi pemisahan traffic dan kueri per revisi jika Agent Gateway dilampirkan ke konfigurasi agen.

    Untuk memperbarui agen tanpa mengubah ID mesin penalaran atau merusak pengikatan kebijakan, perbarui instance agen di tempat seperti yang dijelaskan dalam Memperbarui instance Agent Runtime.

Langkah berikutnya

Codelab

Pelajari cara mengelola beban kerja agentic dengan Agent Gateway di Gemini Enterprise Agent Platform.

Panduan

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

Panduan

Pelajari cara memantau Agent Gateway.

Pemecahan masalah

Pelajari cara memecahkan masalah konektivitas Agent Gateway.