Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Ingress Agent Gateway ke Agent Runtime dengan Model Armor

1. Pengantar

Codelab ini membahas tata kelola ingress Agent Gateway untuk agen AI yang dihosting di Agent Runtime.

Agent Gateway yang beroperasi dalam mode ingress (client-to-agent) mendukung pengaturan komunikasi antara klien–pengguna akhir manusia, agen desktop, IDE coding, agen peer, dll.–dan agen yang dihosting Agent Runtime. Mode ini digunakan untuk melindungi agen dari serangan injeksi perintah masuk atau konten berbahaya yang dikirim oleh klien. Semua traffic masuk diproses menggunakan ekstensi otorisasi dan Model Armor untuk mengamankan titik masuk jaringan untuk semua interaksi agen.

Yang Anda bangun

Agent Gateway dalam mode ingress (client-to-agent)
Ekstensi otorisasi Model Armor
Agen ADK Agent Runtime dengan identitas agen
Data file Cloud Storage yang dikueri oleh agen menggunakan MCP
Template Model Armor untuk menyaring perintah dan respons LLM
Template Sensitive Data Protection untuk melakukan de-identifikasi data

Gambar 1. Arsitektur codelab

Yang Anda pelajari

Cara men-deploy Agent Gateway untuk menyaring traffic masuk ke agen
Cara mengonfigurasi ekstensi dan delegasi otorisasi Model Armor
Cara membuat dan men-deploy template Model Armor kustom
Cara membuat dan men-deploy template Sensitive Data Protection kustom
Cara menguji dan memvalidasi kebijakan penyaringan LLM

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) terinstal
Alat command line: git, curl, jq (pemroses JSON), Python 3, dan uv (pengelola paket Python)

2. Konsep

Peran arah lalu lintas dan gateway

Agent Gateway berfungsi sebagai proxy jaringan yang mendukung agen, tetapi peran operasionalnya berubah bergantung pada arah traffic:

Mode agent-to-anywhere (keluar): berfungsi sebagai proxy keluar. Saat agen memanggil alat database eksternal, server MCP pihak ketiga, atau API, gateway egress mengelola penemuan layanan, perutean, TLS bersama (mTLS), penyisipan kredensial OAuth dinamis, dan kontrol akses ke endpoint.
Mode client-to-agent (ingress): berfungsi sebagai gateway keamanan frontend. Tujuan utamanya adalah melindungi pintu masuk ke runtime eksekusi agen dengan mencegat dan membersihkan perintah bahasa alami yang masuk sebelum mencapai kode agen atau model AI.

Jalur ingress ke Agent Runtime

Permintaan klien yang menargetkan agen yang dihosting di Agent Runtime ditujukan untuk endpoint API aiplatform.googleapis.com.

POST https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query

Aliran komunikasi masuk ke endpoint API ini mewakili jalur masuk klien-ke-agen.

Untuk mengamankan jalur ingress yang dikelola Google ini, Agent Gateway terintegrasi langsung dengan Google Front End (GFE) di lapisan infrastruktur penayangan API. Saat men-deploy agen terkelola ke Agent Runtime, Google secara native mengikat kebijakan otorisasi gateway ingress ke permintaan klien yang masuk di edge jaringan.

Gambar 2. Tata kelola ingress dengan Agent Gateway ke Agent Runtime

Karena inspeksi terjadi di tingkat frontend sebelum permintaan memasuki Agent Runtime, arsitektur ini tidak menimbulkan overhead jaringan tambahan atau latensi hop internal. Penskalaan ditangani secara otomatis oleh infrastruktur frontend, sehingga Anda tidak perlu mengelola rentang IP internal, load balancer, atau rute DNS kustom.

Sanitasi ancaman inline dengan Model Armor

Mengevaluasi kredensial pemanggil dan menerapkan kontrol akses IAM (roles/aiplatform.user) ditangani secara native oleh tingkat hosting API aiplatform. Gateway ingress itu sendiri tidak melakukan otorisasi identitas, tetapi berfokus pada keamanan konten menggunakan ekstensi otorisasi yang dikonfigurasi dengan profil CONTENT_AUTHZ. Gateway bertindak sebagai titik penerapan kebijakan inline, yang mencegat perintah bahasa alami dalam transit sebelum mencapai reasoning loop agen AI atau LLM yang mendasarinya.

Saat perintah pengguna yang masuk tiba di layanan frontend, gateway akan memulai callout ext_proc (pemrosesan eksternal) ke layanan ekstensi otorisasi Model Armor regional, yang melakukan streaming panggilan ke dataplane Model Armor. Model Armor berfungsi sebagai firewall bahasa alami, yang mengevaluasi teks berdasarkan template aktif untuk memindai risiko keamanan dan keselamatan:

Upaya injeksi perintah tidak langsung dan jailbreak
URL berbahaya, bahasa yang tidak sopan, atau konten yang tidak aman
Kebocoran data sensitif dan informasi identitas pribadi (PII)

Jika template menyertakan filter Sensitive Data Protection (SDP), Model Armor akan melakukan panggilan gRPC tambahan ke layanan SDP Cloud. SDP Cloud memeriksa payload menggunakan template yang ditentukan, melakukan de-identifikasi atau penyamaran yang diminta, dan menampilkan hasil yang sudah dibersihkan kembali ke rantai untuk diteruskan dengan aman.

Jika pelanggaran kebijakan atau kecocokan data sensitif yang tidak disamarkan terdeteksi, gateway akan memblokir atau menyamarkan payload di edge sebelum memasuki runtime. Akibatnya, aplikasi agen AI yang sedang berjalan tetap terlindungi dan tidak pernah memproses payload berbahaya atau yang tidak disunting.

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
Sensitive Data Protection	`roles/dlp.admin`	Mengelola template inspeksi dan de-identifikasi SDP
Model Armor	`roles/modelarmor.admin`	Membuat dan mengelola template keselamatan
Agent Platform	`roles/aiplatform.admin`	Men-deploy workload Agent Runtime
Cloud Storage	`roles/storage.admin`	Mengelola bucket data pelanggan dan deployment
Administrasi IAM	`roles/resourcemanager.projectIamAdmin`	Mengikat izin tingkat project untuk identitas agen
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"
echo ${SLUG}
echo ${REGION}

# 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)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-cta"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-crm"
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 DATA_BUCKET="customer-data-${PROJ_NO}"
export MCP_URL="https://storage.mtls.googleapis.com/storage/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${DATA_BUCKET}
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

# enable google apis (all the rest)
gcloud services enable \
  dlp.googleapis.com

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

4. Gateway

Deploy Agent Gateway yang dikelola Google yang beroperasi dalam mode client-to-agent (CLIENT_TO_AGENT). Tidak seperti gateway keluar yang memerlukan asosiasi Agent Registry untuk merutekan panggilan keluar, gateway masuk terikat langsung di tingkat frontend untuk berfungsi sebagai titik penerapan inline untuk perintah masuk yang menargetkan Agent Runtime.

Meskipun kebijakan egress sering kali dimulai dalam mode DRY_RUN di lapisan gateway, tata kelola konten ingress (CONTENT_AUTHZ) di-deploy langsung dalam mode diterapkan. Logging hanya audit terperinci atau pemblokiran aktif dikontrol di hulu dalam setiap template Model Armor.

Buat gateway

# create agent gateway config file
cat > cfg/${AGW_NAME}.yaml <<EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: CLIENT_TO_AGENT
EOF

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

Verifikasi gateway

# list agent gateways (in region)
gcloud network-services agent-gateways list --location=${REGION}

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

Bagian gateway telah selesai... selanjutnya kita akan membahas bagian Model Armor.

5. Model Armor

Template SDP

Buat template pemeriksaan dan de-identifikasi Sensitive Data Protection (SDP) yang akan digunakan dalam template respons Model Armor. Konfigurasi ini menandai Nomor Jaminan Sosial (SSN) AS untuk disamarkan.

Buat template pemeriksaan

Template pemeriksaan mengidentifikasi informasi sensitif (US_SOCIAL_SECURITY_NUMBER) dalam data.

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

Membuat template de-identifikasi

Template de-identifikasi menentukan transformasi yang akan diterapkan pada SSN yang ditemukan oleh template pemeriksaan. Dalam hal ini, transformasi adalah mengganti SSN dengan jenis info.

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

Memverifikasi template SDP

# get (describe) inspect template
curl -fsS -X GET "https://dlp.googleapis.com/v2/projects/${PROJ_ID}/locations/${REGION}/inspectTemplates" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "x-goog-user-project: ${PROJ_ID}" | jq

# get (describe) de-identify template
curl -fsS -X GET "https://dlp.googleapis.com/v2/projects/${PROJ_ID}/locations/${REGION}/deidentifyTemplates" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "x-goog-user-project: ${PROJ_ID}" | jq

Template Model Armor

Endpoint default untuk Model Armor API bersifat global (modelarmor.googleapis.com). Namun, resource Model Armor untuk template dan mesin evaluasi dilokalkan ke wilayah geografis tertentu. Endpoint Proxy Regional Google Cloud (REP), atau endpoint API regional, untuk Model Armor adalah https://modelarmor.${LOCATION}.rep.googleapis.com/.

Secara default, saat menjalankan gcloud model-armor ..., CLI akan mencoba mengirim permintaan API ke endpoint global standar (https://modelarmor.googleapis.com/). Penggantian endpoint API digunakan untuk mengalihkan semua permintaan HTTP SDK/CLI untuk Model Armor langsung ke tingkat API rep.googleapis.com regional tempat template terikat lokasi tersebut dibuat, disimpan, dan dikueri.

Menetapkan penggantian API

# set api endpoint override per location
gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.${REGION}.rep.googleapis.com/"

Memverifikasi penggantian API

# view api overrides on active gcloud config
gcloud config list api_endpoint_overrides/

Membuat template filter permintaan

Buat template filter permintaan untuk memblokir ujaran kebencian, pelecehan, konten seksual vulgar, dan serangan injeksi URI. Logging akan diaktifkan untuk merekam informasi peristiwa mendetail tentang penegakan kebijakan. Kode dan pesan error kustom juga dikonfigurasi saat permintaan diblokir.

# create model armor template (request)
gcloud beta model-armor templates create ${AGW_NAME}-modar-req-template \
  --project=${PROJ_ID} \
  --location=${REGION} \
  --rai-settings-filters='[
    { "filterType": "HATE_SPEECH", "confidenceLevel": "MEDIUM_AND_ABOVE" },
    { "filterType": "HARASSMENT", "confidenceLevel": "MEDIUM_AND_ABOVE" },
    { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "MEDIUM_AND_ABOVE" }
  ]' \
  --pi-and-jailbreak-filter-settings-enforcement=enabled \
  --pi-and-jailbreak-filter-settings-confidence-level=medium-and-above \
  --template-metadata-enforcement-type=INSPECT_AND_BLOCK \
  --malicious-uri-filter-settings-enforcement=enabled \
  --template-metadata-custom-llm-response-safety-error-code=798 \
  --template-metadata-custom-llm-response-safety-error-message="ahoy! model response blocked by content filter :(" \
  --template-metadata-custom-prompt-safety-error-code=799 \
  --template-metadata-custom-prompt-safety-error-message="ahoy! the request was blocked by ye content filter... so rephrase the prompt and try again!" \
  --template-metadata-ignore-partial-invocation-failures \
  --template-metadata-log-operations \
  --template-metadata-log-sanitize-operations

Membuat template filter respons

Buat template filter respons untuk memblokir konten yang sama dengan template filter permintaan. DLP dikonfigurasi pada bagian respons untuk menyamarkan SSN untuk pesan yang dikembalikan ke klien dari agen.

# create model armor template (response)
gcloud beta model-armor templates create ${AGW_NAME}-modar-resp-template \
  --project=${PROJ_ID} \
  --location=${REGION} \
  --rai-settings-filters='[
      { "filterType": "HATE_SPEECH", "confidenceLevel": "MEDIUM_AND_ABOVE" },
      { "filterType": "HARASSMENT", "confidenceLevel": "MEDIUM_AND_ABOVE" },
      { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "MEDIUM_AND_ABOVE" }
  ]' \
  --malicious-uri-filter-settings-enforcement=enabled \
  --advanced-config-inspect-template=projects/${PROJ_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template \
  --advanced-config-deidentify-template=projects/${PROJ_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template \
  --template-metadata-enforcement-type=INSPECT_AND_BLOCK \
  --template-metadata-custom-llm-response-safety-error-code=798 \
  --template-metadata-custom-llm-response-safety-error-message="ahoy! model response blocked by content filter :(" \
  --template-metadata-custom-prompt-safety-error-code=799 \
  --template-metadata-custom-prompt-safety-error-message="ahoy! the request was blocked by ye content filter... so rephrase the prompt and try again!" \
  --template-metadata-ignore-partial-invocation-failures \
  --template-metadata-log-operations \
  --template-metadata-log-sanitize-operations

Memverifikasi template Model Armor

# list model armor templates
gcloud model-armor templates list --location=${REGION}

# show request filter template details
gcloud model-armor templates describe ${AGW_NAME}-modar-req-template --location=${REGION}

# show response filter template details
gcloud model-armor templates describe ${AGW_NAME}-modar-resp-template --location=${REGION}

Izin IAM

Model Armor melakukan panggilan API untuk memanggil layanan Sensitive Data Protection (SDP). Berikan izin IAM identitas layanan Model Armor untuk menggunakan template inspeksi dan de-identifikasi SDP.

Mengikat kebijakan IAM untuk Sensitive Data Protection

# grant dlp (sdp) user role to the model armor service identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-modelarmor.iam.gserviceaccount.com" \
  --role="roles/dlp.user"

Memverifikasi izin IAM

# show iam policy for all dlp (sdp) roles on project
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.role:roles/dlp" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Bagian Model Armor telah selesai... selanjutnya kita akan membahas bagian Otorisasi.

6. Otorisasi

Izin IAM

Untuk memeriksa traffic inline menggunakan Model Armor, agen layanan Ekstensi Layanan (DEP) memerlukan binding IAM eksplisit (bahkan di seluruh resource dalam project yang sama):

roles/modelarmor.calloutUser & roles/serviceusage.serviceUsageConsumer: Diberikan di project gateway untuk mengizinkan balon inspeksi inline.
roles/modelarmor.user: Diberikan di project template untuk mengizinkan akses dan evaluasi template Model Armor.

Mengikat kebijakan IAM untuk Model Armor

# grant model armor callout user role to dep (service extension) service agent
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/modelarmor.calloutUser"

# grant service usage consumer role to dep (service extension) service agent
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

# grant model armor user role to dep (service extension) service agent
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/modelarmor.user"

Memverifikasi izin IAM

# show iam policy on project for dep (service extension) service agent
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Ekstensi otorisasi

Konfigurasi ekstensi otorisasi untuk Agent Gateway menentukan setelan integrasi yang akan berlaku untuk traffic payload masuk dan keluar. Konfigurasi menentukan layanan pemrosesan eksternal (service) yang mereferensikan Model Armor API regional, dan ditautkan ke template permintaan dan respons tertentu menggunakan kolom metadata model_armor_settings.

Membuat ekstensi otorisasi

# create authz extension config file (enforced mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-modar.yaml <<EOF
name: ${AGW_NAME}-svc-ext-authz-modar
service: modelarmor.${REGION}.rep.googleapis.com
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/${PROJ_ID}/locations/${REGION}/templates/${AGW_NAME}-modar-req-template",
      "response_template_id": "projects/${PROJ_ID}/locations/${REGION}/templates/${AGW_NAME}-modar-resp-template"
    }
  ]'
failOpen: true
timeout: 5s
EOF

Impor ekstensi authz

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

Verifikasi ekstensi authz

# list authz extensions
gcloud service-extensions authz-extensions list --location=${REGION}

# show authz extension details
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-modar \
  --location=${REGION}

Kebijakan otorisasi

Kebijakan otorisasi menggunakan profil kebijakan untuk menentukan jenis evaluasi yang dilakukan. Meskipun profil berbasis permintaan (REQUEST_AUTHZ) mengevaluasi header HTTP, konfigurasi ini menggunakan profil otorisasi berbasis konten (CONTENT_AUTHZ) untuk mengikat ekstensi Model Armor ke gateway untuk pemeriksaan payload mendalam.

Membuat kebijakan otorisasi

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

Mengimpor kebijakan authz

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

Memverifikasi kebijakan authz

# list authz policies
gcloud beta network-security authz-policies list --location=${REGION}

# show authz policy details
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-modar \
  --location=${REGION}

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

7. Codebase

Kode agen dan data file 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.

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_ingress_modar

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_ingress_modar/codelabs/agw-cuj-arun-ingress-modar/agent-crm ./agent-crm

# remove temporary directory
rm -rf temp_agw_cuj_arun_ingress_modar

Bucket penyimpanan untuk penyiapan digunakan oleh Agent Runtime untuk mengupload, membangun, dan men-deploy kode aplikasi agen yang dipaketkan dan artefak dependensinya.

Membuat bucket penyimpanan untuk penyiapan

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

Memverifikasi bucket penyimpanan

# list storage buckets
gcloud storage buckets list --format="value(storage_url)"

Bagian codebase ini telah selesai... selanjutnya ke bagian Data Pelanggan GCS.

Data pelanggan

Buat bucket Cloud Storage untuk menyimpan data pelanggan. Agen akan membaca secara langsung menggunakan library klien Google Cloud standar yang memanggil endpoint MCP Cloud Storage.

Buat bucket penyimpanan untuk data pelanggan

# create storage bucket
gcloud storage buckets create gs://${DATA_BUCKET} --location=${REGION}

Memverifikasi bucket penyimpanan

# list storage buckets
gcloud storage buckets list --format="value(storage_url)"

Upload data pelanggan

# copy local data to bucket
gcloud storage cp -r ./agent-crm/data/* gs://${DATA_BUCKET}/

Memverifikasi data pelanggan

# list bucket objects
gcloud storage ls gs://${DATA_BUCKET}/ --long

Bagian Data Pelanggan GCS ini telah selesai... selanjutnya ke bagian agen ADK.

8. Agen ADK

Agen ADK agent-crm 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 principal berbasis SPIFFE yang unik untuk agen
"client_to_agent_config": {"agent_gateway": "${AGW_URI}"} untuk mengarahkan semua traffic masuk untuk agen ke jalur evaluasi dan penegakan kebijakan Agent Gateway

Agen juga meneruskan URL server mTLS MCP untuk server MCP Cloud Storage dan nama bucket data untuk memanggil alat MCP GCS melalui koneksi yang aman.

Men-deploy agen

# deploy agent
uv --directory agent-crm 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 customer data" \
  --mcp-server-url="${MCP_URL}" \
  --data-bucket=${DATA_BUCKET} \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-ingress=${AGW_URI} \
  --allow-token-sharing

Memverifikasi deployment

Mengambil tanda vital deployment

# fetch agent runtime (reasoning engine) resource 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 \
  --project=${PROJ_ID} --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

Verifikasi konfigurasi gateway

# show agent runtime config details (gateway config)
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}'

Izin IAM

Mengikat kebijakan IAM untuk identitas agen

# grant mcp tool user role to agent set (all agent runtime agents in project)
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_ID_SET}" \
  --role="roles/mcp.toolUser"

# grant storage object viewer role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/storage.objectViewer"

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

# grant cloudtrace agent role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/cloudtrace.agent"

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

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

# grant telemetry writer role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/telemetry.writer"

# grant service usage consumer role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/serviceusage.serviceUsageConsumer"

# grant browser role to agent identity
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Memverifikasi izin IAM

# show agent identity roles on project
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', 'principal://agents.[...]/locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

# show agent set roles on project
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_ID_SET}" \
  --format="table(bindings.members.sub('^.*platformContainer/', 'principalSet://agents.[...]/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Hal ini mengakhiri bagian agen ADK... selanjutnya ke bagian Test.

9. Uji

Mengirim kueri dari CLI

Menguji perintah yang aman

# post query to agent streamQuery
curl --no-buffer -s -X POST "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJ_ID}" \
  -d @- <<EOF | jq -r --unbuffered 'if type == "array" then .[] else . end | select(.content.parts != null) | .content.parts[].text // empty'
{
  "input": {
    "message": "what are the names of our west customers?",
    "user_id": "test-user"
  }
}
EOF

Akan melihat respons seperti... "Pelanggan kami di barat adalah: Bob Johnson dan Alice Brown."

Menguji pemicu penyamaran

# post query to agent streamQuery
curl --no-buffer -s -X POST "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJ_ID}" \
  -d @- <<EOF | jq -r --unbuffered 'if type == "array" then .[] else . end | select(.content.parts != null) | .content.parts[].text // empty'
{
  "input": {
    "message": "what are ssn's for bob johnson and alice brown?",
    "user_id": "test-user"
  }
}
EOF

Menguji perintah aman lainnya

# post query to agent streamQuery
curl --no-buffer -s -X POST "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" -H "X-Goog-User-Project: ${PROJ_ID}" \
  -d @- <<EOF | jq -r --unbuffered 'if type == "array" then .[] else . end | select(.content.parts != null) | .content.parts[].text // empty'
{
  "input": {
    "message": "what are bob johnson's and alice brown's email addresses?",
    "user_id": "test-user"
  }
}
EOF

Log audit

Melihat log rekaman aktivitas

Jika telemetri diaktifkan, Agent Runtime akan melakukan streaming peristiwa terstruktur yang merepresentasikan kueri pengguna, parameter alat, alur eksekusi, dan output pilihan model.

# show agent runtime (reasoning engine) telemetry and trace logs
gcloud logging read \
  "logName:\"projects/${PROJ_ID}/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout\" AND labels.managed-by=\"reasoning-engine\"" \
  --project=${PROJ_ID} \
  --limit=15 \
  --format="table(
    timestamp.date(format=\"%I:%M:%S %p\", tz=LOCAL):label=TIME,
    trace.basename().sub('^(.{8}).*$', '\\1'):label=TRACE_ID,
    labels.\"event.name\".scope(-1):label=EVENT,
    jsonPayload.content.role:label=ROLE,
    jsonPayload.content.parts[0].text:label=TEXT_CONTENT,
    jsonPayload.content.parts[0].function_call.name:label=TOOL_CALL
  )"

TRACE_ID mengelompokkan kueri pengguna, panggilan alat perantara, dan keputusan model bersama-sama ke dalam satu linimasa:

TIME         TRACE_ID  EVENT                  ROLE   TEXT_CONTENT                                     TOOL_CALL
HH:MM:SS PM  3070a1fd  gen_ai.choice          model  Bob Johnson's SSN is 219-45-7895.
                                                     Alice Brown's SSN is 219-45-7896.
HH:MM:SS PM  3070a1fd  gen_ai.user.message    user
HH:MM:SS PM  3070a1fd  gen_ai.user.message    model                                                   read_customer_file
HH:MM:SS PM  3070a1fd  gen_ai.user.message    user
HH:MM:SS PM  3070a1fd  gen_ai.user.message    model                                                   read_customer_file
HH:MM:SS PM  3070a1fd  gen_ai.user.message    user
HH:MM:SS PM  3070a1fd  gen_ai.user.message    model                                                   list_customer_files
HH:MM:SS PM  3070a1fd  gen_ai.user.message    user   what are ssn's for bob johnson and alice brown?
HH:MM:SS PM  3070a1fd  gen_ai.system.message
HH:MM:SS PM  3070a1fd  gen_ai.choice          model                                                   read_customer_file

Melihat log sanitasi Model Armor

Log ini menunjukkan ancaman inline dua arah real-time dan pembersihan yang dilakukan oleh Model Armor saat traffic mengalir melalui Agent Gateway.

# show model armor logs
gcloud logging read \
  "logName:\"projects/${PROJ_ID}/logs/modelarmor.googleapis.com%2Fsanitize_operations\"" \
  --project=${PROJ_ID} \
  --limit=50 \
  --format="table(
    timestamp.date(format=\"%I:%M:%S %p\", tz=LOCAL):label=TIME,
    jsonPayload.sanitizationResult.sanitizationVerdict:label=VERDICT,
    jsonPayload.sanitizationInput.byteItem.byteData.decode(base64).decode(utf-8).sub('\n', ' \\\\\\\\n ').trailoff(123):label=INPUT_DATA
  )"

Perhatikan entri log untuk permintaan yang dibersihkan dan diblokir.

TIME         VERDICT                                 INPUT_DATA
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  Bob Johnson's email address is bob.j@example.com. \n Alice Brown's email address is alice.b...
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  what are bob johnson's and alice brown's email addresses?
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_BLOCK  6��
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  what are ssn's for bob johnson and alice brown?
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  Our west customers are: Bob Johnson and Alice Brown.
HH:MM:SS PM  MODEL_ARMOR_SANITIZATION_VERDICT_ALLOW  what are the names of our west customers?

Ini mengakhiri bagian Test... selanjutnya ke bagian Cleanup.

10. Pembersihan

# remove agent iam bindings
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/storage.objectViewer"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/aiplatform.user"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/cloudtrace.agent"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/monitoring.metricWriter"

# next

# remove more agent and agent set iam bindings
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/logging.logWriter"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/telemetry.writer"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/serviceusage.serviceUsageConsumer"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_IDENTITY}" --role="roles/browser"

# next

# remove rest of iam bindings
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="${RE_AGENT_ID_SET}" --role="roles/mcp.toolUser"
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} --member="serviceAccount:service-${PROJ_NO}@gcp-sa-modelarmor.iam.gserviceaccount.com" --role="roles/dlp.user"

# next

# delete agent runtime (reasoning engine) 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)" \
  -H "Content-Type: application/json"

# next

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

# next

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

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

# next

# remove dep (service extensions) service agent iam bindings
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/modelarmor.calloutUser"

gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com" \
  --role="roles/modelarmor.user"

# next

# delete model armor templates
gcloud -q model-armor templates delete ${AGW_NAME}-modar-resp-template --location=${REGION}
gcloud -q model-armor templates delete ${AGW_NAME}-modar-req-template --location=${REGION}

# unset model armor api endpoint override
gcloud config unset api_endpoint_overrides/modelarmor

# next

# delete sdp (dlp) templates
curl -fsS -X DELETE "https://dlp.googleapis.com/v2/projects/${PROJ_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJ_ID}"

curl -fsS -X DELETE "https://dlp.googleapis.com/v2/projects/${PROJ_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: ${PROJ_ID}"

# next

# delete agent gateway ingress
gcloud -q network-services agent-gateways delete ${AGW_NAME} --location=${REGION} --async

# end

Ini mengakhiri bagian pembersihan... selanjutnya ke bagian Kesimpulan.

11. Kesimpulan

Selamat! Anda telah berhasil men-deploy Agent Gateway dan mengatur traffic masuk ke agen AI.

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!

Ingress Agent Gateway ke Agent Runtime dengan Model Armor

1. Pengantar

Yang Anda bangun

Yang Anda pelajari

Yang Anda perlukan

2. Konsep

Peran arah lalu lintas dan gateway

Jalur ingress ke Agent Runtime

Sanitasi ancaman inline dengan Model Armor

3. Penyiapan

Peran IAM yang diperlukan

Mengakses project Anda

Menetapkan Project ID

Mengautentikasi sesi

Menetapkan variabel lingkungan shell

Perbarui gcloud cli (direkomendasikan)

Mengaktifkan layanan API

4. Gateway

Buat gateway

Verifikasi gateway

5. Model Armor

Template SDP

Buat template pemeriksaan

Membuat template de-identifikasi

Memverifikasi template SDP

Template Model Armor

Menetapkan penggantian API

Memverifikasi penggantian API

Membuat template filter permintaan

Membuat template filter respons

Memverifikasi template Model Armor

Izin IAM

Mengikat kebijakan IAM untuk Sensitive Data Protection

Memverifikasi izin IAM

6. Otorisasi

Izin IAM

Mengikat kebijakan IAM untuk Model Armor

Memverifikasi izin IAM

Ekstensi otorisasi

Membuat ekstensi otorisasi

Impor ekstensi authz

Verifikasi ekstensi authz

Kebijakan otorisasi

Membuat kebijakan otorisasi

Mengimpor kebijakan authz

Memverifikasi kebijakan authz

7. Codebase

Mengambil artefak jarak jauh

Membuat bucket penyimpanan untuk penyiapan

Memverifikasi bucket penyimpanan

Data pelanggan

Buat bucket penyimpanan untuk data pelanggan

Memverifikasi bucket penyimpanan

Upload data pelanggan

Memverifikasi data pelanggan

8. Agen ADK

Men-deploy agen

Memverifikasi deployment

Mengambil tanda vital deployment

Verifikasi konfigurasi gateway

Izin IAM

Mengikat kebijakan IAM untuk identitas agen

Memverifikasi izin IAM

9. Uji

Mengirim kueri dari CLI

Menguji perintah yang aman

Menguji pemicu penyamaran

Menguji perintah aman lainnya

Log audit

Melihat log rekaman aktivitas

Melihat log sanitasi Model Armor

10. Pembersihan

11. Kesimpulan

Apa langkah selanjutnya?

Perbarui `gcloud cli` (direkomendasikan)