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

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

1. Giriş

Gemini Enterprise Ajan Platformu, 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ın Google Cloud'da güvenli bir şekilde çalıştırılması 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 ajanı 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ğ 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 güvenli hale getirir.
Agent-to-Anywhere (çıkış): Google Cloud'da çalışan aracıların ve herhangi bir yerde çalışan sunucuların, araçların veya API'lerin 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ıyla sıkı bir şekilde entegre olur:

Aracı Kayıt Defteri: Onaylanmış aracıların ve araçların (üçüncü taraf MCP sunucuları dahil) merkezi kitaplığı.
Aracı Kimliği: Her aracı için benzersiz ve izlenebilir bir karakterdir. Uçtan uca mTLS ile otomatik olarak güvenli hale getirilir.
Identity-Aware 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ğ yolu arasından seçim yapabilirsiniz:

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 yöntem için özel DNS alanları gerekmez ve yönetim kavramlarını öğrenmenin en hızlı yoludur.
Güvenli (Özel Ağ): İsteğe bağlı, tamamen özel bir mimari. MCP sunucuları kısıtlanmıştır (ingress=internal-and-cloud-load-balancing) ve Sunucusuz NEG ile dahili uygulama yük dengeleyicisi üzerinden kullanıma sunulur. Google tarafından yönetilen bir sertifika sağlamak için herkese açık bir DNS alanına sahip olmanız gerekir.

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, Agent Runtime, Agent Gateway, Cloud Run'daki MCP sunucuları

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.

VPC ve Temsilci Ağ Geçidiniz olarak yapılandırılmış bir dahili uygulama yük dengeleyicisi de dahil olmak üzere temel ağ oluşturma işlemlerini sağlayarak baş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ğrulaması (income-verification)

Araçlar hazır olduğunda, ADK ile oluşturulan bir Mortgage Asistanı'nı (mortgage-agent) Agent Runtime'a dağıtırsınız. Bu aracıyı, ö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ının yalnızca yetkili araçlara erişmesini sağlamak için Aracı Kimliği'ni araç başına IAM politikalarına göre doğrular. İ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 tetikleyecek 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 kursu 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 kümesi 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. Bunların çoğu Cloud Shell'de 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

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 yük dengeleyicisi arkasında ingress = internal-and-cloud-load-balancing ile Cloud Run) geçmek istiyorsanız Certificate Manager'ın yük dengeleyici 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:

Herkese açık Cloud DNS bölgesi 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 herkese açık 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 yalnızca terraform.tfvars içindeki üç 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ı)

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

Dahili uygulama LB
Google tarafından yönetilen sertifika
Cloud Run ile ingress = internal-and-cloud-load-balancing
Aracı ağ geçidi 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
terraform apply

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 arayüzü, aracı ağ geçidi ortak konumu), 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, özel ağ iletişimi etkin olduğunda ./mcp adresine kaydedilir)

Yalnızca enable_cloud_run_private_networking = true:

Sunucusuz NEG'li (URL maskeli yönlendirme) dahili bölgesel uygulama yük dengeleyici + özel DNS A kayıtları
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 aracı ağ geçidi DNS eşlemesi (otomatik olarak önceden 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 bunu 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 düzlemidir. 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. UAI 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: İçerik temizleme için gövde etkinliklerini uzantıya aktarır. Burada, Sensitive Data Protection (SDP) aracılığıyla istem enjeksiyonu, jailbreak, RAI ihlalleri ve (isteğe bağlı olarak) 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'da sdpSettings.basicConfig yerleşik bir infoType listesi kullanılır. Daha ayrıntılı kontrol (özel bilgi türleri, kısmi maskeleme, yedek değiştirme, olasılığa göre karartma) için Model Armor'u sdpSettings.advancedConfig üzerinden 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 noktada, Terraform'un model_armor modülü, bağlarsanız advanced_config'yi ayarlayacaktır):

{
  "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ı kayıt defterinde proje genelinde roles/iap.egressor bağlama 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 komutunu çalıştırı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}'ye (Cloud Run giriş notu) referans verir. Oluşturulan manifestoların enable_cloud_run_private_networking ile senkronize kalması için Terraform çıktısı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

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

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 \
  --model-endpoint-location=global

Komut dosyası tamamlandığında, yazdırılan reasoningEngines/ simgesini kabuğunuza kopyalayın:

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

13. Aracıya MCP sunucusu başına çıkış izni verme

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 giden trafik politikası oluşturma başlıklı makaleyi inceleyin.

Komut dosyası (scripts/grant_agent_mcp_egress.sh), projects/${PROJECT_ID}/locations/${REGION} altındaki aracı kayıt defterinde 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ıtarak).

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. Bu özellikler şunlardı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 kısıtlayı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" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Bu işlem çalıştı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 izin 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ı test etmenin ve izlemeleri incelemenin en hızlı yoludur.

Google Cloud Console'da Agent Platform Deployments (Aracı Platformu Dağıtımları) sayfasını açın.
Çalışma zamanı listesini daraltmanız gerekiyorsa Filtre alanını kullanın, ardından mortgage-agent çalışma zamanınızı tıklayın.
Playground sekmesini açın.
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 SSN'ler de karartılmalıdır. 5. Ek bir istem yazın:

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

Ajan, send_email aracına erişimi olmadığını belirlemeli ve buna göre yanıt vermelidir.

Aracı OpenTelemetry enstrümantasyonu ile dağıtıldığından Playground, aracı 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.

Google Cloud Console'da Agent Platform Deployments (Aracı Platformu Dağıtımları) sayfasını açın.
Çalışma zamanı listesini daraltmanız gerekiyorsa Filtre alanını kullanın, ardından mortgage-agent çalışma zamanınızı tıklayın.
Playground sekmesini açın.
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 SSN'ler de karartılmalıdır. 5. Ek bir istem 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ılavuzunu inceleyin.

ADK temsilcimizi Gemini Enterprise'a kaydetme

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

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

Aynı istemleri Agent Runtime Playground'da deneyin:

Başlangıçtaki 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 Aracı Dağıtımı bölümüne geri dönüp aracı 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. Sorun giderme ve sık karşılaşılan düzeltmeler

terraform apply, "kaynak oluşturuluyor ve bu nedenle güncellenemiyor" hatasıyla aracı ağ geçidinde başarısız oluyor: Yetkilendirme politikalarının eklenmesi için 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örmelisiniz (Cloud Run MCP hizmeti başına bir giriş). Liste boşsa MCP hizmetlerine VPC'nin içinden erişilebildiğini ve Ajan Ağ Geçidi'nin 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, temsilci yeniden dağıtıldıktan sonra yeniden izin vermeyi unutmaktır (reasoningEngines/ her dağıtımda değişir).
skaffold run, "hizmet hesabında izin reddedildi" hatasıyla başarısız oluyor: roles/iam.serviceAccountUser eksik. Önceki adımdaki kendi kendine izin verme işlemini tekrar ç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 sondaki nokta ile bittiğinden emin olun.
terraform plan, Cloud Run görüntü etiketlerini sürekli güncellemek istiyor. Bu durum, lifecycle { ignore_changes } kuralı nedeniyle olmamalıdır. Bu durumda, mcp_services[*].image adlı işletmeyi skaffold run tarihinden sonra terraform.tfvars içinde düzenlemediğinizi onaylayın.

18. Temizleme

Akıl yürütme motoru Terraform tarafından yönetilmez (ADK SDK tarafından oluşturulur). Manuel olarak silmek için:

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

Terraform tarafından oluşturulan 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

19. 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, Agent-to-Anywhere çı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
Aracı 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

Aracı Yönetimi Politikalarına Genel Bakış
Agent Gateway Belgeleri
Agent Identity Documentation (Aracı Kimlik Belgeleri)
Gemini Enterprise Ajan Platformuna Genel Bakış