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. Gateway ini menyediakan konektivitas yang aman dan diatur untuk semua interaksi agentic, baik yang terjadi antara pengguna dan agen, agen dan alat, maupun di antara agen itu sendiri.

Sebelum memulai

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

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

    Satu instance Runtime dapat terikat ke gateway Agen-ke-Mana Saja (egress) dan gateway Klien-ke-Agen (ingress) secara bersamaan.

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

Merutekan traffic Agent Runtime melalui Agent Gateway

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

  1. Membuat Agent Gateway

    Buat resource Agent Gateway dan lampirkan kebijakan otorisasi apa pun sesuai kebutuhan. Anda dapat membuat gateway dalam mode Agen-ke-Mana Saja (egress) atau mode Klien-ke-Agen (ingress).

    • Untuk mode Client-to-Agent (ingress), agen dan gateway harus dibuat di project dan region yang sama.
    • Untuk mode Agent-to-Anywhere (egress), 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 dalam project yang sama dengan Agent Gateway.

    Untuk mengetahui petunjuknya, lihat Menyiapkan Gateway Agen.

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

  2. Opsional: Mengonfigurasi akses gateway egress lintas project

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

    gcloud

    1. Buat peran IAM khusus di project Gateway Agen:
    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.

    1. Tetapkan peran khusus dalam project gateway ke agen layanan Agent Runtime dari 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 dari project tempat agen Runtime di-deploy.

    Terraform

    Untuk memberikan akses lintas project dari beberapa project workload Runtime ke project Agent Gateway pusat secara deklaratif, buat peran IAM khusus di project gateway pusat dan berikan peran tersebut ke agen layanan Runtime setiap project workload:

    variable "runtime_project_numbers" {
  type        = set(string)
  description = "Project numbers hosting cross-project Agent Runtime workloads"
  default     = ["AGENT_RUNTIME_PROJECT_NUMBER"]
}

resource "google_project_iam_custom_role" "ar_agw_cross_project_sa" {
  project     = "AGENT_GATEWAY_PROJECT_ID"
  role_id     = "ar_agw_cross_project_sa"
  title       = "Runtime Agent Gateway Cross-Project SA"
  description = "Custom role for cross-project service agents to access Agent Gateway"
  permissions = [
    "networkservices.agentGateways.get",
    "networkservices.operations.get",
  ]
}

resource "google_project_iam_member" "ar_agw_cross_project_binding" {
  for_each = var.runtime_project_numbers

  project = "AGENT_GATEWAY_PROJECT_ID"
  role    = google_project_iam_custom_role.ar_agw_cross_project_sa.name
  member  = "serviceAccount:service-${each.value}@gcp-sa-aiplatform.iam.gserviceaccount.com"
}

  3. Mengonfigurasi agen Anda untuk merutekan traffic melalui Agent Gateway

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

    • Untuk agen baru yang menggunakan Python SDK

      Tentukan resource gateway saat men-deploy agen Anda. Misalnya, untuk men-deploy agen di Agent Runtime, gunakan client.runtimes.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. Backend menerapkan identity_type = "AGENT_IDENTITY" di level API setiap kali agent_gateway_config ditentukan, sehingga menyebabkan validasi deployment gagal jika identitas instance Runtime dihilangkan atau salah dikonfigurasi.

      Agent-to-Anywhere 

      remote_agent = client.runtimes.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 (egress)

      Klien ke Agen 

      remote_agent = client.runtimes.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 Klien-ke-Agen (ingress)

    • Untuk agen baru yang menggunakan Terraform

      Saat Anda menyediakan agen dengan Terraform, gunakan penyedia google-beta dan konfigurasikan blok agent_gateway_config di dalam resource google_vertex_ai_reasoning_engine. Untuk mengetahui detail tentang penyiapan Terraform, lihat Menyediakan agen dengan Terraform.

      Agent-to-Anywhere

      Gunakan konfigurasi Terraform berikut untuk mengaitkan agen dengan gateway Agent-to-Anywhere untuk egress.

      resource "google_vertex_ai_reasoning_engine" "agent" {
provider = google-beta

project      = "AGENT_RUNTIME_PROJECT_ID"
region       = "REGION"
display_name = "AGENT_DISPLAY_NAME"
description  = "AGENT_DESCRIPTION"

spec {
  identity_type = "AGENT_IDENTITY"

  container_spec {
    image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
  }

  deployment_spec {
    agent_gateway_config {
      agent_to_anywhere_config {
        agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
      }
    }
  }
}
}

      Ganti kode berikut:

      • AGENT_RUNTIME_PROJECT_ID: project ID tempat agen di-deploy
      • REGION: region tempat agen dan gateway di-deploy
      • AGENT_DISPLAY_NAME: nama tampilan untuk agen Anda
      • AGENT_DESCRIPTION: deskripsi agen Anda
      • REPOSITORY: repositori Artifact Registry yang berisi image container Anda
      • IMAGE: nama image container
      • TAG: tag image container
      • AGENT_GATEWAY_PROJECT_ID: project ID tempat Gateway Agen di-deploy
      • AGENT_GATEWAY_TO_ANYWHERE_NAME: nama Agent Gateway yang Anda buat dalam mode Agent-to-Anywhere (egress)

      Klien ke Agen

      Gunakan konfigurasi Terraform berikut untuk mengaitkan agen dengan gateway Client-to-Agent untuk traffic masuk.

      resource "google_vertex_ai_reasoning_engine" "agent" {
provider = google-beta

project      = "PROJECT_ID"
region       = "REGION"
display_name = "AGENT_DISPLAY_NAME"
description  = "AGENT_DESCRIPTION"

spec {
  identity_type = "AGENT_IDENTITY"

  container_spec {
    image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
  }

  deployment_spec {
    agent_gateway_config {
      client_to_agent_config {
        agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
      }
    }
  }
}
}

      Ganti kode berikut:

      • PROJECT_ID: project ID tempat agen dan gateway di-deploy
      • REGION: region tempat agen dan gateway di-deploy
      • AGENT_DISPLAY_NAME: nama tampilan untuk agen Anda
      • AGENT_DESCRIPTION: deskripsi agen Anda
      • REPOSITORY: repositori Artifact Registry yang berisi image container Anda
      • IMAGE: nama image container
      • TAG: tag image container
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME: nama Agent Gateway yang Anda buat dalam mode Klien-ke-Agen (ingress)

    • Untuk agen yang sudah ada yang menggunakan REST API

      Agent-to-Anywhere

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

      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 (egress)
      • RESOURCE_ID: ID resource agen

      Klien ke Agen

      Gunakan permintaan REST API berikut untuk mengaitkan agen yang ada dengan gateway Klien-ke-Agen 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 Klien-ke-Agen (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 

    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 entri agen yang dapat dibaca manusia di registry
    • RUNTIME_AGENT_PROJECT_NUMBER: nomor project dari project tempat agen Runtime di-deploy
    • ENGINE_ID: ID resource agen

    Terraform 

    resource "google_agent_registry_service" "runtime_agent_entry" {
  project      = "AGENT_GATEWAY_PROJECT_ID"
  location     = "REGION"
  service_id   = "RUNTIME_AGENT_SERVICE_NAME"
  display_name = "RUNTIME_AGENT_DISPLAY_NAME"

  endpoint_spec {
    no_spec {}
  }

  interfaces {
    url              = "https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID"
    protocol_binding = "jsonrpc"
  }
}

    Untuk mengetahui informasi selengkapnya, lihat Mendaftarkan agen. Untuk mempelajari pendaftaran manual agen dalam penyiapan multi-project, lihat Mendaftarkan agen dari project lain.

  5. Membuat binding kebijakan IAM agen ke registry

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

    gcloud 

    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

    Terraform 

    resource "google_iap_agent_registry_endpoint_iam_member" "egress_binding" {
  project     = "AGENT_GATEWAY_PROJECT_ID"
  location    = "REGION"
  endpoint_id = "AGENT_ENDPOINT_ID"
  role        = "roles/iap.egressor"
  member      = "MEMBER"
}

    Ganti kode berikut:

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

    • MEMBER: Akun utama identitas agen yang akan diberi peran. Format untuk setiap mesin penalaran adalah: principal://TRUST_DOMAIN/resources/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID.

      Jika Anda ingin memberikan akses egress ke semua agen dalam sebuah project atau di seluruh organisasi, alih-alih mengikat instance satu per satu, Anda dapat mengikat kebijakan IAM ke set akun utama:

      • Untuk memberikan akses ke semua agen dalam project: principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
      • Untuk memberikan akses ke semua agen di seluruh organisasi: principalSet://TRUST_DOMAIN/*

      Dalam string akun utama ini, TRUST_DOMAIN biasanya adalah agents.global.org-ORGANIZATION_ID.system.id.goog.

  6. Mengizinkan API penting untuk operasi Runtime

    Sampai di sini, traffic agen Anda kini diarahkan melalui Agent Gateway. Namun, Gateway Agen menerapkan kebijakan tolak default. Untuk mengaktifkan fungsi Platform Agen tertentu, Anda harus memastikan bahwa agen dapat berkomunikasi dengan endpoint berikut:

    Pencocokan nama host di Agent Gateway bersifat persis. Karakter pengganti, seperti *.googleapis.com, atau bentuk awalan tidak didukung. Anda harus mendaftarkan setiap varian nama host standar, regional, dan aman (mTLS) yang di-resolve oleh SDK agen atau aplikasi klien Anda.

    Untuk mengaktifkan fungsi Agent Platform tertentu serta memastikan inisialisasi dan telemetri berhasil, Anda harus mengizinkan traffic ke endpoint berikut di Agent Registry:

    Endpoint platform penting

    Tabel berikut mencantumkan endpoint platform penting yang diperlukan agen Anda untuk operasi standar, pelacakan, logging, dan resolusi metadata:

    Nama layanan Nama host standar Nama host mTLS Varian regional dan varian lainnya
    Agent Registry agentregistry.googleapis.com — —
    Cloud Logging logging.googleapis.com logging.mtls.googleapis.com —
    Cloud Trace/Telemetri telemetry.googleapis.com telemetry.mtls.googleapis.com —
    Trace API cloudtrace.googleapis.com cloudtrace.mtls.googleapis.com —
    Cloud Monitoring monitoring.googleapis.com monitoring.mtls.googleapis.com —
    Secret Manager secretmanager.googleapis.com secretmanager.mtls.googleapis.com —
    Resource Manager cloudresourcemanager.googleapis.com cloudresourcemanager.mtls.googleapis.com —
    Kredensial IAM iamcredentials.googleapis.com iamcredentials.mtls.googleapis.com —
    Agent Platform (aiplatform) aiplatform.googleapis.com aiplatform.mtls.googleapis.com REGION-aiplatform.googleapis.com
    REGION-aiplatform.mtls.googleapis.com
    aiplatform.REGION.rep.googleapis.com

    Endpoint khusus fitur

    Selain itu, jika agen Anda menggunakan fitur seperti Sesi atau Bank Memori Platform Agen, Anda harus memastikan bahwa agen dapat berkomunikasi dengan endpoint tertentu yang digunakan oleh layanan ini:

    • 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 hanya mendaftarkan dan mengizinkan 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 di-resolve 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. Jika memiliki penyiapan multi-project, Anda dapat mendaftarkan beberapa endpoint API Google inti dalam satu layanan Agent Registry. Untuk informasi selengkapnya, lihat Mendaftarkan endpoint Google API gabungan. Anda juga harus memastikan bahwa agen memiliki izin iap.resources.egressViaIAP untuk endpoint ini. Untuk mengetahui petunjuknya, lihat Membuat kebijakan egress 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 Deployment details. Konfigurasi ingress dan egress Agent Gateway tersedia di kolom Deployment spec.

    gcloud

    Gunakan permintaan REST API berikut untuk memvalidasi bahwa agen kini terkait dengan gateway. Jika output yang ditampilkan adalah null, berarti Runtime gagal mengikat 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 memasukkan sertifikat CA selama pembuatan image. Untuk image container kustom, Anda harus mengambil sertifikat CA gateway secara eksplisit, menginstalnya ke dalam trust store CA sistem di dalam Dockerfile, dan menetapkan variabel lingkungan paket sertifikat yang diperlukan oleh Python SDK, library klien HTTP, dan gRPC.

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

  1. Ambil root certificate 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 Agent Gateway egress Anda
    • REGION: region tempat gateway di-deploy
    • AGENT_GATEWAY_PROJECT_ID: project ID tempat gateway di-deploy

  2. Perbarui Dockerfile Anda untuk 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 substitusi:

    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 image dan repositori Artifact Registry Anda.

  4. Men-deploy agen dalam container.

    Tentukan URI image container yang di-build beserta konfigurasi Agent Gateway Anda dalam permintaan deployment (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 (egress), 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 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 di 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 kustom.

    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 di 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 Agen-ke-Mana Saja (egress). Dalam mode Client-to-Agent (ingress), agen dan Gateway Agen 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 diikat ke Runtime Mesin Penalaran yang dibuat sebelum 29 April 2026.

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

    Misalnya, jika sebuah 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 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 binding yang sama ini juga berlaku untuk gateway ingress dalam project dan region.

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

  • Dalam mode Klien ke Agen (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.

  • Mengubah binding Agent Gateway di agen Runtime akan mengarsipkan setiap revisi agen yang sudah ada sebelumnya. Pengarsipan tidak dapat dibatalkan. Lihat Agent Gateway dan revisi.

    Untuk mengupdate agen tanpa mengubah ID mesin penalarannya atau merusak binding kebijakan, update instance agen Anda di tempat seperti yang dijelaskan dalam Mengupdate instance Agent Runtime.

Langkah berikutnya

Codelab

Pelajari cara mengelola workload 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.