Agent Registry'yi kullanarak özel MCP sunucusuna Agent Gateway çıkışı olan Gemini Enterprise

1. Giriş

Bu codelab'de, agent-to-anywhere (çıkış) modunda Agent Gateway kullanılarak Gemini Enterprise için özel ve yönetilen çıkış bağlantısı ele alınmaktadır. Bir VPC ağındaki Google API'leri için bir PSC uç noktasına bağlanmak üzere Private Service Connect (PSC) arayüzlerini kullanarak trafiği Agent Gateway üzerinden yönlendirerek Cloud Run'da barındırılan özel bir Model Bağlam Protokolü (MCP) sunucusunu güvenli bir şekilde çağırmak için bir Gemini Enterprise uygulaması yapılandıracaksınız.

Bu laboratuvarda, Agent Registry'den bir MCP sunucu yapılandırması ve araç özellikleri içe aktararak Gemini Enterprise özel MCP veri deposu oluşturma işlemi gösterilmektedir.

Alternatif bir yaklaşım olarak, özel MCP veri deposunu doğrudan Gemini Enterprise uygulamasında yapılandırmak için Gemini Enterprise with Agent Gateway egress to private custom MCP server başlıklı Codelab'e bakın.

Kurumsal ortamlarda, bağımsız aracılara doğrudan ağ erişimi verilmesi veri hırsızlığına ve onaylanmamış araçların yürütülmesine yol açabilir. Agent Gateway, akışa alınabilir HTTP MCP aracı yüklerini dinamik olarak inceleyen merkezi ve platform düzeyinde bir sıfır güven zorunlu kılma noktası sağlar. Giden isteklerin kimliği, kriptografik olarak doğrulanabilir bir aracı kimliği ile doğrulanır ve Identity-Aware Proxy (IAP) aracılığıyla yetkilendirilir. Bu işlemde, Common Expression Language (CEL) kurallarıyla birlikte IAM Unified Access Policies (UAP) kullanılır. Bu sayede, arka uç iş yüklerini herkese açık internete maruz bırakmadan belirli MCP araçları ve yöntemleri üzerinde ayrıntılı erişim denetimi sağlanır.

Ne oluşturacaksınız?

• Agent Registry uç nokta doğrulaması ile çıkış (agent-to-anywhere) modunda çalışan Agent Gateway
• Agent Registry'de araç özellikleriyle kaydedilmiş, özel olarak yayınlanabilir bir HTTP MCP sunucusunu barındıran Cloud Run hizmeti (--ingress=internal)
• Agent Gateway için Identity-Aware Proxy (IAP) yetkilendirme uzantısı
• MCP aracı yetkilendirmesi için CEL koşulları içeren IAM Birleştirilmiş Erişim Politikaları (UAP)
• Agent Gateway'e bağlı ve Agent Registry'den içe aktarılan bir özel MCP sunucusu veri deposuna bağlı Gemini Enterprise uygulaması
• VPC ağı kaynakları, Cloud DNS bölgesi ve Google API'leri için PSC uç noktası
• Agent Gateway özel VPC çıkışı için PSC ağ eki
• VPC trafiğini güvenli hale getirmek için Cloud Next Generation Firewall (NGFW) politika kuralları

Şek. 1. Codelab mimarisi

Öğrenecekleriniz

• Cloud Run'da kaynaktan özel bir akışa aktarılabilir HTTP MCP sunucusu dağıtma ve uç noktasını ile araç şemasını Agent Registry'ye kaydetme
• Uygun kayıt defteri girişleriyle Agent Gateway'i yapılandırma ve Gemini Enterprise uygulama aracı çağrılarını ağ geçidi üzerinden yönlendirme
• PSC ağ eklerini ve arayüzlerini kullanarak özel VPC çıkışı oluşturma
• Aracı ağ geçidi yetkilendirmesini Identity-Aware Proxy'ye (IAP) nasıl devrederim?
• MCP aracının yürütülmesini kısıtlamak için destination.agent_registry.* ve destination.is_registered CEL özelliklerini kullanarak IAM Birleştirilmiş Erişim Politikaları (UAP) oluşturma ve bağlama
• Cloud Logging kullanarak politika yaptırımını ve ağ çıkışını doğrulama

İhtiyacınız olanlar

• Faturalandırmanın etkin olduğu bir Google Cloud projesi
• Etkin bir Gemini Enterprise lisansı veya 30 günlük deneme sürümü
• Ağ iletişimi hizmetleri, Gemini Enterprise ve Agent Platform kaynaklarını sağlama için IAM izinleri
• Google Cloud KSA (gcloud), curl ve jq yüklü bir POSIX uyumlu kabuk (bash veya zsh)

Giriş bölümünü tamamladık. Şimdi Kavramlar bölümüne geçiyoruz.

2. Kavramlar

Dağıtım sırası

Bu codelab, MCP araçlarını Gemini Enterprise'a kaydetmeden ve bağlamadan önce özel ağ yollarının ve yönetim kontrollerinin çalışır durumda olması için önce altyapıyı dağıtır:

1. Ağ altyapısı: VPC alt ağları, PSC uç noktası, PSC ağ eki, Cloud NGFW politika kuralları ve özel Cloud DNS bölgeleri sağlayın.
2. Agent Gateway: Agent Registry entegrasyonu (registries) ve özel VPC çıkışı (networkAttachment) ile Agent Gateway'i çıkış modunda dağıtın.
3. Yetkilendirme politikaları: destination.is_registered ve destination.agent_registry.* CEL koşullarını kullanarak IAP yetkilendirme uzantısını, Gateway Authz politikasını ve IAM Birleşik Erişim Politikası'nı (UAP) yapılandırın.
4. MCP sunucusunu dağıtma ve kaydetme: Kaynaktan Cloud Run'a matematik MCP sunucusunu dağıtın (--ingress=internal) ve hizmet ile araç spesifikasyonlarını (add ve subtract) Agent Registry'ye kaydedin.
5. Gemini Enterprise uygulaması: Gemini Enterprise uygulamasını oluşturun (Engine), kimlik ve gözlemlenebilirlik ayarlarını yapılandırın ve giden çıkışı Agent Gateway'e bağlayın (agentGatewaySetting).
6. Özel MCP veri bağlayıcısını içe aktarma: Kayıtlı MCP sunucusunun destekleyici veri deposunu Gemini Enterprise uygulamasına bağlamak için REGISTRY_MCP veri bağlayıcısını (:setUpDataConnector) oluşturun ve etkinleştirin.
7. Doğrulama: Sohbet sırasında izin verilen ve reddedilen araç yürütmelerini test edin ve Agent Gateway, DNS, güvenlik duvarı ve Cloud Run günlüklerinde politika uygulamasını doğrulayın.

Gemini Enterprise çıkışı

Gemini Enterprise, hem Engine üzerindeki agentGatewaySetting hem de DataConnector üzerindeki use_agent_gateway_egress: true yapılandırıldığında özel MCP sunucusu aracı isteklerini Agent Gateway'e yönlendirir.

Şekil 2. Gemini Enterprise çıkış mimarisi

Gemini Enterprise uygulaması, araç yönlendirmeyi dört temel alana göre düzenler:

1. Widget (default_search_widget_config):
   • Web istemcisi arayüzüne hizmet eder. Widget, kullanıcıdan istemler alır ve temel motorla sohbet oturumları başlatır.
2. Temel Asistan (assistants/default_assistant/agents/default/core_assistant):
   • Motordaki temel etkileşimli akıl yürütme ajanı. Temel Asistan, bir kullanıcı sorgusunu değerlendirirken aritmetik hesaplama gerekip gerekmediğini belirler, mevcut araçları inceler ve yürütme işlemini sentezlenmiş Agent Gateway alt aracısına devreder.
3. Veri Deposu ve Veri Bağlayıcı:
   • DataStore: :setUpDataConnector çalışırken özel bir Collection içinde sağlanan bu araç, içe aktarılan Agent Registry aracı şemalarını (add, subtract), bağımsız değişken türlerini ve aracı talimatlarını Gemini Enterprise'a (Engine) bağlar (dataStoreIds).
   • DataConnector: Uzak MCP sunucusuna (instance_uri) REGISTRY_MCP işlem bağlantısını (createBapConnection: true) yönetir, Agent Registry MCP sunucu kaynağını (registry_mcp_server_name) çözer ve Agent Gateway çıkışını (use_agent_gateway_egress: true) etkinleştirir.
4. Agent Identity, Agent Registry ve Agent Gateway:
   • Veri bağlayıcı, giden araç çağrısını gönderdiğinde trafiği agentGatewaySetting içinde belirtilen ağ geçidine yönlendirir. Core Assistant, kimliğini onaylayan bir SPIFFE kimlik jetonu oluşturur: principal://agents.global.org-.../agents/default/core_assistant.
   • Agent Gateway, hedef uç noktaları ve kayıtlı araç şemalarını dinamik olarak çözümlemek için registries alanını kullanarak Agent Registry ile entegre olur. destination.is_registered ve destination.agent_registry.* özelliklerini doldurur ve VPC ağına geçişe izin vermeden önce IAM Birleşik Erişim Politikası (UAP) CEL kurallarına göre değerlendirilmek üzere IAP v2'ye iletir.

Ağ geçidi VPC bağlantısı

Agent Gateway, iki YAML alanı kullanarak özel VPC ağı bağlantısını etkinleştirir:

• networkConfig.egress.networkAttachment: Özel IP trafiğinin, PSC ağ eki üzerinden VPC ağına yönlendirilmesini sağlar.
• dnsPeeringConfig.domains: Hedef ana makine adlarının (*.run.app) VPC ağında tanımlanan özel PSC uç noktası IP adresine çözümlenmesi için VPC ağı Cloud DNS bölgesiyle DNS çözümlemesi eşlemesi yapar.

Sınırlamalar ve şartlar

NOT: Gemini Enterprise, giden (agent-to-anywhere) çıkış için yalnızca Agent Gateway'i kullanır. Gelen (her yerden ajana) giriş, Gemini Enterprise için desteklenen bir veri yolu değildir.

• Yalnızca StreamableHTTP: Eski Server-Sent Events (SSE) aktarımı desteklenmez. MCP sunucuları StreamableHTTP kullanmalıdır.
• Public CA TLS'si zorunludur: MCP uç noktalarına PSC üzerinden özel olarak erişildiğinde bile herkese açık olarak güvenilen bir Public CA tarafından imzalanan TLS sertifikaları kullanılmalıdır.
• Kuruluş politikası geçersiz kılma: Veri deposunu kaydetmeden önce özel MCP veri depoları için kuruluş politikasını açıkça geçersiz kılmanız gerekir.

Kavramlar bölümünü tamamladık. Şimdi Kurulum bölümüne geçiyoruz.

3. Kurulum

Gerekli IAM rolleri

Codelab'i tamamlamak için aşağıdaki roller gereklidir:

Alan	Gerekli IAM rolleri
Proje ve IAM	roles/orgpolicy.policyAdmin roles/resourcemanager.projectIamAdmin roles/iam.accessPolicyAdmin roles/serviceusage.serviceUsageAdmin roles/iam.serviceAccountUser
Ağ ve Ağ Geçidi	roles/networkservices.admin roles/networksecurity.admin roles/serviceextensions.admin roles/compute.networkAdmin roles/dns.admin
Gemini Enterprise ve Registry	roles/discoveryengine.admin roles/agentregistry.admin (veya roles/apphub.admin)
İş yükleri ve derleme	roles/run.admin roles/cloudbuild.builds.editor roles/artifactregistry.writer roles/storage.admin
Gözlemlenebilirlik	roles/logging.viewer roles/logging.logWriter

Alternatif olarak, roles/owner tek başına kuruluş politikalarını değiştiremediğinden roles/orgpolicy.policyAdmin ile birlikte roles/owner gibi geniş kapsamlı bir temel 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 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

NOT: Özel MCP sunucuları ve çıkış aracı ağ geçitleri us-central1 ve europe-west1'de desteklenir. REGION'nın desteklenen konumlardan birine ayarlandığından emin olun (varsayılan: us-central1).

# 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 for agent platform (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export UAP_POLICY_NAME="uap-policy-${SLUG}"
export UAP_BINDING_NAME="uap-binding-${SLUG}"
export MCP_NAME="math-wizard"
export MCP_URL="https://${MCP_NAME}-${PROJ_NO}.${REGION}.run.app/mcp"

echo ${AGW_NAME}
echo ${AGW_URI}
echo ${UAP_POLICY_NAME}
echo ${UAP_BINDING_NAME}
echo ${MCP_NAME}
echo ${MCP_URL}

# create resource vars for gemini enterprise (automatic)
export GE_APP_DISPLAY_NAME="Codelab app"
export GE_APP_ORG_NAME="${SLUG}, Inc."
export GE_LOCATION="global"
export GE_APP_NAME="app-${SLUG}-${GE_LOCATION}"
export GE_APP_INIT="${GE_APP_NAME}_$(date +%s)"

echo ${GE_APP_DISPLAY_NAME}
echo ${GE_APP_ORG_NAME}
echo ${GE_LOCATION}
echo ${GE_APP_NAME}
echo ${GE_APP_INIT}

Aracı kimliği güven alanlarını ayarlama

if-then-else ifadesi, asıl aracı kimlikleri için doğru güven alanını ayarlamak amacıyla projenin bir kuruluşa ait olup olmadığını kontrol eder.

# set var for trust domain
if [[ -n "${ORG_ID}" ]]; then
  export TRUST_DOMAIN="agents.global.org-${ORG_ID}.system.id.goog"
else
  export TRUST_DOMAIN="agents.global.proj-${PROJ_NO}.system.id.goog"
fi

echo "trust domain: ${TRUST_DOMAIN}"

Faturalandırma ve kota projesini ayarlama

# set cli quota project
gcloud config set billing/quota_project ${PROJ_ID}

# set api quota project
gcloud auth application-default set-quota-project ${PROJ_ID}

Yapılandırma dosyaları için yerel dizin oluşturma

# create config folder
mkdir -p cfg

gcloud cli uygulamasını güncelleyin (önerilir).

Google Cloud SDK'nın kendi kendine yönetilen bir yüklemesini (ör. Cloud Shell dışında) çalıştırıyorsanız bileşenleri en son sürüme güncelleyin.

# update gcloud cli
gcloud components update

API hizmetlerini etkinleştirme

# enable google apis (part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  agentidentity.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 \
  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 (part 2)
gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  discoveryengine.googleapis.com \
  dns.googleapis.com \
  orgpolicy.googleapis.com \
  run.googleapis.com \
  saasservicemgmt.googleapis.com \
  securitycenter.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

Kuruluş Politikaları

Varsayılan Google Cloud yönetilen kuruluş politikası kısıtlamaları, bu Codelab'de kullanılan özellikleri kısıtlar:

• discoveryengine.managed.disableCustomMcpServerConnector:
  • Veri kaynağı olarak özel bir MCP sunucusu (custom_mcp) kullanan veri bağlayıcılarının oluşturulmasını kısıtlar (varsayılan olarak uygulanır).
• iam.managed.disableAccessPolicyBinding:
  • IAM v3 erişim politikası bağlamalarını kaynaklarla kısıtlar (varsayılan olarak zorunlu kılınır).
• discoveryengine.managed.allowedEgressFqdns:
  • VPC Hizmet Kontrolleri (VPC-SC) etkin olduğunda veya proje kuruluşun enforcedProjects parametresinde listelendiğinde veri bağlayıcıları için giden çıkış alanlarını (instance_uri FQDN'ler) kısıtlar.
• discoveryengine.managed.allowedDataSources:
  • VPC-SC etkin olduğunda veya proje kuruluşun enforcedProjects parametresinde listelendiğinde izin verilen veri bağlayıcı türlerini (dataSource) kısıtlar.

enforce: false değerini açıkça ayarlayarak proje düzeyinde devralınan kuruluş politikası kısıtlamalarını geçersiz kılın.

Özel MCP kısıtlamasını devre dışı bırakma

# disable data connector constraint (allow custom mcp servers)
gcloud org-policies set-policy /dev/stdin << EOF
name: projects/${PROJ_NO}/policies/discoveryengine.managed.disableCustomMcpServerConnector
spec:
  rules:
  - enforce: false
EOF

# verify org policy constraint on project
gcloud org-policies describe discoveryengine.managed.disableCustomMcpServerConnector \
  --project=${PROJ_ID} --effective

Erişim politikası kısıtlamasını devre dışı bırakma

# disable iam v3 constraint (allow v3 access policies)
gcloud org-policies set-policy /dev/stdin << EOF
name: projects/${PROJ_NO}/policies/iam.managed.disableAccessPolicyBinding
spec:
  rules:
  - enforce: false
EOF

# verify org policy constraint on project
gcloud org-policies describe iam.managed.disableAccessPolicyBinding \
  --project=${PROJ_ID} --effective

Koşullu veri bağlayıcısı kısıtlamalarını kontrol etme ve devre dışı bırakma

Varsayılan olarak, discoveryengine.managed.allowedEgressFqdns ve discoveryengine.managed.allowedDataSources yalnızca projeniz bir VPC Hizmet Kontrolleri (VPC SC) çevresindeyse veya bir kuruluş yöneticisi projenizi enforcedProjects'e eklediyse bağlayıcı oluşturmayı engeller.

Öncelikle projenizdeki etkin politikaları inceleyin:

# check effective egress fqdn constraint on project
gcloud org-policies describe discoveryengine.managed.allowedEgressFqdns \
  --project=${PROJ_ID} --effective

# check effective data source constraint on project
gcloud org-policies describe discoveryengine.managed.allowedDataSources \
  --project=${PROJ_ID} --effective

NOT: enforce: true varsayılan olarak gösterilse de enforcedProjects: [] boş olduğu sürece (ve projeniz bir VPC SC çevresinde olmadığı sürece) kısıtlama projenizde etkin değildir ve herhangi bir değişiklik yapmadan devam edebilirsiniz.

Bu kısıtlamalar ~~IF~~ zorunlu kılınırsa, VPC SC'de veya politika kısıtlamalı bir kuruluşta custom_mcp bağlayıcı kurulumunu engellememek için projenizin her iki politikasında da enforce: false ayarını yapın:

# disable egress fqdn constraint on project
gcloud org-policies set-policy /dev/stdin << EOF
name: projects/${PROJ_NO}/policies/discoveryengine.managed.allowedEgressFqdns
spec:
  rules:
  - enforce: false
EOF

# disable allowed data sources constraint on project
gcloud org-policies set-policy /dev/stdin << EOF
name: projects/${PROJ_NO}/policies/discoveryengine.managed.allowedDataSources
spec:
  rules:
  - enforce: false
EOF

# verify both constraints are disabled on project
gcloud org-policies describe discoveryengine.managed.allowedEgressFqdns \
  --project=${PROJ_ID} --effective

gcloud org-policies describe discoveryengine.managed.allowedDataSources \
  --project=${PROJ_ID} --effective

IAM izinleri

Kullanıcı hesabınıza ve Cloud Build tarafından kullanılan Compute Engine varsayılan hizmet hesabına gerekli IAM rollerini atayın:

• Kullanıcı hesabı (${USER_IDENTITY}):
  • Cloud Run hizmetlerini dağıtmak ve çağırmak (roles/run.admin, roles/run.invoker, roles/iam.serviceAccountUser), kapsayıcı görüntüleri oluşturmak (roles/cloudbuild.builds.editor), Gemini Enterprise'ı yönetmek (roles/discoveryengine.admin) ve Birleştirilmiş Erişim Politikaları oluşturmak (roles/iam.accessPolicyAdmin) için izinler gerekir.
• Compute Engine varsayılan hizmet hesabı(${PROJ_NO}[e-mail]):
  • Cloud Build tarafından kaynak kodu Cloud Storage'da (roles/storage.admin) hazırlamak, görüntüleri Artifact Registry'ye (roles/artifactregistry.writer) aktarmak ve derleme günlüklerini (roles/logging.logWriter) yazmak için kullanılır.

Rol bağlamalarını atamak için aşağıdaki komutları yürütün:

# grant roles to user account
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.admin"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/discoveryengine.admin"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/iam.accessPolicyAdmin"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/cloudbuild.builds.editor"

# grant roles to default compute (cloud build) service account
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}[e-mail]" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}[e-mail]" \
  --role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}[e-mail]" \
  --role="roles/logging.logWriter"

IAM izinlerini doğrulama

Kullanıcı hesabında altı (6) rol bağlaması olup olmadığını kontrol edin.

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

Varsayılan Compute hizmet hesabında üç (3) rol bağlaması olup olmadığını kontrol edin.

# show iam policy on project for default compute service account
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${PROJ_NO}[e-mail]" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Hizmet aracısı bağlamalarını doğrulama (önlem amaçlı)

Yeni bir projede, networkservices.googleapis.com ilk kez etkinleştirildiğinde Google Cloud, Agent Gateway hizmet aracısını otomatik olarak sağlar ve roles/agentgateway.serviceAgent izni verir. Önceki temizleme işlemlerinde varsayılan hizmet aracısı bağlamalarının kaldırılmış olabileceği mevcut bir projeyi yeniden kullanıyorsanız kimlik ve rol bağlamasının bozulmamış olduğundan emin olmak için aşağıdaki komutları yedek olarak çalıştırın:

# ensure network services service account has been created
gcloud beta services identity create \
  --service=networkservices.googleapis.com \
  --project="${PROJ_ID}"

# ensure network services service account has service agent roles applied
gcloud projects add-iam-policy-binding "${PROJ_ID}" \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-agentgateway.iam.gserviceaccount.com" \
  --role="roles/agentgateway.serviceAgent"

Kurulum bölümü sona erdi. Şimdi Ağ bölümüne geçiyoruz.

4. Ağ

Bu bölümde, VPC ağına aracı ağ geçidi ağ çıkışı için PSC ağ ekini destekleyen özel bir /28 alt ağı (192.168.10.0/28) ile özel modu kullanarak bir VPC ağı dağıtacaksınız.

Google API'leri için PSC uç noktası, Google API'lerine ve hizmetlerine özel dahili erişimi desteklemek için tek bir /32global dahili IPv4 adresi (172.16.20.20) kullanılarak dağıtılır. Bu Codelab'de Agent Gateway, Cloud DNS eşlemesiyle run.app. alanını çözümleyerek PSC uç noktasını kullanarak Cloud Run'ı hedefler.

Ağ oluşturma

Global bir VPC ağı oluşturun.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Aracı Ağ Geçidi PSC ağ eki için alt ağlar oluşturun:

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

Güvenlik duvarı kuralları oluşturma

Günlük kaydı etkin durumdayken tüm çıkış trafiğine izin verecek bir güvenlik duvarı politikası oluşturun. Bu, Agent Gateway'den VPC ağına çıkan trafiği izlemek için kullanılır. Cloud NGFW, ağ güvenliği ve trafik izleme için hem Essentials hem de Standard katmanlarını destekler.

NOT: Agent Gateway bağlantısı için açık bir çıkış güvenlik duvarı kuralı gerekli değildir. Google Cloud VPC ağları varsayılan olarak giden çıkışa izin verir. Ancak bu Codelab'de doğrulama ve izleme amacıyla, günlük kaydı etkinleştirilmiş açık bir çıkış kuralı yapılandırılır.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# bind fw policy to network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

PSC ağ eki oluşturma

Agent Gateway'den gelen bağlantıları otomatik olarak kabul edecek şekilde yapılandırılmış bir Private Service Connect (PSC) ağ eki oluşturun. Ağ eki, giden çıkış trafiği için Agent Gateway üretici tarafıyla güvenli bir şekilde bağlantı kurmak üzere bağlantının tüketici VPC ağı tarafını oluşturur. Alt ağ gereksinimleri ve IP aralığı özellikleri hakkında daha fazla bilgi için VPC bağlantısını yapılandırma başlıklı makaleyi inceleyin.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

PSC ağ ekini doğrulama

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

PSC ağ eklerinin kaynak URI'sini alın ve PSC_NA_URI ortam değişkeninde saklayın. Bu URI, VPC ağına ağ çıkışı için PSC arayüzünü sağlamak üzere Agent Gateway yapılandırmasında (networkConfig.egress.networkAttachment) referans olarak kullanılır:

# fetch psc network attachment uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

PSC uç noktası oluşturma

Google API'leri için Private Service Connect (PSC) uç noktası, trafiği herkese açık internete maruz bırakmadan dahili bir ağ yolu üzerinden Cloud Run MCP sunucusuna özel bağlantı oluşturmak üzere Agent Gateway için kullanılır. Agent Gateway'den VPC ağına çıkan giden araç çağrıları, hedef Cloud Run hizmeti URL'sini (*.run.app) bu özel uç nokta IP adresine dönüştürür.

PSC uç noktası için genel bir dahili IPv4 adresi ayırın. Seçilen IP adresi, VPC ağınızdaki mevcut alt ağlarla çakışmayan bir /32 adresi olmalıdır:

# set env var for psc ep ip address
export PSC_EP_IP="172.16.20.20"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

all-apis paketini kullanarak Google API'leri için bir PSC uç noktası oluşturun. Bu paket Cloud Run'ı içerir (run.app).

NOT: Agent Gateway'den Google API'leri için bir PSC uç noktasına trafik yönlendirmek, Cloud Run'da (*.run.app) herkese açık olarak imzalanmış bir sertifika yetkilisi (CA) sertifikasını sonlandırma şartını karşılar. Özel MCP sunucuları için alternatif bir mimari olarak, sunucusuz NEG arka ucuyla bir dahili uygulama yük dengeleyicisi (ILB) dağıtabilir ve yük dengeleyiciye herkese açık olarak imzalanmış bir sertifika uygulayabilirsiniz.

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

PSC uç noktasını doğrulama

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

DNS bölgesi ve kayıtları oluşturma

Cloud DNS, Agent Gateway'in Cloud Run'da barındırılan MCP sunucusuyla özel olarak iletişim kurmasını sağlamak için kullanılır. Agent Gateway, Cloud Run'ı hedefleyen giden araç isteklerini değerlendirirken VPC ağınızla ilişkili özel Cloud DNS bölgenizi kullanarak *.run.app için DNS sorgularını çözümlemek üzere DNS eşlemesini (dnsPeeringConfig.domains) kullanır. Özel DNS kaydı, sorguyu dahili PSC uç noktası IP adresiyle (172.16.20.20) döndürür. Böylece MCP aracı istekleri özel bir ağ yolu üzerinden yönlendirilebilir.

run.app. alanı için özel bir Cloud DNS tarafından yönetilen bölge oluşturun:

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for run.app" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

A için, *.run.app. alanını PSC uç noktasının IP adresine yönlendiren bir joker karakter DNS kaydı oluşturun:

# create dns record
gcloud dns record-sets create "*.run.app." \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

DNS sorgusu günlüğünü etkinleştirmek için bir Cloud DNS politikası oluşturun. DNS günlüğü, VPC ağınızdaki Agent Gateway'den kaynaklanan alan çözümleme isteklerini yakalar. Bu sayede denetlenebilirlik sağlanır ve *.run.app aracı isteklerinin dahili PSC uç noktasına doğru şekilde çözümlendiğini doğrulayabilirsiniz:

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

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

5. Agent Gateway

Agent Gateway, özel VPC bağlantısı için PSC ağ eki ve DNS eşleme ayarlarını yapılandıran networkConfig alanlarının yanı sıra Agent Registry örnekleri için registries değerini belirtir:

• registries: Ağ geçidini en fazla iki Agent Registry örneğiyle (biri bölgesel (../locations/${REGION}), biri global (../locations/global)) ilişkilendirir. Bu, Agent Gateway'i Agent Registry ile entegre ederek hem bölgesel dağıtımları (ör. ${REGION} bölgesindeki Cloud Run MCP sunucuları) hem de global kaynakları (ör. Gemini Enterprise aracıları ve global uç noktalar) ayrıntılı IAP v2 politikası uygulaması için çözer. Hedef URL'ler çözümlenirken bölgesel girişler, genel girişlere göre önceliklidir.
• networkAttachment: Agent Gateway'i özel çıkış için VPC ağınıza bağlayan PSC ağ ekini (psc-na-${REGION}-agw) gösterir.
• dnsPeeringConfig.domains: run.app. hizmetini, Cloud Run hizmetleri için Agent Gateway'den kaynaklanan DNS sorgularının, ana makine adlarını Cloud DNS özel bölgenizde yapılandırılan özel Google API'leri PSC uç nokta IP adresine (172.16.20.20) çözümlemek üzere DNS eşlemesini kullanacak şekilde yapılandırır.

Agent Gateway'i dağıtma

Aracı Ağ Geçidi yapılandırma dosyasını oluşturun ve içe aktarın.

NOT: dnsPeeringConfig içinde listelenen domains:, sondaki bir nokta (.) ile bitmelidir.

# create agent gateway config file
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

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

Temsilci ağ geçidi dağıtımını doğrulama

Aracı kayıt defterini ve ağ yapılandırmasını onaylayın:

# show agent gateway registries and network config
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION} \
  --format="yaml(registries,networkConfig)"

Beklenen çıkış:

networkConfig:
  dnsPeeringConfig:
    domains:
    - run.app.
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
    targetProject: ${PROJ_ID}
  egress:
    networkAttachment: projects/${PROJ_ID}/regions/${REGION}/networkAttachments/psc-na-${REGION}-agw
registries:
- //agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}

Çıkışta gerekli yapılandırma ayrıntılarının gösterildiğini doğrulayın:

• registries: Ağ geçidiyle ilişkili bölgesel (${REGION}) Agent Registry URI'sini listeler.
• egress.networkAttachment: VPC çıkışı için PSC ağ eki URI'sini belirtir.
• dnsPeeringConfig.domains: Özel alan adı çözümlemesi için targetNetwork'i işaret eden run.app. içerir.

Ağ geçidi bağlantısını onaylamak için PSC ağ ekini inceleyin:

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="yaml(connectionEndpoints)"

Kabul edilen bir bağlantı uç noktası olup olmadığını kontrol edin:

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '<AGW_TENANT_PROJ_NO>'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

Yetkilendirme verme

Aracı Ağ Geçidi, Identity-Aware Proxy (IAP) Birleşik Erişim Politikaları (UAP) ile entegre edilmiş Yetkilendirme Politikaları (networksecurity.authzPolicies) kullanarak giden araç trafiğini güvenli hale getirir ve yönetir.

Agent Gateway, temel satır içi ALLOW ve DENY kurallarını desteklese de kurumsal ortamlarda merkezi, kimlik odaklı yönetim gerekir. IAM Birleşik Erişim Politikaları (veya Erişim Politikaları) ile çıkış erişim kurallarını standart IAM v3 erişim politikalarını kullanarak yönetirsiniz.

Şekil 3. Yetkilendirme mimarisi

Yetkilendirme akışı üç bileşeni birbirine bağlar:

1. Ağ Geçidi Yetkilendirme Politikası (authzPolicy):
   • Agent Gateway'i hedefleyen bölgesel bir kaynak.
   • Tüm giden yetkilendirme kontrollerini IAP Authz uzantısına yönlendirmek için policyProfile: REQUEST_AUTHZ ve action: CUSTOM ile yapılandırılır.
2. IAP Hizmet Uzantısı (authzExtension):
   • İstek yetkilendirmesini Identity-Aware Proxy'ye (iap.googleapis.com) devreden bölgesel bir kaynak.
   • ENFORCE modundaki politikaları V2 politika sürümünü kullanarak değerlendirir.
3. IAM Birleştirilmiş Erişim Politikası ve Bağlama (accessPolicy & policyBinding):
   • Ayrıntılı erişim kuralları içeren global IAM v3 kaynakları.
   • Çağıran aracının SPIFFE asıl kimliğini doğrular, evrensel iap.googleapis.com/resources.egressViaIAP iznini doğrular ve Common Expression Language (CEL) koşullarını hedef özelliklerine göre değerlendirir.

Yetkilendirme uzantısını dağıtma

Yetkilendirme kararlarını IAP hizmetine devreden bir service-extensions yetkilendirme uzantısı yapılandırması oluşturun:

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

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

Yetkilendirme uzantısını doğrulama

Yetkilendirme uzantısının etkin olup olmadığını kontrol edin:

# list authz extensions
gcloud service-extensions authz-extensions list \
  --location=${REGION} \
  --format="table(
    name.basename():label=NAME,
    createTime.date(tz=LOCAL):label=CREATED,
    updateTime.date(tz=LOCAL):label=MODIFIED,
    service:label=SERVICE,
    metadata:label=METADATA,
    timeout:label=TIMEOUT
  )"

Yetkilendirme politikasını dağıtma

Agent Gateway'i hedefleyen ve IAP için istek doğrulamasını yetkilendirme uzantısına devreden bir network-security yetkilendirme politikası yapılandırması oluşturun:

# create authz policy config file
cat > cfg/${AGW_NAME}-authz-policy-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-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"
EOF

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

Yetkilendirme politikasını doğrulama

Yetkilendirme politikasının etkin olup olmadığını kontrol edin:

# list authz policies
gcloud network-security authz-policies list \
  --location=${REGION} \
  --format="table(
    name.basename():label=NAME,
    action:label=ACTION,
    customProvider.list().sub('\W.*', ''):label=CUSTOM_PROVIDER_TYPE,
    policyProfile:label=POLICY_PROFILE,
    customProvider.authzExtension.resources[0].basename():label=CUSTOM_PROVIDER_RESOURCE
  )"

IAM erişim politikaları oluşturma

Agent Gateway artık yetkilendirme kontrollerini IAP'ye devreder ve hedef meta verilerini Agent Registry'den çözer. Ardından, giden araç yürütme işlemlerini yönetmek için bir IAM Birleşik Erişim Politikası kuralı tanımlayın.

NOT: Agent Gateway'deki hedef uç noktalar iki kategoriye ayrılır: kayıtlı (Agent Registry'de kataloglanmış) ve kayıtsız (doğrudan dahili veya harici URL'ler). Aracı Ağ Geçidi, registries ile yapılandırıldığından giden istekleri Aracı Kayıt Defteri'ne göre çözer ve politika değerlendirmesi için destination.is_registered ve destination.agent_registry.* özelliklerini IAP v2'ye iletir.

IAP, CEL özelliği ifadelerini aşağıdaki Agent Registry hedef özelliklerine göre değerlendirir:

• Kayıtlı durum (destination.is_registered):
  • Hedefin Agent Registry'de kataloglanıp kataloglanmadığını belirten Boole değeri (true/false).
• MCP sunucu adı (destination.agent_registry.mcp_server.name):
  • Agent Registry'ye kaydedilen standart MCP sunucusu kaynak adı.
• MCP yöntemi (destination.agent_registry.mcp_server.method):
  • Çağrılan MCP yöntemi (ör. tools/call, tools/list, initialize).
• Aracın adı (destination.agent_registry.mcp_server.tool.name):
  • Çağrılan aracın adı (ör. subtract veya add). Bu sayede, kayıtlı MCP sunucularında araç düzeyinde ayrıntılı yetkilendirme yapılabilir.

IAM erişim politikası kuralı tanımlama

IAM politikası kuralı manifesti şunları belirtir:

• Asıl öğeler: Gemini Enterprise'ın temel asistan aracısını temsil eden SPIFFE asıl öğe kimliği.
• İzinler: Tüm IAP tarafından yönetilen çıkış trafiği için gerekli olan evrensel iap.googleapis.com/resources.egressViaIAP izni.
• Koşullar: Ajanın yalnızca Ajan Kayıt Defteri'nde kataloglanan uç noktaları çağırabilmesini sağlayan bir CEL ifadesi (destination.is_registered == true).

NOT: Gemini Enterprise, ilk bağlantı sırasında belirli araç çağrıları gerçekleşmeden önce bir yaşam döngüsü sırası (initialize → notifications/initialized → tools/list) gerçekleştirir. Keşif sırasında araç özellikleri henüz mevcut değildir. destination.is_registered == true kullanıldığında, eksik araç parametreleri nedeniyle başarısız olmadan keşif ve el sıkışma işlemlerinin başarılı olması sağlanır.

Politika kuralı manifest dosyasını oluşturun:

# create access policy rule file
cat > cfg/${UAP_POLICY_NAME}-rules.json << EOF
[
  {
    "description": "allow ge assistant to any registered service",
    "effect": "ALLOW",
    "principals": [
      "principal://${TRUST_DOMAIN}/resources/discoveryengine/projects/${PROJ_NO}/locations/global/engines/${GE_APP_INIT}/assistants/default_assistant/agents/default/core_assistant"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true"
      }
    }
  }
]
EOF

IAM erişim politikasını dağıtma

Manifest dosyasında tanımlanan kuralları kullanarak genel IAM erişim politikasını oluşturun:

# create iam access policy
gcloud iam access-policies create ${UAP_POLICY_NAME} \
  --details-rules=cfg/${UAP_POLICY_NAME}-rules.json \
  --project=${PROJ_ID} \
  --location=global

IAM erişim politikasını doğrulama

IAM erişim politikasının başarıyla oluşturulduğunu kontrol edin ve kural ayrıntılarını inceleyin:

# show iam access policy details
gcloud iam access-policies describe ${UAP_POLICY_NAME} \
  --project=${PROJ_ID} \
  --location=global

Beklenen çıkış:

details:
  rules:
  - conditions:
      iap.googleapis.com:
        expression: destination.is_registered == true
    description: allow ge assistant to any registered service
    effect: ALLOW
    operation:
      permissions:
      - iap.googleapis.com/resources.egressViaIAP
    principals:
    - principal://agents.global.org-${ORG_ID}.system.id.goog/resources/discoveryengine/projects/${PROJ_NO}/locations/global/engines/${GE_APP_INIT}/assistants/default_assistant/agents/default/core_assistant
name: projects/${PROJ_ID}/locations/global/accessPolicies/${UAP_POLICY_NAME}

IAM erişim politikasını projeye bağlama

Projenizdeki tüm aracı ağ geçitlerinde zorunlu kılmayı etkinleştirmek için IAM erişim politikasını proje kaynağına ekleyen bir politika bağlama oluşturun:

# bind iam access policy to project resource
gcloud iam policy-bindings create ${UAP_BINDING_NAME} \
  --policy="projects/${PROJ_ID}/locations/global/accessPolicies/${UAP_POLICY_NAME}" \
  --target-resource="//cloudresourcemanager.googleapis.com/projects/${PROJ_ID}" \
  --project=${PROJ_ID} \
  --location=global

IAM erişim politikası bağlamasını doğrulama

Etkin politika bağlama noktalarının doğru politikaya ve hedefe yönlendirdiğini kontrol edin:

# show policy binding details
gcloud iam policy-bindings describe ${UAP_BINDING_NAME} \
  --project=${PROJ_ID} \
  --location=global

Beklenen çıkış:

name: projects/${PROJ_ID}/locations/global/policyBindings/${UAP_BINDING_NAME}
policy: projects/${PROJ_ID}/locations/global/accessPolicies/${UAP_POLICY_NAME}
policyKind: ACCESS
target:
  resource: //cloudresourcemanager.googleapis.com/projects/${PROJ_ID}

Agent Gateway bölümünü tamamladık. Şimdi MCP sunucusu bölümüne geçiyoruz.

6. MCP sunucusu

Bu bölümde, add ve subtract araçlarını kullanıma sunan özel bir FastMCP sunucusu oluşturacak ve bunu doğrudan kaynaktan Cloud Run'a dağıtacaksınız. Kaynak dağıtımı sırasında (--source), Cloud Build, container görüntüsünü Dockerfile ve uv'ı kullanarak paketler (pyproject.toml içinde tanımlanan bağımlılıkları yükler ve server.py'ı başlatır).

Cloud Run hizmeti dağıtıldıktan sonra, Gemini Enterprise'ın araçlarını keşfedip çağırabilmesi için MCP sunucusunu Agent Registry'ye araç spesifikasyonuyla (toolspec.json) birlikte kaydedersiniz.

MCP sunucusu uygulaması oluşturma

Uygulama kodu için bir math-wizard proje dizini oluşturun:

# create directory for code
mkdir -p math-wizard

Python proje manifest dosyasını yazın:

# create python project manifest file
cat > math-wizard/pyproject.toml << 'EOF'
[project]
name = "math-wizard"
version = "0.1.0"
description = "math wizard mcp server"
requires-python = ">=3.12"
dependencies = [
    "fastmcp==2.13.1",
]
EOF

Cloud Logging ve Cloud Trace doğrulama için gelen HTTP üstbilgilerini (mcp-session-id, x-forwarded-for, user-agent ve x-cloud-trace-context) yakalamak üzere koda bazı ek enstrümantasyon işlevleri dahil edilmiştir.

Uygulama kodu dosyasını yazın:

# create mcp server application code
cat > math-wizard/server.py << 'EOF'
import asyncio
import json
import logging
import os
from fastmcp import FastMCP
from fastmcp.server.dependencies import get_http_headers
from mcp.types import ToolAnnotations

logger = logging.getLogger(__name__)
logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO)

mcp = FastMCP("math wizard mcp server")

def log_network_context(tool_name: str, a: int, b: int) -> None:
    headers = get_http_headers()
    print(json.dumps({
        "severity": "INFO",
        "message": f">>> 🛠️ Tool: '{tool_name}' called with numbers '{a}' and '{b}'",
        "tool": tool_name,
        "mcp_session_id": headers.get("mcp-session-id"),
        "x_forwarded_for": headers.get("x-forwarded-for"),
        "user_agent": headers.get("user-agent"),
        "trace_header": headers.get("x-cloud-trace-context"),
    }), flush=True)

@mcp.tool(
    annotations=ToolAnnotations(
        readOnlyHint=True,
    )
)
def add(a: int, b: int) -> int:
    """Use this to add two numbers together.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The sum of the two numbers.
    """
    logger.info(f">>> 🛠️ Tool: 'add' called with numbers '{a}' and '{b}'")
    log_network_context("add", a, b)
    return a + b

@mcp.tool(
    annotations=ToolAnnotations(
        readOnlyHint=True,
    )
)
def subtract(a: int, b: int) -> int:
    """Use this to subtract two numbers.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The difference of the two numbers.
    """
    logger.info(f">>> 🛠️ Tool: 'subtract' called with numbers '{a}' and '{b}'")
    log_network_context("subtract", a, b)
    return a - b

if __name__ == "__main__":
    logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}")
    asyncio.run(
        mcp.run_async(
            transport="streamable-http",
            host="0.0.0.0",
            port=int(os.getenv("PORT", 8080)),
        )
    )
EOF

Container görüntüsü oluşturma talimatlarını ve başlangıç komutlarını tanımlamak için Dockerfile yazın:

# create dockerfile
cat > math-wizard/Dockerfile << 'EOF'
# use official python 3.12 image
FROM python:3.12-slim

# install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# install the project into /app
COPY . /app
WORKDIR /app

# allow statements and log messages to immediately appear in the logs
ENV PYTHONUNBUFFERED=1

# install dependencies
RUN uv sync

EXPOSE 8080

# run the mcp server
CMD ["uv", "run", "server.py"]
EOF

Hizmeti Cloud Run'a dağıtma

Cloud Build'i (proje varsayılan Compute hizmet hesabını ${PROJ_NO}[e-mail] kullanır) kullanarak MCP sunucusunu kaynaktan dağıtın:

# deploy cloud run service
gcloud run deploy ${MCP_NAME} \
  --source math-wizard \
  --region=${REGION} \
  --no-invoker-iam-check \
  --ingress=internal \
  --quiet

NOT: --no-invoker-iam-check ayarı, allUsers bağlamadan Cloud Run IAM çağırma denetimini devre dışı bırakır (Domain Restricted Sharing kuruluş politikası hatalarını önler). --ingress=internal ise ağ erişimini kesinlikle VPC ile kısıtlar.

Cloud Run dağıtımını doğrulama

Etkin yapılandırmasını doğrulamak için Cloud Run hizmeti ayrıntılarını kontrol edin:

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION}

Beklenen çıkış:

<snip>
✔ Service math-wizard in region ${REGION}

URL:     https://math-wizard-${PROJ_NO}.${REGION}.run.app
Ingress: internal
Traffic:
  100% LATEST (currently math-wizard-00001-<id>)
</snip>

MCP sunucusunu Agent Registry'ye kaydetme

Gemini Enterprise'ın MCP sunucusunda bulunan araçları tam olarak keşfedebilmesi için Agent Registry'ye kayıt sırasında bir araç spesifikasyonları dosyası (toolspec.json) sağlanmalıdır.

MCP aracı spesifikasyonu oluşturma

# create tool spec file
cat > cfg/toolspec.json << 'EOF'
{
  "tools": [
    {
      "name": "add",
      "description": "Use this to add two numbers together.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "a": { "type": "integer", "description": "The first number." },
          "b": { "type": "integer", "description": "The second number." }
        },
        "required": ["a", "b"]
      },
      "isReadOnly": true,
      "isDestructive": false,
      "isIdempotent": true,
      "isOpenWorld": false
    },
    {
      "name": "subtract",
      "description": "Use this to subtract two numbers.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "a": { "type": "integer", "description": "The first number." },
          "b": { "type": "integer", "description": "The second number." }
        },
        "required": ["a", "b"]
      },
      "isReadOnly": true,
      "isDestructive": false,
      "isIdempotent": true,
      "isOpenWorld": false
    }
  ]
}
EOF

MCP sunucusunu Agent Registry'ye kaydetme

# register mcp server in agent registry
gcloud agent-registry services create ${MCP_NAME} \
  --project=${PROJ_ID} \
  --location=${REGION} \
  --display-name="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app" \
  --description="MANDATORY MATH & ARITHMETIC AGENT: You MUST ALWAYS invoke \
this tool for ANY mathematical calculation, addition (+), subtraction (-), \
sum, difference, or arithmetic question (including simple questions like \
'what is 67 + 345?'). NEVER compute arithmetic yourself and NEVER transfer \
math queries to file_and_coding_agent / code interpreter. Always delegate \
every math question to this tool." \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=cfg/toolspec.json \
  --interfaces=protocolBinding=JSONRPC,url="${MCP_URL}"

Agent Registry'de MCP sunucusunu doğrulama

Dağıtılan Cloud Run hizmetinin, uç nokta URL'si ve kullanılabilir araçlarıyla birlikte bölgede kayıtlı bir MCP sunucusu olarak listelendiğini doğrulayın:

# list registered mcp servers in agent registry
gcloud agent-registry mcp-servers list \
  --location=${REGION} \
  --project=${PROJ_ID} \
  --format="table(
    name.basename():label=REGISTRY_ID,
    displayName:label=DISPLAY_NAME,
    interfaces[0].url:label=ENDPOINT_URL,
    tools[].name.list():label=TOOLS
  )"

Beklenen çıkış:

REGISTRY_ID                                         DISPLAY_NAME                                  ENDPOINT_URL                                              TOOLS
agentregistry-00000000-0000-0000-0012-3456789abcde  math-wizard-${PROJ_NO}.${REGION}.run.app      https://math-wizard-${PROJ_NO}.${REGION}.run.app/mcp      add,subtract

Her araç için tam araç tanımlarını, giriş şemalarını ve davranış ek açıklamalarını kaydettiğini görmek üzere hizmet yapılandırma spesifikasyonunu görüntüleyin:

# describe mcp server tool specs
gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --project=${PROJ_ID} \
  --format="yaml(mcpServerSpec.content.tools)"

MCP sunucusu bölümünü tamamladık. Şimdi Gemini Enterprise bölümüne geçiyoruz.

7. Gemini Enterprise

Bu bölümde, Gemini Enterprise uygulaması ve bağlı bir özel MCP sunucusu veri deposu kaynağı oluşturup yapılandıracaksınız.

Discovery Engine kaynak modeli

Gemini Enterprise uygulaması (Discovery Engine API'de Engine kaynağı olarak gösterilir), son kullanıcılar için merkezi düzenleme katmanı ve etkileşimli arayüzdür. Kullanıcı sohbet oturumlarını yönetir, üretken modelleri kurumsal verilerle temellendirir ve dinamik araç yürütmeyi koordine eder.

Gemini Enterprise uygulamaları, veri depoları aracılığıyla veriler ve sistemlerle etkileşim kurar:

• Bilgi veri depoları: Almayla artırılmış üretim (RAG) için statik içerikleri (ör. Cloud Storage, Google Drive, BigQuery) alma ve dizine ekleme.
• Veri bağlayıcıları (işlem sağlayıcılar): Dinamik üçüncü taraf veya özel API'lere bağlanın. Özel bir MCP sunucusu veri deposu, Model Context Protocol (MCP) tarafından tanımlanan araçları kullanıma sunarak modelin bir sohbet sırasında harici işlevleri dinamik olarak çağırmasına olanak tanır.

Agent Gateway üzerinden çıkış yönlendirmesi

Varsayılan olarak Gemini Enterprise, bağlayıcı ve araç yürütme trafiğini genel ağlar üzerinden yönlendirir. Ancak özel VPC iş yükleri ve sıfır güven yönetimi için motor, çıkışı Agent Gateway üzerinden yönlendirecek şekilde yapılandırılabilir:

• Bu laboratuvarın ilerleyen bölümlerinde özel MCP sunucusu veri deposunu oluştururken veri deposu ayarlarında Çıkış trafiğini Agent Gateway üzerinden yönlendir'i etkinleştirirsiniz.
• Bu işlem, motorun giden araç çağrılarını bölgesel Agent Gateway'inize bağlayarak tüm MCP isteklerinin uygulamanın Agent Identity ile taşınmasını, IAP ve IAM Birleşik Erişim Politikaları (UAP) kullanılarak çalışma zamanı yetkilendirmesinden geçmesini ve PSC ağ ekini özel VPC'nize geçmesini sağlar.

NOT: Bu codelab'de, global konumunda Gemini Enterprise uygulaması dağıtılırken Agent Gateway'in ${REGION} (us-central1) konumunda dağıtılması gösterilmektedir. agentGatewaySetting yapılandırıldığında, Gemini Enterprise çıkış yönlendirmesi için bu bölgesel bağlama oluşturulur.

Gemini Enterprise uygulaması oluşturma

Aşağıdaki yöntemde, Gemini Enterprise uygulama kaynaklarını ve yapılandırmasını oluşturmak için discoveryengine.googleapis.com API'si kullanılır. Google Cloud Console kullanıcı arayüzünü kullanarak yapılandırma hakkında talimatlar için Uygulama oluşturma başlıklı makaleyi inceleyin.

# create engine (ge app)
curl -s -X POST "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines?engineId=${GE_APP_INIT}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "displayName": "${GE_APP_DISPLAY_NAME}",
  "dataStoreIds": [],
  "solutionType": "SOLUTION_TYPE_SEARCH",
  "industryVertical": "GENERIC",
  "appType": "APP_TYPE_INTRANET",
  "searchEngineConfig": {
    "searchTier": "SEARCH_TIER_ENTERPRISE",
    "searchAddOns": [
      "SEARCH_ADD_ON_LLM"
    ]
  },
  "commonConfig": {
    "companyName": "${GE_APP_ORG_NAME}"
  }
}
EOF

Uygulama oluşturmayı doğrulama

# fetch engine (ge app) id
export GE_APP_ID=$(curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq -r --arg name "${GE_APP_DISPLAY_NAME}" '.engines[] | select(.displayName==$name) | .name | split("/") | last')

echo "engine (ge app) id: ${GE_APP_ID}"

Oluşturulan yapılandırmayı görmek için motor ayrıntılarını görüntüleyin:

# get engine (ge app) details
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

JSON yanıtındaki aşağıdaki sunucu tarafından doldurulan özelliklere dikkat edin:

• name: Standart kaynak yolu (projects/${PROJ_NO}/locations/global/collections/default_collection/engines/${GE_APP_ID}).
• sessionConfig.sessionManagementPolicy: Çok aşamalı etkileşimi ve araç çağrısı durumunu Agent Platform'da (eski adıyla Vertex AI) kalıcı hale getiren "VERTEX_AI_MANAGED" olarak ayarlanır.
• observabilityConfig.observabilityEnabled: Temel metrikler için varsayılan olarak true ayarlanır (ayrıntılı istem ve araç yükü günlüğü daha sonraki bir adımda etkinleştirilir).

Kimlik sağlayıcıyı etkinleştirme

Gemini Enterprise uygulamanızda son kullanıcı kimlik doğrulaması için kimlik sağlayıcı olarak Google Identity'yi etkinleştirin.

Aşağıdaki yöntemde, Gemini Enterprise uygulama kimliği sağlayıcısını yapılandırmak için discoveryengine.googleapis.com API'si kullanılır. Google Cloud Console kullanıcı arayüzünü kullanarak yapılandırma yapmak için talimatları Kimlik sağlayıcıyı yapılandırma başlıklı makalede bulabilirsiniz.

# set identity provider
curl -s -X PATCH "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/aclConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "idpConfig": {
    "idpType": "GSUITE"
  }
}
EOF

Kimlik sağlayıcıyı doğrulama

# show identity provider
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/aclConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

Çıkış "idpType": "GSUITE", Google Identity sağlayıcısına karşılık gelir.

(İsteğe bağlı) Gemini Enterprise deneme lisansını etkinleştirme

Gemini Enterprise lisanslarının atandığı bir proje kullanıyorsanız bu adımı atlayabilirsiniz. Lisansı olmayan yeni bir proje kullanıyorsanız devam edin ve bu adımları uygulayın.

Gemini Enterprise kullanıcı koltuklarına 30 gün boyunca hak kazandırmak için bir lisans yapılandırma kaynağı oluşturun. Bu işlem, varsayılan lisansı yeni deneme sürümüne ayarlar. Böylece, oturum açan her kullanıcıya otomatik olarak yer verilir:

# configure free trial subscription
curl -s -X POST "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/licenseConfigs?licenseConfigId=free_trial_gemini" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "subscriptionTier": "SUBSCRIPTION_TIER_SEARCH_AND_ASSISTANT",
  "freeTrial": true
}
EOF

Lisansın uygulandığını doğrulama

# show license config
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/licenseConfigs/free_trial_gemini" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

"subscriptionTerm": "SUBSCRIPTION_TERM_ONE_MONTH" ve "freeTrial": true olup olmadığını kontrol edin.

# verify auto-registration enabled on default user store
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/userStores/default_user_store" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

../free_trial_gemini" ve "enableLicenseAutoRegister": true olup olmadığını kontrol edin.

Gözlemlenebilirlik ayarlarını etkinleştirme

Gemini Enterprise uygulaması (motor) düzeyinde gözlemlenebilirliği etkinleştirdiğinizde, temel asistanın etkileşimlerini Metrik Gezgini'ndeki metrik verileriyle birlikte görüntüleyebilir ve Cloud Trace'teki uçtan uca izleri ilişkilendirebilirsiniz.

# set observability on engine (ge app)
curl -s -X PATCH "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}?updateMask=observabilityConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "observabilityConfig": {
    "observabilityEnabled": true,
    "sensitiveLoggingEnabled": true
  }
}
EOF

İzlenebilirlik ayarlarını doğrulama

# verify observability is enabled on engine (ge app)
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq '{observabilityConfig: .observabilityConfig}'

"sensitiveLoggingEnabled": true olup olmadığını kontrol edin.

Agent Gateway'e bağlanma

Gemini Enterprise'dan çıkan trafiği Agent Gateway üzerinden yönlendirmek, tüm yapay zeka aracı çağrıları için merkezi bir sıfır güven yönetimi ve güvenlik uygulama sınırı oluşturur:

• Merkezi politika zorunluluğu: Agent Gateway, trafiğin aracı ortamından ayrılmadan önce giden araç isteklerini yetkilendirme politikalarına ve yönetim denetimlerine göre değerlendiren satır içi bir proxy görevi görür.
• Özel ağdan çıkış: Gemini Enterprise'ı Agent Gateway'e bağlamak, Cloud Run'daki özel MCP sunucularını hedefleyen araç çağrılarının genel interneti atlayarak Private Service Connect (PSC) üzerinden güvenli bir şekilde yönlendirilmesini sağlar.
• Birleştirilmiş denetlenebilirlik: Tüm bağlı MCP sunucularında ve harici araçlarda merkezi istek günlüğü kaydı, telemetri ve denetleme izleri sağlar.

Gemini Enterprise uygulamanızda agentGatewaySetting özelliğini yapılandırdığınızda, son kullanıcı sorgularıyla başlatılan giden araç ve temsilci çağrıları (ör. Agent Registry'den içe aktarılan özel MCP sunucularına ve A2A temsilcilerine yapılan çağrılar) otomatik olarak Agent Gateway üzerinden yönlendirilir.

NOT: Agent Gateway, sorgu sırasında Gemini Enterprise'ın harici MCP sunucularına, işlem bağlayıcılarına ve aracılara çıkışını yönetir. Model çıkarımı, bilgi veri deposu alma (RAG), yerleşik asistan araçları veya bağlayıcı alma işleri için proxy oluşturmaz.

NOT: Bu bağlamayı REST API'yi (aşağıda gösterilmiştir) kullanarak veya Cloud Console'da Gemini Enterprise > Uygulama Ayarları > Ağ Geçidi Ayarları bölümünde yapılandırabilirsiniz. Ayrıntılar için Aracı Ağ Geçidi'ni Gemini Enterprise'a bağlama başlıklı makaleyi inceleyin.

Aşağıdakileri etkinleştirmek için motoru agentGatewaySetting yamalayın:

# bind engine (ge app) to agent gateway
curl -s -X PATCH "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}?updateMask=agentGatewaySetting.defaultEgressAgentGateway.name" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "agentGatewaySetting": {
    "defaultEgressAgentGateway": {
      "name": "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
    }
  }
}
EOF

Temsilci ağ geçidi bağlamasını doğrulama

agentGatewaySetting bağlamasını onaylamak için uygulama yapılandırmasını alın:

# verify engine (ge app) agent gateway configuration
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq '{name: .name, displayName: .displayName, agentGatewaySetting: .agentGatewaySetting}'

Beklenen çıkış:

{
  "name": "projects/${PROJ_NO}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}",
  "displayName": "${GE_APP_DISPLAY_NAME}",
  "agentGatewaySetting": {
    "defaultEgressAgentGateway": {
      "name": "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
    }
  }
}

Özel MCP sunucusu veri deposu oluşturma

Bu bölümde, özel bir MCP veri deposu oluşturarak MCP sunucusunu Gemini Enterprise'a bağlayacaksınız.

Discovery Engine API'yi kullanırken bu işlem iki adımdan oluşur:

1. Oluştur (:setUpDataConnector): Özel bir Collection kaynağı (${MCP_NAME}-%timestamp-collection) oluşturur, DataConnector (custom_mcp) ekler ve destekleyen DataStore (..._mcp_data) kaynağını sağlar.
2. Etkinleştir (PATCH .../dataConnector?updateMask=actionConfig): Bağlayıcının işlem çalışma zamanını (actionState: "ACTIVE") Agent Registry aracı spesifikasyonunu kullanarak etkinleştirir ve DataStore (dataStoreIds) öğesini Gemini Enterprise Engine'ınıza bağlar.

# fetch mcp server agent registry resource name
export MCP_REGISTRY_URI=$(gcloud agent-registry mcp-servers list \
  --location=${REGION} \
  --project=${PROJ_ID} \
  --filter="displayName:${MCP_NAME}" \
  --format="value(name)")

echo "mcp registry name: ${MCP_REGISTRY_URI}"
echo "mcp url: ${MCP_URL}"

Veri bağlayıcısı oluşturma

# create custom mcp data connector from agent registry and link to engine
curl -s -X POST "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}:setUpDataConnector" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "collectionId": "${MCP_NAME}-$(date +%s)-collection",
  "collectionDisplayName": "${MCP_NAME}-collection",
  "dataConnector": {
    "dataSource": "custom_mcp",
    "dataSourceVersion": 1,
    "params": {
      "oauth_access_token": "unused"
    },
    "refreshInterval": "86400s",
    "entities": [
      {
        "entityName": "mcp_data"
      }
    ],
    "connectorModes": [
      "FEDERATED"
    ],
    "actionConfig": {
      "isActionConfigured": true,
      "createBapConnection": true,
      "actionParams": {
        "auth_type": "NO_AUTH",
        "instance_uri": "${MCP_URL}",
        "mcp_server_source": "REGISTRY_MCP",
        "registry_mcp_server_name": "${MCP_REGISTRY_URI}",
        "mcp_agent_instructions": "MANDATORY MATH & ARITHMETIC AGENT: Always invoke this tool for any mathematical calculation, addition (+), subtraction (-), sum, or difference.",
        "use_agent_gateway_egress": true,
        "agent_gateway_engine": "projects/${PROJ_ID}/locations/global/collections/default_collection/engines/${GE_APP_ID}"
      }
    }
  }
}
EOF

Veri bağlayıcısı oluşturmayı doğrulama

# fetch collection id
export GE_COLLECTION_ID=$(curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq -r --arg dname "${MCP_NAME}-collection" '.collections[] | select(.displayName == $dname) | .name | split("/") | last' | head -n 1)

echo "ge collection id: ${GE_COLLECTION_ID}"

"registry_mcp_server_name" alanının, MCP sunucusunun Agent Registry UUID'siyle doldurulup doldurulmadığını kontrol edin:

# show data connector details
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/${GE_COLLECTION_ID}/dataConnector" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq '{name, state, actionState, connectorModes, bapConfig, registry_mcp_server_name: .actionConfig.actionParams.registry_mcp_server_name}'

Google Cloud Console kullanıcı arayüzünde MCP sunucu kayıt defteri girişini görüntüleyin:

echo "mcp server registry page url: https://console.cloud.google.com/agent-platform/agent-registry/mcp-servers/${REGION}/${MCP_REGISTRY_URI##*/}/overview?project=${PROJ_ID}"

Veri bağlayıcısını etkinleştirme

# activate and bind data connector
curl -s -X PATCH "https://discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/global/collections/${GE_COLLECTION_ID}/dataConnector?updateMask=actionConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "name": "projects/${PROJ_ID}/locations/global/collections/${GE_COLLECTION_ID}/dataConnector",
  "actionConfig": {
    "isActionConfigured": true,
    "createBapConnection": true,
    "actionParams": {
      "auth_type": "NO_AUTH",
      "instance_uri": "${MCP_URL}",
      "mcp_server_source": "REGISTRY_MCP",
      "registry_mcp_server_name": "${MCP_REGISTRY_URI}",
      "mcp_agent_instructions": "MANDATORY MATH & ARITHMETIC AGENT: Always invoke this tool for any mathematical calculation, addition (+), subtraction (-), sum, or difference.",
      "use_agent_gateway_egress": true,
      "agent_gateway_engine": "projects/${PROJ_ID}/locations/global/collections/default_collection/engines/${GE_APP_ID}"
    }
  }
}
EOF

Özel MCP sunucusu bağlantılarını doğrulama

# show engine (ge app) details
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq '{name: .name, dataStoreIds: .dataStoreIds, agentGatewaySetting: .agentGatewaySetting}'

Bağlı veri deposunu "dataStoreIds": "collection-math-wizard-_mcp_data" kontrol edin.

# show collection details
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq --arg app "${GE_APP_ID}" '.collections[] | select(.dataConnector.actionConfig.actionParams.agent_gateway_engine // "" | endswith($app)) | .dataConnector | {name: .name, state: .state, actionState: .actionState, connectorModes: .connectorModes, actionParams: .actionConfig.actionParams}'

Tüm parametreler doldurulmuşken "state": "ACTIVE" olup olmadığını kontrol edin.

Araç işlemleri

Gemini Enterprise kontrol panelinde math-wizard-collection veri deposunu incelerken İşlemler sekmesinin kullanılmadığını ve ↻ Özel işlemleri yeniden yükle düğmesinin devre dışı olduğunu görürsünüz. Bu, beklenen bir davranıştır.

Google Cloud Console kullanıcı arayüzünde veri deposu ayrıntıları sayfasını görüntüleyin:

echo "data store details page url: https://console.cloud.google.com/gemini-enterprise/locations/${GE_LOCATION}/collections/${GE_COLLECTION_ID}/connector/details?project=${PROJ_ID}"

Özel bir MCP sunucusunu Gemini Enterprise'a nasıl bağladığınıza bağlı olarak araç keşfi ve yönetimi iki şekilde ele alınır:

• Doğrudan özel MCP (BYO_MCP iş akışı): Özel bir MCP sunucusunu Agent Registry olmadan doğrudan Gemini Enterprise'da yapılandırdığınızda araç kataloğunu (connectorModes: ["FEDERATED", "ACTIONS"]) veri deposu yönetir. tools/list şemasını getirmek için İşlemler sekmesini açıp ↻ Özel işlemleri yeniden yükle'yi tıklamanız ve kullanıcı arayüzünde tek tek araçları (add ve subtract) manuel olarak açıp kapatmanız gerekir.
• Agent Registry'den İçe Aktarma (REGISTRY_MCP Bu codelab'de kullanılan iş akışı): Agent Registry'den bir MCP sunucusu içe aktardığınızda Agent Registry, MCP uç noktası, arayüz meta verileri ve araç kataloğu (connectorModes: ["FEDERATED"]) için yetkili doğru kaynak olarak hizmet verir. Gemini Enterprise, veri deposu kullanıcı arayüzünde işlemleri manuel olarak yeniden yüklemenizi veya değiştirmenizi gerektirmeden, motorun Agent Gateway'i aracılığıyla kayıtlı MCP araçlarını çalışma zamanında otomatik olarak etkinleştirir.

NOT: Ajan Kayıt Defteri iş akışında, Gemini Enterprise veri deposunun İşlemler sekmesinde tek tek araçları etkinleştirmek veya devre dışı bırakmak yerine, Ajan Ağ Geçidi'ndeki Birleşik Erişim Politikaları'nı (destination.operation.mcp_tool.name) kullanarak ağın ucunda merkezi olarak hangi araçların (add veya subtract) keşfedilmesine ve çağrılmasına izin verileceğini yönetirsiniz.

Gemini Enterprise uygulaması bölümü sona erdi. Şimdi Doğrulama bölümüne geçiyoruz.

8. Doğrula

Bu bölümde, Gemini Enterprise web uygulamasından canlı MCP aracı çağrılarını tetikleyecek ve Agent Gateway, Cloud DNS, VPC güvenlik duvarı ve Cloud Run günlüklerindeki istek akışını izleyeceksiniz. Ardından, add öğesini engellerken subtract öğesine izin vermek için IAM Birleşik Erişim Politikası'nı sıkılaştırarak ağ geçidinde sıfır güven uygulamasını doğrulayacaksınız.

Kullanıcı erişimi

Gemini Enterprise web uygulamasının URL'sini oluşturun:

# fetch app user url
export GE_WIDGET_ID=$(curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}/widgetConfigs/default_search_widget_config" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  -H "Content-Type: application/json" \
  | jq -r '.configId')

export GE_APP_USER_URL="https://vertexaisearch.cloud.google.com/home/cid/${GE_WIDGET_ID}"

echo "app user url: ${GE_APP_USER_URL}"

Bağlantıyı tıklayarak tarayıcınızda Gemini Enterprise web uygulaması sohbet arayüzünü açın ve Başlayın'ı tıklayın.

Sohbetteki ajan sorgularını test etme

Sohbet kullanıcı arayüzünde, sohbet kutusunun alt kısmındaki Bağlayıcılar için yapboz parçası simgesini tıklayarak math-wizard-collection veri bağlayıcısının etkinleştirildiğini onaylayın. Açık (renkli) bir açma/kapatma düğmesi görürsünüz.

Aşağıdaki test sorgularını deneyin:

what is 2342345 - 98234798324?

what is 72347234 + 234234?

Asistanın doğru yanıtlar döndürdüğünü ve her yanıtın altında, aracın yürütüldüğünü onaylayan etkileşimli bir eylem alıntı rozeti (ör. Math Calculation (8s) 🤖 Agentgateway Agent) gösterdiğini doğrulayın.

Cloud Logging'deki günlükleri inceleme

Cloud Logging'deki günlükleri inceleyerek Gemini Enterprise'ın araç çağrılarını Agent Gateway ve özel VPC ağı üzerinden yönlendirdiğini doğrulayın.

1. Temsilci ağ geçidi ve IAP yetkilendirmesini doğrulama

Agent Gateway'in isteği yakaladığını, Agent Registry'de hedefi çözdüğünü, yetkilendirmeyi IAP'ye devrettiğini ve araç çağrısına izin verdiğini onaylayın:

# show agent gateway logs
gcloud logging read 'resource.type="networkservices.googleapis.com/Gateway"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    httpRequest.serverIp:label=SERVER_IP, \
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD, \
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    jsonPayload.agentGatewayInfo.agentRegistryResource.basename():label=REGISTRY_MCP
  )"

Çıktının aşağıdakileri içerdiğini doğrulayın:

• STATUS: 200 (başarılı yürütme) ve 202 (notifications/initialized el sıkışması).
• SERVER_IP: Google API'leri PSC uç nokta IP'si (172.16.20.20:443).
• MCP_METHOD ve TOOL: MCP protokol dizisi (notifications/initialized, tools/list ve tools/call ile add veya subtract).
• AUTHZ: ALLOWED (UİSA yetkilendirmesi çıkışa izin veriyor).
• REGISTRY_MCP: Çözümlenen Agent Registry kaynak kimliği (agentregistry-...).

2. DNS ve güvenlik duvarı geçişini doğrulama

Cloud DNS'nin ana makine adını PSC uç noktasına çözümlediğini ve güvenlik duvarının aracı ağ geçidi arayüzünden gelen trafiğe izin verdiğini doğrulayın:

# show dns logs
gcloud logging read 'resource.type="dns_query"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    jsonPayload.queryName:label=QUERY_NAME, \
    jsonPayload.queryType:label=TYPE, \
    jsonPayload.responseCode:label=RCODE, \
    jsonPayload.rdata:label=RDATA
  )"

# show firewall logs
gcloud logging read 'logName:"compute.googleapis.com%2Ffirewall"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    jsonPayload.connection.src_ip:label=SRC_IP, \
    jsonPayload.connection.dest_ip:label=DEST_IP, \
    jsonPayload.connection.dest_port:label=PORT, \
    jsonPayload.rule_details.reference.basename():label=RULE, \
    jsonPayload.disposition:label=DISPOSITION
  )"

Aşağıdaki değerleri doğrulayın:

• DNS QUERY_NAME & RDATA: math-wizard-...run.app. (A kaydı, NOERROR) öğesini 172.16.20.20 olarak çözer.
• Güvenlik duvarı SRC_IP & DEST_IP: 192.168.10.2 (Aracı ağ geçidi PSC arayüzü IP'si) ile 172.16.20.20:443 arasında.
• Güvenlik duvarı RULE ve DISPOSITION: firewallPolicy:fw-policy-... ile ALLOWED eşleşti.

3. Cloud Run aracının yürütülmesini doğrulama

Cloud Run kapsayıcısının araç çağrısını aldığını ve işlediğini onaylayın:

# show cloud run logs
gcloud logging read 'resource.type="cloud_run_revision"
  AND textPayload:"Tool:"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="value(timestamp.date(tz=LOCAL), textPayload)"

textPayload aracının, araç yürütme girişlerini (ör. >>> 🛠️ Tool: 'subtract' called with numbers '[x]' and '[y]') gösterdiğini doğrulayın.

En az ayrıcalık ilkesi yaptırımını test etme

İlk IAM erişim politikasında, hedef kayıtlı olduğu sürece (destination.is_registered == true) herhangi bir yönteme veya araca izin veriliyordu. Bu adımda, yalnızca subtract aracına izin verip add aracını engelleyerek politikayı en az ayrıcalık ilkesini uygulayacak şekilde güncelleyin.

IAM erişim politikasını güncelleme

MCP aracının yürütülmesini kısıtlarken iki kuraldan oluşan bir kalıp kullanın:

1. 1. Kural (MCP bulma ve el sıkışma): Araç çağrısı dışındaki MCP yaşam döngüsü yöntemlerine (destination.is_registered == true ve destination.agent_registry.mcp_server.method != 'tools/call') izin verir. Gemini Enterprise, bir aracı çağırmadan önce akış kurulumu ve bulma (initialize, notifications/initialized, tools/list) işlemlerini gerçekleştirdiğinden ve destination.agent_registry.mcp_server.tool.name yalnızca tools/call sırasında doldurulduğundan oturum başlatma ve katalog bulma işlemlerinin çalışmaya devam etmesi için 1. Kural gereklidir.
2. 2. Kural (Araç düzeyinde kısıtlama): tools/call yürütmesini kısıtlar. Böylece yalnızca subtract aracına izin verilir (destination.is_registered == true, destination.agent_registry.mcp_server.method == 'tools/call' ve destination.agent_registry.mcp_server.tool.name == 'subtract').

Erişim politikası kuralı manifest dosyasını her iki kuralı da içerecek şekilde güncelleyin:

# create access policy rule file (update: allow subtract only)
cat > cfg/${UAP_POLICY_NAME}-rule-update.json << EOF
[
  {
    "description": "allow ge assistant to any registered endpoint to perform mcp discovery and handshake",
    "effect": "ALLOW",
    "principals": [
      "principal://${TRUST_DOMAIN}/resources/discoveryengine/projects/${PROJ_NO}/locations/global/engines/${GE_APP_ID}/assistants/default_assistant/agents/default/core_assistant"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true && \
         destination.agent_registry.mcp_server.method != 'tools/call'"
      }
    }
  },
  {
    "description": "allow ge assistant to any registered mcp server with tool call subtract",
    "effect": "ALLOW",
    "principals": [
      "principal://${TRUST_DOMAIN}/resources/discoveryengine/projects/${PROJ_NO}/locations/global/engines/${GE_APP_ID}/assistants/default_assistant/agents/default/core_assistant"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true && \
         destination.agent_registry.mcp_server.method == 'tools/call' && \
         destination.agent_registry.mcp_server.tool.name == 'subtract'"
      }
    }
  }
]
EOF

NOT: IAP erişim politikasının güncellenmesi (bu durumda, subtract aracına açıkça izin verilirken add aracına örtülü olarak izin verilmez) politikanın geçerlilik kazanması ve HTTP 403 Forbidden yanıtının gözlemlenmesi için küresel olarak yayılması birkaç dakika sürebilir.

Güncellenen kuralları IAM erişim politikasına uygulayın:

# update iam access policy
gcloud iam access-policies update ${UAP_POLICY_NAME} \
  --details-rules=cfg/${UAP_POLICY_NAME}-rule-update.json \
  --project=${PROJ_ID} \
  --location=global

IAM erişim politikasını doğrulama

Yeni IAM erişim politikasının uygulandığını ve yalnızca çıkarma aracına izin verildiğini kontrol edin:

# show iam access policy details
gcloud iam access-policies describe ${UAP_POLICY_NAME} \
  --project=${PROJ_ID} \
  --location=global \
  --flatten="details.rules[]" \
  --format="table( \
    details.rules.principals[0].scope(engines).sub('assistants/default_assistant/agents/default', '...'):label=PRINCIPAL, \
    details.rules.effect:label=EFFECT, \
    details.rules.conditions.'iap.googleapis.com'.expression.sub('\s*&&\s*', '\n&& ').sub('\s*\|\|\s*', '\n|| '):label=EXPRESSION
  )"

Yasaklanmış bir araç çağrısını test etme

Gemini Enterprise web uygulaması sohbet kullanıcı arayüzüne dönüp başka bir test sorgusu deneyin:

what is 100 plus 20?

Asistan, add işlevini çağırmaya çalışır ancak Agent Gateway ve IAP, IAM politika koşulunu false olarak değerlendirir ve çıkış isteğini HTTP 403 Forbidden ile reddeder. Sohbet kullanıcı arayüzünde, engellenen araç çağrısı yeniden denenirken asistanın Calculate Sum simgesini gösterip 🤖 Agentgateway Agent ... Working on it. simgesini döndürdüğünü fark edeceksiniz. Bu, beklenen bir davranıştır. Agent Gateway ve IAP'nin, ağ düzeyinde izin verilmeyen araç yürütmelerini etkin bir şekilde engellediğini ve reddettiğini onaylar.

NOT: Engellenen add araç çağrısının zaman aşımına uğraması veya 403 Forbidden ile başarısız olması durumunda sohbet asistanı, kendi dahili model bilgisini kullanarak temel aritmetik işlemlere yanıt vermeye devam edebilir. Ancak bu durumda tamamlanmış MCP aracı alıntı rozetinin görünmeyeceğini unutmayın.

Cloud Logging'deki günlükleri yeniden inceleme

Agent Gateway günlük girişlerini görüntüleyin ve izin verilmeyen add araç çağrısına karşılık gelen yeni 403 girişlerini inceleyin:

# show agent gateway logs
gcloud logging read 'resource.type="networkservices.googleapis.com/Gateway"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    httpRequest.serverIp:label=SERVER_IP, \
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD, \
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    jsonPayload.agentGatewayInfo.agentRegistryResource.basename():label=REGISTRY_MCP
  )"

Beklenen çıkış:

TIMESTAMP            STATUS  SERVER_IP         MCP_METHOD                 TOOL  AUTHZ    REGISTRY_MCP
YYYY-MM-DDTHH:MM:SS  403                       tools/call                 add   DENIED   agentregistry-00000000-0000-0000-0012-3456789abcde
YYYY-MM-DDTHH:MM:SS  403
YYYY-MM-DDTHH:MM:SS  202     172.16.20.20:443  notifications/initialized        ALLOWED  agentregistry-00000000-0000-0000-0012-3456789abcde
YYYY-MM-DDTHH:MM:SS          172.16.20.20:443                                   ALLOWED  agentregistry-00000000-0000-0000-0012-3456789abcde
YYYY-MM-DDTHH:MM:SS  200     172.16.20.20:443  initialize                       ALLOWED  agentregistry-00000000-0000-0000-0012-3456789abcde

Ek isteğin Cloud Run arka ucuna hiç ulaşmadığını kontrol edin:

# show cloud run logs
gcloud logging read 'resource.type="cloud_run_revision"
  AND textPayload:"Tool:"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="value(timestamp.date(tz=LOCAL), textPayload)"

Komut yeni giriş döndürmez. Bu, Agent Gateway'in IAM erişim politikasını başarıyla uyguladığını onaylar.

NOT: Gemini Enterprise aracıları ile özel MCP veri bağlayıcıları arasındaki doğrudan iletişim, bir çıkış ağ geçidi üzerinden açıkça yönlendirilmediği sürece Agent Gateway politika uygulamasını tetiklemez. Daha fazla bilgi için Agent Registry'den MCP sunucularını içe aktarma başlıklı makaleyi inceleyin.

Doğrulama bölümünün sonuna geldik. Şimdi Temizleme bölümüne geçiyoruz.

9. Temizleme

Bu laboratuvarda oluşturulan kaynakları ve yapılandırmaları silmek için aşağıdaki adımları uygulayın.

Gemini Enterprise bileşenlerini kaldırma

# delete gemini enterprise engine (app)
curl -s -X DELETE "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

# delete custom mcp collection, data connector, and backing data store
curl -s -X DELETE "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/${GE_COLLECTION_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

# reset identity provider configuration
curl -s -X PATCH "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/aclConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  -H "Content-Type: application/json" \
  -d '{"idpConfig":{"idpType":"IDP_TYPE_UNSPECIFIED"}}'

MCP sunucusu bileşenlerini kaldırma

# delete agent registry service
gcloud -q agent-registry services delete ${MCP_NAME} \
  --location=${REGION} \
  --project=${PROJ_ID}

# delete cloud run service, source-deploy artifact registry repo, and staging bucket
gcloud -q run services delete ${MCP_NAME} \
  --region=${REGION} \
  --project=${PROJ_ID}

gcloud -q artifacts repositories delete cloud-run-source-deploy \
  --location=${REGION} \
  --project=${PROJ_ID}

gcloud -q storage rm --recursive gs://run-sources-${PROJ_ID}-${REGION} \
  --project=${PROJ_ID}

Aracı ağ geçidini ve IAM erişim politikalarını kaldırma

# delete gateway authorization policy, iap extension, and agent gateway
gcloud -q network-security authz-policies delete ${AGW_NAME}-authz-policy-iap \
  --location=${REGION} \
  --project=${PROJ_ID}

gcloud -q service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap \
  --location=${REGION} \
  --project=${PROJ_ID}

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

# delete iam policy binding and access policy
gcloud -q iam policy-bindings delete ${UAP_BINDING_NAME} \
  --location=global \
  --project=${PROJ_ID}

gcloud -q iam access-policies delete ${UAP_POLICY_NAME} \
  --location=global \
  --project=${PROJ_ID}

DNS ve güvenlik duvarı bileşenlerini kaldırma

# delete dns record set, managed zone, and policy
gcloud -q dns record-sets delete "*.run.app." \
  --type=A \
  --zone=priv-zone-run \
  --project=${PROJ_ID}

gcloud -q dns managed-zones delete priv-zone-run \
  --project=${PROJ_ID}

gcloud -q dns policies update dns-policy-${SLUG} \
  --networks="" \
  --project=${PROJ_ID}

gcloud -q dns policies delete dns-policy-${SLUG} \
  --project=${PROJ_ID}

# delete firewall policy association, rule, and policy
gcloud -q compute network-firewall-policies associations delete \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --project=${PROJ_ID}

gcloud -q compute network-firewall-policies rules delete 1001 \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --project=${PROJ_ID}

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} \
  --global \
  --project=${PROJ_ID}

PSC ve VPC ağı bileşenlerini kaldırma

# delete psc forwarding rule and internal ip address
gcloud -q compute forwarding-rules delete psc2gapis \
  --global \
  --project=${PROJ_ID}

gcloud -q compute addresses delete ip-psc2gapis \
  --global \
  --project=${PROJ_ID}

# delete psc network attachment, subnet, and vpc network
gcloud -q compute network-attachments delete psc-na-${REGION}-agw \
  --region=${REGION} \
  --project=${PROJ_ID}

gcloud -q compute networks subnets delete subnet-${REGION}-agw \
  --region=${REGION} \
  --project=${PROJ_ID}

gcloud -q compute networks delete vnet-${SLUG} \
  --project=${PROJ_ID}

Kuruluş politikası geçersiz kılmalarını ve yerel dosyaları kaldırma

# delete project-level organization policy overrides
gcloud -q org-policies delete discoveryengine.managed.disableCustomMcpServerConnector --project=${PROJ_ID}
gcloud -q org-policies delete iam.managed.disableAccessPolicyBinding --project=${PROJ_ID}

# remove local project files
rm -rf cfg math-wizard

Temizleme işlemi tamamlandı. Şimdi Sonuç bölümüne geçiyoruz.

10. Sonuç

Tebrikler! Gemini Enterprise uygulamasının, özel bir MCP sunucusundaki araçları güvenli bir şekilde keşfetmesini ve çağırmasını sağlayan uçtan uca bir mimari oluşturdunuz:

• Özel MCP sunucusu ve Agent Registry: Cloud Run'da özel bir FastMCP hizmeti dağıtıldı (--ingress=internal) ve uç noktası ile araç şeması (add ve subtract) Agent Registry'ye kaydedildi.
• Gemini Enterprise entegrasyonu: Gemini Enterprise uygulaması sağlandı, giden araç trafiği Agent Gateway'e bağlandı ve kayıtlı MCP sunucusu REGISTRY_MCP veri bağlayıcısı olarak eklendi.
• Özel VPC çıkışı ve sıfır güven yönetimi: PSC (172.16.20.20) üzerinden özel olarak yönlendirilen araç yürütme ve IAP ile IAM Birleşik Erişim Politikaları (destination.agent_registry.*) kullanılarak araç düzeyinde en az ayrıcalık uygulanması.

Cosmpup, Codelab'lerin kesinlikle harika 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ırın.
• İşletme kurallarını ve doğal dil sorgularıyla ilgili 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!