Traffic keluar Agent Gateway dari Agent Runtime ke Google MCP

1. Pengantar

Codelab ini membahas tata kelola egress Agent Gateway untuk agen AI yang mengakses server Model Context Protocol (MCP) Google Cloud jarak jauh.

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
• Kebijakan otorisasi dengan kontrol akses IAM
• Set data BigQuery yang akan dikueri menggunakan MCP

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 mengaudit log Agent Gateway untuk memvalidasi tata kelola keluar

Yang Anda perlukan

• Project Google Cloud yang mengaktifkan penagihan
• Izin IAM untuk menyediakan layanan jaringan, set data BigQuery, 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)

2. Konsep

Urutan deployment

Saat men-deploy Agent Gateway dengan kontrol tata kelola, penting untuk mengikuti urutan konfigurasi terstruktur agar agen memiliki akses ke resource yang diperlukan saat inisialisasi dan permintaan jaringan akan berhasil.

Codelab ini menggunakan urutan deployment berikut:

• Mulai dalam mode uji coba: Jika runtime agen dikonfigurasi untuk merutekan panggilan keluar ke gateway sebelum gateway disediakan sepenuhnya, workload akan gagal diinisialisasi. Mengonfigurasi ekstensi otorisasi gateway dalam mode DRY_RUN terlebih dahulu memastikan bahwa saat traffic agen tiba di gateway, tidak ada permintaan yang dibatalkan.
• Mendaftarkan semua layanan: Semua agen, server MCP, dan endpoint yang menggunakan Agent Gateway harus didaftarkan di Agent Registry. Permintaan ditolak untuk sumber atau tujuan yang tidak terdaftar. Agen yang di-deploy di server Google MCP dan Agent Runtime akan otomatis terdaftar. Endpoint API Google atau server MCP kustom harus didaftarkan secara manual.
• Terapkan kebijakan otorisasi: Kebijakan otorisasi digunakan untuk mengizinkan akses agen terdaftar ke komponen agentik dengan memberikan peran roles/iap.egressor kepada principal identitas agen dan mengikatnya ke resource registri target. Evaluasi perilaku agen menggunakan mode uji coba, lalu tentukan kebijakan untuk mengizinkan traffic keluar yang dipilih melalui gateway. Setelah kebijakan diterapkan, beralihlah ke mode ENFORCED untuk mengaktifkan gateway agar secara aktif menerapkan kebijakan tata kelola.

Gambar 2. Urutan deployment

Topologi perutean traffic keluar

Gateway biasanya mengelola traffic masuk (ingress) ke layanan backend. Agent Gateway, yang beroperasi dalam mode keluar (agent-ke-mana saja), berfungsi sebagai proxy keluar zero-trust yang terpusat untuk beban kerja agentic.

Saat aplikasi AI atau beban kerja agentik mencoba memanggil alat atau API eksternal, permintaan keluar akan dicegat oleh Agent Gateway dan dievaluasi berdasarkan kebijakan tata kelola sebelum dirutekan ke tujuannya:

• 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 Google jarak jauh untuk BigQuery.

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
BigQuery	roles/bigquery.admin	Menyiapkan skema dan set data pengujian
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-dj"
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}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

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 \
  discoveryengine.googleapis.com

CATATAN: Beberapa fitur mungkin menggunakan perintah gcloud beta. Jika belum diinstal, jalankan gcloud components install beta untuk mengaktifkan.

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.

1. 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.
2. 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.
3. 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, set data BigQuery, dan skrip pendaftaran 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 yang tidak diperlukan.

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_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

Buat set data BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

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 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 registry... selanjutnya ke bagian Runtime.

8. Runtime

Agen ADK agent-dj 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-dj 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 dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

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 AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

Memverifikasi entri registri

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

CATATAN: Men-deploy agen di Agent Runtime akan otomatis membuat link registri (RuntimeReference), mengekspos pokok identitas agen yang digunakan untuk kebijakan keluar IAP (RuntimeIdentity), dan menampilkan penemuan endpoint dinamis (protocols.interfaces).

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

Verifikasi konfigurasi gateway

# verify agent gateway routing specification
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

VERIFIKASI: Periksa apakah agentGateway menampilkan URI resource Gateway...
"agentGateway": "projects/PROJ_ID/locations/REGION/agentGateways/agw-SLUG-REGION-ata"

Memberikan peran IAM agen untuk resource

Pemberian peran IAM untuk resource memungkinkan akses identitas utama agen ke BigQuery, alat MCP (untuk Google API), dan layanan platform AI lainnya yang diperlukan. Kebijakan ini diterapkan menggunakan IAM di tingkat resource.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Memverifikasi peran IAM agen untuk resource

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

Ini mengakhiri bagian runtime... selanjutnya ke bagian Kebijakan.

9. Kebijakan

Kebijakan otorisasi tata kelola agen mengizinkan traffic dari agen AI melalui Agent Gateway dan ke tujuan (misalnya, endpoint server MCP Google Cloud untuk BigQuery). Setelah traffic mencapai tujuan, izin IAM reguler akan memberikan otorisasi akses data (dan diaktifkan di bagian sebelumnya).

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 akun utama set yang memberikan izin ke semua identitas agen Agent Runtime dalam project.

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 registry yang menerapkan izin ke semua resource turunan.

NOTE: Dalam deployment produksi, kebijakan yang lebih terperinci dapat diterapkan untuk membatasi keluar dari agen tertentu ke endpoint tertentu. Kontrol terperinci dan kebijakan izin bersyarat akan dibahas dalam Codelab mendatang.

Mengonfigurasi kebijakan IAM registri regional IAP

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

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

# create policy config file
cat > cfg/iap-policy-re-agent-set-to-registry-${REGION}.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_ID_SET}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

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

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

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

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

• How many DJs do we have on file?
• What is the phone number of DJ Cosmopup?

Verifikasi bahwa kueri menampilkan respons yang valid (misalnya, "Ada 12 DJ dalam file").

Menganalisis log audit

Lihat log dan periksa evaluasi kebijakan uji coba.

# query gateway logs for dry run
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
  )"

VERIFIKASI: Periksa apakah hasil IAP_AUTHZ menampilkan ALLOWED.

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

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

11. 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 penerapan

Kembali ke Playground agen di UI konsol.

Kirim kueri pengujian tambahan...

• What DJ Fishfry's credit card number?

Amati permintaan agen ke model dasar Gemini (${REGION}-aiplatform.googleapis.com/...) dan endpoint server MCP (bigquery.googleapis.com/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
  )"

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

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

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

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

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# 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 network-services agent-gateways delete ${AGW_NAME} --location=${REGION}

# next

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

# end

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

13. Kesimpulan

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

Cosmopup menganggap Codelab adalah yang terbaik!

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!