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

Agent Gateway thoát khỏi Agent Runtime sang mạng VPC

1. Giới thiệu

Lớp học lập trình này khám phá hoạt động quản trị lưu lượng truy cập đi ra của Cổng tác nhân cho các tác nhân AI truy cập vào các điểm cuối từ xa thông qua mạng VPC riêng tư. Agent Gateway hoạt động ở chế độ truyền dữ liệu đi (agent-to-anywhere) hỗ trợ kết nối riêng tư với mạng VPC bằng giao diện Private Service Connect (PSC). Trong trường hợp này, Agent Runtime sử dụng Agent Gateway để truy cập vào một máy chủ MCP HTTP có thể truyền trực tuyến từ xa do Cloud Run lưu trữ bằng cách sử dụng một điểm cuối Private Service Connect (PSC) cho các API của Google trong mạng VPC.

Các ứng dụng AI (từ chatbot độc lập đến hệ thống tự động có quy trình công việc nhiều tác nhân) có thể tự động gọi các công cụ bên ngoài. Việc cung cấp cho các tác nhân quyền truy cập có kiểm soát để truy vấn cơ sở dữ liệu, tìm nạp nội dung trên web và thực hiện các hành động là điều cần thiết để đảm bảo các tác nhân hoạt động an toàn và hiệu quả. Tuy nhiên, trong môi trường doanh nghiệp, việc bảo mật quá trình thực thi công cụ của tác nhân là một thách thức. Nếu có quyền truy cập trực tiếp vào mạng, các cuộc tấn công tiêm câu lệnh hoặc ảo giác của mô hình có thể khiến tác nhân đánh cắp dữ liệu nhạy cảm hoặc chạy các lệnh phá hoại.

Để quản lý các tác nhân tự trị ở quy mô lớn, Agent Gateway cung cấp một điểm thực thi tập trung, không tin tưởng bất cứ điều gì được tích hợp trực tiếp vào cấu trúc Agent Platform. Thay vì dựa vào các phương thức triển khai tuỳ chỉnh riêng cho từng ứng dụng hoặc mã tác nhân, Agent Gateway cung cấp tính năng định tuyến mạng, quản trị tác nhân và bảo mật thời gian chạy được thực thi ở cấp nền tảng.

Khi hoạt động ở chế độ truyền dữ liệu ra (agent-to-anywhere), Agent Gateway sẽ uỷ quyền tất cả các yêu cầu gửi đi từ những tác nhân được định cấu hình để sử dụng cổng này. Mỗi yêu cầu về khối lượng công việc của tác nhân đều được xác thực bằng Danh tính tác nhân duy nhất và được uỷ quyền bằng các chính sách Uỷ quyền truy cập dựa trên danh tính (IAP). Các lệnh gọi công cụ MCP được giải mã và kiểm tra linh hoạt để thực thi chính sách. Quản trị viên bảo mật có thể thực thi các quyền chi tiết một cách tập trung để đảm bảo các tác nhân chỉ có thể gọi các phương thức và điểm cuối đã được phê duyệt.

Sản phẩm bạn sẽ tạo ra

Agent Gateway ở chế độ truyền dữ liệu ra (agent-to-anywhere)
Tiện ích uỷ quyền Identity-Aware Proxy (IAP)
Tác nhân ADK Thời gian chạy của tác nhân có danh tính của tác nhân
Máy chủ MCP HTTP có thể truyền phát của Cloud Run
Sổ đăng ký tác nhân bằng Google API và các điểm cuối MCP tuỳ chỉnh
Chính sách uỷ quyền có tính năng kiểm soát quyền truy cập IAM
Tài nguyên mạng VPC, vùng Cloud DNS và điểm cuối PSC cho các API của Google
Tệp đính kèm mạng PSC cho lưu lượng truy cập đi của Agent Gateway
Quy tắc của chính sách tường lửa Tường lửa thế hệ mới (NGFW) trên đám mây

Hình 1. Cấu trúc lớp học lập trình

Kiến thức bạn sẽ học được

Cách triển khai Agent Gateway theo một trình tự cấu hình có cấu trúc
Cách định cấu hình Agent Gateway bằng khả năng kết nối mạng VPC riêng tư
Cách chuyển đổi chính sách uỷ quyền từ chế độ chạy thử sang chế độ thực thi
Cách đăng ký các điểm cuối Google API và máy chủ MCP trong Agent Registry
Cách kiểm tra nhật ký Cổng tác nhân để xác thực hoạt động quản trị dữ liệu đầu ra
Cách xác thực lưu lượng truy cập xuất của Cổng tác nhân bằng nhật ký Cloud NGFW

Bạn cần có

Một dự án trên Google Cloud đã bật tính năng thanh toán
Quyền IAM để cung cấp các dịch vụ mạng, tập dữ liệu BigQuery và tài nguyên Nền tảng tác nhân
Một trình bao tương thích với POSIX (bash hoặc zsh) đã cài đặt Google Cloud CLI (các thành phần gcloud và bq)
Công cụ dòng lệnh: git, curl, jq (trình xử lý JSON), Python 3 và uv (trình quản lý gói Python)

2. Khái niệm

Trình tự triển khai

Lớp học lập trình này tuân theo một trình tự cấu hình có cấu trúc để các tác nhân có quyền truy cập vào các tài nguyên cần thiết khi khởi tạo và có thể xác nhận khả năng kết nối trước khi áp dụng các chính sách truy cập bắt buộc.

Lớp học lập trình này sử dụng trình tự triển khai sau:

Bắt đầu ở chế độ DRY_RUN: Đảm bảo rằng các yêu cầu của tác nhân đang đến được cổng và đi qua (chỉ ở chế độ kiểm tra).
Đăng ký tất cả các dịch vụ: Đăng ký tất cả thành phần dựa trên tác nhân trong Sổ đăng ký tác nhân và xác nhận quyền truy cập vào công cụ của tác nhân. Sử dụng Cloud Logging và trang tổng quan về khả năng quan sát của Agent Gateway để xem các truy vấn đến Agent Registry.
Tạo chính sách uỷ quyền: Tạo và áp dụng chính sách uỷ quyền để cho phép lưu lượng truy cập truyền dữ liệu ra bên ngoài từ các tác nhân đến máy chủ và điểm cuối MCP.
Chuyển sang chế độ ENFORCED: Cập nhật chính sách về tiện ích uỷ quyền để thực thi các chính sách và chặn lưu lượng truy cập đi ra trái phép.

Hình 2. Trình tự triển khai

Cấu trúc liên kết định tuyến xuất dữ liệu

Cổng Agent Gateway (agent-to-anywhere) đóng vai trò là một proxy đi ra tập trung, không tin cậy cho các khối lượng công việc có tác nhân. Khi một tác nhân đưa ra yêu cầu đối với một công cụ hoặc API bên ngoài, yêu cầu gửi đi sẽ bị Agent Gateway chặn và đánh giá dựa trên các chính sách quản trị trước khi được định tuyến đến đích đến. Trong cấu trúc Nền tảng tác nhân của Google Cloud, Cổng tác nhân cung cấp khả năng kết nối lớp dữ liệu với:

Mạng riêng (VPC): Lưu lượng truy cập đi nhắm đến các API nội bộ của doanh nghiệp, các vi dịch vụ, cơ sở dữ liệu được lưu trữ trong các VPC riêng tư và các mạng tại chỗ hoặc trên nhiều đám mây có thể truy cập thông qua kết nối kết hợp.
Mạng bên ngoài (Internet): Lưu lượng truy cập đi nhắm đến các dịch vụ web của bên thứ ba, API SaaS hoặc các điểm cuối công khai.
Dịch vụ AI và Nền tảng tác nhân: Lưu lượng truy cập đi nhắm đến các API được quản lý của Google Cloud, các mô hình cơ sở, các điểm cuối Google MCP (chẳng hạn như BigQuery) và các dịch vụ quản trị nền tảng (Agent Registry và các chính sách IAP).

Hình 3. Cấu trúc liên kết định tuyến truyền dữ liệu ra của Cổng đại lý

Lớp học lập trình này tập trung vào lưu lượng truy cập đi ra từ một tác nhân tuỳ chỉnh trên Thời gian chạy tác nhân nhắm đến một điểm cuối PSC cho API của Google được triển khai trong một mạng VPC. Cấu trúc này cho phép truy cập riêng tư vào máy chủ MCP được lưu trữ trên Cloud Run bằng cách sử dụng tệp đính kèm mạng PSC cho lưu lượng truy cập đi ra của Agent Gateway.

Khả năng kết nối VPC

Cổng ra của Agent Gateway (agent-to-anywhere) có thể kết nối với một mạng VPC bằng cách chỉ định networkConfig: egress: networkAttachment: [URI] trong tệp cấu hình YAML triển khai. Chế độ cài đặt này định cấu hình các quy tắc định tuyến trên Agent Gateway để gửi lưu lượng truy cập phân giải thành địa chỉ IP riêng tư thông qua phần đính kèm mạng PSC vào mạng VPC.

Hình 4. Khả năng kết nối VPC của Agent Gateway

Agent Gateway có thể phân giải tên máy chủ DNS riêng tư bằng cách sử dụng tính năng kết nối ngang hàng của Cloud DNS với một dự án mục tiêu và mạng VPC được chỉ định. Mọi vùng riêng tư có trong cấu hình dnsPeeringConfig: domains: [NAME] sẽ sử dụng bản ghi Cloud DNS trong dự án mục tiêu. Mọi truy vấn DNS khác sẽ sử dụng trình phân giải công khai Cloud DNS mặc định của VPC.

Đến đây là kết thúc phần khái niệm... tiếp theo là phần Thiết lập.

3. Thiết lập

Các vai trò IAM bắt buộc

Bạn cần có các vai trò sau đây để tạo tài nguyên trong Lớp học lập trình này:

Danh mục	Vai trò IAM bắt buộc (ID)	Mô tả
Quản lý API	`roles/serviceusage.serviceUsageAdmin`	Bật các dịch vụ Google Cloud API
Kết nối mạng và cổng	`roles/networkservices.admin`	Cấp phép Agent Gateway
Tiện ích dịch vụ	`roles/serviceextensions.admin`	Định cấu hình tiện ích định tuyến
Bảo mật mạng	`roles/networksecurity.admin`	Triển khai chính sách uỷ quyền
Sổ đăng ký tác nhân	`roles/agentregistry.admin`	Máy chủ được phép trong danh mục
Vertex AI và các tác nhân	`roles/aiplatform.admin`	Triển khai khối lượng công việc Thời gian chạy tác nhân
Chính sách xuất dữ liệu	`roles/iap.admin`	Áp dụng chính sách của `roles/iap.egressor`
Cloud Storage	`roles/storage.admin`	Quản lý các vùng lưu trữ dàn dựng việc triển khai
Nhật ký và kiểm tra	`roles/logging.viewer`	Kiểm tra dấu vết và nhật ký kiểm tra
Nhà phát triển Cloud Run	`roles/run.developer`	Triển khai các dịch vụ Cloud Run
Người đọc Artifact Registry	`roles/artifactregistry.reader`	Kéo hình ảnh vùng chứa
Quản trị viên mạng máy tính	`roles/compute.networkAdmin`	Quản lý tài nguyên mạng VPC
Quản trị viên DNS	`roles/dns.admin`	Quản lý các bản ghi và vùng Cloud DNS

Ngoài ra, hãy sử dụng một vai trò cơ bản rộng như roles/admin hoặc vai trò cũ roles/owner.

Truy cập vào dự án của bạn

Lớp học lập trình này sử dụng một dự án duy nhất trên Google Cloud. Các bước định cấu hình sử dụng CLI gcloud và các lệnh shell Linux.

Bắt đầu bằng cách truy cập vào dòng lệnh của dự án trên Google Cloud:

Cloud Shell tại shell.cloud.google.com, hoặc
Một dòng lệnh cục bộ đã cài đặt gcloud CLI

Đặt mã dự án

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Xác thực phiên

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

Đặt các biến môi trường của trình bao

# 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)
export USER_IDENTITY=$(gcloud config get-value account)
echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# 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-weather"
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}"
export MCP_NAME="mcp-weather"
export MCP_DISPLAY_NAME="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app"
export MCP_URL="https://${MCP_DISPLAY_NAME}/mcp"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}
echo ${MCP_NAME}
echo ${MCP_DISPLAY_NAME}
echo ${MCP_URL}

# create local dir for config files
mkdir -p cfg

Cập nhật vào `gcloud cli` (nên làm)

Nếu bạn đang chạy bản cài đặt do chính mình quản lý của Google Cloud SDK (tức là bên ngoài Cloud Shell), hãy cập nhật các thành phần lên phiên bản mới nhất.

# update gcloud cli
gcloud components update

Bật dịch vụ 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

# enable google apis (all the rest)
gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com

Đến đây là kết thúc phần thiết lập... tiếp theo là phần Mạng.

4. Mạng

Mạng VPC được triển khai bằng chế độ tuỳ chỉnh để tạo các mạng con thông thường hỗ trợ phần đính kèm mạng PSC cho Agent Gateway và lưu lượng truy cập trực tiếp ra khỏi VPC của Cloud Run.

Điểm cuối PSC cho các API của Google được triển khai bằng một /32địa chỉ IPv4 nội bộ toàn cầu để hỗ trợ quyền truy cập nội bộ riêng tư vào Cloud Run. Địa chỉ IP này không được chỉ định từ bất kỳ mạng con khu vực nào.

Tạo mạng

Tạo một mạng VPC toàn cầu.

# create vpc network
gcloud compute networks create vnet-${SLUG} --subnet-mode=custom

Tạo mạng con cho tệp đính kèm mạng PSC của Agent Gateway và lưu lượng truy cập trực tiếp ra khỏi VPC của Cloud Run.

# create subnet for agent gateway psc na
gcloud compute networks subnets create subnet-${REGION}-agw \
  --network=vnet-${SLUG} \
  --range=192.168.10.0/28 \
  --region=${REGION} \
  --enable-private-ip-google-access

# create subnet for cloud run dvpc egress
gcloud compute networks subnets create subnet-${REGION}-crun \
  --network=vnet-${SLUG} \
  --range=10.10.10.0/24 \
  --region=${REGION} \
  --enable-private-ip-google-access

Tạo quy tắc tường lửa

Tạo chính sách và quy tắc tường lửa để cho phép tất cả lưu lượng truy cập đi có nhật ký được bật. Điều này sẽ được dùng để theo dõi lưu lượng truy cập thoát ra từ Agent Gateway đến mạng VPC.

# create fw policy
gcloud compute network-firewall-policies create fw-policy-${SLUG} --global

# create fw policy rule
gcloud compute network-firewall-policies rules create 1001 \
  --description="allow all out and log" \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --action=allow \
  --direction=EGRESS \
  --layer4-configs=all \
  --dest-ip-ranges=0.0.0.0/0 \
  --enable-logging

# associate fw policy to vpc network
gcloud compute network-firewall-policies associations create \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --network=vnet-${SLUG} \
  --global-firewall-policy

Tạo tệp đính kèm mạng PSC

Tạo một tệp đính kèm mạng PSC được định cấu hình để tự động chấp nhận các kết nối mới của nhà sản xuất.

# create psc network attachment
gcloud compute network-attachments create psc-na-${REGION}-agw \
  --region=${REGION} \
  --subnets=subnet-${REGION}-agw \
  --connection-preference=ACCEPT_AUTOMATIC

Xác minh việc đính kèm mạng PSC

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

# fetch psc na uri
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Tạo điểm cuối PSC

Tạo một chế độ đặt trước địa chỉ IP cho điểm cuối PSC toàn cầu. Địa chỉ được sử dụng ở đây không được đến từ hoặc trùng lặp với một mạng con hiện có.

# set env var for psc ep ip address
export PSC_EP_IP="240.0.0.10"
echo ${PSC_EP_IP}

# reserve internal global ipv4 address
gcloud compute addresses create ip-psc2gapis \
  --global \
  --purpose=PRIVATE_SERVICE_CONNECT \
  --addresses=${PSC_EP_IP} \
  --network=vnet-${SLUG}

Tạo một điểm cuối PSC cho các API của Google bằng cách sử dụng gói all-apis, bao gồm Cloud Run (run.app).

# create psc endpoint for google apis
gcloud compute forwarding-rules create psc2gapis \
  --global \
  --network=vnet-${SLUG} \
  --address=ip-psc2gapis \
  --target-google-apis-bundle=all-apis

Xác minh điểm cuối PSC

# show psc endpoint details
gcloud compute forwarding-rules describe psc2gapis --global

Tạo vùng và bản ghi DNS

Tạo một vùng được quản lý Cloud DNS riêng tư cho miền run.app.

# create private dns zone
gcloud dns managed-zones create priv-zone-run \
  --description="private zone for cloud run" \
  --dns-name="run.app." \
  --visibility=private \
  --networks=vnet-${SLUG}

Tạo bản ghi DNS A có ký tự đại diện cho *.run.app. trỏ đến địa chỉ IP của điểm cuối PSC.

# create dns record
gcloud dns record-sets create *.run.app \
  --zone=priv-zone-run \
  --type=A \
  --ttl=300 \
  --rrdatas=${PSC_EP_IP}

Tạo một chính sách Cloud DNS để bật tính năng ghi nhật ký truy vấn DNS.

# create dns policy (logging)
gcloud dns policies create dns-policy-${SLUG} \
  --description="dns logging for vnet-${SLUG}" \
  --networks=vnet-${SLUG} \
  --enable-logging

Tạo Cloud NAT

Tạo một Cloud Router và Cloud NAT để hỗ trợ tính năng truyền dữ liệu trực tiếp ra khỏi VPC của Cloud Run để máy chủ MCP có thể truy cập vào dữ liệu thời tiết bên ngoài thông qua mạng VPC.

# create router for nat
gcloud compute routers create cr-nat-${SLUG}-${REGION} \
  --network=vnet-${SLUG} \
  --asn=16550 \
  --region=${REGION}

# create nat gateway
gcloud compute routers nats create nat-${SLUG}-${REGION} \
  --router=cr-nat-${SLUG}-${REGION} \
  --region=${REGION} \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges

Đến đây là kết thúc phần mạng... tiếp theo là phần Cổng.

5. Cổng

Trước khi thực thi các chế độ kiểm soát quyền truy cập, hãy triển khai Agent Gateway và định cấu hình tiện ích uỷ quyền ở chế độ DRY_RUN. Điều này cho phép các lệnh gọi công cụ gửi đi thành công trong khi ghi nhật ký kết quả đánh giá cho mục đích kiểm tra.

Ở đây, Agent Gateway sử dụng một sổ đăng ký theo khu vực để hỗ trợ các tài nguyên Agent Runtime theo khu vực và chỉ định các trường networkConfig cho tệp đính kèm mạng PSC của mạng VPC và cấu hình ngang hàng DNS.

Tạo cổng

# create new agent gateway config file (with network settings)
cat > cfg/${AGW_NAME}-networkConfig.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
networkConfig:
  egress:
    networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domains:
      - run.app.
    targetProject: ${PROJ_ID}
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
EOF

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

Xác minh cổng

# show agent gateway details
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw --region=${REGION}

Kiểm tra để đảm bảo có một điểm cuối kết nối được chấp nhận.

connectionEndpoints:
- ipAddress: 192.168.10.2
  projectIdOrNum: '[AGW_PROJECT_NO]'
  status: ACCEPTED
  subnetwork: https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/regions/${REGION}/subnetworks/subnet-${REGION}-agw

Đến đây là kết thúc phần cổng... tiếp theo là phần Uỷ quyền.

6. Ủy quyền

Tiện ích uỷ quyền Agent Gateway cho Identity-Aware Proxy (IAP) là một loại Tiện ích dịch vụ dùng để uỷ quyền quyết định uỷ quyền cho tất cả thông tin liên lạc của Nền tảng Agent.

Quy trình uỷ quyền: Khi một tác nhân cố gắng gọi một điểm cuối bên ngoài hoặc máy chủ MCP, tác nhân đó sẽ định tuyến yêu cầu đến Cổng tác nhân. Thay vì đánh giá quyền truy cập cục bộ, cổng sẽ sử dụng tiện ích uỷ quyền để gửi một lệnh gọi đến dịch vụ đánh giá IAP. IAP đánh giá danh tính của tác nhân (dựa trên SPIFFE) dựa trên chính sách IAM của tài nguyên đích trong Sổ đăng ký tác nhân. IAP trả về quyết định ALLOW hoặc DENY cho cổng, cổng này sẽ chuyển tiếp lưu lượng truy cập hoặc chặn lưu lượng truy cập bằng mã trạng thái HTTP 403 Forbidden.
Chế độ thực thi: Ở chế độ DRY_RUN, IAP đánh giá các yêu cầu và ghi lại quyết định trong Cloud Logging mà không chặn lưu lượng truy cập. Ở chế độ ENFORCE, mọi yêu cầu từ một tác nhân không được uỷ quyền hoặc đến một mục tiêu chưa đăng ký đều bị chặn ngay lập tức.
Lớp liên kết: Tiện ích dịch vụ được kết nối với Agent Gateway bằng một chính sách uỷ quyền được định cấu hình bằng hồ sơ REQUEST_AUTHZ.

Tiện ích uỷ quyền

Một tiện ích uỷ quyền chỉ định dịch vụ nhà cung cấp bảo mật bằng chế độ cài đặt kết nối và các tham số khác xác định cách dịch vụ sẽ hoạt động và tích hợp với Agent Gateway.

Tạo tiện ích uỷ quyền

# 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

Nhập tiện ích uỷ quyền

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

Xác minh tiện ích uỷ quyền

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

Chính sách ủy quyền

Chính sách uỷ quyền liên kết nhà cung cấp dịch vụ bảo mật (IAP) với tài nguyên đích của cổng và chỉ định hồ sơ chặn (REQUEST_AUTHZ).

Tạo chính sách uỷ quyền

# 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

Chính sách uỷ quyền liên kết

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

Xác minh chính sách uỷ quyền

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

Đến đây là kết thúc phần uỷ quyền... tiếp theo là phần Cơ sở mã.

7. Cơ sở mã

Tác nhân, máy chủ MCP và mã đăng ký điểm cuối được dùng cho Lớp học lập trình này được duy trì trong một kho lưu trữ Google Cloud GitHub từ xa. Các bước sau đây sẽ sao chép kho lưu trữ trên máy, sao chép các tệp cần thiết vào cấu trúc thư mục đang hoạt động hiện tại, sau đó dọn dẹp các tệp tạm thời.

Một vùng lưu trữ tạm thời sẽ được tạo cho Thời gian chạy của tác nhân để tải lên, tạo và triển khai mã ứng dụng tác nhân được đóng gói và các cấu phần phần mềm phụ thuộc của mã đó.

Tìm nạp cấu phần phần mềm từ xa

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

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/agent-weather ./agent-weather
cp -r temp_agw_cuj_arun_egress_vpc/codelabs/agw-cuj-arun-egress-vpc/mcp-weather ./mcp-weather

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_vpc

Tạo vùng lưu trữ tạm thời

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

Đến đây là kết thúc phần cơ sở mã... tiếp theo là phần Registry (Sổ đăng ký).

8. Đăng ký

Agent Registry là một kho lưu trữ tập trung của tất cả các tác nhân, máy chủ MCP và điểm cuối (API) trong hệ sinh thái AI. Đây cũng là một danh mục mà bạn có thể dùng để liệt kê, tìm kiếm và khám phá các công cụ và dịch vụ đã đăng ký khác để các ứng dụng AI sử dụng. Agent Gateway sử dụng mô hình dữ liệu của sổ đăng ký làm khung quản trị để thực thi quyền kiểm soát truy cập đầu ra. Các quyền cấp vai trò IAM cho các tác nhân gọi chính được kiểm tra dựa trên chính sách được liên kết với tài nguyên sổ đăng ký.

Để khởi động môi trường và hỗ trợ tác nhân bằng nhiều API và Dịch vụ của Google, hãy tạo một dịch vụ điểm cuối đăng ký duy nhất, kết hợp các giao diện API cốt lõi cần thiết cho phòng thí nghiệm này. Việc này sẽ giúp bạn dễ dàng quản lý các chính sách quản trị cho những bộ công cụ phổ biến mà hầu hết nhân viên sẽ sử dụng.

Đăng ký điểm cuối

# create endpoint service (with multiple entries)
gcloud agent-registry services create core-gapi-services \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="core apis and services" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com

Xác minh việc đăng ký điểm cuối

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

Đến đây là kết thúc phần đăng ký... tiếp theo là phần máy chủ MCP.

9. Máy chủ MCP

Cấp quyền IAM để triển khai

Cấp quyền cho tài khoản dịch vụ mặc định của Compute Engine để hỗ trợ triển khai các dịch vụ Cloud Run từ mã nguồn.

# grant cloud run builder role to default compute sa
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

Xác minh quyền IAM

# show iam policy on project for default compute sa
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members=serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Triển khai máy chủ MCP

# deploy cloud run service
gcloud -q run deploy ${MCP_NAME} \
  --source=mcp-weather/server \
  --region=${REGION} \
  --no-allow-unauthenticated \
  --min-instances=1 \
  --network=vnet-${SLUG} \
  --subnet=subnet-${REGION}-crun \
  --vpc-egress=all-traffic \
  --startup-probe=httpGet.path=/warmup

Cấp quyền IAM cho lưu lượng truy cập đến

Liên kết chính sách để cấp quyền truy cập cho người dùng

Cấp quyền cho tài khoản người dùng (chính bạn) để gọi máy chủ MCP được lưu trữ trên Cloud Run. Bạn cần có quyền này để chạy tập lệnh tạo toolspec.

# grant run invoker role to user account on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --region=${REGION} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

Xác minh quyền IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Tạo SA tuỳ chỉnh để gọi MCP

Tạo một tài khoản dịch vụ tuỳ chỉnh để gọi máy chủ MCP được lưu trữ trên Cloud Run. Tác nhân sẽ sử dụng tài khoản dịch vụ này để tìm nạp mã thông báo nhận dạng OIDC hợp lệ do Google ký để truy cập vào Cloud Run.

# create custom sa for mcp server invocation
gcloud iam service-accounts create sa-${MCP_NAME}-invoker \
  --display-name="custom sa to invoke ${MCP_NAME}"

# set env var for service account identity
export MCP_INVOKER_SA="sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com"
echo ${MCP_INVOKER_SA}

Chính sách liên kết cho tài khoản dịch vụ

# grant run invoker role to custom sa on cloud run service level
gcloud run services add-iam-policy-binding ${MCP_NAME} \
  --role="roles/run.invoker" \
  --member="serviceAccount:${MCP_INVOKER_SA}" \
  --region=${REGION}

Xác minh quyền IAM

# show iam policy on cloud run service for invoker role
gcloud run services get-iam-policy ${MCP_NAME} \
  --region=${REGION} \
  --flatten="bindings[].members" \
  --filter="bindings.role=roles/run.invoker" \
  --format="table(bindings.members:label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Cấp quyền IAM để xác thực

Cấp vai trò mạo danh tài khoản dịch vụ cho Tài khoản dịch vụ Compute mặc định. Thao tác này sẽ cho phép tác nhân (chạy trong Application Default Credentials (ADC)) tạo mã thông báo OIDC do Google ký thay mặt cho tài khoản dịch vụ trình gọi tuỳ chỉnh để xác thực các lệnh gọi đến Cloud Run.

Chính sách liên kết để xác thực

# grant oidc token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

# grant service account token creator role to default compute service account
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com"

Xác minh quyền IAM

# show iam policy for the custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Tạo MCP `toolspec`

Khi đăng ký máy chủ MCP theo cách thủ công, bạn phải thêm một tệp chỉ định công cụ. Tệp toolspec.json liệt kê tất cả các công cụ do máy chủ MCP cung cấp và cho phép người dùng khác khám phá các công cụ đó sau khi đăng ký.

Tập lệnh test_mcp.py (có trong cơ sở mã mcp-weather/) sẽ tạo tệp toolspec.json bằng cách kết nối với máy chủ MCP mục tiêu (qua SSE hoặc HTTP) và gọi list_tools() để truy xuất tất cả các công cụ có sẵn do máy chủ cung cấp.

# fetch oidc token for cloud run authentication
export OIDC_TOKEN=$(gcloud auth print-identity-token)

# generate toolspec for registry ingestion
uv --directory mcp-weather run test_mcp.py --toolspec=include --token="${OIDC_TOKEN}"

Khi xem xét đầu ra toolspec đã tạo, bạn sẽ thấy các thuộc tính MCP mà Agent Gateway có thể dùng để đánh giá và thực thi chính sách xuất cảnh.

Xác minh MCP `toolspec`

# show toolspec mcp attributes
jq '.tools[] | {name, isReadOnly, isDestructive, isIdempotent, isOpenWorld}' mcp-weather/toolspec.json

Cập nhật cổng vào Cloud Run

Thay đổi chế độ cài đặt lưu lượng truy cập vào cho dịch vụ Cloud Run để dịch vụ này chỉ chấp nhận các yêu cầu đến từ mạng VPC. Điều này ngăn chặn quyền truy cập công khai trực tiếp vào điểm cuối MCP và chỉ cho phép các tài nguyên nội bộ truy cập vào điểm cuối này. Lưu lượng truy cập đến điểm cuối PSC cho các API của Google trong mạng VPC sẽ được coi là lưu lượng truy cập nội bộ và được phép.

# update cloud run service config
gcloud run services update ${MCP_NAME} \
  --region=${REGION} \
  --ingress=internal

Xác minh lưu lượng truy cập vào Cloud Run

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION} | grep -iE 'ingress|egress'

Đăng ký máy chủ MCP

Giờ đây, khi đã có toolspec, hãy đăng ký máy chủ MCP với Agent Registry theo khu vực.

# register mcp server
gcloud agent-registry services create ${MCP_NAME} \
  --location=${REGION} \
  --display-name="${MCP_DISPLAY_NAME}" \
  --description="mcp server for weather info" \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=mcp-weather/toolspec.json \
  --interfaces=url=${MCP_URL},protocolBinding=JSONRPC

Xác minh việc đăng ký MCP

# list registry regional mcp servers
gcloud agent-registry mcp-servers list --location=${REGION} --format="table(displayName, interfaces.url)"

# show mcp server registry details
gcloud agent-registry services describe ${MCP_NAME} --location=${REGION}

# fetch mcp server registry id
export MCP_REGISTRY_ID=$(gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --format="value(registryResource.basename())")
echo ${MCP_REGISTRY_ID}

Đến đây là kết thúc phần máy chủ MCP... tiếp theo là phần tác nhân ADK.

10. Tác nhân ADK

Tác nhân ADK agent-weather được triển khai cho Thời gian chạy tác nhân được định cấu hình bằng các chế độ cài đặt sau trong tập lệnh triển khai để tích hợp với Nền tảng tác nhân:

"identity_type": types.IdentityType.AGENT_IDENTITY để cung cấp một danh tính chính dựa trên SPIFFE riêng biệt cho tác nhân
"agent_gateway_config": { "agent_to_anywhere_config": {"agent_gateway": } } để chuyển hướng tất cả lưu lượng truy cập đi do nhân viên hỗ trợ bắt đầu đến Cổng nhân viên hỗ trợ để đánh giá và thực thi chính sách

Tác nhân này cũng được định cấu hình để sử dụng máy chủ MCP bằng cách truyền URL và tài khoản dịch vụ để tìm nạp mã thông báo nhận dạng OIDC.

Triển khai tác nhân

# deploy agent runtime workload
uv --directory agent-weather 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 weather info" \
  --mcp-server-url="${MCP_URL}" \
  --mcp-invoker-sa="${MCP_INVOKER_SA}" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

Xác minh quá trình triển khai

Tìm nạp chỉ số quan trọng về việc triển khai

# 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 RE_AGENT_REGISTRY_ID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${RE_AGENT_REGISTRY_ID}

Xác minh mục đăng ký

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

Xác minh cấu hình cổng

# show agent config details (gateway config)
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}'

Cấp quyền IAM để xác thực

Khi được định cấu hình để sử dụng Danh tính của tác nhân, tác nhân sẽ nhận được một mã thông báo (định dạng JWT-SVID) từ Dịch vụ mã thông báo bảo mật (STS) liên kết do sts.googleapis.com (nhà cung cấp danh tính SPIFFE) ký.

Tuy nhiên, chế độ kiểm tra trình gọi IAM Cloud Run tích hợp chỉ tin tưởng và có thể xác minh mã thông báo nhận dạng OIDC tiêu chuẩn do trình phát hành OIDC chính của Google (accounts.google.com) ký.

Vì vậy, một tài khoản dịch vụ tuỳ chỉnh được dùng để trao đổi mã thông báo STS liên kết (JWT-SVID) do danh tính tác nhân thu được để lấy mã thông báo Google (OIDC) tiêu chuẩn thu được bằng cách sử dụng tính năng mạo danh tài khoản dịch vụ trong thời gian chạy.

Tạo các liên kết vai trò cần thiết cho tài khoản dịch vụ tuỳ chỉnh.

Liên kết chính sách để xác thực (mạo danh)

# grant service account token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

# grant service account openid token creator role to agent principal identity
gcloud iam service-accounts add-iam-policy-binding ${MCP_INVOKER_SA} \
  --role="roles/iam.serviceAccountOpenIdTokenCreator" \
  --member="${RE_AGENT_IDENTITY}"

Xác minh quyền IAM

# show iam policy for custom service account
gcloud iam service-accounts get-iam-policy ${MCP_INVOKER_SA} \
  --flatten="bindings[].members" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Cấp quyền IAM cho thời gian chạy

Cấp quyền IAM cho thời gian chạy cho phép tác nhân truy cập vào các dịch vụ của nền tảng AI và các API cũng như dịch vụ cốt lõi khác của Google bằng cách sử dụng danh tính tác nhân chính dựa trên SPIFFE. Các chính sách này được thực thi bằng IAM ở cấp tài nguyên.

Tạo các liên kết vai trò cần thiết cho danh tính của tác nhân.

Liên kết các chính sách về quyền truy cập của tác nhân

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

Xác minh quyền IAM

# show iam policy on project for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="table(bindings.members.sub('^.*locations/', '.../locations/'):label=PRINCIPAL_IDENTITY, bindings.role:label=ROLE)"

Đến đây là kết thúc phần về tác nhân ADK... tiếp theo là phần Chính sách.

11. Chính sách

Các chính sách uỷ quyền quản trị tác nhân cho phép lưu lượng truy cập được định tuyến từ một tác nhân AI thông qua Agent Gateway và đến đích đến cuối cùng của tài nguyên (ví dụ: điểm cuối máy chủ MCP riêng để truy xuất dữ liệu). Sau khi lưu lượng truy cập đến đích đến, các quyền thông thường ở cấp dịch vụ hoặc cấp ứng dụng sẽ cho phép truy cập vào dữ liệu.

Cấp vai trò IAM cho lưu lượng truy cập đi của Agent Gateway cho phép các chính sách truy cập cho phép quyền truy cập danh tính của đối tượng chính của tác nhân vào các tài nguyên đích đã đăng ký thông qua Agent Gateway. Các chính sách được thực thi ở cấp Cổng đại lý và được xác thực bằng các chính sách IAM của Identity-Aware Proxy (IAP).

Cấp vai trò IAM cho lưu lượng truy cập đi của Agent Gateway

Agent Gateway kiểm tra các yêu cầu đến để xác thực danh tính của tác nhân gọi có quyền iap.webServiceVersions.egressViaIAP (do vai trò roles/iap.egressor cấp) đối với tài nguyên đích.

Việc cấp roles/iap.egressor cho danh tính tác nhân hoặc nhóm thực thể Agent Runtime trên tài nguyên đích đến đã chọn sẽ cho phép lưu lượng truy cập đi ra này. Trong lớp học lập trình này, vai trò được áp dụng cho tác nhân chính, cấp quyền cho danh tính tác nhân cụ thể của Agent Runtime.

Các chính sách IAM được liên kết với các tài nguyên đích như được xác định trong mô hình dữ liệu của Sổ đăng ký tác nhân. Tài nguyên iap_web/agentRegistry đại diện cho cấp "trên toàn bộ sổ đăng ký" trong hệ thống phân cấp IAM. Trong đó agentRegistry đóng vai trò là phần tử mẹ của từng tài nguyên con cho agents, mcpServers và endpoints. Trong lớp học lập trình này, chính sách IAM được liên kết với các cấp mcpServer và endpoint. Chính sách này áp dụng quyền cho các tài nguyên con cụ thể.

Định cấu hình chính sách tác nhân cho máy chủ MCP

Tạo chính sách cho tác nhân đối với máy chủ mcp

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

LƯU Ý: etag: sẽ trả về ACAB mặc định vì chưa có chính sách nào được xác định.

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

Chính sách liên kết cho tác nhân với máy chủ mcp

# import policy file
gcloud beta iap web set-iam-policy cfg/iap-policy-agent-to-mcp.json \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID} \
  --region=${REGION}

Xác minh quyền IAM

# show iap iam policy on mcp server for agent
gcloud beta iap web get-iam-policy \
  --region=${REGION} \
  --resource-type=agent-registry \
  --mcp-server=${MCP_REGISTRY_ID}

Đến đây là kết thúc phần chính sách... tiếp theo là phần Kiểm tra.

12. Kiểm tra

Tiện ích uỷ quyền Agent Gateway đang hoạt động ở chế độ DRY_RUN. Các yêu cầu gửi đi sẽ được theo dõi và ghi nhật ký nhưng không bị chặn. Việc phân tích nhật ký trước khi chuyển sang chế độ ENFORCED sẽ xác nhận những chính sách cần được định cấu hình để cho phép lưu lượng truy cập dự kiến.

Kiểm thử các truy vấn của nhân viên hỗ trợ

Mở cửa sổ trình duyệt đến giao diện người dùng Google Cloud Console rồi chuyển đến:

Agent Platform → Agents → Deployments → agent-weather
Chọn thẻ Sân chơi

Hoặc lặp lại lệnh này trên thiết bị đầu cuối rồi nhấp vào đường liên kết để chuyển đến sân chơi của tác nhân:

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

Gửi một số truy vấn thử nghiệm...

What is the weather like in London?
How warm is it in New York?

Xác minh rằng các truy vấn trả về phản hồi hợp lệ.

Phân tích nhật ký kiểm tra

Xem nhật ký và kiểm tra các hoạt động đánh giá chính sách chạy thử.

# show gateway logs for endpoints and authz status (duplicates removed)
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=50 \
  --freshness=24h \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    httpRequest.requestUrl.sub('(https?://[^/:]+).*', '\1'):label=ENDPOINT \
  )" | awk 'NR==1 {print; next} ! seen[$2,$3,$4]++'

TIMESTAMP            STATUS  AUTHZ    ENDPOINT
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://cloudresourcemanager.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://${REGION}-aiplatform.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://iamcredentials.googleapis.com
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app
YYYY-MM-DDTHH:MM:SS  200     ALLOWED  https://telemetry.googleapis.com
YYYY-MM-DDTHH:MM:SS  202     ALLOWED  https://mcp-weather-${PROJ_NO}.${REGION}.run.app

Định cấu hình chính sách tác nhân đối với điểm cuối

Vì các API cốt lõi của Google cho agent-weather được đăng ký trong một dịch vụ điểm cuối tập thể trong sổ đăng ký (gapi.core.services), nên chỉ cần một chính sách duy nhất để cấp quyền truy cập ra ngoài cho tác nhân để truy cập vào điểm cuối.

Tạo chính sách cho tác nhân đến điểm cuối

# set var for endpoint display name
export ENDPOINT_DISPLAY_NAME="gapi.core.services"
echo ${ENDPOINT_DISPLAY_NAME}

# fetch endpoint registry id
export ENDPOINT_REGISTRY_ID=$(gcloud agent-registry services list \
  --location=${REGION} \
  --filter="displayName=${ENDPOINT_DISPLAY_NAME}" \
  --format="value(registryResource.basename())")
echo ${ENDPOINT_REGISTRY_ID}

# create policy config file
cat > cfg/iap-policy-agent-to-ep.json << EOF
{
  "bindings": [
    {
      "role": "roles/iap.egressor",
      "members": [
        "${RE_AGENT_IDENTITY}"
      ]
    }
  ]
}
EOF

Liên kết chính sách cho tác nhân với điểm cuối

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

Xác minh quyền IAM

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

Đến đây là kết thúc phần kiểm tra... tiếp theo là phần Thực thi.

13. Thi hành

Tác nhân đã có thể thực hiện các yêu cầu thành công thông qua cổng ở chế độ DRY_RUN. Nhật ký truy cập và điểm cuối đã được phân tích để tạo một bộ chính sách quản trị cho phép lưu lượng truy cập truyền dữ liệu cần thiết từ tác nhân. Giờ đây, hãy chuyển tiện ích uỷ quyền IAP của Agent Gateway sang chế độ ENFORCE bằng cách cập nhật chính sách uỷ quyền.

Cập nhật tiện ích uỷ quyền

Tạo tiện ích uỷ quyền

# 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

Nhập tiện ích uỷ quyền

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

Xác minh tiện ích uỷ quyền

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

Cập nhật chính sách uỷ quyền

Tạo chính sách uỷ quyền

# 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

Chính sách uỷ quyền liên kết

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

Xác minh chính sách uỷ quyền

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

Xác minh biện pháp thực thi

Quay lại Playground của tác nhân trong giao diện người dùng bảng điều khiển.

Nhấp vào nút "+ Phiên mới" để tạo một phiên trò chuyện mới

Gửi một truy vấn kiểm thử bổ sung...

What is the current temperature in Los Angeles?

Quan sát các yêu cầu của tác nhân đối với mô hình cơ sở Gemini (${REGION}-aiplatform.googleapis.com/...) và điểm cuối của máy chủ MCP (mcp-weather-${PROJ_NO}.${REGION}.run.app/mcp) được truyền bằng mã trạng thái HTTP 200 OK.

Phân tích nhật ký cổng

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

Kiểm tra để đảm bảo không có yêu cầu nào bị chặn. Tìm mọi nỗ lực truy cập bị từ chối có mã trạng thái HTTP 403 Forbidden trong nhật ký kiểm tra cổng.

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

Xem nhật ký MCP của Agent Gateway và lưu ý cách tải trọng ứng dụng MCP (JSON-RPC) được kiểm tra để hiển thị siêu dữ liệu giao thức, bao gồm cả những công cụ đang được thực thi.

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

Phân tích nhật ký tường lửa

Xem nhật ký về mức độ ưu tiên của quy tắc chính sách tường lửa mạng 1001.

# show firewall logs for rule 1001
gcloud logging read \
  "jsonPayload.rule_details.priority=1001" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.disposition:label=ACTION,
    jsonPayload.connection.src_ip:label=SRC_IP,
    jsonPayload.connection.dest_ip:label=DEST_IP,
    jsonPayload.connection.dest_port:label=DEST_PORT,
    jsonPayload.vpc.subnetwork_name:label=SUBNET
  )"

Lưu ý chế độ xem ở cấp mạng của các đường dẫn lưu lượng truy cập khác nhau:

Agent Gateway giao tiếp với các tài nguyên mạng VPC nội bộ bằng subnet-${REGION}-agw
Máy chủ MCP được lưu trữ trên Cloud Run gọi các API thời tiết bên ngoài bằng subnet-${REGION}-crun

TIMESTAMP            ACTION   SRC_IP        DEST_IP        DEST_PORT  SUBNET
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   188.40.99.226  443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  10.10.10.16   202.61.206.6   443        subnet-${REGION}-crun
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw
YYYY-MM-DDTHH:MM:SS  ALLOWED  192.168.10.2  240.0.0.10     443        subnet-${REGION}-agw

Phân tích nhật ký DNS

Xem nhật ký truy vấn DNS cho các yêu cầu được phân giải bằng vùng DNS riêng (priv-zone-run).

gcloud logging read \
  "resource.type=\"dns_query\" AND resource.labels.target_name=\"priv-zone-run\"" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    jsonPayload.queryName:label=QUERY_NAME,
    jsonPayload.queryType:label=TYPE,
    jsonPayload.rdata:label=RESPONSE_RDATA,
    jsonPayload.sourceNetwork:label=NETWORK,
    resource.labels.source_type:label=SRC_TYPE
  )"

Xin lưu ý rằng các hoạt động tra cứu DNS cho dịch vụ Cloud Run (mcp-weather...run.app) bắt nguồn từ mạng VPC bằng cách sử dụng tính năng kết nối ngang hàng DNS và được phân giải thành công thành điểm cuối PSC nội bộ cho các API của Google (240.0.0.10).

TIMESTAMP            QUERY_NAME                                     TYPE  RESPONSE_RDATA                                                     NETWORK   SRC_TYPE
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone
YYYY-MM-DDTHH:MM:SS  mcp-weather-${PROJ_NO}.${REGION}.run.app.  A     mcp-weather-${PROJ_NO}.${REGION}.run.app. 300     IN      a       240.0.0.10  vnet-${SLUG}  peering-zone

Đến đây là kết thúc phần thực thi... tiếp theo là phần Dọn dẹp.

14. Dọn dẹp

# delete agent runtime
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

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

for ROLE in \
  "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 mcp (cloud run) resources
gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/run.builder"

gcloud -q run services delete ${MCP_NAME} --region=${REGION}

gcloud -q artifacts repositories delete cloud-run-source-deploy --location=${REGION}

gcloud -q iam service-accounts delete sa-${MCP_NAME}-invoker@${PROJ_ID}.iam.gserviceaccount.com

gcloud -q agent-registry services delete ${MCP_NAME} --location=${REGION}

# next

# delete gateway resources (policy binding must be deleted synchronously first)
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} --async

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

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

# next

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

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

# next

# delete dns resources
gcloud -q dns record-sets delete *.run.app --type=A --zone=priv-zone-run

gcloud -q dns managed-zones delete priv-zone-run

gcloud -q dns policies update dns-policy-${SLUG} --networks=""

gcloud -q dns policies delete dns-policy-${SLUG}

# next

# delete router (includes nat) and psc resources
gcloud -q compute routers delete cr-nat-${SLUG}-${REGION} --region=${REGION}

gcloud -q compute forwarding-rules delete psc2gapis --global

gcloud -q compute addresses delete ip-psc2gapis --global

# next

# delete firewall resources
gcloud -q compute network-firewall-policies associations delete --name=fw-policy-bind-${SLUG} --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies rules delete 1001 --firewall-policy=fw-policy-${SLUG} --global-firewall-policy

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} --global

# next

# delete network resources
gcloud -q compute networks subnets delete subnet-${REGION}-agw --region=${REGION}

gcloud -q compute networks subnets delete subnet-${REGION}-crun --region=${REGION}

gcloud -q compute network-attachments delete psc-na-${REGION}-agw --region=${REGION}

gcloud -q compute networks delete vnet-${SLUG}

# next

# clean up local working directories and generated configs
rm -rf cfg agent-weather mcp-weather

# end

Đến đây là kết thúc phần dọn dẹp... tiếp theo là phần Kết luận!

15. Kết luận

Xin chúc mừng! Bạn đã triển khai thành công Agent Gateway và kiểm soát lưu lượng truy cập của tác nhân AI gửi đi!

cosmopup

Cosmopup cho rằng Codelabs là một ý tưởng tuyệt vời!

Bước tiếp theo là gì?

Hãy xem tài liệu về Nền tảng tác nhân Gemini Enterprise để biết các tính năng nâng cao và hướng dẫn
Định cấu hình các biện pháp bảo vệ Model Armor trên Agent Gateway để tăng cường độ an toàn và bảo mật cho AI
Khám phá Chính sách quản trị ngữ nghĩa để thực thi các quy tắc kinh doanh và việc tuân thủ đối với các cụm từ tìm kiếm bằng ngôn ngữ tự nhiên

Bạn có thể thoải mái đưa ra ý kiến nhận xét, câu hỏi hoặc nội dung chỉnh sửa bằng cách sử dụng biểu mẫu phản hồi này.

Cảm ơn bạn!

Agent Gateway thoát khỏi Agent Runtime sang mạng VPC

1. Giới thiệu

Sản phẩm bạn sẽ tạo ra

Kiến thức bạn sẽ học được

Bạn cần có

2. Khái niệm

Trình tự triển khai

Cấu trúc liên kết định tuyến xuất dữ liệu

Khả năng kết nối VPC

3. Thiết lập

Các vai trò IAM bắt buộc

Truy cập vào dự án của bạn

Đặt mã dự án

Xác thực phiên

Đặt các biến môi trường của trình bao

Cập nhật vào gcloud cli (nên làm)

Bật dịch vụ API

4. Mạng

Tạo mạng

Tạo quy tắc tường lửa

Tạo tệp đính kèm mạng PSC

Xác minh việc đính kèm mạng PSC

Tạo điểm cuối PSC

Xác minh điểm cuối PSC

Tạo vùng và bản ghi DNS

Tạo Cloud NAT

5. Cổng

Tạo cổng

Xác minh cổng

6. Ủy quyền

Tiện ích uỷ quyền

Tạo tiện ích uỷ quyền

Nhập tiện ích uỷ quyền

Xác minh tiện ích uỷ quyền

Chính sách ủy quyền

Tạo chính sách uỷ quyền

Chính sách uỷ quyền liên kết

Xác minh chính sách uỷ quyền

7. Cơ sở mã

Tìm nạp cấu phần phần mềm từ xa

Tạo vùng lưu trữ tạm thời

8. Đăng ký

Đăng ký điểm cuối

Xác minh việc đăng ký điểm cuối

9. Máy chủ MCP

Cấp quyền IAM để triển khai

Xác minh quyền IAM

Triển khai máy chủ MCP

Cấp quyền IAM cho lưu lượng truy cập đến

Liên kết chính sách để cấp quyền truy cập cho người dùng

Xác minh quyền IAM

Tạo SA tuỳ chỉnh để gọi MCP

Chính sách liên kết cho tài khoản dịch vụ

Xác minh quyền IAM

Cấp quyền IAM để xác thực

Chính sách liên kết để xác thực

Xác minh quyền IAM

Tạo MCP toolspec

Xác minh MCP toolspec

Cập nhật cổng vào Cloud Run

Xác minh lưu lượng truy cập vào Cloud Run

Đăng ký máy chủ MCP

Xác minh việc đăng ký MCP

10. Tác nhân ADK

Triển khai tác nhân

Xác minh quá trình triển khai

Tìm nạp chỉ số quan trọng về việc triển khai

Xác minh mục đăng ký

Xác minh cấu hình cổng

Cấp quyền IAM để xác thực

Liên kết chính sách để xác thực (mạo danh)

Xác minh quyền IAM

Cấp quyền IAM cho thời gian chạy

Liên kết các chính sách về quyền truy cập của tác nhân

Xác minh quyền IAM

11. Chính sách

Cấp vai trò IAM cho lưu lượng truy cập đi của Agent Gateway

Định cấu hình chính sách tác nhân cho máy chủ MCP

Tạo chính sách cho tác nhân đối với máy chủ mcp

Chính sách liên kết cho tác nhân với máy chủ mcp

Cập nhật vào `gcloud cli` (nên làm)

Tạo MCP `toolspec`

Xác minh MCP `toolspec`