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

การออกของ Agent Gateway จาก Agent Runtime ไปยัง Google MCP

1. บทนำ

Codelab นี้จะสำรวจการกำกับดูแลขาออกของ Agent Gateway สำหรับ Agent AI ที่เข้าถึงเซิร์ฟเวอร์ Model Context Protocol (MCP) ของ Google Cloud จากระยะไกล

แอป AI ตั้งแต่แชทบอทแบบสแตนด์อโลนไปจนถึงระบบอัตโนมัติที่มีเวิร์กโฟลว์แบบหลายเอเจนต์สามารถเรียกใช้เครื่องมือภายนอกแบบไดนามิกได้ การให้สิทธิ์เข้าถึงที่ควบคุมแก่เอเจนต์เพื่อค้นหาฐานข้อมูล ดึงเนื้อหาเว็บ และดำเนินการต่างๆ เป็นสิ่งจำเป็นสำหรับเอเจนต์ที่ปลอดภัยและมีประสิทธิภาพ อย่างไรก็ตาม ในสภาพแวดล้อมขององค์กร การรักษาความปลอดภัยในการดำเนินการเครื่องมือของเอเจนต์เป็นเรื่องที่ท้าทาย หากตัวแทนมีสิทธิ์เข้าถึงเครือข่ายโดยตรง การโจมตีแบบแทรกพรอมต์หรือการหลอนของโมเดลอาจทำให้ตัวแทนขโมยข้อมูลที่ละเอียดอ่อนหรือเรียกใช้คำสั่งที่เป็นอันตรายได้

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

เมื่อ Agent Gateway ทำงานในโหมดขาออก (agent-to-anywhere) ระบบจะพร็อกซีคำขอขาออกทั้งหมดจากเอเจนต์ที่กำหนดค่าให้ใช้เกตเวย์ ระบบจะตรวจสอบสิทธิ์คำขอภาระงานของเอเจนต์แต่ละรายการโดยใช้ข้อมูลประจำตัวของเอเจนต์ที่ไม่ซ้ำกัน และให้สิทธิ์โดยใช้นโยบาย Identity-Aware Proxy (IAP) การเรียกใช้เครื่องมือ MCP จะได้รับการถอดรหัสและตรวจสอบแบบไดนามิกเพื่อการบังคับใช้นโยบาย ผู้ดูแลระบบความปลอดภัยสามารถบังคับใช้สิทธิ์แบบละเอียดจากส่วนกลางเพื่อให้มั่นใจว่าตัวแทนจะเรียกใช้ได้เฉพาะปลายทางและวิธีการที่ได้รับอนุมัติเท่านั้น

สิ่งที่คุณสร้าง

Agent Gateway ในโหมดขาออก (agent-to-anywhere)
ส่วนขยายการให้สิทธิ์ Identity-Aware Proxy (IAP)
Agent ADK ของ Agent Runtime ที่มีข้อมูลระบุตัวตนของ Agent
Agent Registry ที่มี API ของ Google และปลายทาง MCP
นโยบายการให้สิทธิ์ที่มีการควบคุมการเข้าถึง IAM
ชุดข้อมูล BigQuery ที่จะค้นหาโดยใช้ MCP

รูปที่ 1 สถาปัตยกรรม Codelab

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

วิธีติดตั้งใช้งาน Agent Gateway ในลําดับการกําหนดค่าที่มีโครงสร้าง
วิธีเปลี่ยนนโยบายการให้สิทธิ์จากโหมดทดลองเรียกใช้เป็นโหมดบังคับใช้
วิธีลงทะเบียนปลายทาง Google API และเซิร์ฟเวอร์ MCP ใน Agent Registry
วิธีตรวจสอบบันทึกของ Agent Gateway เพื่อตรวจสอบการควบคุมการออก

สิ่งที่ต้องมี

โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน
สิทธิ์ IAM ในการจัดสรรบริการเครือข่าย ชุดข้อมูล BigQuery และทรัพยากร Agent Platform
Shell ที่เข้ากันได้กับ POSIX (bash หรือ zsh) ที่ติดตั้ง Google Cloud CLI (คอมโพเนนต์ gcloud และ bq)
เครื่องมือบรรทัดคำสั่ง: git, curl, jq (ตัวประมวลผล JSON), Python 3 และ uv (ตัวจัดการแพ็กเกจ Python)

2. แนวคิด

ลำดับการติดตั้งใช้งาน

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

Codelab นี้ใช้ลำดับการติดตั้งใช้งานต่อไปนี้

เริ่มในโหมดทดสอบ: หากกำหนดค่ารันไทม์ของตัวแทนให้กำหนดเส้นทางการโทรขาออกไปยังเกตเวย์ก่อนที่จะจัดสรรเกตเวย์อย่างเต็มรูปแบบ เวิร์กโหลดจะเริ่มต้นไม่สำเร็จ การกำหนดค่าส่วนขยายการให้สิทธิ์เกตเวย์ในโหมด DRY_RUN ก่อนจะช่วยให้มั่นใจได้ว่าเมื่อการเข้าชมของตัวแทนมาถึงเกตเวย์ จะไม่มีการทิ้งคำขอ
ลงทะเบียนบริการทั้งหมด: ต้องลงทะเบียนตัวแทน เซิร์ฟเวอร์ MCP และปลายทางทั้งหมดที่ใช้ Agent Gateway ใน Agent Registry ระบบจะปฏิเสธคำขอสำหรับแหล่งที่มาหรือปลายทางที่ไม่ได้ลงทะเบียน ระบบจะลงทะเบียน Agent ที่ติดตั้งใช้งานใน Agent Runtime และเซิร์ฟเวอร์ MCP ของ Google โดยอัตโนมัติ คุณต้องลงทะเบียนปลายทาง Google API หรือเซิร์ฟเวอร์ MCP ที่กำหนดเองด้วยตนเอง
บังคับใช้นโยบายการให้สิทธิ์: นโยบายการให้สิทธิ์ใช้เพื่ออนุญาตให้ตัวแทนที่ลงทะเบียนเข้าถึงคอมโพเนนต์ของตัวแทนโดยการให้บทบาท roles/iap.egressor แก่หลักการระบุตัวตนของตัวแทนและเชื่อมโยงกับทรัพยากรรีจิสทรีเป้าหมาย ประเมินลักษณะการทำงานของ Agent โดยใช้โหมดการทดสอบ แล้วกำหนดนโยบายเพื่ออนุญาตให้การรับส่งข้อมูลขาออกที่เลือกผ่านเกตเวย์ เมื่อตั้งค่านโยบายแล้ว ให้เปลี่ยนไปใช้โหมด ENFORCED เพื่อเปิดใช้เกตเวย์ให้บังคับใช้นโยบายการกำกับดูแลอย่างแข็งขัน

รูปที่ 2 ลำดับการติดตั้งใช้งาน

โทโพโลยีการกำหนดเส้นทางขาออก

โดยปกติแล้ว เกตเวย์จะจัดการการรับส่งข้อมูลขาเข้า (Ingress) ไปยังบริการแบ็กเอนด์ Agent Gateway ซึ่งทำงานในโหมดขาออก (Agent-to-Anywhere) จะทำหน้าที่เป็นพร็อกซีขาออกแบบ Zero Trust ที่มีศูนย์กลางสำหรับภาระงานของ Agent

เมื่อแอป AI หรือภาระงานของเอเจนต์พยายามเรียกใช้เครื่องมือหรือ API ภายนอก Agent Gateway จะสกัดกั้นคำขอขาออกและประเมินตามนโยบายการกำกับดูแลก่อนที่จะกำหนดเส้นทางไปยังปลายทาง

เครือข่ายส่วนตัว (VPC): การรับส่งข้อมูลขาออกที่กำหนดเป้าหมายเป็น API ภายในขององค์กร, ไมโครเซอร์วิส, ฐานข้อมูลที่โฮสต์ภายใน VPC ส่วนตัว และเครือข่ายในองค์กรหรือข้ามระบบคลาวด์ที่เข้าถึงได้ผ่านการเชื่อมต่อแบบผสม
เครือข่ายภายนอก (อินเทอร์เน็ต): การรับส่งข้อมูลขาออกที่กำหนดเป้าหมายไปยังบริการเว็บของบุคคลที่สาม, API ของ SaaS หรือปลายทางสาธารณะ
บริการ AI และแพลตฟอร์มเอเจนต์: การรับส่งข้อมูลขาออกที่กำหนดเป้าหมายไปยัง Google Cloud API ที่มีการจัดการ, โมเดลพื้นฐาน, จุดปลายทาง Google MCP (เช่น BigQuery) และบริการการกำกับดูแลแพลตฟอร์ม (Agent Registry และนโยบาย IAP)

รูปที่ 3 โทโพโลยีการกำหนดเส้นทางขาออกของ Agent Gateway

Codelab นี้มุ่งเน้นที่การรับส่งขาออกจาก Agent ที่กำหนดเองใน Agent Runtime ซึ่งกำหนดเป้าหมายไปยังปลายทางเซิร์ฟเวอร์ Google MCP ระยะไกลสำหรับ BigQuery

3. ตั้งค่า

บทบาท IAM ที่จำเป็น

คุณต้องมีบทบาทต่อไปนี้เพื่อสร้างทรัพยากรใน Codelab นี้

หมวดหมู่	บทบาท IAM (รหัส) ที่ต้องมี	คำอธิบาย
การจัดการ API	`roles/serviceusage.serviceUsageAdmin`	เปิดใช้บริการ Google Cloud API
เครือข่ายและเกตเวย์	`roles/networkservices.admin`	จัดสรร Agent Gateway
ส่วนขยายบริการ	`roles/serviceextensions.admin`	กำหนดค่าส่วนขยายการกำหนดเส้นทาง
การรักษาความปลอดภัยของเครือข่าย	`roles/networksecurity.admin`	ติดตั้งใช้งานนโยบายการให้สิทธิ์
Agent Registry	`roles/agentregistry.admin`	โฮสต์ที่อนุญาตของแคตตาล็อก
Vertex AI และเอเจนต์	`roles/aiplatform.admin`	ทำให้ภาระงาน Agent Runtime ใช้งานได้
นโยบายขาออก	`roles/iap.admin`	ใช้นโยบาย `roles/iap.egressor`
BigQuery	`roles/bigquery.admin`	ตั้งค่าสคีมาและชุดข้อมูลทดสอบ
Cloud Storage	`roles/storage.admin`	จัดการที่เก็บข้อมูลการจัดเตรียมการทำให้ใช้งานได้
บันทึกและการตรวจสอบ	`roles/logging.viewer`	ตรวจสอบการติดตามและบันทึกการตรวจสอบ

หรือจะใช้บทบาทพื้นฐานแบบกว้าง เช่น roles/admin หรือบทบาทเดิม roles/owner ก็ได้

เข้าถึงโปรเจ็กต์

Codelab นี้ใช้โปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google เดียว ขั้นตอนการกำหนดค่าใช้คำสั่ง CLI ของ gcloud และคำสั่ง Shell ของ Linux

เริ่มต้นด้วยการเข้าถึงบรรทัดคำสั่งของโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google โดยทำดังนี้

Cloud Shell ที่ shell.cloud.google.com หรือ
เทอร์มินัลในเครื่องที่gcloud CLI ติดตั้งแล้ว

ตั้งค่ารหัสโปรเจ็กต์

gcloud config set project SET_YOUR_PROJECT_ID_HERE

ตรวจสอบสิทธิ์เซสชัน

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

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

# set custom var for slug (eg, "foo") and region preference
export SLUG="foo"
export REGION="us-central1"
export MREGION="us"
echo ${SLUG}
echo ${REGION}
echo ${MREGION}

# create project vars (automatic)
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-dj"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

เปิดใช้บริการ API

# enable google apis (agent platform bundle, part 1)
gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iamconnectors.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  discoveryengine.googleapis.com

ส่วนการตั้งค่าก็มีเพียงเท่านี้... ต่อไปเราจะไปที่ส่วนเกตเวย์

4. เกตเวย์

ก่อนบังคับใช้การควบคุมการเข้าถึง ให้ติดตั้งใช้งาน Agent Gateway และกำหนดค่าส่วนขยายการให้สิทธิ์ในโหมด DRY_RUN ซึ่งจะช่วยให้การเรียกใช้เครื่องมือขาออกสำเร็จในขณะที่บันทึกผลการประเมินเพื่อวัตถุประสงค์ในการตรวจสอบ

ในที่นี้ Agent Gateway ใช้รีจิสทรีระดับภูมิภาคเพื่อรองรับทรัพยากร Agent Runtime ระดับภูมิภาค

สร้างเกตเวย์

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

ส่วนของเกตเวย์จบลงแล้ว... ต่อไปเป็นส่วนการให้สิทธิ์

5. การให้สิทธิ์

ส่วนขยายการให้สิทธิ์ Agent Gateway สำหรับ Identity-Aware Proxy (IAP) เป็นส่วนขยายบริการประเภทหนึ่งที่ใช้ในการมอบสิทธิ์การตัดสินใจด้านการให้สิทธิ์สำหรับการสื่อสารทั้งหมดของแพลตฟอร์ม Agent

ขั้นตอนการมอบสิทธิ์: เมื่อ Agent พยายามเรียกใช้ปลายทางภายนอกหรือเซิร์ฟเวอร์ MCP ระบบจะกำหนดเส้นทางคำขอไปยัง Agent Gateway เกตเวย์จะใช้ส่วนขยายการให้สิทธิ์เพื่อส่งการเรียกใช้ไปยังบริการประเมิน IAP แทนการประเมินการเข้าถึงในเครื่อง IAP จะประเมินข้อมูลระบุตัวตนของเอเจนต์ (อิงตาม SPIFFE) กับนโยบาย IAM ของทรัพยากรเป้าหมายใน Agent Registry IAP จะส่งการตัดสินใจ ALLOW หรือ DENY กลับไปยังเกตเวย์ ซึ่งจะส่งต่อการเข้าชมหรือบล็อกการเข้าชมด้วยรหัสสถานะ HTTP 403 Forbidden
โหมดการบังคับใช้: ในโหมดDRY_RUN IAP จะประเมินคำขอและบันทึกการตัดสินใจใน Cloud Logging โดยไม่บล็อกการรับส่งข้อมูล ในโหมด ENFORCE ระบบจะบล็อกคำขอจากเอเจนต์ที่ไม่ได้รับอนุญาตหรือคำขอที่ส่งไปยังเป้าหมายที่ไม่ได้ลงทะเบียนทันที
เลเยอร์การเชื่อมโยง: ส่วนขยายบริการเชื่อมต่อกับ Agent Gateway โดยใช้นโยบายการให้สิทธิ์ที่กำหนดค่าด้วยโปรไฟล์ REQUEST_AUTHZ

ส่วนขยายการให้สิทธิ์

สร้างส่วนขยายการให้สิทธิ์

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

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

# show authz extension details (verify extension state)
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap-dryrun \
  --location=${REGION}

นโยบายการให้สิทธิ์

นโยบายการให้สิทธิ์จะเชื่อมโยงผู้ให้บริการด้านความปลอดภัย (IAP) กับทรัพยากรเกตเวย์เป้าหมาย และระบุโปรไฟล์การสกัดกั้น (REQUEST_AUTHZ)

สร้างนโยบายการให้สิทธิ์

# create authz policy config file (attach dry-run authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-dryrun"
EOF

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

# show authz policy details (verify dry run mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

ส่วนการให้สิทธิ์ก็จบลงเพียงเท่านี้... ต่อไปเราจะไปที่ส่วนฐานของโค้ด

6. ฐานของโค้ด

เราจะดูแลโค้ดของเอเจนต์ ชุดข้อมูล BigQuery และสคริปต์การลงทะเบียนที่ใช้สำหรับ Codelab นี้ในที่เก็บ GitHub ของ Google Cloud ที่อยู่ระยะไกล ขั้นตอนต่อไปนี้จะโคลนที่เก็บในเครื่อง คัดลอกไฟล์ที่จำเป็นไปยังโครงสร้างไดเรกทอรีการทำงานปัจจุบัน แล้วล้างไฟล์ชั่วคราวที่ไม่จำเป็น

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

ดึงข้อมูลอาร์ติแฟกต์ระยะไกล

# clone remote repository to temp local dir
git clone https://github.com/GoogleCloudPlatform/cloud-networking-solutions.git ./temp_agw_cuj_arun_egress_gmcp

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

สร้างชุดข้อมูล BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

สร้าง Bucket สำหรับการทดสอบ

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

ส่วนของโค้ดเบสก็มีเพียงเท่านี้... ต่อไปเป็นส่วนรีจิสทรี

7. รีจิสทรี

Agent Registry คือพื้นที่เก็บข้อมูลส่วนกลางของเอเจนต์ เซิร์ฟเวอร์ MCP และปลายทาง (API) ทั้งหมดในระบบนิเวศ AI นอกจากนี้ ยังเป็นแคตตาล็อกที่ใช้เพื่อแสดง ค้นหา และค้นพบเครื่องมือและบริการอื่นๆ ที่ลงทะเบียนไว้สำหรับแอปพลิเคชัน AI ได้ด้วย โหมดขาออกของ Agent Gateway (agent-to-anywhere) ใช้รูปแบบข้อมูลรีจิสทรีเป็นกรอบการกำกับดูแลเพื่อบังคับใช้การควบคุมการเข้าถึงขาออก ระบบจะตรวจสอบการให้บทบาท IAM สำหรับผู้ใช้หลักที่เรียกใช้เอเจนต์กับนโยบายที่เชื่อมโยงกับทรัพยากรรีจิสทรี

ในการเริ่มต้นสภาพแวดล้อมและสนับสนุนตัวแทนที่ใช้ Google APIs และบริการต่างๆ จะมีการใช้สคริปต์เพื่อลงทะเบียนชุดปลายทาง API ทั่วไปอย่างรวดเร็วโดยใช้ชื่อโฮสต์และตำแหน่งจาก endpoints/googleapis.txt

ลงทะเบียนอุปกรณ์ปลายทาง

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

ยืนยันอุปกรณ์ปลายทาง

# list regional endpoints (verify registration)
gcloud agent-registry endpoints list --location=${REGION} \
  --format="table(displayName, name.basename():label=ENDPOINT_ID, interfaces[0].url:label=URL)"

ส่วนรีจิสทรีก็มีเพียงเท่านี้... ต่อไปเราจะไปที่ส่วนรันไทม์

8. รันไทม์

agent-dj Agent ADK ที่ติดตั้งใช้งานใน Agent Runtime จะได้รับการกำหนดค่าด้วยการตั้งค่าต่อไปนี้ในสคริปต์การติดตั้งใช้งานเพื่อผสานรวมกับ Agent Platform

"identity_type": types.IdentityType.AGENT_IDENTITY เพื่อจัดสรรข้อมูลประจำตัวหลักที่ไม่ซ้ำกันซึ่งอิงตาม SPIFFE สำหรับตัวแทน
"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } เพื่อนำการรับส่งข้อมูลทั้งหมดที่เอเจนต์เริ่มต้นขาออกไปยัง Agent Gateway เพื่อการประเมินและการบังคับใช้นโยบาย

ติดตั้งใช้งาน Agent

# deploy agent runtime workload
uv --directory agent-dj run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

ดึงข้อมูล Vitals ของการทำให้ใช้งานได้

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET \
  "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" \
  '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

ยืนยันรายการรีจิสทรี

# show agent resource registry details
gcloud agent-registry agents describe ${AGENT_UID} --location=${REGION}

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

ยืนยันการกำหนดค่าเกตเวย์

# verify agent gateway routing specification
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

มอบบทบาท IAM ของตัวแทนสำหรับทรัพยากร

การให้สิทธิ์บทบาท IAM สำหรับทรัพยากรช่วยให้ข้อมูลประจำตัวหลักของ Agent เข้าถึง BigQuery, เครื่องมือ MCP (สำหรับ Google API) และบริการแพลตฟอร์ม AI อื่นๆ ที่จำเป็นได้ นโยบายเหล่านี้บังคับใช้โดยใช้ IAM ที่ระดับทรัพยากร

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

ยืนยันบทบาท IAM ของตัวแทนสำหรับทรัพยากร

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

ส่วนรันไทม์ก็มีเพียงเท่านี้... ต่อไปเราจะไปที่ส่วนนโยบาย

9. นโยบาย

นโยบายการให้สิทธิ์การกำกับดูแลของ Agent อนุญาตให้การรับส่งจาก AI Agent ผ่าน Agent Gateway และไปยังปลายทาง (เช่น ปลายทางเซิร์ฟเวอร์ MCP ของ Google Cloud สำหรับ BigQuery) เมื่อการเข้าชมไปถึงปลายทาง สิทธิ์ IAM ปกติจะให้สิทธิ์เข้าถึงข้อมูล (และเปิดใช้ในส่วนก่อนหน้า)

การให้สิทธิ์บทบาท IAM สำหรับขาออกของ Agent Gateway จะเปิดใช้นโยบายการเข้าถึงที่อนุญาตให้สิทธิ์เข้าถึงข้อมูลประจำตัวหลักของ Agent เข้าถึงทรัพยากรปลายทางที่ลงทะเบียนผ่าน Agent Gateway ระบบจะบังคับใช้นโยบายที่ระดับเกตเวย์ของตัวแทนและตรวจสอบโดยใช้นโยบาย IAM ของ Identity-Aware Proxy (IAP)

มอบบทบาท IAM ของ Agent สำหรับขาออกของ Agent Gateway

Agent Gateway จะตรวจสอบคำขอขาเข้าเพื่อยืนยันว่าตัวแทนที่เรียกใช้มีสิทธิ์ iap.webServiceVersions.egressViaIAP (ได้รับจากบทบาท roles/iap.egressor) ในทรัพยากรเป้าหมาย

การให้สิทธิ์ roles/iap.egressor แก่ข้อมูลประจำตัวของ Agent หรือชุดหลักของ Agent Runtime ในทรัพยากรปลายทางที่เลือกจะอนุญาตการรับส่งข้อมูลขาออกนี้ ใน Codelab นี้ บทบาทจะใช้กับชุดผู้ใช้หลัก ซึ่งจะให้สิทธิ์แก่ข้อมูลประจำตัวของ Agent ทั้งหมดใน Agent Runtime ในโปรเจ็กต์

นโยบาย IAM จะเชื่อมโยงกับทรัพยากรปลายทางตามที่กำหนดไว้ในโมเดลข้อมูลของรีจิสทรีตัวแทน iap_web/agentRegistry ทรัพยากรแสดงถึงระดับ "ทั่วทั้งรีจิสทรี" ในลำดับชั้น IAM โดย agentRegistry จะเป็นทรัพยากรหลักของทรัพยากรย่อยแต่ละรายการสำหรับ agents, mcpServers และ endpoints ใน Codelab นี้ นโยบาย IAM จะเชื่อมโยงกับระดับรีจิสทรี ซึ่งจะใช้สิทธิ์กับทรัพยากรย่อยทั้งหมด

กำหนดค่านโยบาย IAM ของรีจิสทรีระดับภูมิภาคของ IAP

# show iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

# retrieve active etag on policy for regional registry
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION} --format="value(etag)")
echo ${IAP_ETAG}

# create policy config file
cat > cfg/iap-policy-re-agent-set-to-registry-${REGION}.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_ID_SET}"
      ]
    }
  ],
  "etag": "${IAP_ETAG}"
}
EOF

# import policy file (bind iam policy)
gcloud beta iap web set-iam-policy cfg/iap-policy-re-agent-set-to-registry-${REGION}.json \
  --resource-type=agent-registry \
  --region=${REGION}

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

ส่วนนโยบายก็มีเพียงเท่านี้... ต่อไปเราจะไปที่ส่วนการตรวจสอบ

10. ตรวจสอบ

ส่วนขยายการให้สิทธิ์ Agent Gateway ทำงานในโหมด DRY_RUN ระบบจะสังเกตและบันทึกคำขอขาออก แต่จะไม่บล็อก

ทดสอบการค้นหาของ Agent

เปิดหน้าต่างเบราว์เซอร์ไปยัง UI ของคอนโซล Google Cloud แล้วไปที่

แพลตฟอร์มตัวแทน → ตัวแทน → การติดตั้งใช้งาน → agent-dj
เลือกแท็บสนามเด็กเล่น

หรือใช้คำสั่งเทอร์มินัลนี้แล้วคลิกลิงก์เพื่อไปยังสนามเด็กเล่นของ Agent

# playground
echo "https://console.cloud.google.com/agent-platform/runtimes/locations/${REGION}/agent-engines/${RE_ENGINE_ID}/playground?project=${PROJ_ID}"

ส่งคำค้นหาทดสอบบางรายการ....

How many DJs do we have on file?
What is the phone number of DJ Cosmopup?

ตรวจสอบว่าคำค้นหาแสดงคำตอบที่ถูกต้อง (เช่น "มีดีเจ 12 คนในไฟล์")

วิเคราะห์บันทึกการตรวจสอบ

ดูบันทึกและตรวจสอบการประเมินนโยบายแบบดรายรัน

# query gateway logs for dry run
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL
  )"

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

ส่วนการตรวจสอบสิ้นสุดลงแล้ว... ต่อไปเป็นส่วนบังคับใช้

11. บังคับใช้

เอเจนต์สามารถส่งคำขอผ่านเกตเวย์ในโหมด DRY_RUN ได้สำเร็จ เปลี่ยนส่วนขยายการให้สิทธิ์ IAP ของ Agent Gateway เป็นโหมด ENFORCE โดยการอัปเดตนโยบายการให้สิทธิ์

อัปเดตส่วนขยายการให้สิทธิ์

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

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

# list authz extensions (imported configs)
gcloud service-extensions authz-extensions list --location=${REGION}

อัปเดตนโยบายการให้สิทธิ์

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

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

# show authz policy details (verify enforced mode)
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION}

ยืนยันการบังคับใช้

กลับไปที่ Playground ของเอเจนต์ใน UI ของคอนโซล

ส่งคำค้นหาทดสอบเพิ่มเติม...

What DJ Fishfry's credit card number?

สังเกตว่าคำขอของเอเจนต์ไปยังโมเดลพื้นฐานของ Gemini (${REGION}-aiplatform.googleapis.com/...) และปลายทางของเซิร์ฟเวอร์ MCP (bigquery.googleapis.com/mcp) จะส่งผ่านด้วยรหัสสถานะ HTTP 200 OK

# show gateway logs for http requests
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL)"

ตรวจสอบว่าไม่มีคำขอที่ถูกบล็อก มองหาความพยายามในการออกที่ถูกปฏิเสธด้วยรหัสสถานะ HTTP 403 Forbidden ในบันทึกการตรวจสอบเกตเวย์

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

ส่วนการบังคับใช้ก็มีเพียงเท่านี้... ต่อไปเราจะไปที่ส่วนการล้างข้อมูล

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

# delete agent
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

# delete storage bucket
gcloud -q storage rm --recursive gs://${STAGING_BUCKET}

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

# reset/clear iap regional registry iam policy
export IAP_ETAG=$(gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION} --format="value(etag)")
cat > cfg/iap-policy-empty.json << EOF
{
  "bindings": [],
  "etag": "${IAP_ETAG}"
}
EOF

gcloud beta iap web set-iam-policy cfg/iap-policy-empty.json \
  --resource-type=agent-registry \
  --region=${REGION}

# next

# delete gateway resources
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

gcloud -q beta service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap-dryrun --location=${REGION}

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

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

ส่วนการทำความสะอาดข้อมูลก็มีเพียงเท่านี้... ต่อไปเราจะไปที่บทสรุปกัน

13. บทสรุป

ยินดีด้วย คุณได้ติดตั้งใช้งานและควบคุมการสื่อสารขาออกสำหรับตัวแทนที่เข้าถึงเครื่องมือโดยใช้ Agent Gateway เรียบร้อยแล้ว

cosmopup

Cosmopup คิดว่า Codelab ยอดเยี่ยมมาก

ขั้นตอนถัดไป

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

โปรดแสดงความคิดเห็น ถามคำถาม หรือแก้ไขโดยใช้แบบฟอร์มความคิดเห็นนี้

ขอขอบคุณ