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

Agent Runtime'dan Google MCP'ye Agent Gateway çıkışı

1. Giriş

Bu Codelab'de, uzak Google Cloud Model Context Protocol (MCP) sunucularına erişen yapay zeka ajanları için Agent Gateway çıkış yönetimi incelenmektedir.

Bağımsız chatbot'lardan çoklu ajan iş akışlarına sahip otonom sistemlere kadar yapay zeka uygulamaları, harici araçları dinamik olarak çağırabilir. Ajanlara veritabanlarını sorgulama, web içeriğini getirme ve işlemleri yürütme konusunda kontrollü erişim sağlamak, güvenli ve verimli ajanlar için çok önemlidir. Ancak kurumsal ortamlarda aracı araç yürütme işleminin güvenliğini sağlamak zordur. Bir aracının doğrudan ağ erişimi varsa istem enjeksiyonu saldırıları veya model halüsinasyonları, aracının hassas verileri sızdırmasına ya da yıkıcı komutlar çalıştırmasına neden olabilir.

Agent Gateway, özerk aracıları geniş ölçekte yönetmek için doğrudan Agent Platform mimarisine entegre edilmiş merkezi bir sıfır güven zorlama noktası sağlar. Agent Gateway, her uygulamaya veya aracı koduna özgü özel uygulamalara güvenmek yerine platform düzeyinde uygulanan ağ yönlendirme, aracı yönetimi ve çalışma zamanı güvenliği sağlar.

Agent Gateway, çıkış (agent-to-anywhere) modunda çalıştığında, ağ geçidini kullanacak şekilde yapılandırılmış aracıların tüm giden isteklerini proxy'ler. Her aracı iş yükü isteğinin kimliği, benzersiz Aracı Kimliği kullanılarak doğrulanır ve Identity-Aware Proxy (IAP) politikaları kullanılarak yetkilendirilir. MCP aracı çağrıları, politika yaptırımı için dinamik olarak kod çözülür ve incelenir. Güvenlik yöneticileri, aracıların yalnızca onaylanmış uç noktaları ve yöntemleri çağırabilmesini sağlamak için ayrıntılı izinleri merkezi olarak zorunlu kılabilir.

Ne oluşturacaksınız?

Çıkışta (agent-to-anywhere) Agent Gateway
Identity-Aware Proxy (IAP) yetkilendirme uzantısı
Ajan kimliğine sahip Agent Runtime ADK aracısı
Google API ve MCP uç noktalarıyla Agent Registry
IAM erişim denetimi ile yetkilendirme politikaları
MCP ile sorgulanacak BigQuery veri kümesi

Şek. 1. Codelab mimarisi

Öğrenecekleriniz

Agent Gateway'i yapılandırılmış bir yapılandırma sırasıyla dağıtma
Yetkilendirme politikalarını prova modundan zorunlu moda geçirme
Google API uç noktalarını ve MCP sunucularını Agent Registry'ye kaydetme
Çıkış yönetimi doğrulamak için aracı ağ geçidi günlükleri nasıl denetlenir?

İhtiyacınız olanlar

Faturalandırmanın etkin olduğu bir Google Cloud projesi
Ağ hizmetleri, BigQuery veri kümeleri ve Agent Platform kaynaklarını sağlama için IAM izinleri
Google Cloud KSA'nın (gcloud ve bq bileşenleri) yüklü olduğu POSIX uyumlu bir kabuk (bash veya zsh)
Komut satırı araçları: git, curl, jq (JSON işlemcisi), Python 3 ve uv (Python paket yöneticisi)

2. Kavramlar

Dağıtım sırası

Yönetim kontrolleriyle birlikte Agent Gateway'i dağıtırken, başlatma sırasında aracıların gerekli kaynaklara erişebilmesi ve ağ isteklerinin başarılı olması için yapılandırılmış bir yapılandırma sırası izlemek önemlidir.

Bu Codelab'de aşağıdaki dağıtım sırası kullanılır:

Prova modunda başlatma: Bir aracı çalışma zamanı, giden aramaları ağ geçidi tam olarak temel hazırlığı yapılmadan önce ağ geçidine yönlendirecek şekilde yapılandırılırsa iş yükü başlatılamaz. Ağ geçidi yetkilendirme uzantısını önce DRY_RUN modunda yapılandırmak, aracı trafiği ağ geçidine ulaştığında hiçbir isteğin bırakılmamasını sağlar.
Tüm hizmetleri kaydedin: Agent Gateway'i kullanan tüm aracıların, MCP sunucularının ve uç noktaların Agent Registry'ye kaydedilmesi gerekir. Kayıtlı olmayan kaynaklar veya hedefler için istekler reddedilir. Agent Runtime ve Google MCP sunucularına dağıtılan aracıların kaydı otomatik olarak yapılır. Tüm Google API uç noktaları veya özel MCP sunucuları manuel olarak kaydedilmelidir.
Yetkilendirme politikalarını zorunlu kılma: Yetkilendirme politikaları, kayıtlı aracıların aracı bileşenlerine erişmesine izin vermek için kullanılır. Bu amaçla, aracı kimliği asıl sorumlusuna roles/iap.egressor rolü verilir ve bu rol hedef kayıt kaynağına bağlanır. Test moduyla aracı davranışını değerlendirin ve ardından seçilen çıkış trafiğinin ağ geçidinden geçmesine izin verecek politikalar tanımlayın. Politikalar uygulandıktan sonra, ağ geçidinin yönetim politikalarını etkin bir şekilde zorunlu kılmasını sağlamak için ENFORCED moduna geçin.

Şekil 2. Dağıtım sırası

Çıkış yönlendirme topolojisi

Ağ geçitleri genellikle arka uç hizmetlerine gelen trafiği (giriş) yönetir. Çıkış (agent-to-anywhere) modunda çalışan Agent Gateway, agent tabanlı iş yükleri için merkezi bir sıfır güven çıkış proxy'si olarak işlev görür.

Bir yapay zeka uygulaması veya temsilci tabanlı iş yükü harici bir aracı ya da API'yi çağırmaya çalıştığında giden istek, Agent Gateway tarafından yakalanır ve hedefine yönlendirilmeden önce yönetim politikalarına göre değerlendirilir:

Özel ağlar (VPC): Şirket içi API'leri, mikro hizmetleri, özel VPC'lerde barındırılan veritabanlarını ve karma bağlantı üzerinden erişilebilen şirket içi veya bulutlar arası ağları hedefleyen giden trafik.
Harici ağlar (İnternet): Üçüncü taraf web hizmetlerini, SaaS API'lerini veya herkese açık uç noktaları hedefleyen giden trafik.
Yapay zeka hizmetleri ve aracı platformu: Yönetilen Google Cloud API'lerini, temel modelleri, Google MCP uç noktalarını (ör. BigQuery) ve platform yönetimi hizmetlerini (aracı kayıt defteri ve IAP politikaları) hedefleyen giden trafik.

Şekil 3. Agent Gateway çıkış yönlendirme topolojisi

Bu codelab'in odak noktası, Agent Runtime'da özel bir aracıdan BigQuery için uzak Google MCP sunucusu uç noktasını hedefleyen giden trafiktir.

3. Kurulum

Gerekli IAM rolleri

Bu Codelab'deki kaynakları oluşturmak için aşağıdaki roller gereklidir:

Kategori	Gerekli IAM rolü (kimlik)	Açıklama
API yönetimi	`roles/serviceusage.serviceUsageAdmin`	Google Cloud API hizmetlerini etkinleştirme
Ağ ve ağ geçidi	`roles/networkservices.admin`	Agent Gateway'i sağlama
Hizmet uzantıları	`roles/serviceextensions.admin`	Yönlendirme uzantılarını yapılandırma
Ağ güvenliği	`roles/networksecurity.admin`	Yetkilendirme politikalarını dağıtma
Agent Registry	`roles/agentregistry.admin`	Katalog için izin verilen ana makineler
Vertex AI ve temsilciler	`roles/aiplatform.admin`	Agent Runtime iş yüklerini dağıtma
Çıkış politikaları	`roles/iap.admin`	`roles/iap.egressor` politikalarını uygulama
BigQuery	`roles/bigquery.admin`	Şemaları ayarlama ve veri kümelerini test etme
Cloud Storage	`roles/storage.admin`	Dağıtım hazırlama paketlerini yönetme
Günlükler ve denetleme	`roles/logging.viewer`	İzleri ve denetleme günlüklerini inceleme

Alternatif olarak, roles/admin gibi geniş kapsamlı bir temel rol veya roles/owner gibi eski bir rol kullanın.

Projenize erişme

Bu Codelab'de tek bir Google Cloud projesi kullanılır. Yapılandırma adımlarında gcloud KSA'sı ve Linux kabuk komutları kullanılır.

Google Cloud projenizin komut satırına erişerek başlayın:

shell.cloud.google.com adresindeki Cloud Shell veya
gcloud KSA'nın yüklü olduğu yerel bir terminal

Proje kimliğinizi ayarlama

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Oturumun kimliğini doğrulama

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Kabuk ortamı değişkenlerini ayarlama

# 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

API hizmetlerini etkinleştirme

# 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

Kurulum bölümünün sonuna geldik. Şimdi Ağ Geçidi bölümüne geçiyoruz.

4. Ağ geçidi

Erişim kontrollerini zorunlu kılmadan önce Agent Gateway'i dağıtın ve yetkilendirme uzantısını DRY_RUN modunda yapılandırın. Bu, giden araç çağrılarının başarılı olmasına olanak tanırken denetim amacıyla değerlendirme sonuçlarını da kaydeder.

Burada Agent Gateway, bölgesel Agent Runtime kaynaklarını desteklemek için bölgesel bir kayıt defteri kullanır.

Ağ geçidi oluştur

# 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}

Ağ geçidi bölümünü tamamladık. Şimdi Yetkilendirme bölümüne geçiyoruz.

5. Yetkilendirme

Identity-Aware Proxy (IAP) için Agent Gateway yetkilendirme uzantısı, tüm Agent Platform iletişimleri için yetkilendirme kararlarını temsilciye devretmek üzere kullanılan bir hizmet uzantısı türüdür.

Yetkilendirme akışı: Bir aracı, harici bir uç noktayı veya MCP sunucusunu çağırmaya çalıştığında isteği Agent Gateway'e yönlendirir. Ağ geçidi, erişimi yerel olarak değerlendirmek yerine yetkilendirme uzantısını kullanarak IAP değerlendirme hizmetine bir açıklama metni gönderir. IAP, temsilci (SPIFFE tabanlı) kimliğini, Temsilci Kayıt Defteri'ndeki hedef kaynağın IAM politikasına göre değerlendirir. IAP, ağ geçidine ALLOW veya DENY kararı döndürür. Ağ geçidi, trafiği iletir ya da HTTP 403 Forbidden durum koduyla engeller.
Zorunlu kılma modları: DRY_RUN modunda IAP, istekleri değerlendirir ve trafiği engellemeden kararları Cloud Logging'e kaydeder. ENFORCE modunda, yetkisiz bir aracıdan gelen veya kayıtlı olmayan bir hedefe yönelik tüm istekler anında engellenir.
Bağlama katmanı: Hizmet uzantısı, REQUEST_AUTHZ profiliyle yapılandırılmış bir yetkilendirme politikası kullanılarak Agent Gateway'e bağlanır.

Yetkilendirme uzantısı

Yetkilendirme uzantısı oluşturma

# 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}

Yetkilendirme politikası

Yetkilendirme politikası, güvenlik sağlayıcıyı (IAP) hedef ağ geçidi kaynağına bağlar ve yakalama profilini (REQUEST_AUTHZ) belirtir.

Yetkilendirme politikası oluşturma

# 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}

Yetkilendirme bölümünü tamamladık. Şimdi Kod Tabanı bölümüne geçiyoruz.

6. Kod tabanı

Bu Codelab'de kullanılan aracı kodu, BigQuery veri kümesi ve kayıt komut dosyası uzak bir Google Cloud GitHub deposunda tutulur. Aşağıdaki adımlarda, depo yerel olarak klonlanır, gerekli dosyalar mevcut çalışma dizini yapısına kopyalanır ve ardından gereksiz geçici dosyalar temizlenir.

Agent Runtime'ın paketlenmiş aracı uygulama kodunu ve bağımlılık yapılarını yüklemesi, oluşturması ve dağıtması için bir depolama hazırlama paketi oluşturulur.

Uzak yapıları getirme

# 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

BigQuery veri kümesi oluşturma

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

Hazırlık paketi oluşturma

# 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)"

Kod tabanı bölümünü tamamladık. Şimdi Kayıt Defteri bölümüne geçiyoruz.

7. Kayıt otoritesi

Agent Registry, yapay zeka ekosistemindeki tüm aracıların, MCP sunucularının ve uç noktaların (API'ler) merkezi bir envanteridir. Ayrıca, yapay zeka uygulamalarının kullanabileceği diğer kayıtlı araç ve hizmetleri listelemek, aramak ve keşfetmek için kullanılabilecek bir katalogdur. Aracı Ağ Geçidi çıkış (agent-to-anywhere) modu, çıkış erişim denetimini zorunlu kılmak için kayıt veri modelini yönetim çerçevesi olarak kullanır. Arayan aracı için IAM rolü izinleri, kayıt kaynağına bağlı politika ile karşılaştırılarak kontrol edilir.

Ortamı başlatmak ve çeşitli Google API'leri ve Hizmetleri'ni kullanan aracıları desteklemek için endpoints/googleapis.txt'daki ana makine adlarını ve konumları kullanarak ortak bir API uç noktaları grubunu hızlıca kaydetmek için bir komut dosyası kullanılır.

Uç noktaları kaydetme

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

Uç noktaları doğrulama

# 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)"

Kayıt defteri bölümünü tamamladık. Şimdi Çalışma Zamanı bölümüne geçiyoruz.

8. Çalışma zamanı

Agent Runtime'a dağıtılan agent-dj ADK aracısı, Agent Platform ile entegrasyon için dağıtım komut dosyasında aşağıdaki ayarlarla yapılandırılır:

"identity_type": types.IdentityType.AGENT_IDENTITY, aracı için SPIFFE tabanlı benzersiz bir asıl kimlik sağlamak üzere
Giden tüm aracı tarafından başlatılan trafiği politika değerlendirmesi ve yaptırımı için aracı ağ geçidine yönlendirmek üzere "agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } }

Ajanı dağıtma

# 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

Dağıtım önemli verilerini getirme

# 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}

Kayıt defteri girişini doğrulama

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

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'

Ağ geçidi yapılandırmasını doğrulama

# 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}'

Kaynaklar için aracı IAM rolleri verme

Kaynaklar için IAM rolü izinleri, aracı asıl kimliğinin BigQuery, MCP araçları (Google API'leri için) ve diğer gerekli yapay zeka platformu hizmetlerine erişmesini sağlar. Bu politikalar, kaynak düzeyinde IAM kullanılarak uygulanır.

# 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"

Kaynaklar için aracı IAM rollerini doğrulama

# 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)"

Çalışma zamanı bölümünü tamamladık. Şimdi Politikalar bölümüne geçiyoruz.

9. Politikalar

Aracı yönetimi yetkilendirme politikaları, bir yapay zeka aracısından gelen trafiğin Aracı Ağ Geçidi üzerinden ve hedefe (ör. BigQuery için Google Cloud MCP sunucu uç noktası) ulaşmasına izin verir. Trafik hedefe ulaştığında, normal IAM izinleri veri erişimini yetkilendirir (ve önceki bölümde etkinleştirilmiştir).

Agent Gateway çıkışı için IAM rolü verme, aracı asıl kimliğinin Agent Gateway üzerinden kayıtlı hedef kaynaklara erişmesine izin veren erişim politikalarını etkinleştirir. Politikalar, aracı ağ geçidi düzeyinde uygulanır ve Identity-Aware Proxy (IAP) IAM politikaları kullanılarak doğrulanır.

Agent Gateway çıkışı için aracıya IAM rolleri verme

Agent Gateway, gelen istekleri kontrol ederek arayan aracının kimliğinin hedef kaynakta iap.webServiceVersions.egressViaIAP iznine (roles/iap.egressor rolü tarafından verilir) sahip olduğunu doğrular.

Seçilen hedef kaynakta ajan kimliğine veya Agent Runtime asıl kümesine roles/iap.egressor izni verilmesi, bu çıkış trafiğine izin verir. Bu codelab'de rol, projede tüm Agent Runtime aracı kimliklerine izin veren set ana hesabına uygulanır.

IAM politikaları, Agent Registry veri modelinde tanımlandığı şekilde hedef kaynaklara bağlıdır. iap_web/agentRegistry kaynağı, IAM hiyerarşisinde "kayıt genelinde" bir düzeyi temsil eder. Burada agentRegistry, agents, mcpServers ve endpoints için ayrı ayrı alt kaynakların üst öğesi olarak kullanılır. Bu codelab'de IAM politikası, izni tüm alt kaynaklara uygulayan kayıt defteri düzeyine bağlıdır.

IAP bölgesel kayıt defteri IAM politikasını yapılandırma

# 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}

Politikalar bölümümüzün sonuna geldik. Şimdi Denetim bölümüne geçiyoruz.

10. Denetim

Agent Gateway yetkilendirme uzantısı DRY_RUN modunda çalışıyor. Giden istekler gözlemlenir ve günlüğe kaydedilir ancak engellenmez.

Test temsilcisi sorguları

Google Cloud Console kullanıcı arayüzü için bir tarayıcı penceresi açın ve şuraya gidin:

Agent Platform → Agents → Deployments → agent-dj
Playground sekmesini seçin.

Alternatif olarak, bu terminal komutunu tekrarlayın ve bağlantıyı tıklayarak aracı deneme alanına gidin:

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

Bazı test sorguları gönderin....

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

Sorguların geçerli yanıtlar döndürdüğünü doğrulayın (ör. "Dosyada 12 DJ var").

Denetleme günlüklerini analiz etme

Günlükleri görüntüleyin ve deneme amaçlı politika değerlendirmelerini inceleyin.

# 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
  )"

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

Denetim bölümümüzün sonuna geldik. Şimdi Uygulama bölümüne geçiyoruz.

11. Zorunlu kıl

Aracı, DRY_RUN modunda ağ geçidi üzerinden başarılı istekler gönderebildi. Yetkilendirme politikasını güncelleyerek Agent Gateway IAP yetkilendirme uzantısını ENFORCE moduna geçirin.

Yetkilendirme uzantısını güncelleme

# 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}

Yetkilendirme politikasını güncelleme

# 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}

Politika uygulamasını doğrulama

Konsol kullanıcı arayüzünde aracı Playground'a geri dönün.

Ek bir test sorgusu gönderin...

What DJ Fishfry's credit card number?

Gemini temel modeline (${REGION}-aiplatform.googleapis.com/...) ve MCP sunucusu uç noktasına (bigquery.googleapis.com/mcp) yapılan aracı isteklerinin HTTP 200 OK durum kodlarıyla iletildiğini gözlemleyin.

# 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)"

Engellenen istek olup olmadığını kontrol edin. Ağ geçidi denetleme günlüklerinde HTTP 403 Forbidden durum kodlarıyla reddedilen çıkış girişimlerini arayın.

# 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
  )"

Yaptırım bölümünü tamamladık. Şimdi Temizleme bölümüne geçiyoruz.

12. Temizleme

# 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

Temizleme bölümümüzü tamamladık. Şimdi Sonuç bölümüne geçiyoruz.

13. Sonuç

Tebrikler! Agent Gateway'i kullanarak araçlara erişen bir aracı için giden iletişimi başarıyla dağıttınız ve yönetiyorsunuz.

cosmopup

Cosmopup, Codelab'lerin en iyisi olduğunu düşünüyor.

Sırada ne var?

Gelişmiş özellikler ve eğitimler için Gemini Enterprise Agent Platform belgelerine göz atın.
Ek yapay zeka güvenliği için Agent Gateway'de Model Armor korumalarını yapılandırma
Doğal dil sorgularında işletme kurallarını ve uygunluğu zorunlu kılmak için Anlamsal Yönetim Politikaları'nı inceleyin.

Bu geri bildirim formunu kullanarak yorum, soru veya düzeltme önerilerinizi paylaşabilirsiniz.

Teşekkürler!