Mengatur beban kerja agentic dengan Agent Gateway di Platform Agen Gemini Enterprise

1. Pengantar

Platform Agen Gemini Enterprise adalah platform terbuka untuk membangun, menskalakan, mengatur, dan mengoptimalkan agen AI tingkat perusahaan yang didasarkan pada data Anda.

Agent Runtime menyediakan lingkungan eksekusi terkelola untuk menjalankan agen, seperti agen yang dibangun dengan Agent Development Kit (ADK) open source, secara aman dalam Google Cloud.

Codelab ini menjelaskan cara menggunakan elemen penyusun inti ini untuk mengatur agen yang dimulai oleh pengguna di Gemini Enterprise saat agen tersebut menjangkau alat internal secara aman.

Tentang Agent Gateway

Agent Gateway adalah komponen jaringan dari rangkaian Tata Kelola Agen platform. Layanan ini bertindak sebagai titik masuk dan keluar jaringan untuk semua interaksi agen, sehingga memungkinkan administrator keamanan menerapkan tata kelola terpusat tanpa mengharuskan developer mengelola primitif jaringan yang kompleks.

Memfasilitasi dua jalur akses yang diatur utama:

• Client-to-Agent (ingress): Mengamankan komunikasi antara klien eksternal (seperti Cursor atau Gemini CLI) dan agen Anda.
• Agent-to-Anywhere (keluar): Mengamankan komunikasi antara agen yang berjalan di Google Cloud dan server, alat, atau API yang berjalan di mana saja.

Dalam codelab ini, Anda akan berfokus pada mode Agent-to-Anywhere (keluar).

Untuk menerapkan kebijakan keamanan, Agent Gateway terintegrasi erat dengan ekosistem lainnya:

• Agent Registry: Library terpusat untuk agen dan alat yang disetujui (termasuk server MCP pihak ketiga).
• Identitas Agen: Persona unik yang dapat dilacak untuk setiap agen, yang diamankan secara otomatis dengan mTLS end-to-end.
• Identity-Aware Proxy (IAP) & IAM: Lapisan penerapan default yang memvalidasi identitas agen terhadap izin IAM terperinci sebelum mengizinkan panggilan ke alat tertentu.
• Model Armor: Pembatasan keamanan AI yang diintegrasikan melalui Ekstensi Layanan untuk membersihkan konten dan melindungi dari serangan injeksi perintah atau kebocoran data.

Mode deployment (Jaringan publik vs. pribadi untuk Cloud Run)

Agar codelab ini dapat diakses, Anda dapat memilih antara dua jalur jaringan untuk alat internal (server MCP) yang di-deploy di Cloud Run:

1. Default (Ingress Publik): Server MCP di-deploy ke Cloud Run dengan nama host publik (ingress=all). Traffic dirutekan dari agen ke alat melalui URL *.run.app standar. Opsi ini tidak memerlukan domain DNS kustom dan merupakan cara tercepat untuk mempelajari konsep tata kelola.
2. Aman (Jaringan Pribadi): Arsitektur opsional yang sepenuhnya bersifat pribadi. Server MCP dibatasi (ingress=internal-and-cloud-load-balancing) dan diekspos melalui Load Balancer Aplikasi Internal dengan NEG Serverless. Anda harus memiliki domain DNS publik untuk menyediakan sertifikat yang dikelola Google.

Anda akan memilih jalur yang diinginkan saat mengonfigurasi Terraform.

Untuk mempelajari lebih lanjut traffic masuk endpoint jaringan untuk Cloud Run, baca dokumentasi kami.

Yang akan Anda lakukan

• Menyediakan stack infrastruktur inti menggunakan Terraform
• Membangun dan men-deploy alat internal sebagai server MCP di Cloud Run
• Men-deploy agen ADK ke Agent Runtime menggunakan keluar antarmuka PSC
• Mengonfigurasi ekstensi layanan Agent Gateway untuk akses berbasis identitas (IAM) dan penyaringan konten (Model Armor)
• Lacak dan validasi eksekusi end-to-end yang aman dari agen

Yang Anda butuhkan

• Browser web seperti Chrome
• Project Google Cloud dengan penagihan diaktifkan dan akses Pemilik
• Izin IAM tingkat organisasi (codelab memberikan peran cakupan organisasi)
• Domain yang Anda kontrol didelegasikan ke Cloud DNS (untuk sertifikat terkelola publik)
• Memahami Terraform, gcloud, dan jaringan Google Cloud dasar

Topologi codelab

Dalam codelab ini, Anda akan men-deploy agen penjaminan pinjaman rumah menyeluruh yang berkomunikasi secara aman dengan tiga alat internal.

Anda akan memulai dengan menyediakan jaringan dasar, termasuk VPC dan Load Balancer Aplikasi internal yang dikonfigurasi sebagai Gateway Agen Anda. Selanjutnya, Anda akan men-deploy tiga server Model Context Protocol (MCP) ke Cloud Run. Alat ini berfungsi sebagai alat internal eksklusif Anda:

• Pengelolaan Dokumen (legacy-dms)
• Email Perusahaan (corporate-email)
• Verifikasi Pendapatan (income-verification)

Setelah alat tersedia, Anda akan men-deploy Asisten Hipotek (mortgage-agent) yang dibangun dengan ADK ke Agent Runtime. Anda akan mengonfigurasi agen ini untuk menggunakan Antarmuka PSC untuk egress pribadi dan mengaktifkan penemuan alat runtime melalui Registry Agen.

Untuk mengamankan alur, Anda akan mengonfigurasi Agent Gateway dengan dua ekstensi layanan. Pertama, ekstensi REQUEST_AUTHZ akan memverifikasi Identitas Agen terhadap kebijakan IAM per alat, sehingga memastikan agen hanya mengakses alat yang berwenang. Kedua, ekstensi CONTENT_AUTHZ yang menggunakan Model Armor akan menyaring perintah dan respons agen.

Terakhir, Anda akan mendaftarkan agen di Gemini Enterprise, memicu tugas penjaminan pinjaman rumah sebagai pengguna akhir, dan memverifikasi eksekusi yang aman dan diatur menggunakan Cloud Trace.

Codelab ini ditujukan bagi engineer platform dan keamanan dari semua tingkat keahlian. Anda akan memerlukan waktu sekitar 100 menit untuk menyelesaikannya.

2. Sebelum memulai

Membuat project dan melakukan autentikasi

Buat project GCP baru (atau gunakan kembali project yang sudah ada) dengan penagihan diaktifkan, lalu lakukan autentikasi Cloud Shell atau mesin lokal Anda:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

Aktifkan API bootstrap

Modul dasar Terraform mengaktifkan sekitar 30 API pada penerapan pertamanya, tetapi serangkaian bootstrap kecil diperlukan untuk terraform init dan bucket status GCS:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

Menginstal alat yang diperlukan

Instal toolchain. Di Cloud Shell, sebagian besar sudah ada; di workstation:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

Anda juga memerlukan Terraform >= 1.12.2, Python 3.12+, dan Google Cloud SDK (gcloud).

Menetapkan variabel lingkungan

Bagian selanjutnya dari codelab mengasumsikan bahwa variabel ini diekspor di shell Anda.

Jika Anda mengikuti jalur jaringan aman opsional, tentukan DOMAIN_NAME (misalnya, agw.example.com); jika tidak, Anda dapat mengabaikannya.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com" 

Pastikan semua variabel Anda diisi dengan benar, Anda akan mendapatkan tiga nilai yang ditampilkan.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Jika ID Organisasi Anda tidak terisi, Anda dapat menemukannya dan menyetelnya secara manual.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Melakukan cloning repositori

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

Tur singkat tentang isi direktori demo:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Buat bucket status Terraform dan konfigurasi backend

Buat bucket GCS untuk menyimpan status jarak jauh, lalu salin template backend:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

Edit terraform/backend.conf dengan nilai Anda:

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

terraform/backend.conf diabaikan git. Setiap pengguna menyimpan salinannya sendiri.

5. (Opsional) Buat zona Cloud DNS publik

Lewati langkah ini jika Anda menggunakan Jalur default. Jika Anda ingin menggunakan penyiapan paling sederhana dengan URL Cloud Run publik, lanjutkan langsung ke langkah berikutnya.

Secara default untuk lab ini, Cloud Run memiliki konfigurasi ingress yang disetel ke all dan Agent Registry mendaftarkan setiap server MCP di URL *.run.app publiknya — tidak diperlukan DNS, sertifikat, atau load balancer tambahan. Jika ingin beralih ke jaringan pribadi (Cloud Run dengan ingress = internal-and-cloud-load-balancing di belakang LB Aplikasi internal), Anda juga memerlukan zona Cloud DNS publik agar Certificate Manager dapat memvalidasi sertifikat LB.

Alur umum jaringan pribadi

Untuk menggunakan pendekatan jaringan pribadi:

1. Buat zona Cloud DNS publik — Certificate Manager memvalidasi sertifikat terkelola regional dengan menulis CNAME ke dalamnya:

gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

Zona pribadi yang sesuai untuk mcp.${DOMAIN_NAME} (digunakan oleh LB internal MCP dan peering DNS dari Agent Runtime) dibuat secara otomatis oleh Terraform — Anda tidak perlu membuatnya secara manual. Jika jaringan pribadi dinonaktifkan, zona publik maupun zona pribadi tidak disediakan.

Untuk mengetahui penjelasan mendalam tentang pola DNS split-horizon publik dan pribadi yang digunakan demo ini (penyiapan managed-zone, peering DNS di seluruh VPC, alur validasi sertifikat), lihat panduan penyiapan DNS.

6. Mengonfigurasi variabel Terraform

Salin contoh tfvars dan edit:

cp terraform/example.tfvars terraform/terraform.tfvars

Ada dua jalur demo, yang diatur oleh enable_cloud_run_private_networking.

Jalur default: Cloud Run dengan ingress publik

**Penyiapan paling sederhana.**Untuk jalur default, Anda hanya perlu mengedit tiga nilai di terraform.tfvars. Setiap variabel lain dalam file sudah memiliki default yang cocok untuk demo.

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:[e-mail]"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

Kita akan mengonfigurasi IAP dalam mode hanya audit uji coba, untuk menguji kebijakan otorisasi IAP tanpa menerapkannya. Setelah memvalidasi deployment, kami akan memperbarui mode penegakan ke "DITEGAKKAN"

Private networking (opsional)

Tetapkan enable_cloud_run_private_networking = true dan tambahkan variabel di bawah untuk menyediakan stack aman lengkap:

• LB Aplikasi Internal
• Sertifikat yang dikelola Google
• Cloud Run dengan ingress = internal-and-cloud-load-balancing
• Peering DNS Agent Gateway.

enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

Gambar Cloud Run di atas mengarah ke placeholder Google. Hal ini disengaja — Terraform membuat layanan Cloud Run dengan lifecycle { ignore_changes = [template[0].containers[0].image] }, sehingga pemanggilan skaffold run berikutnya menggantikan image tanpa Terraform membatalkannya.

agent_gateway_subnet_cidr harus minimal /28, RFC 1918, dan tidak boleh tumpang-tindih dengan 10.0.0.0/24, 10.0.1.0/24, atau 10.0.2.0/24. Rentang ini dicadangkan untuk keluar dari Agent Gateway.

LB internal MCP menyajikan TLS untuk *.mcp.${DOMAIN_NAME} menggunakan sertifikat regional yang sama yang dikelola Google. Jangan tetapkan mcp_internal_dns_zone.domain ke akhiran yang tidak dapat dirutekan seperti mcp-server.internal. saat enable_agent_gateway = true DAN enable_cloud_run_private_networking = true.

Agent Gateway saat ini tidak memvalidasi sertifikat penggantian yang ditandatangani sendiri. Konfigurasi Terraform menerapkan hal ini dengan blok check pada waktu perencanaan (dilewati saat jaringan pribadi nonaktif, karena tidak ada sertifikat LB yang perlu divalidasi).

7. Men-deploy infrastruktur dengan Terraform

Lakukan inisialisasi, tinjau, dan terapkan:

cd terraform
terraform init -backend-config=backend.conf
terraform plan
terraform apply

terraform apply menyediakan sekitar 40 resource di jalur default dan memerlukan waktu 8–10 menit di project baru (sekitar 60 resource / 15–20 menit saat enable_cloud_run_private_networking = true). Tindakan ini akan membuat:

• Dasar project (API, identitas layanan, kuota)
• VPC, subnet (primer, hanya proxy, PSC, PSC-Interface, kolokasi Agent Gateway), Cloud NAT, aturan firewall
• Repo Artifact Registry untuk image Cloud Run
• Tiga layanan Cloud Run + SA runtime per layanan (ingress = all secara default; internal-and-cloud-load-balancing saat jaringan pribadi aktif)
• Template Model Armor + IAM
• Agent Gateway, lampiran jaringan PSC-I, ekstensi IAP dan Model Armor, kedua kebijakan otorisasi, dan pemberian roles/iap.egressor tingkat project
• Endpoint Agent Registry (Vertex AI, IAP, Discovery Engine, ...) ditambah tiga server MCP (terdaftar di *.run.app/mcp secara default; di ./mcp saat jaringan pribadi aktif)

Hanya jika enable_cloud_run_private_networking = true:

• LB Aplikasi regional internal dengan NEG serverless (pemilihan rute URL-mask) + data A DNS pribadi
• Zona DNS pribadi MCP (mcp..) yang terpasang ke VPC
• Modul zona DNS publik (otorisasi DNS Certificate Manager) + Sertifikat yang dikelola Google regional
• Zona DNS Antarmuka PSC (tidak digunakan jika tidak ada nama host pribadi yang akan di-resolve, sehingga juga dibatasi oleh tanda master)
• Peering DNS Agent Gateway untuk mcp.. (ditambahkan secara otomatis)

8. Periksa endpoint Agent Registry

Hanya referensi. Perintah di bagian ini telah dijalankan untuk Anda oleh modul agent-registry-endpoints Terraform. Endpoint tersebut ditampilkan agar Anda dapat melihat dengan tepat seperti apa tampilan pendaftaran endpoint yang dapat ditemukan MCP.

Agent Registry adalah katalog layanan per project (Google API dan server MCP Anda sendiri) yang ditemukan oleh agen saat runtime. Agen pemberi pinjaman membaca saat startup dan mengikat alat secara dinamis — tidak ada URL MCP yang dimasukkan ke dalam kode agen atau perintah deployment-nya.

Endpoint

Apa yang dijalankan Terraform atas nama Anda — untuk setiap Google API di agent_registry_google_apis, Terraform mendaftarkan lima varian (global, mTLS global, regional, mTLS regional, REP regional). Misalnya, untuk aiplatform:

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

Server MCP

Terraform juga mendaftarkan 3 Server MCP untuk Anda. Untuk mendaftarkan server MCP lainnya, Anda dapat mengikuti langkah-langkah dalam dokumentasi.

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

Verifikasi Endpoint dan Server MCP yang terdaftar.

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

Sumber: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl

9. Meninjau konfigurasi Agent Gateway

Hanya referensi. Terraform telah mengimpor Agent Gateway ini. YAML di bawah ini setara dengan terraform/modules/agent-gateway/main.tf.

Agent Gateway adalah bidang tata kelola yang dikelola Google antara Agent Runtime dan alat Anda. Dalam mode AGENT_TO_ANYWHERE, Agent Engine terikat ke Agent Registry project dan melakukan egress melalui Antarmuka PSC milik pelanggan sehingga dapat menjangkau server MCP pribadi di VPC Anda.

Jika Anda mengimpor gateway ini secara manual, YAML akan terlihat seperti ini:

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

Verifikasi gateway yang dibuat Terraform:

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

terraform-provider-google-beta saat ini belum mengekspos network_config.dns_peering_config. Terraform menerapkannya melalui PATCH setelah penerapan di networkservices.googleapis.com/v1beta1. Anda akan melihatnya di terraform_data.dns_peering dalam modul.

10. Memeriksa otorisasi IAP dan Model Armor

Hanya referensi. Terraform telah membuat kedua ekstensi dan kedua kebijakan. Perintah di bawah ini berasal langsung dari terraform/modules/agent-gateway/main.tf.

Agent Gateway mendelegasikan otorisasi ke ekstensi layanan. Dua profil kebijakan mencakup demo:

• REQUEST_AUTHZ — dievaluasi sekali per permintaan pada tahap header. Digunakan di sini untuk memanggil IAP, yang memeriksa apakah identitas agen pemanggil memiliki roles/iap.egressor di server MCP target.
• CONTENT_AUTHZ — mengalirkan peristiwa isi ke ekstensi untuk pembersihan konten. Digunakan di sini untuk memanggil Model Armor, yang menyaring injeksi perintah, jailbreak, pelanggaran RAI, dan (opsional) PII melalui Sensitive Data Protection (SDP).

Ekstensi IAP REQUEST_AUTHZ

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

Ikat ke Agent Gateway dengan kebijakan REQUEST_AUTHZ:

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

Ekstensi CONTENT_AUTHZ Model Armor

metadata.model_armor_settings ekstensi membawa ID template permintaan dan respons yang digunakan Model Armor untuk mengevaluasi setiap info:

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

Template DLP kustom

sdpSettings.basicConfig Model Armor menggunakan daftar jenis info bawaan. Untuk kontrol yang lebih baik (jenis info kustom, penyamaran parsial, penggantian pengganti, pengeditan berdasarkan kemungkinan), arahkan Model Armor ke template pemeriksaan dan penghapusan identifikasi Cloud DLP Anda sendiri melalui sdpSettings.advancedConfig.

Buat template inspeksi yang menandai Nomor Jaminan Sosial AS dengan kemungkinan POSSIBLE atau lebih tinggi:

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates" \
  -d '{
    "templateId": "agw-ssn-inspect-template",
    "inspectTemplate": {
      "displayName": "SSN Inspect Template",
      "inspectConfig": {
        "infoTypes": [
          { "name": "US_SOCIAL_SECURITY_NUMBER" }
        ],
        "minLikelihood": "POSSIBLE"
      }
    }
  }'

Buat template de-identifikasi yang mengganti setiap temuan dengan token jenis infonya (misalnya, [US_SOCIAL_SECURITY_NUMBER]):

curl -fsS -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  "https://dlp.googleapis.com/v2/projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates" \
  -d '{
    "templateId": "agw-ssn-redaction-template",
    "deidentifyTemplate": {
      "displayName": "SSN Redaction Template",
      "deidentifyConfig": {
        "infoTypeTransformations": {
          "transformations": [{
            "primitiveTransformation": { "replaceWithInfoTypeConfig": {} }
          }]
        }
      }
    }
  }'

Kemudian, arahkan konfigurasi respons template Model Armor ke pasangan melalui sdpSettings.advancedConfig (di sinilah modul model_armor Terraform akan menetapkan advanced_config jika Anda menghubungkannya):

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

Ekstensi Model Armor CONTENT_AUTHZ di atas akan otomatis mengambil template konfigurasi lanjutan ini saat mengevaluasi respons berikutnya — tidak perlu ada perubahan ekstensi. Pastikan agen layanan Model Armor (service-${PROJECT_NUMBER}@gcp-sa-modelarmor.iam.gserviceaccount.com) memiliki roles/dlp.user dan roles/dlp.reader di project (modul model-armor Terraform sudah memberikan akses ini).

IAM keluar IAP (khusus per-server MCP)

Terraform tidak membuat pengikatan roles/iap.egressor di seluruh project pada registry agen IAP implisit. Binding IAP REQUEST_AUTHZ yang sebenarnya dievaluasi adalah per-server MCP dan per-mesin penalaran, yang diberikan setelah agen di-deploy dan Anda mengetahui ID Agen. Langkah "Berikan egress per-server MCP ke agen" menjalankan scripts/grant_agent_mcp_egress.sh untuk itu.

11. Membangun dan men-deploy server MCP ke Cloud Run

File cloudrun/*.yaml.tmpl dan skaffold.yaml.tmpl mereferensikan ${PROJECT_ID}, ${REGION}, dan ${MCP_INGRESS} (anotasi ingress Cloud Run). Sumber MCP_INGRESS dari output Terraform sehingga manifes yang dirender tetap disinkronkan dengan enable_cloud_run_private_networking, lalu render dengan envsubst:

Ekspor konfigurasi ingress Cloud Run Anda.

• all
• internal-and-cloud-load-balancing (Saat menggunakan pendekatan Private Networking)

export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Setiap layanan Cloud Run berjalan sebagai SA runtime per layanan yang dibuat Terraform (misalnya, mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Untuk men-deploy sebagai SA tersebut, Anda memerlukan roles/iam.serviceAccountUser pada diri Anda:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

Bangun dengan Cloud Build dan deploy dengan Skaffold:

skaffold run

Skaffold membangun tiga image (legacy-dms, corporate-email, income-verification-api) ke dalam repo Artifact Registry Anda dan memperbarui setiap layanan Cloud Run untuk mengarah ke ringkasan baru.

Verifikasi:

gcloud run services list --region=${REGION}

Anda akan melihat ketiga layanan dengan status ACTIVE.

12. Men-deploy agen hipotik ke Agent Runtime

Instal dependensi agen dan deploy:

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

Agen menemukan alat MCP saat runtime dengan mencantumkan mcpServers di Registry Agen di bagian projects/${PROJECT_ID}/locations/${REGION}.

Setelah skrip selesai, salin reasoningEngines/ yang dicetak ke shell Anda:

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. Memberikan akses keluar per server MCP kepada agen

Ekstensi IAP REQUEST_AUTHZ mengizinkan setiap panggilan alat dengan memeriksa roles/iap.egressor agen pada endpoint atau server MCP tertentu yang dipanggilnya. Lihat Membuat kebijakan egress server MCP ke agen.

Skrip (scripts/grant_agent_mcp_egress.sh) mencantumkan server MCP di Agent Registry di bagian projects/${PROJECT_ID}/locations/${REGION} dan menggabungkan binding roles/iap.egressor untuk akun utama agen ke dalam kebijakan IAM setiap server (mencerminkan semantik gcloud add-iam-policy-binding).

Kasus penggunaan 1 — Pemberian tanpa syarat yang dicakup ke server MCP tertentu

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

Kasus penggunaan 2 — Pemberian bersyarat (CEL) yang dicakup ke server MCP tertentu

Untuk membatasi agen ke subset alat di satu server MCP, lampirkan kondisi IAM. Agent Gateway memublikasikan atribut per alat yang diekspos IAP REQUEST_AUTHZ ke CEL, termasuk:

• iap.googleapis.com/mcp.toolName
• iap.googleapis.com/mcp.tool.isReadOnly
• iap.googleapis.com/request.auth.type.

Membatasi agen hanya untuk alat baca saja di corporate-email:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Setelah ini berjalan, alat tulis di corporate-email akan menampilkan 403 PermissionDenied dari IAP REQUEST_AUTHZ; alat hanya baca akan terus berfungsi.

Memverifikasi binding

Buka tab Policies dan Anda akan melihat daftar Kebijakan yang dibuat terhadap Endpoint dan Mcp Server.

Kasus Penggunaan Tambahan:

Pemberian akses tanpa syarat di setiap server MCP, yang dicakup ke satu agen

Jalankan perintah ini setelah setiap penyiapan ulang agen. Tanpa filter dan tanpa kondisi, agen bernama akan mendapatkan roles/iap.egressor di setiap server MCP dalam registry:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. Menguji agen di konsol Agent Platform

Konsol Platform Agen dilengkapi dengan Playground yang memungkinkan Anda melakukan percakapan dengan agen yang di-deploy secara langsung. Cara ini adalah cara tercepat untuk menguji panggilan alat dan memeriksa rekaman aktivitas sebelum menghubungkan agen ke Gemini Enterprise.

1. Buka halaman Agent Platform Deployments di Konsol Google Cloud.
2. Gunakan kolom Filter jika Anda perlu mempersempit daftar runtime, lalu klik runtime mortgage-agent Anda.
3. Buka tab Playground.
4. Ketik perintah untuk memulai percakapan dengan agen:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Respons ini harus menampilkan respons dari alat Pengelolaan Dokumen dan alat Verifikasi Pendapatan, serta Nomor Jaminan Sosial (SSN) juga harus disamarkan dalam respons ini. 5. Ketik perintah lanjutan:

Can you send a summary of this to my email [e-mail]

Agen harus mengidentifikasi bahwa ia tidak memiliki akses ke alat send_email dan meresponsnya dengan tepat.

Karena agen di-deploy dengan instrumentasi OpenTelemetry, Playground menampilkan empat tampilan panel samping yang dapat Anda alihkan saat agen merespons:

• Trace — jejak lengkap percakapan, termasuk rentang Agent Gateway, IAP REQUEST_AUTHZ, dan Model Armor CONTENT_AUTHZ
• Peristiwa — grafik alat yang dipanggil dan detail peristiwa untuk giliran saat ini
• State — status sesi agen dan input/output alat
• Sesi — setiap sesi yang telah Anda mulai terhadap runtime ini

Playground sepenuhnya melewati autentikasi Gemini Enterprise, sehingga menjadi tempat tercepat untuk mengonfirmasi bahwa ekstensi IAP REQUEST_AUTHZ memberikan panggilan alat dengan benar. Jika alat menampilkan 403 di sini, jalankan ulang scripts/grant_agent_mcp_egress.sh sebelum melakukan proses debug lebih lanjut.

15. Menerapkan Otorisasi IAP

Setelah memvalidasi deployment, kita dapat memperbarui mode Penerapan IAP ke null untuk menerapkan kebijakan. Buka terraform.tfvars dan perbarui mode dari DRY_RUN ke null

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = null

Terapkan perubahan.

terraform apply

Kembali ke Playground dan coba percakapan lagi.

1. Buka halaman Agent Platform Deployments di Konsol Google Cloud.
2. Gunakan kolom Filter jika Anda perlu mempersempit daftar runtime, lalu klik runtime mortgage-agent Anda.
3. Buka tab Playground.
4. Ketik perintah untuk memulai percakapan dengan agen:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Respons ini harus menampilkan respons dari alat Pengelolaan Dokumen dan alat Verifikasi Pendapatan, serta Nomor Jaminan Sosial (SSN) juga harus disamarkan dalam respons ini. 5. Ketik perintah lanjutan:

Can you send a summary of this to my email [e-mail]

Jika semuanya telah disiapkan dengan benar, agen akan merespons bahwa agen tidak dapat mengirim email karena kebijakan otorisasi.

16. Penyiapan & Pengujian Gemini Enterprise

Menyiapkan Gemini Enterprise

Ikuti panduan memulai penggunaan Gemini Enterprise.

Mendaftarkan Agen ADK kami dengan Gemini Enterprise

Untuk mengikuti langkah-langkah pendaftaran agen kami di Gemini Enterprise, Anda dapat mengikuti langkah-langkah di sini.

1. Di Konsol Google Cloud, buka halaman Gemini Enterprise.
2. Pilih Aplikasi Gemini Enterprise tempat agen terdaftar.
3. Buka URL yang ditampilkan di bagian Aplikasi web Gemini Enterprise Anda sudah siap.
4. Pilih tab Agent dari menu kiri untuk membuka Agent Gallery.
5. Pilih Mortgage Assistant Agent dan mulai chat.

Coba perintah yang sama dari Agent Runtime Playground:

Perintah awal:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Perintah lanjutan:

Can you send a summary of this to my email [e-mail]

Jika Anda kembali ke bagian Agent Deployment di konsol, pilih deployment agen kita dan buka tab traces, Anda akan melihat agen Gemini Assistant dalam rentang yang menunjukkan panggilan berasal dari Gemini Enterprise.

17. Pemecahan masalah & perbaikan umum

• terraform apply gagal di Agent Gateway dengan pesan "resource is being created and therefore can not be updated" — project tenant gateway memerlukan waktu sekitar 30 detik untuk diselesaikan sebelum kebijakan otorisasi dapat dilampirkan. time_sleep.wait_for_gateway modul menangani hal ini; cukup jalankan ulang terraform apply.
• Agen melaporkan "tidak ada server MCP yang ditemukan" atau melakukan booting hanya dengan alat utilitas — konfirmasi enable_agent_registry_endpoints = true di terraform.tfvars, lalu:

  gcloud alpha agent-registry mcp-servers list \
    --project=${PROJECT_ID} --location=${REGION}
  

  Anda akan melihat tiga entri (satu per layanan MCP Cloud Run). Jika daftar kosong, periksa apakah layanan MCP dapat dijangkau dari dalam VPC dan apakah Agent Gateway telah mengisi registry (Agent Gateway melakukannya secara lambat pada daftar alat yang di-proxy pertama).
• Panggilan alat menampilkan 403 PermissionDenied — jalankan ulang scripts/grant_agent_mcp_egress.sh. Penyebab paling umum adalah lupa memberikan kembali izin setelah men-deploy ulang agen (reasoningEngines/ berubah setiap kali deployment).
• skaffold run gagal dengan "izin ditolak di akun layanan" — Anda tidak memiliki roles/iam.serviceAccountUser. Jalankan ulang pemberian izin sendiri pada langkah sebelumnya.
• Error peering DNS dari Agent Gateway ke MCP LB — periksa apakah agent_gateway_dns_peering_config.target_network sama persis dengan projects/${PROJECT_ID}/global/networks/${VPC_NAME}, dan setiap entri domains diakhiri dengan titik di belakangnya.
• terraform plan terus ingin mengupdate tag image Cloud Run — hal ini tidak boleh terjadi karena aturan lifecycle { ignore_changes }. Jika ya, konfirmasi bahwa Anda tidak mengedit mcp_services[*].image di terraform.tfvars setelah skaffold run.

18. Pembersihan

Mesin penalaran tidak dikelola oleh Terraform (ADK SDK membuatnya). Hapus secara manual:

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

Menghapus semua yang dibuat Terraform:

cd terraform
terraform destroy
cd ..

Jika Anda membuat zona DNS publik hanya untuk codelab ini:

gcloud dns managed-zones delete agw-example-com

Terakhir, hapus bucket status Terraform:

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

19. Selamat

Selamat! Anda telah berhasil menerapkan tata kelola agen yang komprehensif untuk agen ADK multi-alat menggunakan Agent Gateway. Dengan bertindak sebagai bidang kontrol jaringan terpusat, Agent Gateway memungkinkan Anda membuat jalur egress yang aman ke alat pribadi, menerapkan kebijakan IAM berbasis identitas yang terperinci melalui Identity-Aware Proxy, dan membersihkan interaksi konten menggunakan batas keamanan Model Armor terintegrasi.

Yang telah Anda pelajari

• Cara men-deploy dan mengonfigurasi Agent Gateway sebagai lapisan tata kelola pusat untuk traffic keluar Agent-to-Anywhere.
• Cara mengintegrasikan Pendaftaran Agen untuk penemuan alat runtime dinamis yang diatur.
• Cara menulis dan menerapkan kebijakan IAM berbasis alat dan kondisi untuk mengontrol jalur eksekusi agen secara ketat.
• Cara memanfaatkan ekstensi layanan Agent Gateway untuk menerapkan kebijakan Model Armor, yang secara otomatis mencegat dan menyamarkan traffic agen yang sensitif.

Dokumen referensi

• Ringkasan Kebijakan Tata Kelola Agen
• Dokumentasi Agent Gateway
• Dokumentasi Identitas Agen
• Ringkasan Platform Agen Gemini Enterprise