การควบคุมปริมาณงานของเอเจนต์ด้วย 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 (ขาออก): รักษาความปลอดภัยในการสื่อสารระหว่างเอเจนต์ที่ทำงานบน 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) และแสดงผ่าน Internal ตัวจัดสรรภาระงานแอปพลิเคชัน ที่มี 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-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 และการ Peering 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 เป็นแคตตาล็อกบริการต่อโปรเจ็กต์ (Google APIs และเซิร์ฟเวอร์ MCP ของคุณเอง) ที่ Agent ค้นพบในขณะรันไทม์ Mortgage Agent จะอ่านรีจิสทรีนี้เมื่อเริ่มต้นระบบและเชื่อมโยงเครื่องมือแบบไดนามิก โดยไม่มีการฝัง URL ของ MCP ไว้ในโค้ดของ Agent หรือคำสั่งการติดตั้งใช้งาน

ปลายทาง

สิ่งที่ Terraform เรียกใช้ในนามของคุณ - สำหรับ Google API แต่ละรายการใน agent_registry_google_apis ระบบจะลงทะเบียน 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 ใช้รายการประเภทข้อมูลในตัว หากต้องการควบคุมอย่างละเอียด (ประเภทข้อมูลที่กำหนดเอง การมาสก์บางส่วน การแทนที่ด้วยข้อมูลทดแทน การปกปิดข้อมูลตามความน่าจะเป็น) ให้ชี้ 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 และต่อเครื่องมือให้เหตุผล โดยจะได้รับหลังจากที่ติดตั้งใช้งานตัวแทนและคุณทราบรหัสตัวแทนแล้ว ขั้นตอน "ให้สิทธิ์การออกของ Agent ต่อเซิร์ฟเวอร์ MCP" จะเรียกใช้ 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. ทำให้ตัวแทนจำนองใช้งานได้กับ 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. ให้สิทธิ์ขาออกต่อเซิร์ฟเวอร์ MCP แก่ Agent

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

สคริปต์ (scripts/grant_agent_mcp_egress.sh) จะแสดงรายการเซิร์ฟเวอร์ MCP ใน Agent Registry ภายใต้ 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 เครื่องมือแบบอ่านอย่างเดียวจะยังคงทำงานต่อไป

ยืนยันการเชื่อมโยง

ไปที่แท็บนโยบาย แล้วคุณจะเห็นรายการนโยบายที่สร้างขึ้นเทียบกับอุปกรณ์ปลายทางและเซิร์ฟเวอร์ MCP

กรณีการใช้งานเพิ่มเติม

ให้สิทธิ์แบบไม่มีเงื่อนไขในเซิร์ฟเวอร์ MCP ทุกเครื่อง โดยกำหนดขอบเขตไว้ที่เอเจนต์เครื่องเดียว

เรียกใช้คำสั่งนี้หลังจากที่ติดตั้งเอเจนต์ใหม่ทุกครั้ง หากไม่มีตัวกรองและไม่มีเงื่อนไข เอเจนต์ที่ระบุจะได้รับ roles/iap.egressor ในเซิร์ฟเวอร์ MCP ทุกเครื่องในรีจิสทรี

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

14. ทดสอบเอเจนต์ในคอนโซลแพลตฟอร์มเอเจนต์

คอนโซลแพลตฟอร์มเอเจนต์มาพร้อมกับ Playground ที่ให้คุณแชทกับเอเจนต์ที่ติดตั้งใช้งานได้โดยตรง ซึ่งเป็นวิธีที่เร็วที่สุดในการทดสอบการเรียกใช้เครื่องมือและตรวจสอบการติดตามก่อนที่จะเชื่อมต่อ Agent กับ Gemini Enterprise

  1. เปิดหน้าการติดตั้งใช้งานแพลตฟอร์ม Agentในคอนโซล Google Cloud
  2. ใช้ช่องตัวกรองหากต้องการจำกัดรายการรันไทม์ให้แคบลง จากนั้นคลิกรันไทม์ mortgage-agent
  3. เปิดแท็บสนามเด็กเล่น
  4. พิมพ์พรอมต์เพื่อแชทกับตัวแทน
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?

ซึ่งควรแสดงผลการตอบกลับจากเครื่องมือจัดการเอกสารและเครื่องมือยืนยันรายได้ และควรมีการปกปิดหมายเลข SSN ในการตอบกลับนี้ด้วย 5. พิมพ์พรอมต์ติดตามผล

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

เอเจนต์จะส่งอีเมลได้สำเร็จ เนื่องจากไม่ได้บังคับใช้นโยบายแบบมีเงื่อนไขเนื่องจากส่วนขยาย IAP อยู่ในโหมดทดลองเรียกใช้

เนื่องจากมีการติดตั้งใช้งานเอเจนต์ด้วยเครื่องมือวัด OpenTelemetry Playground จึงแสดงมุมมองแผงด้านข้าง 4 รายการที่คุณสลับไปมาระหว่างที่เอเจนต์ตอบกลับได้ ดังนี้

  • Trace - Trace แบบเต็มของการสนทนา รวมถึง Agent Gateway, IAP REQUEST_AUTHZ และ Model Armor CONTENT_AUTHZ
  • เหตุการณ์ - กราฟของเครื่องมือที่เรียกใช้และรายละเอียดเหตุการณ์สำหรับเทิร์นปัจจุบัน
  • สถานะ - สถานะเซสชันของตัวแทนและอินพุต/เอาต์พุตของเครื่องมือ
  • เซสชัน - ทุกเซสชันที่คุณเริ่มเทียบกับรันไทม์นี้

15. บังคับใช้การให้สิทธิ์ IAP

ตอนนี้เราได้ตรวจสอบการติดตั้งใช้งานแล้ว จึงสามารถอัปเดตโหมดการบังคับใช้ IAP เป็น null เพื่อบังคับใช้นโยบายได้ เปิด terraform.tfvars แล้วอัปเดตโหมดจาก DRY_RUN เป็น null

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

ใช้การเปลี่ยนแปลง

terraform apply

กลับไปที่ Playground แล้วลองสนทนาอีกครั้ง

  1. เปิดหน้าการติดตั้งใช้งานแพลตฟอร์ม Agentในคอนโซล Google Cloud
  2. ใช้ช่องตัวกรองหากต้องการจำกัดรายการรันไทม์ให้แคบลง จากนั้นคลิกรันไทม์ mortgage-agent
  3. เปิดแท็บสนามเด็กเล่น
  4. พิมพ์พรอมต์เพื่อแชทกับตัวแทน
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?

ซึ่งควรแสดงผลการตอบกลับจากเครื่องมือจัดการเอกสารและเครื่องมือยืนยันรายได้ และควรมีการปกปิดหมายเลข SSN ในการตอบกลับนี้ด้วย 5. พิมพ์พรอมต์ติดตามผล

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

หากตั้งค่าทุกอย่างถูกต้องแล้ว เอเจนต์ควรตอบกลับว่าส่งอีเมลไม่ได้เนื่องจากนโยบายการให้สิทธิ์

16. การตั้งค่าและการทดสอบ Gemini Enterprise

ตั้งค่า Gemini Enterprise

ทำตามคู่มือการเริ่มต้นใช้งาน Gemini Enterprise

ลงทะเบียน Agent ของ ADK กับ Gemini Enterprise

หากต้องการทำตามขั้นตอนเพื่อลงทะเบียนเอเจนต์ใน Gemini Enterprise โปรดทำตามขั้นตอนที่นี่

  1. ในคอนโซล Google Cloud ให้ไปที่หน้า Gemini Enterprise
  2. เลือกแอป Gemini Enterprise ที่ลงทะเบียนเอเจนต์
  3. เปิด URL ที่แสดงในส่วนเว็บแอป Gemini Enterprise พร้อมใช้งานแล้ว
  4. เลือกแท็บเอเจนต์จากเมนูด้านซ้ายเพื่อเปิดแกลเลอรีเอเจนต์
  5. เลือกตัวแทนผู้ช่วยด้านสินเชื่อที่อยู่อาศัย แล้วเริ่มแชท

ลองใช้พรอมต์เดียวกันจาก Agent Runtime Playground

พรอมต์เริ่มต้น

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?

พรอมต์ติดตามผล:

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

หากกลับไปที่ส่วนการติดตั้งใช้งาน Agent ในคอนโซล ให้เลือกการติดตั้งใช้งาน Agent ของเรา แล้วไปที่แท็บการติดตาม ตอนนี้คุณจะเห็น Agent ของ Gemini Assistant ในช่วงที่แสดงการเรียกที่มาจาก Gemini Enterprise

17. แดชบอร์ดความสามารถในการสังเกต

แดชบอร์ดการแก้ไขข้อบกพร่องในการให้สิทธิ์จะแสดงมุมมองเดียวของการรับส่งข้อมูลขาออกจาก Agent ของ Agent Runtime

แดชบอร์ดความสามารถในการสังเกต

แดชบอร์ดจะแสดงข้อมูลต่อไปนี้

  • Agent ➔ ปลายทาง (การปฏิเสธ 403)
  • Agent ➔ เซิร์ฟเวอร์ MCP (การปฏิเสธ 403)
  • Agent ➔ Agent (การปฏิเสธ 403)
  • การบล็อกขาออกที่ไม่ได้จดทะเบียน
  • ภาพรวมการเข้าชมและโหมดการบังคับใช้ IAP
  • การปฏิเสธ IAM ของ GCP API

วิดเจ็ตแต่ละรายการจะแสดงรหัสตัวแทน โฮสต์ที่ขอ เส้นทางทรัพยากรที่ลงทะเบียน และระบุว่าเกตเวย์และ IAP อนุญาตคำขอหรือไม่

  • การบล็อกขาออกที่ไม่ได้ลงทะเบียน - วิดเจ็ตนี้จะแยกการเข้าชมที่ Agent Gateway บล็อกโดยเฉพาะ เนื่องจากไม่มีชื่อโฮสต์ปลายทางในรีจิสทรีของ Agent เนื่องจากพร็อกซีเกตเวย์บล็อกคำขอเหล่านี้ก่อนที่จะส่งไปยัง IAP จึงไม่มีบันทึกการตรวจสอบ IAP สำหรับรายการเหล่านี้
  • ภาพรวมการเข้าชมและโหมดการบังคับใช้ IAP - วิดเจ็ตนี้แสดงตารางที่แสดงรูปแบบการเข้าชมทั้งหมด ที่สำคัญคือสถานะการทดสอบ IAP ซึ่งช่วยให้ผู้ใช้ทราบว่านโยบาย IAP บล็อกการรับส่งข้อมูลอยู่หรือไม่ หรือเพียงแค่สังเกตการณ์
  • การปฏิเสธ IAM ของ GCP API - วิดเจ็ตนี้จะค้นหาบันทึกการตรวจสอบระบบคลาวด์มาตรฐาน (cloudaudit.googleapis.com) เพื่อตรวจหาข้อผิดพลาดเกี่ยวกับสิทธิ์ของ Google Cloud API ที่ซ่อนอยู่สำหรับเอเจนต์

แดชบอร์ดนี้อยู่ใน Cloud Console: Monitoring > Dashboards > Agent Platform: Authorization Debugging

18. การแก้ปัญหาและการแก้ไขทั่วไป

การแก้ไขข้อบกพร่องที่ AI ช่วยด้วย Gemini CLI

คุณใช้agent-platform-debuggerภายใน Gemini CLI เพื่อแก้ปัญหาได้ โดยทักษะนี้จะรวบรวมความรู้เฉพาะทางสำหรับการแก้ไขข้อบกพร่องที่ AI ช่วยเหลือไว้ เนื่องจาก Gemini CLI ถือว่า .agents/skills/ เป็นนามแฝงระดับเฟิร์สคลาสสำหรับ .gemini/skills/ ที่ขอบเขตของพื้นที่ทำงาน คุณจึงใช้ทักษะได้โดยตรง หากต้องการใช้ทักษะนี้จากภายใน Codelab Repo ให้ทำดังนี้

ไปที่ไดเรกทอรีที่เก็บและเริ่ม Gemini CLI โดยทำดังนี้

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

เชื่อถือพื้นที่ทำงานเมื่อได้รับแจ้ง (ทักษะระดับพื้นที่ทำงานจะโหลดจากโฟลเดอร์ที่เชื่อถือได้เท่านั้น) ยืนยันว่าโหลดทักษะแล้ว

/skills list

คุณควรเห็น agent-platform-debugger ในรายการ หากไม่มี ให้โหลดทักษะใหม่โดยทำดังนี้

/skills reload

เคล็ดลับในการแก้ปัญหา

  • terraform apply ล้มเหลวใน Agent Gateway โดยมีข้อความว่า "กำลังสร้างทรัพยากร จึงอัปเดตไม่ได้" — โปรเจ็กต์กลุ่มผู้ใช้ของเกตเวย์ใช้เวลาประมาณ 30 วินาทีในการตั้งค่าก่อนที่จะแนบนโยบายการให้สิทธิ์ได้ time_sleep.wait_for_gateway ของโมดูลจะจัดการเรื่องนี้ เพียงแค่เรียกใช้ terraform apply อีกครั้ง
  • Agent รายงานว่า "ไม่พบเซิร์ฟเวอร์ MCP" หรือบูตด้วยเครื่องมือยูทิลิตีเท่านั้น - ยืนยัน enable_agent_registry_endpoints = true ใน terraform.tfvars จากนั้นทำดังนี้
    gcloud alpha agent-registry mcp-servers list \
  --project=${PROJECT_ID} --location=${REGION}
    คุณควรเห็นรายการ 3 รายการ (รายการละ 1 รายการต่อบริการ MCP ของ Cloud Run) หากรายการว่างเปล่า ให้ตรวจสอบว่าเข้าถึงบริการ MCP จากภายใน VPC ได้ และ Agent Gateway ได้ป้อนข้อมูลรีจิสทรีแล้ว (ระบบจะดำเนินการนี้เมื่อมีการแสดงรายการเครื่องมือที่พร็อกซีเป็นครั้งแรก)
  • การเรียกใช้เครื่องมือแสดงผล 403 PermissionDenied - เรียกใช้ scripts/grant_agent_mcp_egress.sh อีกครั้ง สาเหตุที่พบบ่อยที่สุดคือการลืมให้สิทธิ์อีกครั้งหลังจากติดตั้งใช้งานเอเจนต์ใหม่ (reasoningEngines/ จะเปลี่ยนไปทุกครั้งที่ติดตั้งใช้งาน)
  • skaffold run ล้มเหลวโดยมีข้อความ "สิทธิ์สำหรับบัญชีบริการถูกปฏิเสธ" — คุณไม่มี roles/iam.serviceAccountUser เรียกใช้การให้สิทธิ์ตัวเองอีกครั้งในขั้นตอนก่อนหน้า
  • ข้อผิดพลาดในการเชื่อมต่อ DNS จาก Agent Gateway ไปยัง MCP LB — ตรวจสอบว่า agent_gateway_dns_peering_config.target_network ตรงกับ projects/${PROJECT_ID}/global/networks/${VPC_NAME} ทุกประการ และรายการ domains ทุกรายการลงท้ายด้วยจุด
  • terraform planยังคงต้องการอัปเดตแท็กรูปภาพ Cloud Run ซึ่งไม่ควรเกิดขึ้นเนื่องจากกฎ lifecycle { ignore_changes } หากเกิดขึ้น ให้ยืนยันว่าคุณไม่ได้แก้ไข mcp_services[*].image ใน terraform.tfvars หลังจาก skaffold run

19. ล้างข้อมูล

Terraform ไม่ได้จัดการเครื่องมือให้เหตุผล (ADK SDK เป็นผู้สร้าง) ลบด้วยตนเองโดยทำดังนี้

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

ลบทุกอย่างที่ Terraform สร้างขึ้น

cd terraform
terraform destroy
cd ..

หากคุณสร้างโซน DNS สาธารณะเพื่อใช้กับ Codelab นี้โดยเฉพาะ ให้ทำดังนี้

gcloud dns managed-zones delete agw-example-com

สุดท้าย ให้ลบ Bucket สถานะ Terraform โดยทำดังนี้

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

20. ขอแสดงความยินดี

ยินดีด้วย คุณได้ใช้การกำกับดูแลเอเจนต์ที่ครอบคลุมสําหรับเอเจนต์ ADK แบบหลายเครื่องมือโดยใช้ Agent Gateway เรียบร้อยแล้ว Agent Gateway ทำหน้าที่เป็นระนาบควบคุมเครือข่ายส่วนกลาง ซึ่งช่วยให้คุณสร้างเส้นทางขาออกที่ปลอดภัยไปยังเครื่องมือส่วนตัว บังคับใช้นโยบาย IAM แบบละเอียดตามข้อมูลระบุตัวตนผ่าน Identity-Aware Proxy และล้างข้อมูลการโต้ตอบเนื้อหาโดยใช้การ์ดเรล Model Armor ที่ผสานรวม

สิ่งที่คุณได้เรียนรู้

  • วิธีติดตั้งใช้งานและกำหนดค่า Agent Gateway เป็นเลเยอร์การกำกับดูแลส่วนกลางสำหรับการรับส่งข้อมูลขาออกจาก Agent ไปยังทุกที่
  • วิธีผสานรวมรีจิสทรีของเอเจนต์เพื่อการค้นพบเครื่องมือรันไทม์แบบไดนามิกที่มีการควบคุม
  • วิธีเขียนและบังคับใช้นโยบาย IAM ต่อเครื่องมือและตามเงื่อนไขเพื่อควบคุมเส้นทางการดำเนินการของเอเจนต์อย่างเข้มงวด
  • วิธีใช้ประโยชน์จากส่วนขยายบริการ Agent Gateway เพื่อใช้นโยบาย Model Armor โดยการสกัดกั้นและปกปิดข้อมูลที่ละเอียดอ่อนของการรับส่งข้อมูลของเอเจนต์โดยอัตโนมัติ

เอกสารอ้างอิง