Mengelola agen dengan Agent Gateway

Agent Gateway memungkinkan Anda mengatur traffic keluar dari agen AI yang Anda bangun dan hosting di Cloud Run. Dengan merutekan traffic egress dari layanan Cloud Run Anda melalui Agent Gateway yang dikelola sendiri dan berjalan di Secure Web Proxy, Anda dapat menerapkan kebijakan akses terpusat, memeriksa payload untuk keamanan konten, dan mengumpulkan telemetri kemampuan observasi di seluruh workload agen Anda.

Dokumen ini menjelaskan cara mengonfigurasi arsitektur terpusat untuk Agent Gateway di Cloud Run dan membahas cara melakukan hal berikut:

Arsitektur

Dalam deployment yang dikelola sendiri dan terpusat, Secure Web Proxy bertindak sebagai titik penerapan kebijakan dan berjalan di dalam jaringan Virtual Private Cloud (VPC) Anda. Container sidecar ambient networking memblokir traffic keluar dari agen Cloud Run Anda dan merutekannya melalui Direct VPC egress ke instance Secure Web Proxy Anda. Secure Web Proxy menerapkan aturan akses dan konten dari titik keputusan kebijakan seperti Identity-Aware Proxy (IAP) dan Model Armor.

Diagram arsitektur yang menunjukkan layanan Cloud Run dengan container agen dan container proxy sidecar ambien yang merutekan traffic melalui egress VPC Langsung ke Agent Gateway yang dikelola sendiri dan didukung oleh Secure Web Proxy di dalam Jaringan VPC.
Gambar 1. Arsitektur Agent Gateway yang dikelola sendiri untuk agen Cloud Run.

Untuk merutekan dan mengatur traffic dalam arsitektur ini, Anda harus mengonfigurasi komponen berikut:

  • Egress VPC langsung dan ambient networking: Layanan Cloud Run Anda terhubung ke jaringan VPC dengan --vpc-egress=all dan --ambient-networking, yang menggunakan cakupan regional secara default dan merutekan semua traffic keluar ke jaringan VPC Anda.
  • Agent Gateway yang dikelola sendiri: Resource Agent Gateway logis dalam mode yang dikelola sendiri mengarah ke instance Secure Web Proxy di Jaringan VPC Anda.
  • Kebijakan perutean egress: Kebijakan EgressRouting Network Services API mengarahkan traffic keluar dari layanan Cloud Run ke instance Secure Web Proxy Anda.

Sebelum memulai

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init

  12. Aktifkan Cloud Run Admin API, Network Services API, Keamanan Jaringan API, Service Extensions API, Model Armor API, Certificate Authority Service API, Certificate Manager API, Cloud Resource Manager API, App Hub API, Identity and Access Management API, Identity-Aware Proxy API, Compute Engine API, Traffic Director API, Cloud DNS API, Network Connectivity API, dan Agent Registry API, jika ada yang belum diaktifkan.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Aktifkan API

  13. Buat jaringan VPC dan subnet dengan Akses Google Pribadi diaktifkan di subnet.
  14. Siapkan Agent Registry di project atau organisasi Anda.
  15. Instal dan lakukan inisialisasi Google Cloud CLI.
  16. Update komponen gcloud CLI: 
    gcloud components update

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengonfigurasi Agent Gateway untuk Cloud Run, minta administrator untuk memberi Anda peran IAM berikut pada project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Jika Anda mengonfigurasi deployment lintas project dengan VPC Bersama, minta administrator untuk memberi Anda roles/compute.xpnAdmin di level organisasi atau folder.

Membuat Gateway Agen yang dikelola sendiri

Sebelum membuat resource Gateway Agen, deploy dan konfigurasikan instance Secure Web Proxy di jaringan VPC Anda seperti yang dijelaskan dalam Men-deploy Secure Web Proxy sebagai Gateway Agen:

  1. Siapkan pemeriksaan TLS dan buat kebijakan keamanan gateway yang melampirkan TlsInspectionPolicy Anda. Anda tidak memerlukan aturan kebijakan keamanan atau daftar URL Secure Web Proxy.
  2. Buat resource ServerTlsPolicy dengan allowOpen: false dan mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT. Jangan setel clientValidationTrustConfig.
  3. Deploy instance Secure Web Proxy dalam mode perutean proxy eksplisit dengan addresses, ports, certificateUrls, gatewaySecurityPolicy, dan serverTlsPolicy yang dikonfigurasi saat Anda membuat gateway sehingga Cloud Run meneruskan workload identity agen Anda ke Secure Web Proxy dan IAP melalui mTLS.

Setelah instance Secure Web Proxy Anda siap, buat resource Agent Gateway yang dikelola sendiri yang mengarah ke instance Secure Web Proxy Anda:

  1. Buat file konfigurasi YAML bernama my-agent-gateway.yaml:

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    Ganti kode berikut:

    • AGENT_GATEWAY_NAME: nama yang ingin Anda tetapkan ke resource Agent Gateway.
    • PROJECT_ID: project ID yang menghosting instance Secure Web Proxy Anda.
    • REGION: region instance Secure Web Proxy Anda, seperti us-central1.
    • SWP_NAME: nama instance Secure Web Proxy Anda.

  2. Impor konfigurasi Agent Gateway:

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

  3. Verifikasi resource Agent Gateway Anda:

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

    Pastikan output menampilkan konfigurasi selfManaged dan URI resource instance Secure Web Proxy Anda sebelum melanjutkan ke bagian berikutnya.

Mengonfigurasi jaringan ambient Cloud Run untuk mengakses Traffic Director API

Saat Anda mengonfigurasi layanan Cloud Run dengan egress VPC Langsung dan --vpc-egress=all, semua koneksi keluar dari instance container akan dirutekan melalui jaringan VPC Anda. Hal ini mencakup koneksi sidecar Envoy ke trafficdirector.REGION.rep.googleapis.com.

Agar sidecar dapat me-resolve dan menjangkau Traffic Director API, konfigurasikan zona Cloud DNS pribadi di jaringan VPC Anda berdasarkan apakah lingkungan Anda menggunakan Kontrol Layanan VPC:

Tanpa Kontrol Layanan VPC

Jika project Anda tidak menggunakan Kontrol Layanan VPC, buat zona DNS pribadi Cloud DNS yang merutekan permintaan untuk trafficdirector.REGION.rep.googleapis.com ke alamat IP gateway Secure Web Proxy Anda sehingga Secure Web Proxy mengizinkan traffic melewati:

  1. Ambil alamat IP internal gateway Secure Web Proxy Anda:

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    Ganti kode berikut:

    • SWP_NAME: nama instance Secure Web Proxy Anda.
    • PROJECT_ID: Project ID Google Cloud Anda.
    • REGION: region deployment Anda.

  2. Buat zona Cloud DNS terkelola pribadi untuk Traffic Director API:

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    Ganti VPC_NETWORK_NAME dengan nama jaringan VPC Anda.

  3. Tambahkan data A yang mengarahkan domain regional Traffic Director API ke alamat IP Secure Web Proxy Anda:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. Pastikan set data DNS aktif di zona pribadi:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    Pastikan data A untuk trafficdirector.REGION.rep.googleapis.com. ditetapkan ke alamat IP Secure Web Proxy Anda.

Dengan Kontrol Layanan VPC

Untuk lingkungan Kontrol Layanan VPC, sediakan endpoint regional Private Service Connect yang menargetkan Traffic Director API regional di dalam subnet VPC Anda dan petakan domain menggunakan zona Cloud DNS pribadi:

  1. Buat endpoint regional Private Service Connect yang menargetkan Traffic Director API regional:

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.
    • REGION: region deployment Anda.
    • VPC_NETWORK_NAME: nama jaringan VPC Anda.
    • VPC_SUBNET_NAME: nama subnet VPC Anda.

  2. Ambil alamat IP internal endpoint regional:

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. Buat zona Cloud DNS terkelola pribadi untuk Traffic Director API:

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. Tambahkan data A yang me-resolve domain regional Traffic Director API ke alamat IP endpoint regional:

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. Verifikasi endpoint regional dan set data DNS Anda:

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    Pastikan data A untuk trafficdirector.REGION.rep.googleapis.com. mengarah ke alamat IP endpoint regional.

Men-deploy atau mengupdate layanan Cloud Run dengan Ambient Networking dan egress VPC Langsung

Untuk menghubungkan agen Cloud Run ke instance Secure Web Proxy di jaringan VPC Anda, aktifkan Direct VPC egress dan ambient networking regional, lalu konfigurasikan layanan dengan Agent Identity. Saat Anda men-deploy dengan --functional-type=agent dan --identity-type=agent-identity, Cloud Run memberikan roles/run.agentDefaultAccess, yang mencakup izin roles/trafficdirector.client dan roles/cloudtrace.agent:

  1. Deploy layanan agen Cloud Run baru atau update layanan yang ada untuk mengaktifkan jaringan ambient regional, egress VPC Langsung untuk semua traffic keluar, dan Identitas Agen:

    Layanan baru

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Layanan yang ada

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    Ganti kode berikut:

    • SERVICE_NAME: nama layanan agen Cloud Run Anda.
    • IMAGE_URL: referensi ke image container, misalnya, us-docker.pkg.dev/cloudrun/container/hello:latest. Jika Anda menggunakan Artifact Registry, repositori REPO_NAME harus sudah dibuat. URL mengikuti format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .
    • VPC_NETWORK_NAME: nama jaringan VPC yang menghosting instance Secure Web Proxy Anda. Untuk mengetahui informasi tentang cara membuat jaringan dan subnet VPC, lihat Membuat dan mengelola jaringan VPC.
    • VPC_SUBNET_NAME: nama subnet VPC tempat instance Secure Web Proxy Anda dapat dijangkau.
    • REGION: region layanan Anda.
    • PROJECT_ID: Project ID Google Cloud Anda.

  2. Pastikan layanan Cloud Run Anda menggunakan Ambient Networking, Direct VPC egress, dan Agent Identity:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    Pastikan output menampilkan subnet egress Direct VPC, egress all-traffic, jaringan ambient regional, dan akun utama identitas agen yang ditetapkan.

Mengonfigurasi agen Cloud Run Anda untuk memercayai Agent Gateway

Agar Secure Web Proxy dapat memeriksa payload HTTPS dan menerapkan kebijakan, Secure Web Proxy harus menghentikan sesi TLS keluar dari agen Anda. Container agen Cloud Run Anda harus memercayai sertifikat root atau subordinate certificate authority (CA) yang terkait dengan kebijakan pemeriksaan TLS Secure Web Proxy Anda di CA Service atau PKI perusahaan pribadi Anda:

  1. Ekspor sertifikat CA berenkode PEM dari kumpulan CA Service untuk instance Secure Web Proxy Anda:

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    Ganti kode berikut:

    • CA_POOL_NAME: nama kumpulan CA yang terkait dengan kebijakan pemeriksaan TLS Secure Web Proxy Anda.
    • REGION: region kumpulan CA Anda.
    • PROJECT_ID: Project ID Google Cloud Anda.

  2. Perbarui layanan Cloud Run Anda untuk meneruskan konten sertifikat dalam variabel lingkungan:

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    Ganti kode berikut:

    • SERVICE_NAME: nama layanan agen Cloud Run Anda.
    • REGION: region layanan Anda.
    • PROJECT_ID: Project ID Google Cloud Anda.

    Misalnya, skrip titik entri container Debian atau Ubuntu berikut, entrypoint.sh, menginstal AGENT_GATEWAY_ROOT_CERT ke dalam trust store sistem dan mengekspor jalur paket CA untuk klien Python dan gRPC sebelum memulai aplikasi Anda:

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. Pastikan layanan Anda menetapkan variabel lingkungan AGENT_GATEWAY_ROOT_CERT:

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

Merutekan traffic egress ke Agent Gateway

Setelah mengonfigurasi layanan Cloud Run dan Agent Gateway, buat kebijakan EgressRouting Network Services API untuk mengarahkan traffic keluar dari layanan Cloud Run ke gateway Secure Web Proxy:

  1. Buat resource EgressRouting:

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    Ganti kode berikut:

    • REGION: region layanan dan gateway Cloud Run Anda.
    • PROJECT_ID: Project ID Google Cloud Anda.
    • SWP_NAME: nama resource Gateway Secure Web Proxy yang mendasarinya, bukan resource AgentGateway.
    • SERVICE_NAME: nama layanan agen Cloud Run Anda. Untuk merutekan semua layanan Cloud Run dalam project melalui gateway dengan satu kebijakan, tetapkan workloadUri ke //run.googleapis.com/projects/PROJECT_ID atau //run.googleapis.com/projects/PROJECT_NUMBER.

    Setelah EgressRouting diterapkan, semua traffic keluar dari layanan Cloud Run Anda akan dirutekan melalui Secure Web Proxy. Konfigurasikan kebijakan di bagian berikutnya untuk mengizinkan dan mengatur permintaan keluar.

  2. Pastikan resource EgressRouting aktif:

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    Pastikan sources mencantumkan URI workload Cloud Run Anda dan gateway mereferensikan resource gateway Secure Web Proxy Anda.

Mengonfigurasi kebijakan di Agent Gateway

Setelah Anda merutekan traffic egress melalui Agent Gateway, kelola permintaan keluar agen Anda dengan melampirkan kebijakan otorisasi dan binding ekstensi Service Extensions ke resource Agent Gateway Anda:

  • Pemfilteran alat MCP dan traffic dasar: Izinkan endpoint model serta metode dan alat Model Context Protocol (MCP) yang disetujui menggunakan kebijakan otorisasi ALLOW.
  • Kontrol akses berbasis identitas: Ikat IAP dengan resource ExtensionBinding dan konfigurasikan Unified Access Policy IAM untuk mengontrol agen mana yang dapat memanggil server MCP, alat, atau endpoint tertentu.
  • Keamanan konten: Ikat Model Armor dengan resource ExtensionBinding untuk memeriksa dan membersihkan perintah dan respons dari injeksi perintah, kebocoran data sensitif, atau pelanggaran kebijakan.

Setiap kebijakan otorisasi atau aturan kebijakan keamanan gateway yang dilampirkan ke resource Gateway Secure Web Proxy yang mendasarinya akan diabaikan. Setelah Anda membuat atau memperbarui resource ExtensionBinding, perubahan dapat memerlukan waktu hingga lima menit untuk diterapkan ke gateway. Untuk urutan evaluasi aturan di seluruh aturan jaringan, pemeriksaan TLS, binding ekstensi, dan aturan HTTP, lihat Urutan evaluasi untuk aturan otorisasi.

Mengizinkan traffic egress dasar dan MCP

Secure Web Proxy menolak semua traffic keluar dengan error 403 Forbidden secara default hingga ALLOW AuthzPolicy di resource Agent Gateway Anda mengizinkannya.

Karena layanan Cloud Run Anda menggunakan --vpc-egress=all, semua traffic container keluar, termasuk panggilan alat MCP dan permintaan LLM, dirutekan melalui gateway. Lampirkan kebijakan otorisasi ALLOW ke resource Agent Gateway Anda untuk kedua jenis traffic:

Mengonfigurasi kebijakan egress IAP

Agent Gateway menggunakan IAP sebagai mesin keputusan kebijakan untuk mengevaluasi Unified Access Policies IAM. Untuk menerapkan kebijakan identitas agen, tentukan aturan akses Anda dalam Kebijakan Akses Terpadu IAM dan ikat IAP ke gateway Anda:

  1. Buat Kebijakan Akses Terpadu IAM menggunakan principal Identitas Agen layanan Cloud Run Anda, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME, dan ikat kebijakan tersebut ke project atau gateway Anda dengan mengikuti Membuat kebijakan akses IAM dan Mengikat Kebijakan Akses Terpadu ke project.
  2. Ikat IAP, iap.googleapis.com, ke Agent Gateway Anda dengan ExtensionBinding dengan mengikuti petunjuk di Mengikat IAP ke Agent Gateway.

Karena --vpc-egress=all mengirim panggilan model seperti REGION-aiplatform.googleapis.com melalui gateway, cakupkan matchConditions di ExtensionBinding IAP Anda ke prefix: "urn:mcp" agar panggilan model mengabaikan evaluasi IAP. Untuk juga mengatur traffic agen ke agen, tambahkan prefix: "urn:agent". Jika binding ekstensi Anda cocok dengan host lain, tambahkan aturan izin untuk setiap host di Kebijakan Akses Terpadu IAM Anda, seperti destination.unregistered.host == 'REGION-aiplatform.googleapis.com'. Sebagai contoh, lihat Membuat kebijakan agen ke endpoint yang tidak terdaftar.

Mengonfigurasi kebijakan Model Armor

Untuk memeriksa dan membersihkan perintah dan respons yang melewati Gateway Agen, buat template Model Armor dan ikatkan ke gateway Anda:

  1. Buat template permintaan dan respons Model Armor regional, lalu berikan peran yang diperlukan ke agen layanan Service Extensions dengan mengikuti petunjuk di Mengonfigurasi Model Armor di gateway.
  2. Lampirkan template ke Agent Gateway Anda dengan ExtensionBinding dengan mengikuti petunjuk di Mengikat Model Armor untuk sanitasi perintah dan respons.

Mengonfigurasi deployment lintas project terpusat dengan VPC Bersama

Dalam organisasi multi-project, Anda dapat men-deploy agen Cloud Run di satu atau beberapa project layanan sambil menghosting Gateway Agen, instance Secure Web Proxy, dan Registry Agen di project host jaringan khusus menggunakan VPC Bersama:

  • Project A, project layanan agen: Menghosting layanan agen Cloud Run dan kebijakan EgressRouting lokal.
  • Project B, project host gateway dan jaringan: Bertindak sebagai project host VPC Bersama dan harus menghosting Gateway Agen, instance Secure Web Proxy, Registry Agen, resource ExtensionBinding, dan binding kebijakan IAM.
Diagram arsitektur lintas project yang menunjukkan Project A yang menghosting layanan Cloud Run dan kebijakan perutean traffic keluar, yang terhubung melalui jaringan VPC Bersama ke Project B yang menghosting Gateway Agen, Secure Web Proxy, dan Registry Agen.
Gambar 2. Deployment Gateway Agen lintas project menggunakan VPC Bersama.

Sebelum memulai langkah-langkah ini, aktifkan run.googleapis.com, compute.googleapis.com, networkservices.googleapis.com, dan trafficdirector.googleapis.com di Project A, bersama dengan aiplatform.googleapis.com jika agen Anda memanggil Vertex AI. Di Project B, deploy instance Secure Web Proxy dan resource Agent Gateway di jaringan VPC Bersama seperti yang dijelaskan dalam Membuat Agent Gateway yang dikelola sendiri, dan konfigurasikan perutean DNS atau Private Service Connect seperti yang dijelaskan dalam Mengonfigurasi jaringan ambient Cloud Run untuk mengakses Traffic Director API sehingga sidecar ambient di Project A dapat menjangkau Traffic Director API.

Untuk mengonfigurasi deployment lintas project, selesaikan langkah-langkah berikut:

  1. Konfigurasi Project B sebagai project host VPC Bersama, lampirkan Project A sebagai project layanan, dan bagikan subnet yang menghosting instance Secure Web Proxy Anda. Mengaktifkan VPC Bersama dan menautkan project layanan memerlukan roles/compute.xpnAdmin di level organisasi atau folder. Untuk mengetahui petunjuknya, lihat Mengirim traffic ke jaringan VPC Bersama dengan egress VPC Langsung dan Menyediakan VPC Bersama.

  2. Di Project B, berikan roles/compute.networkUser pada subnet bersama ke agen layanan Cloud Run dari Project A:

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
   --role="roles/compute.networkUser"

    Ganti kode berikut:

    • SHARED_SUBNET_NAME: nama subnet bersama di Project B.
    • PROJECT_B_ID: project ID Project B, gateway, dan project host VPC Bersama.
    • REGION: region subnet bersama.
    • PROJECT_A_NUMBER: nomor project dari Project A, project layanan agen.

  3. Deploy layanan agen Cloud Run di Project A yang mengarah ke subnet bersama di Project B:

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    Ganti kode berikut:

    • SERVICE_NAME: nama layanan agen Cloud Run Anda di Project A.
    • PROJECT_A_ID: project ID Project A, project layanan agen.
    • IMAGE_URL: referensi ke image container, misalnya, us-docker.pkg.dev/cloudrun/container/hello:latest. Jika Anda menggunakan Artifact Registry, repositori REPO_NAME harus sudah dibuat. URL mengikuti format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG .

    Setelah men-deploy layanan, konfigurasikan agen Anda di Project A untuk memercayai sertifikat CA root instance Secure Web Proxy di Project B dengan mengikuti langkah-langkah di Mengonfigurasi agen Cloud Run untuk memercayai Agent Gateway.

  4. Buat kebijakan EgressRouting di Project A yang merujuk ke gateway Secure Web Proxy di Project B. Anda harus memiliki roles/networkservices.admin di Project A:

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    Ganti CENTRAL_SWP_NAME dengan nama gateway Secure Web Proxy di Project B. Untuk merutekan semua layanan Cloud Run di Project A melalui gateway Project B, tetapkan workloadUri ke //run.googleapis.com/projects/PROJECT_A_ID atau //run.googleapis.com/projects/PROJECT_A_NUMBER.

  5. Pastikan resource EgressRouting lintas project aktif di Project A:

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. Konfigurasikan kebijakan dasar pengukuran, IAP, dan Model Armor terpusat pada resource Agent Gateway di Project B seperti yang dijelaskan dalam Mengonfigurasi kebijakan di Agent Gateway:

    • Izinkan traffic MCP dan model dasar di resource Agent Gateway di Project B dengan mengikuti Mengizinkan traffic egress dan MCP dasar.
    • Untuk mengizinkan agen di Project A memanggil server MCP yang terdaftar di Project B, buat IAM Unified Access Policy di Project B yang daftar principals-nya merujuk ke nomor project Project A, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME, ikat kebijakan ke Project B atau resource Agent Gateway-nya, dan lampirkan ExtensionBinding IAP di Project B.
    • Untuk menerapkan guardrail Model Armor terpusat di Project B, buat template Model Armor regional, berikan peran yang diperlukan ke agen layanan Service Extensions Project B, dan lampirkan ExtensionBinding Model Armor ke resource Agent Gateway di Project B.

Melihat log dan trace

Interaksi agen keluar yang dirutekan melalui Agent Gateway menghasilkan log dan trace terdistribusi sehingga Anda dapat memantau keputusan kebijakan dan men-debug perilaku agen:

Jika permintaan keluar gagal atau mengabaikan gateway, lihat Memecahkan masalah Agent Gateway.

Region yang didukung

Anda dapat menggunakan Agent Gateway di Cloud Run di region berikut:

  • europe-west1
  • us-central1

Batasan

Selain batasan jaringan ambien dan pertimbangan Secure Web Proxy dalam Men-deploy Secure Web Proxy sebagai Agent Gateway, batasan berikut berlaku saat Anda menggunakan Agent Gateway dengan Cloud Run:

  • Permintaan agen keluar yang dirutekan melalui instance Secure Web Proxy yang memeriksa TLS ke endpoint *.mtls.googleapis.com dan *.mtls.run.app gagal dengan error 503 karena Secure Web Proxy menghentikan dan memulai ulang sesi TLS tanpa meneruskan sertifikat klien.
  • Setiap Agent Gateway regional yang dikelola sendiri mendukung maksimal satu Agent Registry regional dalam daftar registries-nya.
  • Secara default, setiap project mendukung hingga 10 resource AgentGateway regional dan 10 resource EgressRouting regional per region. Project baru mungkin dimulai dengan batas 2 per region. Untuk meminta penambahan kuota, hubungi tim akun Anda.
  • Anda harus mengekspor sertifikat root atau subordinat dari pool CA Service atau PKI perusahaan pribadi dan mengonfigurasi container agen Anda untuk memercayainya.

Langkah berikutnya