Gemini Enterprise Ajan Platformu'ndaki Agent Gateway ile temsilci tabanlı iş yüklerini yönetme

1. Giriş

Gemini Enterprise Agent Platform, verilerinize dayalı kurumsal düzeyde yapay zeka temsilcileri oluşturmak, ölçeklendirmek, yönetmek ve optimize etmek için kullanılan açık bir platformdur.

Agent Runtime, açık kaynaklı Agent Development Kit (ADK) ile oluşturulanlar gibi aracıları Google Cloud'da güvenli bir şekilde çalıştırmak için yönetilen yürütme ortamını sağlar.

Bu codelab'de, Gemini Enterprise'da bir kullanıcı tarafından başlatılan ve dahili araçlara güvenli bir şekilde ulaşan bir aracı yönetmek için bu temel yapı taşlarının nasıl kullanılacağı ele alınmaktadır.

Agent Gateway hakkında

Agent Gateway, platformun Agent Governance paketinin ağ oluşturma bileşenidir. Tüm aracı etkileşimleri için ağ giriş ve çıkış noktası olarak işlev görür. Böylece güvenlik yöneticileri, geliştiricilerin karmaşık ağ oluşturma temel öğelerini yönetmesini gerektirmeden merkezi yönetimi zorunlu kılabilir.

İki temel yönetilen erişim yolunu kolaylaştırır:

  • Müşteriden temsilciye (giriş): Harici müşteriler (ör. Cursor veya Gemini CLI) ile temsilcileriniz arasındaki iletişimi korur.
  • Agent-to-Anywhere (çıkış): Google Cloud'da çalışan aracılar ile herhangi bir yerde çalışan sunucular, araçlar veya API'ler arasındaki iletişimi güvenli hale getirir.

Bu codelab'de Agent-to-Anywhere (egress) moduna odaklanacaksınız.

Ajan Geçidi ile erişim denetimi

Agent Gateway, güvenlik politikalarını zorunlu kılmak için ekosistemin geri kalan kısmıyla sıkı bir şekilde entegre olur:

  • Agent Registry: Onaylanmış müşteri temsilcilerinin ve araçların (üçüncü taraf MCP sunucuları dahil) merkezi kitaplığı.
  • Aracı Kimliği: Her aracı için benzersiz ve izlenebilir bir karakter. Uçtan uca mTLS ile otomatik olarak güvenli hale getirilir.
  • Kimliğe Duyarlı Proxy (IAP) ve IAM: Belirli araçlara yapılan çağrılara izin verilmeden önce aracının kimliğini ayrıntılı IAM izinlerine göre doğrulayan varsayılan zorunlu kılma katmanı.
  • Model Armor: İçeriği temizlemek ve istem enjeksiyonu saldırılarına veya veri sızıntısına karşı koruma sağlamak için Hizmet Uzantıları aracılığıyla entegre edilen bir yapay zeka güvenlik bariyeri.

Dağıtım modları (Cloud Run için herkese açık ve özel ağ)

Bu codelab'e erişimi kolaylaştırmak için Cloud Run'da dağıtılan dahili araçlarınız (MCP sunucuları) için iki ağ oluşturma yolu arasından seçim yapabilirsiniz:

  1. Varsayılan (Herkese Açık Giriş): MCP sunucuları, herkese açık ana makine adlarıyla (ingress=all) Cloud Run'a dağıtılır. Trafik, standart *.run.app URL'leri üzerinden aracıdan araçlara yönlendirilir. Bu, özel DNS alanları gerektirmez ve yönetim kavramlarını öğrenmenin en hızlı yoludur.
  2. Güvenli (Özel Ağ): İsteğe bağlı, tamamen özel bir mimaridir. MCP sunucuları kısıtlanmıştır (ingress=internal-and-cloud-load-balancing) ve sunucusuz NEG ile dahili bir uygulama yük dengeleyicisi üzerinden kullanıma sunulur. Bu, Google tarafından yönetilen bir sertifika sağlamak için herkese açık bir DNS alanına sahip olmanızı gerektirir.

Terraform'u yapılandırırken tercih ettiğiniz yolu seçersiniz.

Cloud Run için ağ uç noktası girişi hakkında daha fazla bilgi edinmek istiyorsanız lütfen belgelerimizi okuyun.

Yapacaklarınız

  • Terraform'u kullanarak temel altyapı yığınını sağlama
  • Dahili araçları Cloud Run'da MCP sunucuları olarak oluşturma ve dağıtma
  • PSC arayüzü çıkışını kullanarak Agent Runtime'a ADK aracısı dağıtma
  • Kimliğe dayalı erişim (IAM) ve içerik tarama (Model Armor) için Agent Gateway hizmeti uzantılarını yapılandırma
  • Aracının güvenli uçtan uca yürütülmesini izleme ve doğrulama

İhtiyacınız olanlar

  • Chrome gibi bir web tarayıcısı
  • Faturalandırmanın etkin olduğu ve Sahip erişimine sahip bir Google Cloud projesi
  • Kuruluş düzeyinde IAM izinleri (codelab, kuruluş kapsamlı roller verir)
  • Herkese açık olarak yönetilen sertifika için Cloud DNS'ye temsilci olarak atanmış, kontrol ettiğiniz bir alan
  • Terraform, gcloud ve temel Google Cloud ağı hakkında bilgi sahibi olma

Codelab topolojisi

Uçtan uca mimari: Gemini Enterprise'dan Agent Runtime'a, Agent Gateway'den Cloud Run'daki MCP sunucularına

Bu codelab'de, üç dahili araçla güvenli bir şekilde iletişim kuran uçtan uca bir ipotek sigortası aracısı dağıtacaksınız.

Öncelikle, aracı ağ geçidiniz olarak yapılandırılmış bir VPC ve dahili uygulama yük dengeleyici de dahil olmak üzere temel ağ oluşturma işlemlerini sağlayacaksınız. Ardından, Cloud Run'a üç Model Context Protocol (MCP) sunucusu dağıtacaksınız. Bunlar, dahili tescilli araçlarınız olarak işlev görür:

  • Belge Yönetimi (legacy-dms)
  • Kurumsal e-posta (corporate-email)
  • Gelir Doğrulama (income-verification)

Araçlar hazır olduğunda, ADK ile oluşturulmuş bir Mortgage Asistanı'nı (mortgage-agent) Agent Runtime'a dağıtacaksınız. Bu ajanı, özel çıkış için bir PSC arayüzü kullanacak şekilde yapılandıracak ve Agent Registry aracılığıyla çalışma zamanı aracı keşfini etkinleştireceksiniz.

Akışı güvenli hale getirmek için Agent Gateway'inizi iki hizmet uzantısıyla yapılandıracaksınız. İlk olarak, bir REQUEST_AUTHZ uzantısı, aracı kimliğini araç başına IAM politikalarına göre doğrulayarak aracının yalnızca yetkili araçlara erişmesini sağlar. İkincisi olarak, Model Armor kullanan bir CONTENT_AUTHZ uzantısı, aracının istemlerini ve yanıtlarını tarar.

Son olarak, aracıyı Gemini Enterprise'a kaydedecek, son kullanıcı olarak bir ipotek sigortası görevi başlatacak ve Cloud Trace'i kullanarak güvenli ve yönetilen yürütmeyi doğrulayacaksınız.

Bu codelab, her seviyeden platform ve güvenlik mühendisleri içindir. Bu işlemi tamamlamak yaklaşık 100 dakika sürer.

2. Başlamadan önce

Proje oluşturma ve kimlik doğrulama

Faturalandırmanın etkin olduğu yeni bir GCP projesi oluşturun (veya mevcut bir projeyi yeniden kullanın), ardından Cloud Shell'in veya yerel makinenizin kimliğini doğrulayın:

gcloud auth login
gcloud auth application-default login
gcloud config set project <your-project-id>

Bootstrap API'lerini etkinleştirme

Terraform'un temel modülü, ilk uygulamada yaklaşık 30 API'yi etkinleştirir ancak terraform init ve GCS durum paketi için küçük bir bootstrap grubu gerekir:

gcloud services enable \
  compute.googleapis.com \
  serviceusage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  iam.googleapis.com \
  storage.googleapis.com \
  dns.googleapis.com

Gerekli araçları yükleme

Araç zincirini yükleyin. Cloud Shell'de bunların çoğu zaten mevcuttur. İş istasyonunda ise:

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
  sudo install skaffold /usr/local/bin/

# envsubst (gettext)
sudo apt-get install -y gettext-base

Ayrıca Terraform >= 1.12.2, Python 3.12+ ve Google Cloud SDK'yı (gcloud) da yüklemeniz gerekir.

Ortam değişkenlerini ayarlama

Bu codelab'in geri kalanında, bunların kabuğunuza aktarıldığı varsayılır.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export ORG_ID=$(gcloud projects get-ancestors $PROJECT_ID | awk '$2 == "organization" {print $1}')
export REGION="us-central1"

# Only required if using the secure private networking path
export DOMAIN_NAME="agw.example.com"

Tüm değişkenlerinizin doğru şekilde doldurulduğunu doğrulayın. Üç değer döndürülmelidir.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Kuruluş kimliğiniz otomatik olarak doldurulmazsa kimliği bulup manuel olarak ayarlayabilirsiniz.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Depoyu klonlama 

git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git
cd cloud-networking-solutions
cd demos/agent-gateway

Demo dizininde neler olduğuna dair kısa bir tur:

src/                MCP servers (legacy-dms, corporate-email, income-verification-api) + mortgage-agent
terraform/          Root Terraform config + modules (foundation, networking, agent-gateway, model-armor, ...)
cloudrun/           Cloud Run service definitions (rendered from .yaml.tmpl via envsubst)
scripts/            grant_agent_mcp_egress.sh — per-MCP IAP egressor binding
skaffold.yaml.tmpl  Skaffold pipeline that builds + deploys all three MCP services to Cloud Run

4. Terraform durumu paketi ve arka uç yapılandırmasını oluşturma

Uzak durumu tutmak için bir GCS paketi oluşturun, ardından arka uç şablonunu kopyalayın:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

terraform/backend.conf değerini kendi değerlerinizle düzenleyin:

bucket = "<your-project-id>-tfstate"
prefix = "agent-gateway"

5. (İsteğe bağlı) Herkese açık bir Cloud DNS bölgesi oluşturun

Bu laboratuvarda Cloud Run'ın giriş yapılandırması varsayılan olarak all şeklinde ayarlanmıştır ve Agent Registry, her MCP sunucusunu herkese açık *.run.app URL'sinde kaydeder. Ek DNS, sertifika veya yük dengeleyici gerekmez. Özel ağa (dahili uygulama LB'si arkasında ingress = internal-and-cloud-load-balancing ile Cloud Run) geçmek istiyorsanız Certificate Manager'ın LB sertifikasını doğrulayabilmesi için herkese açık bir Cloud DNS bölgesi de gerekir.

Özel ağ iletişimiyle ilgili üst düzey akış

Özel ağ seçeneğinin üst düzey akışı

Özel ağ yaklaşımını kullanmak için:

  1. Herkese açık Cloud DNS bölgesini oluşturun. Certificate Manager, CNAME'leri bu bölgeye yazarak bölgesel yönetilen sertifikayı doğrular:
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

mcp.${DOMAIN_NAME} için karşılık gelen özel bölge (MCP dahili yük dengelemesi ve Agent Runtime'dan DNS eşlemesi tarafından kullanılır) Terraform tarafından otomatik olarak oluşturulur. Bu bölgeyi manuel olarak oluşturmanız gerekmez. Özel ağ devre dışıyken ne genel ne de özel bölge sağlanır.

6. Terraform değişkenlerini yapılandırma

Örnek tfvars dosyasını kopyalayın ve düzenleyin:

cp terraform/example.tfvars terraform/terraform.tfvars

enable_cloud_run_private_networking ile korunan iki demo yolu vardır.

Varsayılan yol: Genel girişli Cloud Run

En basit kurulum: Varsayılan yol için terraform.tfvars bölümünde yalnızca üç değeri düzenlemeniz gerekir. Dosyadaki diğer tüm değişkenler, demoya uygun bir varsayılan değere sahiptir.

# GCP project ID where all resources will be created.
project_id = "my-gcp-project-id"

# GCP organization ID (numeric).
organization_id = "123456789012"

# Members granted demo-wide roles
platform_admin_members = ["user:admin@example.com"]

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = "DRY_RUN"

Özel ağ iletişimi (isteğe bağlı)

Tam güvenli yığını sağlamak için enable_cloud_run_private_networking = true değerini ayarlayın ve aşağıdaki değişkenleri ekleyin:

  • Dahili uygulama LB'si
  • Google tarafından yönetilen sertifika
  • Cloud Run ile ingress = internal-and-cloud-load-balancing
  • Agent Gateway DNS eşlemesi.
enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

7. Terraform ile altyapı dağıtma

Başlatma, inceleme ve uygulama:

cd terraform
terraform init -backend-config=backend.conf
terraform plan -out=tfplan
terraform apply tfplan

terraform apply, varsayılan yolda yaklaşık 40 kaynak sağlar ve yeni bir projede 8-10 dakika sürer (enable_cloud_run_private_networking = true kullanıldığında yaklaşık 60 kaynak / 15-20 dakika). Aşağıdakileri oluşturur:

  • Proje temeli (API'ler, hizmet kimlikleri, kotalar)
  • VPC, alt ağlar (birincil, yalnızca proxy, PSC, PSC-Interface, Agent Gateway ortak konumlandırma), Cloud NAT, güvenlik duvarı kuralları
  • Cloud Run görüntüleri için Artifact Registry deposu
  • Üç Cloud Run hizmeti + hizmet başına çalışma zamanı SA'ları (giriş = varsayılan olarak all; özel ağ iletişimi etkin olduğunda internal-and-cloud-load-balancing)
  • Model Armor şablonu + IAM
  • Agent Gateway, PSC-I ağ eki, IAP ve Model Armor uzantıları, her iki yetkilendirme politikası ve proje düzeyinde roles/iap.egressor izni
  • Agent Registry uç noktaları (Vertex AI, IAP, Discovery Engine, ...) ve üç MCP sunucusu (varsayılan olarak *.run.app/mcp'da, özel ağ etkin olduğunda ./mcp'da kayıtlı)

Yalnızca enable_cloud_run_private_networking = true olduğunda:

  • Sunucusuz NEG (URL maskesi yönlendirme) + özel DNS A kayıtları ile dahili bölgesel uygulama yük dengeleyici
  • VPC'ye bağlı MCP özel DNS bölgesi (mcp..)
  • Herkese açık DNS bölgesi modülü (Certificate Manager DNS yetkilendirmeleri) + bölgesel Google tarafından yönetilen sertifika
  • PSC arayüzü DNS bölgesi (çözümlenecek özel ana makine adı olmadığında bağımsızdır, bu nedenle ana işaretle de sınırlanır)
  • mcp.. için Agent Gateway DNS eşleme (otomatik olarak eklenir)

8. Aracı Kayıt Defteri uç noktalarını inceleme

Aracı Kayıt Defteri, bir aracının çalışma zamanında keşfettiği hizmetlerin (Google API'leri ve kendi MCP sunucularınız) proje bazında bir kataloğudur. Mortgage aracısı, başlatma sırasında bu kataloğu okur ve araçları dinamik olarak bağlar. Aracı koduna veya dağıtım komutuna MCP URL'leri yerleştirilmez.

Uç noktalar

Terraform'un sizin adınıza yaptığı işlemler: agent_registry_google_apis içindeki her Google API için beş varyant (global, mTLS global, bölgesel, bölgesel mTLS, bölgesel REP) kaydetti. Örneğin, aiplatform için:

gcloud alpha agent-registry services create aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-mtls \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform mTLS" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.mtls.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create ${REGION}-aiplatform \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Locational" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://${REGION}-aiplatform.googleapis.com,protocolBinding=JSONRPC"

gcloud alpha agent-registry services create aiplatform-${REGION}-rep \
  --project=${PROJECT_ID} --location=${REGION} \
  --display-name="Vertex AI Platform Regional (REP)" \
  --endpoint-spec-type=no-spec \
  --interfaces="url=https://aiplatform.${REGION}.rep.googleapis.com,protocolBinding=JSONRPC"

MCP sunucuları

Terraform, 3 MCP sunucusunu da sizin için kaydeder. Diğer MCP sunucularını kaydetmek için dokümandaki adımları uygulayabilirsiniz.

gcloud alpha agent-registry services create legacy-dms \
--project=${PROJECT_ID} \
--location=${REGION} \
--display-name="Legacy DMS" \
--mcp-server-spec-type=tool-spec \
--mcp-server-spec-content=src/legacy-dms/toolspec.json \
--interfaces=url=https://dms.${DOMAIN_NAME}/mcp,protocolBinding=JSONRPC

Kayıtlı uç noktaları ve MCP sunucularını doğrulayın.

gcloud alpha agent-registry services list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION} \
  --format="value(displayName,name)"

Kaynak: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl

9. Aracı ağ geçidi yapılandırmasını inceleyin

Agent Gateway, Agent Runtime ile araçlarınız arasında Google tarafından yönetilen bir yönetim katmanıdır. AGENT_TO_ANYWHERE modunda, projenin Agent Registry'sine bağlıdır ve VPC'nizdeki özel MCP sunucularına ulaşabilmesi için müşteriye ait bir PSC arayüzü üzerinden çıkış yapar.

Bu ağ geçidini manuel olarak içe aktarıyorsanız YAML şöyle görünür:

# agent-gateway.yaml — for reference only, Terraform already created this
name: agent-gateway
protocols: [MCP]
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/agent-gateway-na
  dnsPeeringConfig:
    domains:
      - mcp.${DOMAIN_NAME}.
    targetProject: ${PROJECT_ID}
    targetNetwork: projects/${PROJECT_ID}/global/networks/gateway-vpc

gcloud alpha network-services agent-gateways import agent-gateway \
  --source=agent-gateway.yaml \
  --location=${REGION}

Ağ geçidinin Terraform tarafından oluşturulduğunu doğrulayın:

gcloud alpha network-services agent-gateways describe agent-gateway \
  --location=${REGION}

10. UİSA ve Model Armor yetkilendirmesini inceleme

Agent Gateway, yetkilendirmeyi hizmet uzantılarına devreder. Demoyu iki politika profili kapsar:

  • REQUEST_AUTHZ: Başlıklar aşamasında istek başına bir kez değerlendirilir. Burada, arayan aracı kimliğinin hedef MCP sunucusunda roles/iap.egressor olup olmadığını kontrol eden IAP'yi çağırmak için kullanılır.
  • CONTENT_AUTHZ: İçeriğin temizlenmesi için gövde etkinliklerini uzantıya aktarır. Burada, istem enjeksiyonu, jailbreak, RAI ihlalleri ve (isteğe bağlı olarak) Hassas Veri Koruması (SDP) aracılığıyla kimliği tanımlayabilecek bilgiler için tarama yapan Model Armor'u çağırmak için kullanılır.

IAP REQUEST_AUTHZ uzantısı

cat > iap-authz-extension.yaml <<EOF
name: agent-gateway-iap-authz
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-iap-authz \
  --source=iap-authz-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

REQUEST_AUTHZ politikasıyla Agent Gateway'e bağlayın:

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-iap-policy" \
  -d '{
    "name": "agent-gateway-iap-policy",
    "policyProfile": "REQUEST_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-iap-authz"
        ]
      }
    }
  }'

Model Armor CONTENT_AUTHZ uzantısı

Uzantının metadata.model_armor_settings bölümünde, Model Armor'un her açıklama metnini değerlendirmek için kullandığı istek ve yanıt şablonu kimlikleri yer alır:

cat > ma-extension.yaml <<EOF
name: agent-gateway-ma-authz
service: modelarmor.${REGION}.rep.googleapis.com
failOpen: true
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id":  "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-request-template",
      "response_template_id": "projects/${PROJECT_ID}/locations/${REGION}/templates/agw-response-template"
    }
  ]'
EOF

gcloud beta service-extensions authz-extensions import agent-gateway-ma-authz \
  --source=ma-extension.yaml \
  --location=${REGION} \
  --project=${PROJECT_ID}

curl -fsS -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -X POST "https://networksecurity.googleapis.com/v1alpha1/projects/${PROJECT_ID}/locations/${REGION}/authzPolicies?authz_policy_id=agent-gateway-ma-policy" \
  -d '{
    "name": "agent-gateway-ma-policy",
    "policyProfile": "CONTENT_AUTHZ",
    "action": "CUSTOM",
    "target": {
      "resources": [
        "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/agentGateways/agent-gateway"
      ]
    },
    "customProvider": {
      "authzExtension": {
        "resources": [
          "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/authzExtensions/agent-gateway-ma-authz"
        ]
      }
    }
  }'

Özel DLP şablonları

Model Armor'un sdpSettings.basicConfig özelliği, yerleşik bir infoType listesi kullanır. Daha hassas kontrol (özel infoType'lar, kısmi maskeleme, yedekle değiştirme, olasılığa göre redaksiyon) için Model Armor'u sdpSettings.advancedConfig aracılığıyla kendi Cloud DLP inspect ve de-identify şablonlarınıza yönlendirin.

ABD vatandaşlık numaralarını POSSIBLE olasılıkla veya daha yüksek bir olasılıkla işaretleyen bir inceleme şablonu oluşturun:

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

Her bulguyu info-type jetonuyla (ör. [US_SOCIAL_SECURITY_NUMBER]) değiştiren bir kimliksizleştirme şablonu oluşturun:

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

Ardından, sdpSettings.advancedConfig aracılığıyla bir Model Armor şablonunun yanıt yapılandırmasını çifte yönlendirin (Bu, Terraform'un model_armor modülünün, bağlarsanız advanced_config'yi ayarlayacağı yerdir):

{
  "filterConfig": {
    "sdpSettings": {
      "advancedConfig": {
        "inspectTemplate":    "projects/${PROJECT_ID}/locations/${REGION}/inspectTemplates/agw-ssn-inspect-template",
        "deidentifyTemplate": "projects/${PROJECT_ID}/locations/${REGION}/deidentifyTemplates/agw-ssn-redaction-template"
      }
    }
  }
}

IAP egressor IAM (yalnızca MCP sunucusu başına)

Terraform, örtülü IAP aracısı kaydında proje genelinde roles/iap.egressor bağlantısı oluşturmaz. Bağlama IAP REQUEST_AUTHZ, aslında MCP sunucusu ve muhakeme motoru başına değerlendirilir. Bu bağlama, aracı dağıtıldıktan ve aracı kimliğini öğrendikten sonra verilir. Bunun için "Grant the agent per-MCP-server egress" (Aracının MCP sunucusu başına çıkış izni verme) adımı scripts/grant_agent_mcp_egress.sh çalıştırılır.

11. MCP sunucularını oluşturup Cloud Run'a dağıtma

cloudrun/*.yaml.tmpl ve skaffold.yaml.tmpl dosyaları ${PROJECT_ID}, ${REGION} ve ${MCP_INGRESS}'yi (Cloud Run giriş notu) referans alır. Oluşturulan manifestoların enable_cloud_run_private_networking ile senkronize kalması için Terraform çıkışından MCP_INGRESS kaynağını alın, ardından envsubst ile oluşturun:

Cloud Run giriş yapılandırmanızı dışa aktarın.

  • all
  • internal-and-cloud-load-balancing (Özel ağ yaklaşımı kullanılırken)
export MCP_INGRESS=all

Kök demo dizinine geri dönün:

cd ..

Şablon değerlerini değiştirin:

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Her Cloud Run hizmeti, hizmet başına çalışma zamanı SA Terraform'u olarak çalışır (ör. mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Bu SA'lar olarak dağıtım yapmak için kendinizde roles/iam.serviceAccountUser olmalıdır:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountUser"

Cloud Build ile derleme ve Skaffold ile dağıtım:

skaffold run

Skaffold, Artifact Registry deponuzda üç resim (legacy-dms, corporate-email, income-verification-api) oluşturur ve her Cloud Run hizmetini yeni özet işaret edecek şekilde günceller.

Doğrulama:

gcloud run services list --region=${REGION}

Üç hizmetin de ACTIVE durumunda olduğunu görmelisiniz.

12. Mortgage aracısını Agent Runtime'a dağıtma

Kayıt otoritesine kaydettiğimiz tüm uç noktalarda tüm aracılara IAP Egressor rolü verin. Aracı, bu uç noktalara erişmelidir. Çünkü dağıtılırken paketler için github.com'ya ve ardından dağıtım için gereken çeşitli Google API'lerine ulaşması gerekir.

./scripts/grant_agent_mcp_egress.sh --bind-all-agents --endpoints

Aracının bağımlılıklarını yükleyin ve dağıtın:

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --mcp-invoker-sa=$(terraform -chdir=../../terraform output -raw agent_mcp_invoker_email) \
  --model-endpoint-location=global

Komut dosyası tamamlandığında, yazdırılan reasoningEngines/ değerini kabuğunuza kopyalayın (ör. 4262292559201566720):

export AGENT_ID=<numeric-id-from-output>
cd ../..

13. Ajanın MCP sunucusu başına çıkış izni verin.

IAP REQUEST_AUTHZ uzantısı, aracının çağırdığı belirli MCP sunucusunda veya uç noktasında roles/iap.egressor değerini kontrol ederek her araç çağrısını yetkilendirir. Aracıdan MCP sunucusuna çıkış politikası oluşturma başlıklı makaleyi inceleyin.

Komut dosyası (scripts/grant_agent_mcp_egress.sh), projects/${PROJECT_ID}/locations/${REGION} altındaki Agent Registry'de MCP sunucularını numaralandırır ve aracı asıl öğesi için bir roles/iap.egressor bağlamasını her sunucunun IAM politikasıyla birleştirir (gcloud add-iam-policy-binding semantiğini yansıtır).

1. kullanım alanı: Belirli MCP sunucularıyla sınırlı koşulsuz izin

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "legacy-dms income-verification"

2. kullanım alanı: Belirli bir MCP sunucusuyla sınırlı koşullu izin (CEL)

Aracıyı tek bir MCP sunucusundaki araçların bir alt kümesiyle sınırlamak için bir IAM koşulu ekleyin. Aracı Ağ Geçidi, IAP REQUEST_AUTHZ'nin CEL'ye sunduğu araç başına özellikleri yayınlar. Bunlar arasında şunlar yer alır:

  • iap.googleapis.com/mcp.toolName
  • iap.googleapis.com/mcp.tool.isReadOnly
  • iap.googleapis.com/request.auth.type.

Aracı, corporate-email üzerinde yalnızca salt okunur araçlarla sınırlandırın:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID} \
  --mcp-filter "corporate-email" \
  --condition-expression "api.getAttribute('iap.googleapis.com/mcp.tool.isReadOnly', false) == true || api.getAttribute('iap.googleapis.com/mcp.toolName', '') == ''" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Bu işlem çalıştırıldıktan sonra, IAP REQUEST_AUTHZ'den corporate-email return 403 PermissionDenied üzerinde araçları yazın; salt okunur araçlar çalışmaya devam eder.

Bağlamaları doğrulama

Politikalar sekmesine gidin. Uç noktalar ve MCP sunucularına karşı oluşturulan politikaların listesini görürsünüz.

Ek Kullanım Alanları:

Her MCP sunucusunda koşulsuz izin verilir ve kapsamı tek bir aracıyla sınırlıdır.

Bu komutu her aracı yeniden dağıtımından sonra çalıştırın. Filtre ve koşul olmadığında, adlandırılmış aracı, kayıt defterindeki her MCP sunucusunda roles/iap.egressor alır:

./scripts/grant_agent_mcp_egress.sh \
  --mcp \
  --agent-id ${AGENT_ID}

14. Aracıyı Agent Platform Console'da test etme

Aracı Platformu konsolunda, dağıtılan aracıyla doğrudan sohbet etmenizi sağlayan bir Playground bulunur. Bu, aracı Gemini Enterprise'a bağlamadan önce araç çağrılarını hızlı bir şekilde test etmenin ve izlemeleri incelemenin en hızlı yoludur.

  1. Google Cloud Console'da Agent Platform Deployments (Aracı Platformu Dağıtımları) sayfasını açın.
  2. Çalışma zamanı listesini daraltmanız gerekiyorsa Filtre alanını kullanın, ardından mortgage-agent çalışma zamanınızı tıklayın.
  3. Playground sekmesini açın.
  4. Temsilciyle sohbet etmek için bir istem yazın:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Bu işlem, Belge Yönetimi aracı ve Gelir Doğrulama aracından bir yanıt döndürmelidir. Bu yanıtta, Sosyal Güvenlik Numaraları da karartılmalıdır. 5. Ek soru yazın:

Can you send a summary of this to my email jane@example.com

IAP uzantısı deneme modunda olduğundan koşullu politika uygulanmadığı için aracı e-postayı başarıyla gönderebilir.

Ajan OpenTelemetry enstrümanı ile dağıtıldığından Playground, ajan yanıt verirken aralarında geçiş yapabileceğiniz dört yan panel görünümü sunar:

  • İzleme: Agent Gateway, IAP REQUEST_AUTHZ ve Model Armor CONTENT_AUTHZ aralıkları dahil olmak üzere görüşmenin tüm izleri
  • Etkinlik: Geçerli dönüş için çağrılan araçların ve etkinlik ayrıntılarının grafiği
  • Durum: Aracının oturum durumu ve araç girişleri/çıkışları
  • Oturumlar: Bu çalışma zamanına karşı başlattığınız her oturum

15. IAP yetkilendirmesini zorunlu kılma

Dağıtımı doğruladığımıza göre, politikaları zorunlu kılmak için IAP yaptırım modunu null olarak güncelleyebiliriz. terraform.tfvars uygulamasını açın ve modu DRY_RUN'dan null'a güncelleyin.

# IAP Enforcement Mode ("DRY_RUN" or null)
agent_gateway_iap_iam_enforcement_mode = null

Değişikliği uygulayın.

terraform apply

Playground'a geri dönüp görüşmeyi tekrar deneyin.

  1. Google Cloud Console'da Agent Platform Deployments (Aracı Platformu Dağıtımları) sayfasını açın.
  2. Çalışma zamanı listesini daraltmanız gerekiyorsa Filtre alanını kullanın, ardından mortgage-agent çalışma zamanınızı tıklayın.
  3. Playground sekmesini açın.
  4. Temsilciyle sohbet etmek için bir istem yazın:
I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Bu işlem, Belge Yönetimi aracı ve Gelir Doğrulama aracından bir yanıt döndürmelidir. Bu yanıtta, Sosyal Güvenlik Numaraları da karartılmalıdır. 5. Ek soru yazın:

Can you send a summary of this to my email jane@example.com

Her şey doğru şekilde ayarlandıysa temsilci, yetkilendirme politikası nedeniyle e-posta gönderemediğini belirtmelidir.

16. Gemini Enterprise'ı Kurma ve Test Etme

Gemini Enterprise'ı ayarlama

Gemini Enterprise'ı kullanmaya başlama kılavuzundaki adımları uygulayın.

ADK temsilcimizi Gemini Enterprise'a kaydetme

Aracımızı Gemini Enterprise'a kaydetmek için buradaki adımları uygulayabilirsiniz.

  1. Google Cloud Console'da Gemini Enterprise sayfasına gidin.
  2. Ajanın kayıtlı olduğu Gemini Enterprise uygulamasını seçin.
  3. Gemini Enterprise web uygulamanız hazır bölümünde gösterilen URL'yi açın.
  4. Aracı Galerisi'ni açmak için sol menüden Aracı sekmesini seçin.
  5. Mortgage Assistant Agent'ı seçip sohbet etmeye başlayın.

Aynı istemleri Agent Runtime Playground'da deneyin:

İlk istem:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Ek soru:

Can you send a summary of this to my email jane@example.com

Konsolda Ajan Dağıtımı bölümüne geri dönüp ajan dağıtımımızı seçerek izler sekmesine giderseniz artık Gemini Enterprise'dan gelen çağrıyı gösteren aralıkta Gemini Asistanı aracısını görürsünüz.

17. Gözlemlenebilirlik Kontrol Paneli

Yetkilendirme hata ayıklama kontrol paneli, Agent Runtime aracılarının çıkış trafiğiyle ilgili tek bir görünüm sağlar.

Gözlemlenebilirlik Kontrol Paneli

Kontrol panelinde aşağıdakiler gösterilir:

  • Aracı ➔ Uç Nokta (403 Reddetme)
  • Aracı ➔ MCP sunucusu (403 Reddetme)
  • Aracı ➔ Aracı (403 Reddetme)
  • Kayıtlı Olmayan Giden Engellemeler
  • Trafiğe Genel Bakış ve Uygulama İçi Satın Alma Yaptırım Modu
  • GCP API IAM retleri

Her widget'ta aracı kimliği, istenen ana makine, kayıtlı kaynak yolu ve ağ geçidi ile IAP'nin isteği yetkilendirip yetkilendirmediği gösterilir.

  • Kayıtlı Olmayan Giden Engellemeler: Bu widget, özellikle hedef ana makine adı Aracı Kayıt Defteri'nde bulunmadığı için Aracı Ağ Geçidi'nin engellediği trafiği yalıtır. Ağ geçidi proxy'si bu istekleri IAP'ye ulaşmadan önce engellediğinden bu girişlerle ilgili IAP denetleme günlükleri yoktur.
  • Trafiğe Genel Bakış ve uygulama içi satın alma yaptırım modu: Bu widget, tüm trafik kalıplarını gösteren bir tablo sunar. En önemlisi, uygulama içi satın alma deneme çalıştırması durumunu içerir. Böylece kullanıcılar, uygulama içi satın alma politikalarının trafiği etkin bir şekilde engellediğini mi yoksa yalnızca gözlemlediğini mi görebilir.
  • GCP API IAM Denials: Bu widget, Aracıların temel Google Cloud API izni hatalarını yakalamak için standart Cloud Audit Logs'u (cloudaudit.googleapis.com) arar.

Bu kontrol paneline Cloud Console'da ulaşabilirsiniz: Monitoring > Dashboards > Agent Platform: Authorization Debugging

18. Sorun giderme ve sık karşılaşılan düzeltmeler

Gemini CLI ile Yapay Zeka Destekli Hata Ayıklama

Sorunları gidermek için Gemini KSA'daki agent-platform-debugger becerisini kullanabilirsiniz. Beceri paketleri, yapay zeka destekli hata ayıklama için uzmanlık bilgisi sunar. Gemini CLI, .agents/skills/ karakterini çalışma alanı kapsamındaki .gemini/skills/ için birinci sınıf bir takma ad olarak değerlendirdiğinden becerileri doğrudan kullanabilirsiniz. Bu beceriyi Codelab deposundan kullanmak için:

Depo dizinine gidin ve Gemini CLI'yı başlatın:

cd /path/to/cloud-networking-solutions/demos/agent-gateway
gemini

İstendiğinde çalışma alanına güvenin (çalışma alanı kapsamındaki beceriler yalnızca güvenilen klasörlerden yüklenir). Yüklenen beceriyi onaylayın:

/skills list

Listede agent-platform-debugger simgesini görmeniz gerekir. Eksikse becerileri yeniden yükleyin:

/skills reload

Sorun gidermeyle ilgili ipuçları

  • terraform apply, "kaynak oluşturuluyor ve bu nedenle güncellenemiyor" hatasıyla aracı ağ geçidinde başarısız oluyor: Yetkilendirme politikaları eklenmeden önce ağ geçidinin kiracı projesinin yerleşmesi yaklaşık 30 saniye sürer. Bu işlem, modülün time_sleep.wait_for_gateway tarafından gerçekleştirilir. Yalnızca terraform apply komutunu yeniden çalıştırın.
  • Aracı "MCP sunucusu bulunamadı" şeklinde rapor veriyor veya yalnızca yardımcı araçlarla başlatılıyor: enable_agent_registry_endpoints = true'nin terraform.tfvars içinde olduğunu doğrulayın, ardından:
    gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION}
    Üç giriş görmeniz gerekir (Cloud Run MCP hizmeti başına bir giriş). Liste boşsa MCP hizmetlerine VPC'nin içinden erişilebildiğini ve Agent Gateway'in kayıt defterini doldurduğunu (bunu ilk proxy'li araç listesinde geç yapar) kontrol edin.
  • Araç çağrıları 403 PermissionDenied hatası döndürüyor: scripts/grant_agent_mcp_egress.sh yeniden çalıştırın. En yaygın neden, aracı yeniden dağıttıktan sonra yeniden izin vermeyi unutmaktır (reasoningEngines/ her dağıtımda değişir).
  • skaffold run, "hizmet hesabında izin verilmedi" hatasıyla başarısız oluyor: roles/iam.serviceAccountUser eksik. Önceki adımda kendi kendine izin verme işlemini yeniden çalıştırın.
  • Agent Gateway'den MCP LB'ye DNS eşleme hataları: agent_gateway_dns_peering_config.target_network ile projects/${PROJECT_ID}/global/networks/${VPC_NAME}'ün tam olarak eşleştiğinden ve her domains girişinin sonunda nokta olduğundan emin olun.
  • terraform plan, Cloud Run resim etiketlerini güncellemek istiyor: Bu durum, lifecycle { ignore_changes } kuralı nedeniyle gerçekleşmemelidir. Gerçekleşirse skaffold run işleminden sonra terraform.tfvars içinde mcp_services[*].image öğesini düzenlemediğinizi onaylayın.

19. Temizleme

Nedene dayalı çıkarım motoru Terraform tarafından yönetilmez (ADK SDK tarafından oluşturulur). Manuel olarak silme:

gcloud beta ai reasoning-engines delete ${AGENT_ID} \
  --region=${REGION} --project=${PROJECT_ID}

Terraform'un oluşturduğu her şeyi yıkın:

cd terraform
terraform destroy
cd ..

Herkese açık DNS bölgesini yalnızca bu codelab için oluşturduysanız:

gcloud dns managed-zones delete agw-example-com

Son olarak, Terraform durumu paketini silin:

gcloud storage rm -r gs://${PROJECT_ID}-tfstate

20. Tebrikler

Tebrikler! Agent Gateway'i kullanarak çok araçlı bir ADK aracısı için kapsamlı aracı yönetimi uyguladınız. Merkezi ağ kontrol düzlemi olarak hareket eden Agent Gateway, özel araçlara güvenli bir çıkış yolu oluşturmanıza, Identity-Aware Proxy aracılığıyla ayrıntılı kimliğe dayalı IAM politikaları uygulamanıza ve entegre Model Armor koruma sınırlarını kullanarak içerik etkileşimlerini temizlemenize olanak tanıyordu.

Öğrendikleriniz

  • Agent Gateway'i, Ajan-Her Yere çıkış trafiği için merkezi yönetim katmanı olarak dağıtma ve yapılandırma
  • Yönetilen, dinamik çalışma zamanı aracı keşfi için Agent Registry'yi entegre etme
  • Ajan yürütme yollarını sıkı bir şekilde kontrol etmek için araç başına ve koşula dayalı IAM politikaları yazma ve zorunlu kılma
  • Model Armor politikalarını uygulamak için Agent Gateway hizmeti uzantılarından yararlanma. Bu sayede hassas aracı trafiği otomatik olarak engellenir ve düzeltilir.

Referans belgeleri