Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Keluar Agent Gateway dari Agent Runtime ke MCP eksternal

1. Pengantar

Codelab ini membahas tata kelola traffic keluar Agent Gateway untuk agen AI yang mengakses server Model Context Protocol (MCP) eksternal yang dihosting di luar Google Cloud.

Aplikasi AI, mulai dari chatbot mandiri hingga sistem otonom dengan alur kerja multiagen, dapat memanggil alat eksternal secara dinamis. Memberikan akses terkontrol kepada agen untuk membuat kueri database, mengambil konten web, dan menjalankan tindakan sangat penting bagi agen yang aman dan produktif. Namun, dalam lingkungan perusahaan, mengamankan eksekusi alat agen adalah tantangan. Jika agen memiliki akses jaringan langsung, serangan injeksi perintah atau halusinasi model dapat menyebabkan agen memindahkan data sensitif secara tidak sah atau menjalankan perintah yang merusak.

Untuk mengelola agen otonom dalam skala besar, Agent Gateway menyediakan titik penerapan zero-trust terpusat yang terintegrasi langsung ke dalam arsitektur Agent Platform. Daripada mengandalkan penerapan kustom yang unik untuk setiap aplikasi atau kode agen, Agent Gateway menyediakan perutean jaringan, tata kelola agen, dan keamanan runtime yang diterapkan di tingkat platform.

Saat beroperasi dalam mode keluar (agent-to-anywhere), Agent Gateway mem-proxy semua permintaan keluar dari agen yang dikonfigurasi untuk menggunakan gateway. Setiap permintaan beban kerja agen diautentikasi menggunakan Agent Identity yang unik dan diotorisasi menggunakan kebijakan Identity-Aware Proxy (IAP). Panggilan alat MCP didekode dan diperiksa secara dinamis untuk penegakan kebijakan. Admin keamanan dapat menerapkan izin mendetail secara terpusat untuk memastikan agen hanya dapat memanggil endpoint dan metode yang disetujui.

Yang Anda bangun

Agent Gateway dalam mode keluar (agent-to-anywhere)
Ekstensi otorisasi Identity-Aware Proxy (IAP)
Agen ADK Agent Runtime dengan identitas agen
Agent Registry dengan endpoint Google API dan MCP
Konektivitas alat MCP eksternal ke set data publik Data Commons
Kebijakan otorisasi dengan kontrol akses IAM

Gambar 1. Arsitektur codelab

Yang Anda pelajari

Cara men-deploy Agent Gateway dalam urutan konfigurasi terstruktur
Cara mengubah kebijakan otorisasi dari mode uji coba ke mode diterapkan
Cara mendaftarkan endpoint Google API dan server MCP di Agent Registry
Cara menggunakan kebijakan otorisasi bersyarat berdasarkan atribut protokol MCP
Cara mengaudit log Agent Gateway untuk memvalidasi tata kelola keluar

Yang Anda perlukan

Project Google Cloud yang mengaktifkan penagihan
Izin IAM untuk menyediakan layanan jaringan dan resource Agent Platform
Shell yang kompatibel dengan POSIX (bash atau zsh) dengan Google Cloud CLI (komponen gcloud dan bq) yang diinstal
Alat command line: git, curl, jq (pemroses JSON), Python 3, dan uv (pengelola paket Python)
Kunci API Data Commons gratis untuk akses ke set data pengujian kueri

2. Konsep

Urutan deployment

Codelab ini mengikuti urutan konfigurasi terstruktur sehingga agen memiliki akses ke resource yang diperlukan saat inisialisasi dan konektivitas dapat dikonfirmasi sebelum menerapkan kebijakan akses yang diterapkan.

Codelab ini menggunakan urutan deployment berikut:

Mulai dalam mode DRY_RUN: Pastikan permintaan agen berhasil tiba di gateway dan melewati (mode hanya audit).
Mendaftarkan semua layanan: Mendaftarkan semua komponen agen di Registry Agen dan mengonfirmasi akses alat agen.
Membuat kebijakan otorisasi: Buat dan terapkan kebijakan otorisasi untuk mengizinkan traffic keluar dari agen ke server dan endpoint MCP.
Beralih ke mode ENFORCED: Perbarui kebijakan ekstensi otorisasi untuk menerapkan kebijakan dan memblokir traffic keluar yang tidak sah.

Gambar 2. Urutan deployment

Topologi perutean keluar

Egress Agent Gateway (agent-to-anywhere) berfungsi sebagai proxy keluar zero-trust terpusat untuk beban kerja agentic. Saat agen membuat permintaan ke alat atau API eksternal, permintaan keluar akan dicegat oleh Agent Gateway dan dievaluasi berdasarkan kebijakan tata kelola sebelum dirutekan ke tujuannya. Dalam arsitektur Platform Agen Google Cloud, Agent Gateway menyediakan konektivitas data plane ke:

Jaringan pribadi (VPC): Traffic keluar yang menargetkan API perusahaan internal, microservice, database yang dihosting dalam VPC pribadi, dan jaringan lokal atau lintas cloud yang dapat dijangkau melalui konektivitas hybrid.
Jaringan eksternal (Internet): Traffic keluar yang menargetkan layanan web pihak ketiga, API SaaS, atau endpoint publik.
Layanan AI & Platform Agen: Traffic keluar yang menargetkan API Google Cloud terkelola, model dasar, endpoint MCP Google (seperti BigQuery), dan layanan tata kelola platform (kebijakan Agent Registry dan IAP).

Gambar 3. Topologi perutean traffic keluar Agent Gateway

Codelab ini berfokus pada traffic keluar dari agen kustom di Agent Runtime yang menargetkan endpoint server MCP pihak ketiga eksternal yang dapat diakses melalui Internet.

Pemeriksaan protokol MCP

Egress Agent Gateway (agent-to-anywhere) dapat mem-parsing konten permintaan MCP dan mengevaluasi kebijakan akses berdasarkan atribut protokol terperinci. Kebijakan keluar server Agent-to-MCP dapat mencakup kondisi, yang dinyatakan dalam Common Expression Language (CEL), yang diterapkan saat runtime pada setiap permintaan.

Panggilan MCP biasanya menggunakan format protokol melalui kabel JSON-RPC dan transpor HTTP. Detail metode MCP yang dipanggil (misalnya, tools/call), nama alat target, dan argumen apa pun terdapat dalam payload JSON di isi HTTP.

Atribut iap.googleapis.com/mcp.toolName diekstrak oleh Agent Gateway dengan mengurai isi JSON untuk menemukan ID alat yang ditentukan dalam permintaan.

Atribut seperti iap.googleapis.com/mcp.tool.isReadOnly dan mcp.tool.isDestructive biasanya tidak dikirim dalam setiap isi permintaan. Sebagai gantinya, ini adalah anotasi (metadata) yang terkait dengan alat. Jadi, saat Agent Gateway mengekstrak toolName dari isi, Agent Gateway akan mencari definisi alat dan properti terkait dari Agent Registry, tempat konten toolspec.json didaftarkan.

Gambar 4. Pemeriksaan MCP Agent Gateway

Ekspresi CEL yang digunakan dalam kondisi IAM IAP menggunakan format standar api.getAttribute('iap.googleapis.com/ATTRIBUTE_NAME', 'DEFAULT_VALUE')== 'DESIRED_VALUE'.

Tabel ini menjelaskan atribut tata kelola egress Agent Gateway yang dapat diterapkan ke permintaan server MCP:

Atribut	Metode / Lokasi MCP	Deskripsi
`mcp.toolName`	`tools/call` (Body)	ID alat target yang diminta dalam payload RPC (misalnya, `"delete_instance"`)
`mcp.tool.isReadOnly`	Agent Registry (`toolspec.json`)	Menunjukkan apakah alat bersifat hanya baca (tidak mengubah lingkungannya)
`mcp.tool.isDestructive`	Agent Registry (`toolspec.json`)	Menunjukkan apakah pemanggilan alat dapat menyebabkan modifikasi yang tidak dapat dibatalkan atau kehilangan data
`mcp.tool.isIdempotent`	Agent Registry (`toolspec.json`)	Menunjukkan apakah eksekusi alat berulang dengan argumen yang identik menghasilkan status yang sama persis
`mcp.tool.isOpenWorld`	Agent Registry (`toolspec.json`)	Menunjukkan apakah alat menjangkau di luar sistem internal yang terbatas ke internet publik yang tidak terbatas

Bagian konsep ini telah selesai... selanjutnya ke bagian Penyiapan.

3. Penyiapan

Peran IAM yang diperlukan

Peran berikut diperlukan untuk membuat resource di Codelab ini:

Kategori	Peran IAM yang diperlukan (ID)	Deskripsi
Pengelolaan API	`roles/serviceusage.serviceUsageAdmin`	Mengaktifkan layanan Google Cloud API
Jaringan & gateway	`roles/networkservices.admin`	Menyediakan Agent Gateway
Service extensions	`roles/serviceextensions.admin`	Mengonfigurasi ekstensi perutean
Keamanan jaringan	`roles/networksecurity.admin`	Men-deploy kebijakan otorisasi
Agent Registry	`roles/agentregistry.admin`	Host yang diizinkan katalog
Vertex AI & agen	`roles/aiplatform.admin`	Men-deploy workload Agent Runtime
Kebijakan keluar	`roles/iap.admin`	Menerapkan kebijakan `roles/iap.egressor`
Cloud Storage	`roles/storage.admin`	Mengelola bucket penyiapan deployment
Log & audit	`roles/logging.viewer`	Memeriksa rekaman aktivitas dan log audit

Atau, gunakan peran dasar yang luas seperti roles/admin atau peran lama roles/owner.

Mengakses project Anda

Codelab ini menggunakan satu project Google Cloud. Langkah-langkah konfigurasi menggunakan perintah CLI gcloud dan shell Linux.

Mulailah dengan mengakses command line project Google Cloud Anda:

Cloud Shell di shell.cloud.google.com, atau
Terminal lokal dengan gcloud CLI terinstal

Menetapkan Project ID

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Mengautentikasi sesi

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Menetapkan variabel lingkungan shell

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-datacommons"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
export MCP_DISPLAY_NAME="api.datacommons.org"
export MCP_RESOURCE_NAME="${REGION}-datacommons-mcp"
export MCP_URL="https://api.datacommons.org/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_RESOURCE_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Perbarui `gcloud cli` (direkomendasikan)

Jika menjalankan penginstalan Google Cloud SDK yang dikelola sendiri (yaitu, di luar Cloud Shell), update komponen ke versi terbaru.

# update gcloud cli
gcloud components update

Mengaktifkan layanan API

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

Bagian penyiapan ini telah selesai... selanjutnya ke bagian Gateway.

4. Gateway

Sebelum menerapkan kontrol akses, deploy Agent Gateway dan konfigurasi ekstensi otorisasi dalam mode DRY_RUN. Hal ini memungkinkan panggilan alat keluar berhasil sekaligus mencatat hasil evaluasi untuk tujuan audit.

Di sini, Agent Gateway menggunakan registry regional untuk mendukung resource Agent Runtime regional.

Buat gateway

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

# import agent gateway config file (create gateway)
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}.yaml" \
  --location=${REGION}

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

Bagian gateway ini telah selesai... selanjutnya ke bagian Otorisasi.

5. Otorisasi

Ekstensi otorisasi Agent Gateway untuk Identity-Aware Proxy (IAP) adalah jenis Ekstensi Layanan yang digunakan untuk mendelegasikan keputusan otorisasi untuk semua komunikasi Agent Platform.

Alur delegasi: Saat mencoba memanggil endpoint eksternal atau server MCP, agen akan merutekan permintaan ke Agent Gateway. Alih-alih mengevaluasi akses secara lokal, gateway menggunakan ekstensi otorisasi untuk mengirim panggilan ke layanan evaluasi IAP. IAP mengevaluasi identitas agen (berbasis SPIFFE) terhadap kebijakan IAM resource target di Agent Registry. IAP menampilkan keputusan ALLOW atau DENY kembali ke gateway, yang akan meneruskan traffic atau memblokirnya dengan kode status HTTP 403 Forbidden.
Mode penerapan: Dalam mode DRY_RUN, IAP mengevaluasi permintaan dan mencatat keputusan di Cloud Logging tanpa memblokir traffic. Dalam mode ENFORCE, setiap permintaan dari agen yang tidak sah atau ke target yang tidak terdaftar akan langsung diblokir.
Lapisan binding: Ekstensi layanan terhubung ke Agent Gateway menggunakan kebijakan otorisasi yang dikonfigurasi dengan profil REQUEST_AUTHZ.

Ekstensi otorisasi

Membuat ekstensi otorisasi

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml \
  --location=${REGION}

# show authz extension details (verify extension state)
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

Kebijakan otorisasi

Kebijakan otorisasi mengikat penyedia keamanan (IAP) ke resource gateway target dan menentukan profil intersepsi (REQUEST_AUTHZ).

Membuat kebijakan otorisasi

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

# import authz policy config file (enable authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

# show authz policy details (verify dry run mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Bagian otorisasi ini telah selesai... selanjutnya ke bagian Codebase.

6. Codebase

Kode agen dan skrip pendaftaran endpoint yang digunakan untuk Codelab ini dikelola di repositori GitHub Google Cloud jarak jauh. Langkah-langkah berikut akan meng-clone repositori secara lokal, menyalin file yang diperlukan ke struktur direktori kerja saat ini, lalu menghapus file sementara.

Bucket penyiapan penyimpanan dibuat untuk Agent Runtime guna mengupload, mem-build, dan men-deploy kode aplikasi agen yang dipaketkan dan artefak dependensinya.

Mengambil artefak jarak jauh

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_emcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_emcp/codelabs/agw-cuj-arun-egress-emcp/agent-datacommons ./agent-datacommons
cp -r temp_agw_cuj_arun_egress_emcp/codelabs/agw-cuj-arun-egress-emcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_emcp

Buat bucket staging

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

Bagian codebase ini telah selesai... selanjutnya ke bagian Registry.

7. Registry

Agent Registry adalah inventaris terpusat dari semua agen, server MCP, dan endpoint (API) dalam ekosistem AI. Selain itu, katalog ini dapat digunakan untuk mencantumkan, menelusuri, dan menemukan alat serta layanan terdaftar lainnya untuk digunakan oleh aplikasi AI. Mode keluar Agent Gateway (agent-to-anywhere) menggunakan model data registri sebagai framework tata kelola untuk menerapkan kontrol akses keluar. Pemberian peran IAM untuk agen panggilan utama diperiksa berdasarkan kebijakan yang terikat ke resource registry.

Untuk mem-bootstrap lingkungan dan mendukung agen menggunakan berbagai Google API dan Layanan Google, skrip digunakan untuk mendaftarkan serangkaian endpoint API umum dengan cepat menggunakan nama host dan lokasi dari endpoints/googleapis.txt.

Mendaftarkan endpoint

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

Memverifikasi endpoint

# list registry regional endpoints (verify registration)
gcloud agent-registry endpoints list --location=${REGION} \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces[0].url:label=URL)"

Ini mengakhiri bagian pendaftaran... selanjutnya ke bagian Data Commons.

8. Data Commons

Data Commons adalah inisiatif dari Google untuk mengelola set data publik serta menyediakannya dan membuatnya dapat diakses oleh siapa saja. Layanan ini gratis dan dapat diakses menggunakan kunci API setelah membuat akun.

Buat kunci API

Setelah membuat akun, ikuti langkah-langkah berikut untuk mendapatkan kunci API:

Login ke Portal API Data Commons
Klik tombol "Aplikasi Saya" di pojok kanan atas
Klik tombol "+ APLIKASI BARU" di pojok kanan atas di bagian nama pengguna Anda
Beri nama aplikasi Anda (misalnya, "Codelab Agent MCP")
Klik tombol "AKTIFKAN" untuk Data Commons API api.datacommons.org
Klik tombol "SIMPAN" di pojok kanan bawah

Tindakan ini akan membuat kunci dan secret API. Klik ikon "salin" di samping nilai kunci untuk "Salin kunci API". Tempel nilai ke perintah terminal untuk menetapkan variabel lingkungan DC_API_KEY.

# set api key env var
 export DC_API_KEY="YOUR_API_KEY_HERE"

Buat server MCP `toolspec`

Saat mendaftarkan server MCP secara manual, file spesifikasi alat harus disertakan selama pendaftaran. Mengupload file toolspec.json akan mencantumkan semua alat yang disediakan oleh endpoint dan memungkinkan pengguna lain menemukannya.

Skrip test_mcp.py, yang disertakan dalam codebase agent-datacommons/, membuat file toolspec.json dengan terhubung ke server MCP target (melalui SSE atau HTTP) dan memanggil list_tools() untuk mengambil semua alat yang tersedia yang diekspos oleh server.

# generate toolspec for registry ingestion
uv --directory agent-datacommons run python3 test_mcp.py --toolspec=include --token="${DC_API_KEY}"

Melihat output toolspec yang dihasilkan akan menampilkan atribut MCP yang dapat digunakan Agent Gateway untuk evaluasi dan penerapan kebijakan keluar.

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' agent-datacommons/toolspec.json

Mendaftarkan server MCP

# register mcp server
gcloud agent-registry services create ${MCP_RESOURCE_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for data commons" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=agent-datacommons/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_RESOURCE_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_RESOURCE_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

Bagian Data Commons ini telah selesai... selanjutnya ke bagian Runtime.

9. Runtime

Agen ADK agent-datacommons yang di-deploy ke Agent Runtime dikonfigurasi dengan setelan berikut dalam skrip deployment untuk berintegrasi dengan Agent Platform:

"identity_type": types.IdentityType.AGENT_IDENTITY untuk menyediakan identitas utama berbasis SPIFFE yang unik untuk agen
"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } untuk mengarahkan semua traffic keluar yang dimulai agen ke Agent Gateway untuk evaluasi dan penegakan kebijakan

Men-deploy agen

# deploy agent runtime workload
uv --directory agent-datacommons run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for data commons stats" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --env-var="DC_API_KEY=${DC_API_KEY}"

Mengambil tanda vital deployment

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET \
  "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

Memverifikasi entri registri

# show agent resource registry details
gcloud agent-registry agents describe ${RE_AGENT_REGISTRY_ID} --location=${REGION}

10. Kebijakan

Kebijakan otorisasi tata kelola agen mengizinkan traffic dari agen AI melalui Agent Gateway dan ke tujuan (misalnya, endpoint server MCP pihak ketiga untuk aplikasi SaaS). Setelah traffic mencapai tujuan, izin tingkat layanan atau tingkat aplikasi reguler akan mengizinkan akses data.

Pemberian peran IAM untuk egress Agent Gateway memungkinkan kebijakan akses yang mengizinkan akses identitas utama agen ke resource tujuan terdaftar melalui Agent Gateway. Kebijakan diterapkan di tingkat Agent Gateway dan divalidasi menggunakan kebijakan IAM Identity-Aware Proxy (IAP).

Memberikan peran IAM agen untuk keluar dari Agent Gateway

Agent Gateway memeriksa permintaan masuk untuk memvalidasi bahwa identitas agen yang memanggil memiliki izin iap.webServiceVersions.egressViaIAP (diberikan oleh peran roles/iap.egressor) pada resource target.

Memberi roles/iap.egressor pada identitas agen atau set utama Agent Runtime di resource tujuan yang dipilih akan mengizinkan traffic keluar ini. Dalam codelab ini, peran diterapkan ke agen utama yang memberikan izin ke identitas agen Agent Runtime tertentu.

Kebijakan IAM terikat ke resource tujuan seperti yang ditentukan dalam model data Pendaftaran Agen. Resource iap_web/agentRegistry mewakili tingkat "di seluruh registri" dalam hierarki IAM. Dengan agentRegistry sebagai induk untuk setiap resource turunan agents, mcpServers, dan endpoints. Dalam codelab ini, kebijakan IAM terikat ke tingkat mcpServer dan endpoint yang menerapkan izin ke resource turunan tertentu.

Tentang pemfilteran MCP bersyarat

Server MCP Data Commons memiliki dua alat:

search_indicators: untuk kueri tentang penemuan data yang tersedia, penelusuran variabel, atau pemahaman cakupan data
get_observations: untuk kueri guna mengambil titik data atau deret waktu tertentu

Ada beberapa operasi MCP standar yang perlu diperhatikan saat mengonfigurasi kebijakan tata kelola bersyarat di server MCP. Sebelum klien MCP dapat membuat tools/call untuk search_indicators atau get_observations, klien tersebut harus mengirimkan permintaan penemuan & handshake protokol terlebih dahulu:

initialize
notifications/initialized
tools/list

Untuk mendemonstrasikan pemfilteran kebijakan bersyarat, kebijakan akan dikonfigurasi untuk kondisi berikut:

Tabel. Evaluasi kebijakan untuk permintaan MCP

Permintaan / Metode	Nilai `mcp.toolName`	Evaluasi CEL	Hasil
`initialize`	`""`	`"" in ['search_indicators', '']`	✅ DIIZINKAN (200)
`tools/list`	`""`	`"" in ['search_indicators', '']`	✅ DIIZINKAN (200)
`search_indicators`	`"search_indicators"`	`"search_indicators" in [...]`	✅ DIIZINKAN (200)
`get_observations`	`"get_observations"`	`"get_observations" in [...]`	❌ DITOLAK (403)

Untuk mengizinkan handshake protokol dan panggilan alat search_indicators, aturan kebijakan bersyarat menyertakan izin untuk "search_indicators" atau "" (string kosong).

Mengonfigurasi kebijakan IAM server MCP IAP registry

# show iap iam policy for mcp server
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

CATATAN: etag: harus menampilkan ACAB default karena belum ada kebijakan yang ditentukan.

# fetch active etag on policy for mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy \
  --resource-type=agent-registry --region=${REGION} \
  --mcp-server=${MCP_REGISTRY_ID} --format="value(etag)")
echo ${IAP_ETAG}

# create policy config file
cat > cfg/iap-policy-dc-agent-to-dc-mcp-tool-1.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ],
      "condition": {
        "title": "allow ${RE_AGENT_NAME} to use search_indicators tool for ${MCP_DISPLAY_NAME}",
        "expression": "api.getAttribute('iap.googleapis.com/mcp.toolName', '') in ['search_indicators', '']"
      }
    }
  ],
  "etag": "${IAP_ETAG}",
  "version": 3
}
EOF

# import policy file (bind iam policy)
gcloud beta iap web set-iam-policy cfg/iap-policy-dc-agent-to-dc-mcp-tool-1.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

# verify iap iam policy for mcp server
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

Bagian kebijakan telah selesai... selanjutnya kita akan membahas bagian Audit.

11. Audit

Ekstensi otorisasi Agent Gateway beroperasi dalam mode DRY_RUN. Permintaan keluar diamati dan dicatat dalam log, tetapi tidak diblokir.

Menguji kueri agen

Buka jendela browser ke UI konsol Google Cloud, lalu buka:

Agent Platform → Agents → Deployments → agent-datacommons
Pilih tab Playground

Atau, jalankan perintah terminal ini dan klik link untuk membuka playground agen:

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

Kirim beberapa kueri pengujian....

What data do you have on water quality in Zimbabwe?
Compare the life expectancy, economic inequality, and GDP growth for BRICS nations

Verifikasi bahwa kueri menampilkan respons yang valid.

Menganalisis log audit

Lihat log dan periksa evaluasi kebijakan uji coba.

# list unique urls with http status and iap authorization result
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=200 \
  --format="value(httpRequest.status, jsonPayload.authzPolicyInfo.result, httpRequest.requestUrl)" | sort -u

200     ALLOWED https://api.datacommons.org/mcp
200     ALLOWED https://cloudresourcemanager.googleapis.com:443/google.cloud.resourcemanager.v3.Projects/GetProject
200     ALLOWED https://telemetry.googleapis.com/v1/traces
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
200     ALLOWED https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}/events
202     ALLOWED https://api.datacommons.org/mcp

Memperbarui kebijakan IAM endpoint IAP registri

Memberikan izin keluar agen untuk endpoint telemetri

# set var for endpoint display name
export ENDPOINT_1_DISPLAY_NAME="telemetry.googleapis.com"
echo ${ENDPOINT_1_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_1_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_1_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_1_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-1.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-re-agent-to-ep-1.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_1_REGISTRY_ID} \
  --region=${REGION}

# verify iap iam policy for telemetry endpoint
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_1_REGISTRY_ID}

Memberikan izin keluar agen untuk endpoint aiplatform

# set var for endpoint display name
export ENDPOINT_2_DISPLAY_NAME="${REGION}-aiplatform.googleapis.com"
echo ${ENDPOINT_2_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_2_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_2_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_2_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-2.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-re-agent-to-ep-2.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_2_REGISTRY_ID} \
  --region=${REGION}

# verify iap iam policy for aiplatform endpoint
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_2_REGISTRY_ID}

Memberikan izin keluar agen untuk endpoint cloudresourcemanager

# set var for endpoint display name
export ENDPOINT_3_DISPLAY_NAME="cloudresourcemanager.googleapis.com"
echo ${ENDPOINT_3_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_3_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_3_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_3_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-re-agent-to-ep-3.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

# import policy file (bind iam policy)
gcloud -q beta iap web set-iam-policy cfg/iap-policy-re-agent-to-ep-3.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_3_REGISTRY_ID} \
  --region=${REGION}

# verify iap iam policy for cloudresourcemanager endpoint
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_3_REGISTRY_ID}

Ini mengakhiri bagian audit... selanjutnya ke bagian Terapkan.

12. Terapkan

Agen dapat membuat permintaan yang berhasil melalui gateway dalam mode DRY_RUN. Transisikan ekstensi otorisasi IAP Agent Gateway ke mode ENFORCE dengan memperbarui kebijakan otorisasi.

Memperbarui ekstensi otorisasi

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-enforced
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V1"
EOF

# import authz extension file (create extension)
gcloud service-extensions authz-extensions import ${AGW_NAME}-svc-ext-authz-iap-enforced \
  --source=cfg/${AGW_NAME}-svc-ext-authz-iap-enforced.yaml \
  --location=${REGION}

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

Memperbarui kebijakan otorisasi

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

# import authz policy config file (enable new authz policy)
gcloud beta network-security authz-policies import ${AGW_NAME}-authz-policy-profile-iap \
  --source=cfg/${AGW_NAME}-authz-policy-profile-iap.yaml \
  --location=${REGION}

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

Memverifikasi izinkan bersyarat

Kembali ke Playground agen di UI konsol.

Kirimkan kueri pengujian tambahan (coba panggil alat yang diizinkansearch_indicators)...

What data topics do you have for Peru?

Perhatikan bahwa permintaan agen ke model dasar Gemini (${REGION}-aiplatform.googleapis.com/...), Telemetry API (telemetry.googleapis.com/...), dan endpoint server MCP Data Commons (api.datacommons.org/mcp) diteruskan dengan kode status HTTP 200 OK.

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

Pastikan tidak ada permintaan yang diblokir. Cari upaya keluar yang ditolak dengan kode status HTTP 403 Forbidden di log audit gateway.

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

Memverifikasi penolakan bersyarat

Kirimkan kueri pengujian tambahan (coba memanggil alat ditolakget_observations)...

What are the diabetes levels in Peru compared to Slovakia?

Agen akan melihat search_indicators terlebih dahulu, lalu mencoba menggunakan get_observations, tetapi akan gagal dan respons agen akan dibiarkan tidak lengkap.

# show gateway logs for mcp requests with method and tool name
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND jsonPayload.agentGatewayInfo.mcpInfo.method:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL_NAME,
    httpRequest.requestUrl:label=URL
  )"

TIMESTAMP            STATUS  IAP_AUTHZ  MCP_METHOD                 TOOL_NAME          URL
YYYY-MM-DDTHH:MM:SS  403     DENIED     tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS          ALLOWED    tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  403     DENIED     tools/call                 get_observations   https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  200     ALLOWED    tools/call                 search_indicators  https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  200     ALLOWED    tools/list                                    https://api.datacommons.org/mcp
YYYY-MM-DDTHH:MM:SS  202     ALLOWED    notifications/initialized                     https://api.datacommons.org/mcp

Hal ini memvalidasi bahwa kebijakan tata kelola berfungsi seperti yang diharapkan.

Perhatikan bahwa baris kedua yang menunjukkan status kosong dan ALLOWED adalah peristiwa log penutupan koneksi sekunder yang dikeluarkan oleh Agent Gateway saat menutup soket setelah mengirim respons 403 (karena peristiwa penutupan koneksi tidak memiliki kode status respons, httpRequest.status kosong).

Hal ini mengakhiri bagian penerapan... selanjutnya ke bagian Pembersihan.

13. Pembersihan

# delete agent
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# delete storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# next

# clear policy on mcp server
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --mcp-server=${MCP_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 1
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_1_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_1_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 2
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_2_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_2_REGISTRY_ID} \
  --region=${REGION}

# next

# clear policy on endpoint 3
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --endpoint=${ENDPOINT_3_REGISTRY_ID} --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud -q beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --endpoint=${ENDPOINT_3_REGISTRY_ID} \
  --region=${REGION}

# next

# remove manual registry entry
gcloud -q agent-registry services delete ${MCP_RESOURCE_NAME} --location=${REGION}

# delete gateway resources
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-enforced --location=${REGION}

gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-datacommons endpoints

# end

Bagian pembersihan ini telah selesai... selanjutnya ke bagian Kesimpulan.

14. Kesimpulan

Selamat! Anda telah berhasil men-deploy dan mengatur komunikasi keluar untuk agen yang mengakses alat menggunakan Agent Gateway.

cosmopup

Cosmopup menganggap Codelab sangat keren!

Apa langkah selanjutnya?

Lihat dokumen Gemini Enterprise Agent Platform untuk mengetahui fitur dan tutorial lanjutan
Mengonfigurasi pedoman Model Armor di Agent Gateway untuk keamanan dan keselamatan AI tambahan
Pelajari Kebijakan Tata Kelola Semantik untuk menerapkan aturan bisnis dan kepatuhan untuk kueri bahasa alami

Jangan ragu untuk memberikan komentar, pertanyaan, atau koreksi menggunakan formulir masukan ini

Terima kasih!