การควบคุมปริมาณงานของเอเจนต์ด้วย Agent Gateway ในแพลตฟอร์ม Agent ของ Gemini Enterprise

1. บทนำ

แพลตฟอร์ม Agent ของ Gemini Enterprise เป็นแพลตฟอร์มแบบเปิดสำหรับการสร้าง การปรับขนาด การกำกับดูแล และการเพิ่มประสิทธิภาพ AI Agent ระดับองค์กรที่อิงตามข้อมูลของคุณ

Agent Runtime มีสภาพแวดล้อมการดำเนินการที่มีการจัดการสำหรับการเรียกใช้ Agent เช่น Agent ที่สร้างด้วย Agent Development Kit (ADK) แบบโอเพนซอร์สอย่างปลอดภัยภายใน Google Cloud

Codelab นี้จะสำรวจวิธีใช้บล็อกการสร้างหลักเหล่านี้เพื่อควบคุม Agent ที่ผู้ใช้เริ่มต้นใน Gemini Enterprise ขณะที่ Agent ติดต่อเครื่องมือภายในอย่างปลอดภัย

เกี่ยวกับ Agent Gateway

Agent Gateway เป็นคอมโพเนนต์เครือข่ายของชุดเครื่องมือการกำกับดูแลเอเจนต์ของแพลตฟอร์ม โดยทำหน้าที่เป็นจุดเข้าและออกจากเครือข่ายสำหรับการโต้ตอบของเอเจนต์ทั้งหมด ซึ่งช่วยให้ผู้ดูแลระบบความปลอดภัยบังคับใช้การกำกับดูแลแบบรวมศูนย์ได้โดยไม่ต้องให้นักพัฒนาแอปจัดการ Primitive เครือข่ายที่ซับซ้อน

ซึ่งช่วยให้เข้าถึงได้ 2 เส้นทางหลักที่มีการควบคุม ดังนี้

  • ไคลเอ็นต์ถึง Agent (ขาเข้า): รักษาความปลอดภัยในการสื่อสารระหว่างไคลเอ็นต์ภายนอก (เช่น Cursor หรือ Gemini CLI) กับ Agent ของคุณ
  • Agent-to-Anywhere (ขาออก): รักษาความปลอดภัยในการสื่อสารระหว่าง Agent ที่ทำงานใน Google Cloud กับเซิร์ฟเวอร์ เครื่องมือ หรือ API ที่ทำงานทุกที่

ใน Codelab นี้ คุณจะมุ่งเน้นไปที่โหมด Agent-to-Anywhere (ขาออก)

การควบคุมการเข้าถึงด้วย Agent Gateway

Agent Gateway ผสานรวมกับส่วนอื่นๆ ของระบบนิเวศอย่างใกล้ชิดเพื่อบังคับใช้นโยบายความปลอดภัย

  • Agent Registry: คลังส่วนกลางของเอเจนต์และเครื่องมือที่ได้รับอนุมัติ (รวมถึงเซิร์ฟเวอร์ MCP ของบุคคลที่สาม)
  • ข้อมูลประจำตัวของ Agent: ข้อมูลประจำตัวที่ไม่ซ้ำกันและติดตามได้สำหรับ Agent ทุกคน ซึ่งได้รับการรักษาความปลอดภัยโดยอัตโนมัติด้วย mTLS แบบครบวงจร
  • Identity-Aware Proxy (IAP) และ IAM: เลเยอร์การบังคับใช้เริ่มต้นที่ตรวจสอบความถูกต้องของตัวตนของเอเจนต์เทียบกับสิทธิ์ IAM แบบละเอียดก่อนที่จะอนุญาตให้โทรไปยังเครื่องมือที่เฉพาะเจาะจง
  • Model Armor: แนวทางการรักษาความปลอดภัยของ AI ที่ผสานรวมผ่านส่วนขยายบริการเพื่อล้างเนื้อหาและป้องกันการโจมตีแบบแทรกพรอมต์หรือการรั่วไหลของข้อมูล

โหมดการติดตั้งใช้งาน (เครือข่ายสาธารณะเทียบกับเครือข่ายส่วนตัวสำหรับ Cloud Run)

คุณเลือกเส้นทางการเชื่อมต่อเครือข่ายได้ 2 เส้นทางสำหรับเครื่องมือภายใน (เซิร์ฟเวอร์ MCP) ที่ติดตั้งใช้งานใน Cloud Run เพื่อให้เข้าถึง Codelab นี้ได้

  1. ค่าเริ่มต้น (ขาเข้าสาธารณะ): ระบบจะติดตั้งใช้งานเซิร์ฟเวอร์ MCP ใน Cloud Run ด้วยชื่อโฮสต์สาธารณะ (ingress=all) การรับส่งข้อมูลจะกำหนดเส้นทางจากเอเจนต์ไปยังเครื่องมือผ่าน URL *.run.app มาตรฐาน ซึ่งไม่จำเป็นต้องใช้โดเมน DNS ที่กำหนดเองและเป็นวิธีที่เร็วที่สุดในการเรียนรู้แนวคิดด้านการกำกับดูแล
  2. ปลอดภัย (เครือข่ายส่วนตัว): สถาปัตยกรรมส่วนตัวโดยสมบูรณ์ที่ไม่บังคับ เซิร์ฟเวอร์ MCP ถูกจำกัด (ingress=internal-and-cloud-load-balancing) และแสดงผ่านตัวจัดสรรภาระงานแอปพลิเคชันภายในที่มี NEG แบบ Serverless โดยคุณต้องเป็นเจ้าของโดเมน DNS สาธารณะเพื่อจัดสรรใบรับรองที่ Google จัดการ

คุณจะเลือกเส้นทางที่ต้องการเมื่อกำหนดค่า Terraform

ดูข้อมูลเพิ่มเติมเกี่ยวกับการรับส่งข้อมูลขาเข้าของปลายทางเครือข่ายสำหรับ Cloud Run ได้ในเอกสารประกอบ

สิ่งที่คุณต้องทำ

  • จัดสรรสแต็กโครงสร้างพื้นฐานหลักโดยใช้ Terraform
  • สร้างและติดตั้งใช้งานเครื่องมือภายในเป็นเซิร์ฟเวอร์ MCP ใน Cloud Run
  • ติดตั้งใช้งาน ADK Agent ใน Agent Runtime โดยใช้ขาออกของอินเทอร์เฟซ PSC
  • กำหนดค่าส่วนขยายบริการ Agent Gateway สำหรับการเข้าถึงตามข้อมูลประจำตัว (IAM) และการคัดกรองเนื้อหา (Model Armor)
  • ติดตามและตรวจสอบการดำเนินการแบบต้นทางถึงปลายทางที่ปลอดภัยของเอเจนต์

สิ่งที่คุณต้องมี

  • เว็บเบราว์เซอร์ เช่น Chrome
  • โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงินและมีสิทธิ์เข้าถึงระดับเจ้าของ
  • สิทธิ์ IAM ระดับองค์กร (Codelab มอบบทบาทที่มีขอบเขตระดับองค์กร)
  • โดเมนที่คุณควบคุมซึ่งมอบสิทธิ์ให้ Cloud DNS (สำหรับใบรับรองที่มีการจัดการแบบสาธารณะ)
  • คุ้นเคยกับ Terraform, gcloud และเครือข่าย Google Cloud ขั้นพื้นฐาน

โทโพโลยี Codelab

สถาปัตยกรรมแบบครบวงจร: Gemini Enterprise ไปยัง Agent Runtime ไปยัง Agent Gateway ไปยังเซิร์ฟเวอร์ MCP ใน Cloud Run

ใน Codelab นี้ คุณจะได้ติดตั้งใช้งานเอเจนต์การรับประกันสินเชื่อที่อยู่อาศัยแบบครบวงจร ซึ่งสื่อสารกับเครื่องมือภายใน 3 อย่างได้อย่างปลอดภัย

คุณจะเริ่มต้นด้วยการจัดสรรระบบเครือข่ายพื้นฐาน ซึ่งรวมถึง VPC และตัวจัดสรรภาระงานแอปพลิเคชันภายในที่กำหนดค่าเป็นเกตเวย์ของ Agent จากนั้นคุณจะติดตั้งใช้งานเซิร์ฟเวอร์ Model Context Protocol (MCP) 3 เครื่องใน Cloud Run ซึ่งจะทำหน้าที่เป็นเครื่องมือที่เป็นกรรมสิทธิ์ภายในของคุณ

  • การจัดการเอกสาร (legacy-dms)
  • อีเมลองค์กร (corporate-email)
  • การยืนยันรายได้ (income-verification)

เมื่อมีเครื่องมือพร้อมแล้ว คุณจะทำให้ Mortgage Assistant (mortgage-agent) ที่สร้างด้วย ADK ใช้งานได้กับ Agent Runtime คุณจะกำหนดค่า Agent นี้ให้ใช้อินเทอร์เฟซ PSC สำหรับขาออกส่วนตัวและเปิดใช้การค้นหาเครื่องมือรันไทม์ผ่านรีจิสทรีของ Agent

หากต้องการรักษาความปลอดภัยของโฟลว์ คุณจะต้องกำหนดค่า Agent Gateway ด้วยส่วนขยายบริการ 2 รายการ ก่อนอื่น REQUEST_AUTHZส่วนขยายจะยืนยันตัวตนของ Agent กับนโยบาย IAM ต่อเครื่องมือ เพื่อให้มั่นใจว่า Agent จะเข้าถึงได้เฉพาะเครื่องมือที่ได้รับอนุญาตเท่านั้น ประการที่สอง CONTENT_AUTHZ ส่วนขยายที่ใช้ Model Armor จะคัดกรองพรอมต์และการตอบกลับของเอเจนต์

สุดท้าย คุณจะลงทะเบียนเอเจนต์ใน Gemini Enterprise เรียกใช้งานการประเมินสินเชื่อที่อยู่อาศัยในฐานะผู้ใช้ปลายทาง และยืนยันการดำเนินการที่ปลอดภัยและมีการกำกับดูแลโดยใช้ Cloud Trace

Codelab นี้มีไว้สำหรับวิศวกรแพลตฟอร์มและความปลอดภัยทุกระดับ คาดว่าจะใช้เวลาประมาณ 100 นาที ในการทำแบบทดสอบให้เสร็จสมบูรณ์

2. ก่อนเริ่มต้น

สร้างโปรเจ็กต์และตรวจสอบสิทธิ์

สร้างโปรเจ็กต์ GCP ใหม่ (หรือใช้โปรเจ็กต์ที่มีอยู่) โดยเปิดใช้การเรียกเก็บเงิน จากนั้นให้สิทธิ์ Cloud Shell หรือเครื่องในพื้นที่

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

เปิดใช้ Bootstrap API

โมดูลพื้นฐานของ Terraform จะเปิดใช้ API ประมาณ 30 รายการในการใช้ครั้งแรก แต่ต้องมีชุดการเริ่มต้นขนาดเล็กสำหรับ terraform init และที่เก็บข้อมูลสถานะ GCS

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

ติดตั้งเครื่องมือที่จำเป็น

ติดตั้ง Toolchain ใน Cloud Shell ส่วนใหญ่จะมีเครื่องมือเหล่านี้อยู่แล้ว ส่วนในเวิร์กสเตชัน ให้ทำดังนี้

# 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

นอกจากนี้ คุณยังต้องมี Terraform >= 1.12.2, Python 3.12 ขึ้นไป และ Google Cloud SDK (gcloud)

ตั้งค่าตัวแปรสภาพแวดล้อม

ส่วนที่เหลือของ Codelab จะถือว่ามีการส่งออกตัวแปรเหล่านี้ใน Shell

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"

ตรวจสอบว่าตัวแปรทั้งหมดได้รับการป้อนข้อมูลอย่างถูกต้อง คุณควรได้รับค่า 3 ค่า

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

หากรหัสองค์กรไม่ปรากฏขึ้น คุณสามารถค้นหาและตั้งค่าด้วยตนเองได้

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. โคลนที่เก็บ 

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

มาดูคร่าวๆ ว่ามีอะไรอยู่ในไดเรกทอรีตัวอย่าง

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. สร้าง Bucket สถานะ Terraform และการกำหนดค่าแบ็กเอนด์

สร้าง Bucket ของ GCS เพื่อเก็บสถานะระยะไกล แล้วคัดลอกเทมเพลตแบ็กเอนด์

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 ด้วยค่าของคุณ

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

5. (ไม่บังคับ) สร้างโซน Cloud DNS สาธารณะ

โดยค่าเริ่มต้นสำหรับ Lab นี้ Cloud Run จะตั้งค่าการกำหนดค่าขาเข้าเป็น all และรีจิสทรี Agent จะลงทะเบียนเซิร์ฟเวอร์ MCP แต่ละรายการที่ URL สาธารณะ *.run.app โดยไม่จำเป็นต้องใช้ DNS, ใบรับรอง หรือตัวจัดสรรภาระงานเพิ่มเติม หากต้องการเปลี่ยนไปใช้เครือข่ายส่วนตัว (Cloud Run ที่มี ingress = internal-and-cloud-load-balancing อยู่หลัง Application LB ภายใน) คุณจะต้องมีโซน Cloud DNS สาธารณะด้วยเพื่อให้ Certificate Manager ตรวจสอบใบรับรอง LB ได้

ขั้นตอนการทำงานระดับสูงของการเชื่อมต่อเครือข่ายส่วนตัว

ขั้นตอนการดำเนินการระดับสูงของตัวเลือกเครือข่ายส่วนตัว

หากต้องการใช้วิธีการเครือข่ายส่วนตัว ให้ทำดังนี้

  1. สร้างโซน Cloud DNS สาธารณะ - Certificate Manager จะตรวจสอบใบรับรองที่มีการจัดการระดับภูมิภาคโดยการเขียน CNAME ลงในโซน DNS
gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

Terraform จะสร้างโซนส่วนตัวที่เกี่ยวข้องสำหรับ mcp.${DOMAIN_NAME} (ใช้โดย LB ภายในของ MCP และการเชื่อมต่อ DNS จาก Agent Runtime) โดยอัตโนมัติ คุณจึงไม่ต้องสร้างด้วยตนเอง เมื่อปิดการเชื่อมต่อเครือข่ายส่วนตัว ระบบจะไม่จัดสรรทั้งโซนสาธารณะและโซนส่วนตัว

6. กำหนดค่าตัวแปร Terraform

คัดลอกไฟล์ tfvars ตัวอย่างและแก้ไข

cp terraform/example.tfvars terraform/terraform.tfvars

เส้นทางการทดลองมี 2 เส้นทางซึ่งต้องผ่านenable_cloud_run_private_networking

เส้นทางเริ่มต้น: Cloud Run ที่มีการรับส่งข้อมูลขาเข้าแบบสาธารณะ

การตั้งค่าที่ง่ายที่สุด: สำหรับเส้นทางเริ่มต้น คุณเพียงแค่ต้องแก้ไขค่า 3 ค่าใน terraform.tfvars ตัวแปรอื่นๆ ทั้งหมดในไฟล์มีค่าเริ่มต้นที่เหมาะกับการสาธิตอยู่แล้ว

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

เครือข่ายส่วนตัว (ไม่บังคับ)

ตั้งค่า enable_cloud_run_private_networking = true และเพิ่มตัวแปรด้านล่างเพื่อจัดสรรสแต็กที่ปลอดภัยแบบเต็ม

  • ตัวจัดสรรภาระงานของแอปพลิเคชันภายใน
  • ใบรับรองที่จัดการโดย Google
  • Cloud Run พร้อม ingress = internal-and-cloud-load-balancing
  • การเพียร์ DNS ของ Agent Gateway
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

เริ่มต้น ตรวจสอบ และนำไปใช้

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

terraform apply จัดสรรทรัพยากรประมาณ 40 รายการในเส้นทางเริ่มต้นและใช้เวลา 8-10 นาทีในโปรเจ็กต์ใหม่ (ทรัพยากรประมาณ 60 รายการ / 15-20 นาทีเมื่อ enable_cloud_run_private_networking = true) โดยจะสร้างรายการต่อไปนี้

  • รากฐานของโปรเจ็กต์ (API, ข้อมูลประจำตัวของบริการ, โควต้า)
  • VPC, ซับเน็ต (หลัก, เฉพาะพร็อกซี, PSC, อินเทอร์เฟซ PSC, การจัดวางเกตเวย์ของเอเจนต์ร่วมกัน), Cloud NAT, กฎไฟร์วอลล์
  • ที่เก็บ Artifact Registry สำหรับอิมเมจ Cloud Run
  • บริการ Cloud Run 3 รายการ + SA รันไทม์ต่อบริการ (ขาเข้า = all โดยค่าเริ่มต้น internal-and-cloud-load-balancing เมื่อเปิดใช้เครือข่ายส่วนตัว)
  • เทมเพลต Model Armor + IAM
  • Agent Gateway, การเชื่อมต่อเครือข่าย PSC-I, ส่วนขยาย IAP และ Model Armor, นโยบายการให้สิทธิ์ทั้ง 2 รายการ และroles/iap.egressorการให้สิทธิ์roles/iap.egressorระดับโปรเจ็กต์
  • ปลายทางของ Agent Registry (Vertex AI, IAP, Discovery Engine, ...) รวมถึงเซิร์ฟเวอร์ MCP 3 เครื่อง (ลงทะเบียนที่ *.run.app/mcp โดยค่าเริ่มต้น และที่ ./mcp เมื่อเปิดใช้เครือข่ายส่วนตัว)

เฉพาะในกรณีต่อไปนี้ enable_cloud_run_private_networking = true

  • Application Load Balancer ภายในระดับภูมิภาคที่มี NEG แบบ Serverless (การกำหนดเส้นทางมาสก์ URL) + ระเบียน A ของ DNS ส่วนตัว
  • โซน DNS ส่วนตัวของ MCP (mcp..) ที่แนบกับ VPC
  • โมดูลโซน DNS สาธารณะ (การให้สิทธิ์ DNS ของ Certificate Manager) + ใบรับรองที่จัดการโดย Google ระดับภูมิภาค
  • โซน DNS ของอินเทอร์เฟซ PSC (โดดเดี่ยวเมื่อไม่มีชื่อโฮสต์ส่วนตัวที่จะแปลง ดังนั้นจึงมีการควบคุมด้วยค่าสถานะหลักด้วย)
  • การเพียร์ DNS ของ Agent Gateway สำหรับ mcp.. (เพิ่มนำหน้าโดยอัตโนมัติ)

8. ตรวจสอบปลายทางของรีจิสทรีตัวแทน

Agent Registry เป็นแคตตาล็อกบริการต่อโปรเจ็กต์ (Google API และเซิร์ฟเวอร์ MCP ของคุณเอง) ที่เอเจนต์ค้นพบในขณะรันไทม์ ตัวแทนจำนองจะอ่านข้อมูลนี้เมื่อเริ่มต้นระบบและเชื่อมโยงเครื่องมือแบบไดนามิก โดยไม่มีการฝัง URL ของ MCP ไว้ในโค้ดของ Agent หรือคำสั่งการติดตั้งใช้งาน

ปลายทาง

สิ่งที่ Terraform เรียกใช้ในนามของคุณ - สำหรับ Google API แต่ละรายการใน agent_registry_google_apis Terraform จะลงทะเบียน 5 รูปแบบ (ทั่วโลก, mTLS ทั่วโลก, ระดับภูมิภาค, mTLS ระดับภูมิภาค, REP ระดับภูมิภาค) เช่น สำหรับ aiplatform

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

นอกจากนี้ Terraform ยังลงทะเบียนเซิร์ฟเวอร์ MCP 3 เครื่องให้คุณด้วย หากต้องการลงทะเบียนเซิร์ฟเวอร์ MCP อื่นๆ ให้ทำตามขั้นตอนในเอกสารประกอบ

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

ยืนยันอุปกรณ์ปลายทางและเซิร์ฟเวอร์ MCP ที่ลงทะเบียน

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

แหล่งที่มา: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl

9. ตรวจสอบการกำหนดค่า Agent Gateway

Agent Gateway คือระนาบการกำกับดูแลที่ Google จัดการระหว่าง Agent Runtime กับเครื่องมือของคุณ ในโหมด AGENT_TO_ANYWHERE จะเชื่อมโยงกับ Agent Registry ของโปรเจ็กต์และส่งออกผ่านอินเทอร์เฟซ PSC ที่ลูกค้าเป็นเจ้าของเพื่อให้เข้าถึงเซิร์ฟเวอร์ MCP ส่วนตัวใน VPC ได้

หากคุณนำเข้าเกตเวย์นี้ด้วยตนเอง YAML จะมีลักษณะดังนี้

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

ยืนยันเกตเวย์ที่ Terraform สร้างขึ้น

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

10. ตรวจสอบการให้สิทธิ์ IAP และ Model Armor

Agent Gateway จะมอบสิทธิ์ให้ส่วนขยายบริการ โปรไฟล์นโยบาย 2 รายการครอบคลุมการสาธิต

  • REQUEST_AUTHZ - ประเมิน 1 ครั้งต่อคำขอในขั้นตอนส่วนหัว ใช้ที่นี่เพื่อเรียก IAP ซึ่งจะตรวจสอบว่าข้อมูลประจำตัวของ Agent ที่เรียกมี roles/iap.egressor ในเซิร์ฟเวอร์ MCP เป้าหมายหรือไม่
  • CONTENT_AUTHZ - สตรีมเหตุการณ์ในเนื้อหาไปยังส่วนขยายเพื่อการล้างข้อมูลเนื้อหา ใช้ที่นี่เพื่อเรียก Model Armor ซึ่งจะคัดกรองการแทรกพรอมต์ การหลบเลี่ยงข้อจำกัด การละเมิด RAI และ (ไม่บังคับ) PII ผ่านการปกป้องข้อมูลที่ละเอียดอ่อน (SDP)

ส่วนขยาย IAP REQUEST_AUTHZ

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}

เชื่อมโยงกับ Agent Gateway ด้วยนโยบาย REQUEST_AUTHZ ดังนี้

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"
        ]
      }
    }
  }'

ส่วนขยาย CONTENT_AUTHZ ของ Model Armor

metadata.model_armor_settingsของส่วนขยายมีรหัสเทมเพลตคำขอและการตอบกลับที่ Model Armor ใช้เพื่อประเมินข้อความกระตุ้นให้ดำเนินการแต่ละรายการ

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"
        ]
      }
    }
  }'

เทมเพลต DLP ที่กำหนดเอง

sdpSettings.basicConfig ของ Model Armor ใช้รายการ infoType ที่มีอยู่แล้ว หากต้องการควบคุมอย่างละเอียด (ประเภทข้อมูลที่กำหนดเอง การมาสก์บางส่วน การแทนที่ด้วยข้อมูลแทน การปกปิดข้อมูลบางส่วนตามความเป็นไปได้) ให้ชี้ Model Armor ไปยังเทมเพลต inspect และ de-identify ของ Cloud DLP ของคุณเองผ่าน sdpSettings.advancedConfig

สร้างเทมเพลตการตรวจสอบที่แจ้งหมายเลขประกันสังคมของสหรัฐอเมริกาที่POSSIBLEความเป็นไปได้หรือสูงกว่า

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

สร้างเทมเพลตการลบข้อมูลระบุตัวบุคคลที่จะแทนที่ผลการค้นหาแต่ละรายการด้วยโทเค็นประเภทข้อมูล (เช่น [US_SOCIAL_SECURITY_NUMBER])

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": {} }
          }]
        }
      }
    }
  }'

จากนั้นชี้การกำหนดค่าการตอบกลับของเทมเพลต Model Armor ไปที่คู่ผ่าน sdpSettings.advancedConfig (ซึ่งเป็นที่ที่โมดูล model_armor ของ Terraform จะตั้งค่า advanced_config หากคุณเชื่อมต่อไว้)

{
  "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"
      }
    }
  }
}

IAM ขาออกของ IAP (ต่อเซิร์ฟเวอร์ MCP เท่านั้น)

Terraform ไม่สร้างการเชื่อมโยง roles/iap.egressor ระดับโปรเจ็กต์ในรีจิสทรีของตัวแทน IAP โดยนัย การเชื่อมโยง IAP REQUEST_AUTHZ ที่ประเมินจริงคือต่อเซิร์ฟเวอร์ MCP และต่อเครื่องมือให้เหตุผล โดยจะได้รับหลังจากที่ติดตั้งใช้งานเอเจนต์และคุณทราบรหัสเอเจนต์แล้ว ขั้นตอน "ให้สิทธิ์ขาออกต่อเซิร์ฟเวอร์ MCP แก่ Agent" จะเรียกใช้ scripts/grant_agent_mcp_egress.sh สำหรับการดำเนินการดังกล่าว

11. สร้างและติดตั้งใช้งานเซิร์ฟเวอร์ MCP ใน Cloud Run

ไฟล์ cloudrun/*.yaml.tmpl และ skaffold.yaml.tmpl อ้างอิงถึง ${PROJECT_ID}, ${REGION} และ ${MCP_INGRESS} (คำอธิบายประกอบขาเข้าของ Cloud Run) แหล่งข้อมูล MCP_INGRESS จากเอาต์พุตของ Terraform เพื่อให้ไฟล์ Manifest ที่แสดงผลซิงค์กับ enable_cloud_run_private_networking จากนั้นแสดงผลด้วย envsubst

ส่งออกการกำหนดค่าขาเข้าของ Cloud Run

  • all
  • internal-and-cloud-load-balancing (เมื่อใช้แนวทางเครือข่ายส่วนตัว)
export MCP_INGRESS=all

กลับไปที่ไดเรกทอรีการสาธิตรูท

cd ..

แทนที่ค่าเทมเพลต

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

บริการ Cloud Run แต่ละรายการจะทำงานเป็น SA รันไทม์ต่อบริการที่ Terraform สร้างขึ้น (เช่น mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com) หากต้องการทําให้ใช้งานได้ในฐานะ SA เหล่านั้น คุณต้องมี roles/iam.serviceAccountUser ในตัวคุณเอง

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

สร้างด้วย Cloud Build และทำให้ใช้งานได้ด้วย Skaffold

skaffold run

Skaffold สร้างอิมเมจ 3 รายการ (legacy-dms, corporate-email, income-verification-api) ลงในที่เก็บ Artifact Registry และอัปเดตบริการ Cloud Run แต่ละรายการให้ชี้ไปยังข้อมูลสรุปใหม่

ยืนยัน

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

คุณควรเห็นบริการทั้ง 3 รายการมีสถานะเป็น ACTIVE

12. ทำให้ Mortgage Agent ใช้งานได้กับ Agent Runtime

ให้บทบาท IAP Egressor แก่ตัวแทนทั้งหมดในอุปกรณ์ปลายทางทั้งหมดที่เราลงทะเบียนไว้ในรีจิสทรี เอเจนต์ต้องมีสิทธิ์เข้าถึงปลายทางเหล่านี้เนื่องจากเมื่อมีการติดตั้งใช้งาน เอเจนต์จะต้องเข้าถึง github.com เพื่อรับแพ็กเกจ จากนั้นจึงเข้าถึง Google API ต่างๆ ที่จำเป็นต่อการติดตั้งใช้งาน

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

ติดตั้งการขึ้นต่อกันของ Agent และทำให้ใช้งานได้

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

เมื่อสคริปต์ทำงานเสร็จแล้ว ให้คัดลอก reasoningEngines/ ที่พิมพ์ลงในเชลล์ (เช่น 4262292559201566720)

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

13. ให้สิทธิ์การออกของ Agent ต่อเซิร์ฟเวอร์ MCP

ส่วนขยาย IAP REQUEST_AUTHZ จะให้สิทธิ์การเรียกใช้เครื่องมือแต่ละรายการโดยการตรวจสอบ roles/iap.egressor ของ Agent ในเซิร์ฟเวอร์ MCP ที่เฉพาะเจาะจงหรือปลายทางที่ Agent เรียกใช้ ดูสร้างนโยบายขาออกจาก Agent ไปยังเซิร์ฟเวอร์ MCP

สคริปต์ (scripts/grant_agent_mcp_egress.sh) จะแสดงรายการเซิร์ฟเวอร์ MCP ในรีจิสทรี Agent ภายใต้ projects/${PROJECT_ID}/locations/${REGION} และผสานรวมroles/iap.egressorการเชื่อมโยงสำหรับหลักการของ Agent เข้ากับนโยบาย IAM ของแต่ละเซิร์ฟเวอร์ (การจำลองความหมายของ gcloud add-iam-policy-binding)

กรณีการใช้งานที่ 1 - การให้สิทธิ์แบบไม่มีเงื่อนไขที่กำหนดขอบเขตไว้สำหรับเซิร์ฟเวอร์ MCP ที่เฉพาะเจาะจง

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

กรณีการใช้งานที่ 2 - การให้สิทธิ์แบบมีเงื่อนไข (CEL) ที่กำหนดขอบเขตไว้สำหรับเซิร์ฟเวอร์ MCP ที่เฉพาะเจาะจง

หากต้องการจำกัด Agent ให้ใช้เครื่องมือบางอย่างในเซิร์ฟเวอร์ MCP เครื่องเดียว ให้แนบเงื่อนไข IAM Agent Gateway จะเผยแพร่แอตทริบิวต์ต่อเครื่องมือที่ IAP REQUEST_AUTHZ แสดงต่อ CEL ซึ่งรวมถึง

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

จำกัดให้เอเจนต์ใช้เครื่องมือแบบอ่านอย่างเดียวเท่านั้นใน corporate-email

./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"

หลังจากเรียกใช้แล้ว ให้เขียนเครื่องมือใน corporate-email return 403 PermissionDenied จาก IAP REQUEST_AUTHZ เครื่องมือแบบอ่านอย่างเดียวจะยังคงทำงานต่อไป