Quản lý các khối lượng công việc tác nhân bằng Cổng tác nhân trên Nền tảng tác nhân Gemini Enterprise

1. Giới thiệu

Nền tảng tác nhân Gemini Enterprise là một nền tảng mở để xây dựng, mở rộng quy mô, quản lý và tối ưu hoá các tác nhân AI cấp doanh nghiệp dựa trên dữ liệu của bạn.

Thời gian chạy tác nhân cung cấp môi trường thực thi được quản lý để chạy các tác nhân, chẳng hạn như những tác nhân được xây dựng bằng Bộ công cụ phát triển tác nhân (ADK) nguồn mở, một cách an toàn trong Google Cloud.

Lớp học lập trình này khám phá cách sử dụng các thành phần cốt lõi này để điều chỉnh một tác nhân do người dùng khởi tạo trong Gemini Enterprise khi tác nhân đó tiếp cận các công cụ nội bộ một cách an toàn.

Giới thiệu về Agent Gateway

Cổng đại lý là thành phần mạng của bộ công cụ Quản trị đại lý của nền tảng. Nó đóng vai trò là điểm truy cập và thoát mạng cho tất cả các hoạt động tương tác của tác nhân, cho phép quản trị viên bảo mật thực thi hoạt động quản trị tập trung mà không yêu cầu nhà phát triển quản lý các nguyên tắc mạng phức tạp.

Thư mục này hỗ trợ 2 đường dẫn truy cập được quản lý chính:

• Client-to-Agent (ingress): Bảo mật thông tin liên lạc giữa các ứng dụng bên ngoài (chẳng hạn như Cursor hoặc Gemini CLI) và các tác nhân của bạn.
• Agent-to-Anywhere (truy cập): Bảo mật thông tin liên lạc giữa các tác nhân chạy trên Google Cloud và các máy chủ, công cụ hoặc API chạy ở bất kỳ đâu.

Trong lớp học lập trình này, bạn sẽ tập trung vào chế độ Agent-to-Anywhere (thoát).

Để thực thi chính sách bảo mật, Agent Gateway tích hợp chặt chẽ với phần còn lại của hệ sinh thái:

• Sổ đăng ký tác nhân: Một thư viện trung tâm gồm các tác nhân và công cụ được phê duyệt (bao gồm cả máy chủ MCP của bên thứ ba).
• Danh tính của tác nhân: Một nhân dạng duy nhất, có thể theo dõi cho mọi tác nhân, được bảo mật tự động bằng mTLS từ đầu đến cuối.
• Identity-Aware Proxy (IAP) và IAM: Lớp thực thi mặc định xác thực danh tính của tác nhân dựa trên các quyền IAM chi tiết trước khi cho phép các lệnh gọi đến những công cụ cụ thể.
• Model Armor: Một hàng rào bảo vệ AI được tích hợp thông qua Tiện ích dịch vụ để dọn dẹp nội dung và chống lại các cuộc tấn công tiêm câu lệnh (prompt injection) hoặc rò rỉ dữ liệu.

Chế độ triển khai (Mạng công cộng so với mạng riêng tư cho Cloud Run)

Để có thể truy cập vào lớp học lập trình này, bạn có thể chọn một trong hai đường dẫn kết nối mạng cho các công cụ nội bộ (máy chủ MCP) được triển khai trên Cloud Run:

1. Mặc định (Đầu vào công khai): Các máy chủ MCP được triển khai đến Cloud Run bằng tên máy chủ công khai (ingress=all). Lưu lượng truy cập được định tuyến từ tác nhân đến các công cụ thông qua URL *.run.app tiêu chuẩn. Cách này không yêu cầu miền DNS tuỳ chỉnh và là cách nhanh nhất để tìm hiểu các khái niệm về hoạt động quản trị.
2. Bảo mật (Mạng riêng): Một cấu trúc hoàn toàn riêng tư (không bắt buộc). Các máy chủ MCP bị hạn chế (ingress=internal-and-cloud-load-balancing) và được hiển thị thông qua một Bộ cân bằng tải ứng dụng nội bộ bằng một NEG không máy chủ. Bạn cần sở hữu một miền DNS công khai để cấp phép chứng chỉ do Google quản lý.

Bạn sẽ chọn đường dẫn ưu tiên khi định cấu hình Terraform.

Để tìm hiểu thêm về cổng vào điểm cuối mạng cho Cloud Run, vui lòng đọc tài liệu của chúng tôi.

Bạn sẽ thực hiện

• Cung cấp ngăn xếp cơ sở hạ tầng cốt lõi bằng Terraform
• Tạo và triển khai các công cụ nội bộ dưới dạng máy chủ MCP trên Cloud Run
• Triển khai một tác nhân ADK vào Thời gian chạy tác nhân bằng cách sử dụng lưu lượng truy cập ra qua Giao diện PSC
• Định cấu hình các tiện ích dịch vụ Cổng tác nhân để truy cập dựa trên danh tính (IAM) và sàng lọc nội dung (Model Armor)
• Theo dõi và xác thực quá trình thực thi an toàn hai đầu của tác nhân

Bạn cần có

• Một trình duyệt web như Chrome
• Một dự án trên Google Cloud đã bật tính năng thanh toán và có quyền truy cập của Chủ sở hữu
• Quyền IAM ở cấp tổ chức (lớp học lập trình cấp các vai trò theo phạm vi tổ chức)
• Một miền mà bạn kiểm soát được uỷ quyền cho Cloud DNS (đối với chứng chỉ được quản lý công khai)
• Có kiến thức về Terraform, gcloud và mạng cơ bản của Google Cloud

Cấu trúc liên kết lớp học lập trình

Trong lớp học lập trình này, bạn sẽ triển khai một tác nhân bảo lãnh thế chấp toàn diện, giao tiếp an toàn với 3 công cụ nội bộ.

Bạn sẽ bắt đầu bằng cách cung cấp mạng cơ bản, bao gồm một VPC và một Trình cân bằng tải ứng dụng nội bộ được định cấu hình làm Cổng tác nhân. Tiếp theo, bạn sẽ triển khai 3 máy chủ Giao thức ngữ cảnh mô hình (MCP) lên Cloud Run. Đây là những công cụ độc quyền nội bộ của bạn:

• Quản lý tài liệu (legacy-dms)
• Email công ty (corporate-email)
• Xác minh thu nhập (income-verification)

Sau khi có các công cụ, bạn sẽ triển khai Trợ lý thế chấp (mortgage-agent) được tạo bằng ADK cho Thời gian chạy tác nhân. Bạn sẽ định cấu hình tác nhân này để sử dụng Giao diện PSC cho lưu lượng truy cập đi ra riêng tư và cho phép phát hiện công cụ trong thời gian chạy thông qua Agent Registry.

Để bảo mật quy trình, bạn sẽ định cấu hình Agent Gateway bằng 2 tiện ích dịch vụ. Trước tiên, tiện ích REQUEST_AUTHZ sẽ xác minh Danh tính của tác nhân dựa trên các chính sách IAM cho từng công cụ, đảm bảo rằng tác nhân chỉ truy cập vào các công cụ được uỷ quyền. Thứ hai, một tiện ích CONTENT_AUTHZ sử dụng Model Armor sẽ sàng lọc các câu lệnh và câu trả lời của tác nhân.

Cuối cùng, bạn sẽ đăng ký tác nhân trong Gemini Enterprise, kích hoạt một tác vụ bảo lãnh thế chấp với tư cách là người dùng cuối và xác minh quá trình thực thi an toàn, có kiểm soát bằng Cloud Trace.

Lớp học lập trình này dành cho các kỹ sư nền tảng và bảo mật ở mọi cấp độ. Bạn dự kiến sẽ mất khoảng 100 phút để hoàn thành biểu mẫu này.

2. Trước khi bắt đầu

Tạo dự án và xác thực

Tạo một dự án GCP mới (hoặc sử dụng lại một dự án) đã bật tính năng thanh toán, sau đó xác thực Cloud Shell hoặc máy cục bộ của bạn:

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

Bật các API khởi động

Mô-đun nền tảng của Terraform cho phép khoảng 30 API trong lần áp dụng đầu tiên, nhưng bạn cần có một nhóm khởi động nhỏ cho terraform init và vùng chứa trạng thái GCS:

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

Cài đặt các công cụ bắt buộc

Cài đặt chuỗi công cụ. Trên Cloud Shell, hầu hết các công cụ này đã có sẵn; trên một máy trạm:

# 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

Bạn cũng cần có Terraform >= 1.12.2, Python 3.12 trở lên và Google Cloud SDK (gcloud).

Đặt các biến môi trường

Phần còn lại của lớp học lập trình giả định rằng các biến này được xuất trong shell của bạn.

Nếu đang thực hiện đường dẫn mạng bảo mật không bắt buộc, hãy xác định DOMAIN_NAME (ví dụ: agw.example.com); nếu không, bạn có thể bỏ qua đường dẫn này.

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" 

Xác thực rằng tất cả các biến của bạn đều được điền chính xác, bạn sẽ nhận được 3 giá trị.

echo $PROJECT_ID  
echo $PROJECT_NUMBER
echo $ORG_ID

Nếu Mã tổ chức của bạn không xuất hiện, bạn có thể tìm và đặt mã này theo cách thủ công.

gcloud organizations list
export ORG_ID=ID_FROM_OUTPUT

3. Sao chép kho lưu trữ

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

Khám phá nhanh nội dung trong thư mục bản minh hoạ:

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. Tạo vùng chứa trạng thái Terraform và cấu hình phụ trợ

Tạo một bộ chứa GCS để lưu trữ trạng thái từ xa, sau đó sao chép mẫu phụ trợ:

gcloud storage buckets create gs://${PROJECT_ID}-tfstate \
  --location=${REGION} \
  --uniform-bucket-level-access

cp terraform/example.backend.conf terraform/backend.conf

Chỉnh sửa terraform/backend.conf bằng các giá trị của bạn:

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

terraform/backend.conf bị git-ignored. Mỗi người dùng duy trì bản sao của riêng mình.

5. (Không bắt buộc) Tạo một vùng DNS công khai

Bỏ qua bước này nếu bạn đang sử dụng Đường dẫn mặc định. Nếu bạn muốn sử dụng chế độ thiết lập đơn giản nhất với các URL Cloud Run công khai, hãy chuyển thẳng đến bước tiếp theo.

Theo mặc định, đối với phòng thí nghiệm này, Cloud Run có cấu hình chuyển tiếp được đặt thành all và Agent Registry đăng ký từng máy chủ MCP tại URL *.run.app công khai của máy chủ đó – không cần thêm DNS, chứng chỉ hoặc bộ cân bằng tải. Nếu muốn chuyển sang mạng riêng tư (Cloud Run có ingress = internal-and-cloud-load-balancing đằng sau một Application LB nội bộ), bạn cũng cần có một vùng DNS công khai trên Cloud DNS để Certificate Manager có thể xác thực chứng chỉ LB.

Luồng cấp cao của mạng riêng tư

Cách sử dụng phương pháp nối mạng riêng tư:

1. Tạo vùng DNS Cloud DNS công khai – Certificate Manager xác thực chứng chỉ được quản lý theo khu vực bằng cách ghi CNAME vào đó:

gcloud dns managed-zones create agw-example-com \
  --dns-name="${DOMAIN_NAME}." \
  --description="Public zone for ${DOMAIN_NAME}" \
  --visibility=public

Terraform sẽ tự động tạo vùng riêng tư tương ứng cho mcp.${DOMAIN_NAME} (do LB nội bộ và DNS ngang hàng của MCP từ Thời gian chạy của tác nhân sử dụng) – bạn không cần tạo vùng này theo cách thủ công. Khi tắt mạng riêng tư, cả vùng công khai và vùng riêng tư đều không được cung cấp.

Để xem hướng dẫn chi tiết hơn về mẫu DNS phân tách ngang công khai và riêng tư mà bản minh hoạ này sử dụng (thiết lập vùng được quản lý, kết nối ngang hàng DNS trên các VPC, quy trình xác thực chứng chỉ), hãy xem hướng dẫn thiết lập DNS.

6. Định cấu hình các biến Terraform

Sao chép tfvars mẫu rồi chỉnh sửa:

cp terraform/example.tfvars terraform/terraform.tfvars

Có 2 đường dẫn đến bản minh hoạ, được kiểm soát bằng enable_cloud_run_private_networking.

Đường dẫn mặc định: Cloud Run có cổng vào công khai

**Thiết lập đơn giản nhất.**Đối với đường dẫn mặc định, bạn chỉ cần chỉnh sửa 3 giá trị trong terraform.tfvars. Mọi biến khác trong tệp đều đã có giá trị mặc định thân thiện với bản minh hoạ.

# 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:[e-mail]"]

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

Chúng tôi sẽ định cấu hình IAP ở chế độ chỉ kiểm tra chạy thử nghiệm để kiểm thử chính sách uỷ quyền IAP mà không cần thực thi chính sách đó. Sau khi xác thực việc triển khai, chúng tôi sẽ cập nhật chế độ thực thi thành "BẮT BUỘC"

Kết nối mạng riêng tư (không bắt buộc)

Đặt enable_cloud_run_private_networking = true và thêm các biến bên dưới để cung cấp ngăn xếp bảo mật đầy đủ:

• Trình cân bằng tải ứng dụng nội bộ
• Chứng chỉ do Google quản lý
• Cloud Run với ingress = internal-and-cloud-load-balancing
• Thiết lập ngang hàng DNS của Cổng đại lý.

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"

Các hình ảnh Cloud Run ở trên trỏ đến một phần giữ chỗ của Google. Đó là ý định của Terraform – Terraform tạo các dịch vụ Cloud Run bằng lifecycle { ignore_changes = [template[0].containers[0].image] }, vì vậy, các lệnh gọi skaffold run tiếp theo sẽ thay thế hình ảnh mà không cần Terraform phản hồi lại.

agent_gateway_subnet_cidr phải có giá trị tối thiểu là /28, RFC 1918 và không được trùng lặp 10.0.0.0/24, 10.0.1.0/24 hoặc 10.0.2.0/24. Các dải này được dành riêng cho lưu lượng truy cập đi của Agent Gateway.

LB nội bộ MCP phân phát TLS cho *.mcp.${DOMAIN_NAME} bằng cách sử dụng cùng một chứng chỉ khu vực do Google quản lý. Đừng đặt mcp_internal_dns_zone.domain thành một hậu tố không định tuyến được như mcp-server.internal. trong khi enable_agent_gateway = true VÀ enable_cloud_run_private_networking = true.

Agent Gateway hiện không xác thực chứng chỉ dự phòng tự ký. Cấu hình Terraform thực thi điều này bằng một khối check tại thời điểm lập kế hoạch (bỏ qua khi tắt mạng riêng tư, vì không có chứng chỉ LB nào để xác thực).

7. Triển khai cơ sở hạ tầng bằng Terraform

Khởi chạy, xem xét và áp dụng:

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

terraform apply cung cấp khoảng 40 tài nguyên trên đường dẫn mặc định và mất 8 đến 10 phút cho một dự án mới (khoảng 60 tài nguyên / 15 đến 20 phút khi enable_cloud_run_private_networking = true). Nó tạo ra:

• Nền tảng dự án (API, danh tính dịch vụ, hạn mức)
• VPC, mạng con (chỉ dành cho chính, chỉ dành cho proxy, PSC, PSC-Interface, đồng vị trí Cổng đại lý), Cloud NAT, quy tắc tường lửa
• Kho lưu trữ Artifact Registry cho các hình ảnh Cloud Run
• 3 dịch vụ Cloud Run + SA thời gian chạy cho mỗi dịch vụ (mặc định là all; internal-and-cloud-load-balancing khi bật tính năng kết nối mạng riêng tư)
• Mẫu Model Armor + IAM
• Agent Gateway, PSC-I network attachment, IAP và Model Armor extensions, cả hai chính sách ủy quyền và roles/iap.egressor cấp ở cấp dự án
• Các điểm cuối của Agent Registry (Vertex AI, IAP, Discovery Engine, ...) cùng với 3 máy chủ MCP (được đăng ký tại *.run.app/mcp theo mặc định; tại ./mcp khi bật mạng riêng tư)

Chỉ khi enable_cloud_run_private_networking = true:

• Application Load Balancer nội bộ theo khu vực có NEG không máy chủ (định tuyến bằng cách che giấu URL) + bản ghi DNS A riêng tư
• Vùng DNS riêng của MCP (mcp..) được đính kèm vào VPC
• Mô-đun vùng DNS công khai (Uỷ quyền DNS của Trình quản lý chứng chỉ) + Chứng chỉ do Google quản lý theo khu vực
• Vùng DNS của giao diện PSC (không có máy chủ lưu trữ riêng để phân giải, vì vậy, vùng này cũng được kiểm soát bằng cờ chính)
• Thiết lập ngang hàng DNS của Cổng tác nhân cho mcp.. (tự động thêm vào trước)

8. Kiểm tra các điểm cuối của Sổ đăng ký đại lý

Chỉ để tham khảo. Các lệnh trong phần này đã được mô-đun agent-registry-endpoints của Terraform chạy sẵn cho bạn. Các thông tin này xuất hiện để bạn có thể xem chính xác cách đăng ký một điểm cuối có thể phát hiện MCP.

Agent Registry là danh mục dịch vụ theo từng dự án (API của Google và máy chủ MCP của riêng bạn) mà một tác nhân phát hiện trong thời gian chạy. Tác nhân thế chấp đọc tệp này khi khởi động và liên kết các công cụ một cách linh động – không có URL MCP nào được tích hợp vào mã tác nhân hoặc lệnh triển khai của mã đó.

Điểm cuối

Những gì Terraform đã chạy thay cho bạn – đối với mỗi API của Google trong agent_registry_google_apis, API này đã đăng ký 5 biến thể (toàn cầu, mTLS toàn cầu, theo khu vực, mTLS theo khu vực, REP theo khu vực). Ví dụ: đối với 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"

Máy chủ MCP

Terraform cũng đăng ký 3 Máy chủ MCP cho bạn. Để đăng ký các máy chủ MCP khác, bạn có thể làm theo các bước trong tài liệu.

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

Xác minh các Điểm cuối và Máy chủ MCP đã đăng ký.

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

Nguồn: terraform/modules/agent-registry-endpoints/scripts/register_endpoints.sh.tpl

9. Xem lại cấu hình Agent Gateway

Chỉ để tham khảo. Terraform đã nhập Agent Gateway này. YAML bên dưới tương đương với terraform/modules/agent-gateway/main.tf.

Agent Gateway là một lớp quản trị do Google quản lý giữa Agent Runtime và các công cụ của bạn. Ở chế độ AGENT_TO_ANYWHERE, công cụ này được liên kết với Agent Registry của dự án và thoát qua Giao diện PSC do khách hàng sở hữu để có thể truy cập vào các máy chủ MCP riêng tư trong VPC của bạn.

Nếu bạn nhập cổng này theo cách thủ công, thì YAML sẽ trông như sau:

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

Xác minh cổng mà Terraform đã tạo:

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

terraform-provider-google-beta hiện tại chưa hiển thị network_config.dns_peering_config. Terraform áp dụng thông qua PATCH sau khi áp dụng trên networkservices.googleapis.com/v1beta1. Bạn sẽ thấy thông tin này trong terraform_data.dns_peering của mô-đun.

10. Kiểm tra hoạt động uỷ quyền IAP và Model Armor

Chỉ để tham khảo. Terraform đã tạo cả hai tiện ích và cả hai chính sách. Các lệnh bên dưới đến từ terraform/modules/agent-gateway/main.tf.

Agent Gateway uỷ quyền cho các tiện ích dịch vụ. Bản minh hoạ này có 2 hồ sơ chính sách:

• REQUEST_AUTHZ – được đánh giá một lần cho mỗi yêu cầu ở giai đoạn tiêu đề. Được dùng ở đây để gọi IAP, nhằm kiểm tra xem danh tính tác nhân gọi có roles/iap.egressor trên máy chủ MCP mục tiêu hay không.
• CONTENT_AUTHZ – truyền các sự kiện nội dung đến tiện ích để dọn dẹp nội dung. Được dùng ở đây để gọi Model Armor, giúp sàng lọc các trường hợp tiêm câu lệnh (prompt injection), vượt qua các hạn chế, vi phạm AI có trách nhiệm và (không bắt buộc) PII (Thông tin nhận dạng cá nhân) thông qua tính năng Bảo vệ dữ liệu nhạy cảm (SDP).

Tiện ích 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}

Liên kết nó với Agent Gateway bằng chính sách 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"
        ]
      }
    }
  }'

Tiện ích Model Armor CONTENT_AUTHZ

Tiện ích metadata.model_armor_settings mang theo các mã mẫu yêu cầu và phản hồi mà Model Armor dùng để đánh giá từng chú thích:

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

Mẫu DLP tuỳ chỉnh

sdpSettings.basicConfig của Model Armor sử dụng danh sách loại thông tin tích hợp. Để kiểm soát chi tiết hơn (các loại thông tin tuỳ chỉnh, che phủ một phần, thay thế bằng dữ liệu thay thế, biên tập theo khả năng), hãy trỏ Model Armor đến các mẫu kiểm tra và khử nhận dạng Cloud DLP của riêng bạn thông qua sdpSettings.advancedConfig.

Tạo một mẫu kiểm tra gắn cờ Số an sinh xã hội tại Hoa Kỳ với POSSIBLE khả năng hoặc cao hơn:

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

Tạo một mẫu xoá thông tin nhận dạng để thay thế mỗi kết quả bằng mã thông báo loại thông tin tương ứng (ví dụ: [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": {} }
          }]
        }
      }
    }
  }'

Sau đó, hãy trỏ cấu hình phản hồi của mẫu Model Armor vào cặp thông qua sdpSettings.advancedConfig (đây là nơi mô-đun model_armor của Terraform sẽ đặt advanced_config nếu bạn kết nối nó):

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

Tiện ích mở rộng CONTENT_AUTHZ Model Armor ở trên sẽ tự động chọn các mẫu cấu hình nâng cao này vào lần tiếp theo khi đánh giá một phản hồi – không cần thay đổi tiện ích mở rộng. Đảm bảo rằng tác nhân dịch vụ Model Armor (service-${PROJECT_NUMBER}@gcp-sa-modelarmor.iam.gserviceaccount.com) giữ roles/dlp.user và roles/dlp.reader trên dự án (mô-đun model-armor của Terraform đã cấp các quyền này).

IAM của IAP egressor (chỉ dành cho mỗi máy chủ MCP)

Terraform không tạo một chế độ liên kết roles/iap.egressor trên toàn dự án trong sổ đăng ký tác nhân IAP ngầm ẩn. IAP REQUEST_AUTHZ liên kết thực sự đánh giá là theo từng máy chủ MCP và theo từng công cụ suy luận, được cấp sau khi nhân viên hỗ trợ được triển khai và bạn biết Mã nhận dạng nhân viên hỗ trợ. Bước "Grant the agent per-MCP-server egress" (Cấp quyền truy cập cho tác nhân trên mỗi máy chủ MCP) sẽ chạy scripts/grant_agent_mcp_egress.sh cho việc đó.

11. Tạo và triển khai các máy chủ MCP lên Cloud Run

Các tệp cloudrun/*.yaml.tmpl và skaffold.yaml.tmpl tham chiếu ${PROJECT_ID}, ${REGION} và ${MCP_INGRESS} (chú thích về cổng vào Cloud Run). Nguồn MCP_INGRESS từ đầu ra Terraform để các bản kê khai được kết xuất luôn đồng bộ hoá với enable_cloud_run_private_networking, sau đó kết xuất bằng envsubst:

Xuất cấu hình cổng vào Cloud Run.

• all
• internal-and-cloud-load-balancing (Khi sử dụng phương pháp Mạng riêng tư)

export MCP_INGRESS=all

envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < skaffold.yaml.tmpl > skaffold.yaml
for f in cloudrun/*.yaml.tmpl; do
  envsubst '${PROJECT_ID} ${REGION} ${MCP_INGRESS}' < "$f" > "${f%.tmpl}"
done

Mỗi dịch vụ Cloud Run chạy dưới dạng SA thời gian chạy cho mỗi dịch vụ do Terraform tạo (ví dụ: mcp-legacy-dms@${PROJECT_ID}.iam.gserviceaccount.com). Để triển khai dưới dạng các SA đó, bạn cần có roles/iam.serviceAccountUser trên chính mình:

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

Xây dựng bằng Cloud Build và triển khai bằng Skaffold:

skaffold run

Skaffold tạo 3 hình ảnh (legacy-dms, corporate-email, income-verification-api) vào kho lưu trữ Artifact Registry của bạn và cập nhật từng dịch vụ Cloud Run để trỏ đến bản tóm tắt mới.

Xác minh:

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

Bạn sẽ thấy cả 3 dịch vụ đều có trạng thái ACTIVE.

12. Triển khai trợ lý ảo thế chấp cho Thời gian chạy của trợ lý ảo

Cài đặt các deps của tác nhân và triển khai:

cd src/mortgage-agent
uv sync

uv run python deploy_agent.py \
  --project=${PROJECT_ID} \
  --region=${REGION} \
  --enable-agent-identity \
  --agent-name=mortgage-agent \
  --agent-gateway=projects/${PROJECT_ID}/locations/${REGION}/agentGateways/agent-gateway \
  --model-endpoint-location=global

Tác nhân phát hiện các công cụ MCP trong thời gian chạy bằng cách liệt kê mcpServers trong Sổ đăng ký tác nhân trong projects/${PROJECT_ID}/locations/${REGION}.

Khi tập lệnh hoàn tất, hãy sao chép reasoningEngines/ đã in vào trình bao:

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

13. Cấp quyền truy cập egress cho tác nhân theo từng máy chủ MCP

Tiện ích REQUEST_AUTHZ của IAP sẽ uỷ quyền cho từng lệnh gọi công cụ bằng cách kiểm tra roles/iap.egressor của tác nhân trên máy chủ MCP cụ thể hoặc điểm cuối mà tác nhân đang gọi. Xem phần Tạo chính sách chuyển dữ liệu ra cho máy chủ MCP.

Tập lệnh (scripts/grant_agent_mcp_egress.sh) liệt kê các máy chủ MCP trong Agent Registry (Sổ đăng ký tác nhân) trong projects/${PROJECT_ID}/locations/${REGION} và hợp nhất một liên kết roles/iap.egressor cho bên chính của tác nhân vào chính sách IAM của mỗi máy chủ (phản ánh ngữ nghĩa gcloud add-iam-policy-binding).

Trường hợp sử dụng 1 – Cấp quyền vô điều kiện trong phạm vi các máy chủ MCP cụ thể

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

Trường hợp sử dụng 2 – Cấp quyền có điều kiện (CEL) trong phạm vi một máy chủ MCP cụ thể

Để hạn chế tác nhân chỉ sử dụng một số công cụ trên một máy chủ MCP, hãy đính kèm một điều kiện IAM. Agent Gateway xuất bản các thuộc tính cho mỗi công cụ mà IAP REQUEST_AUTHZ hiển thị cho CEL, bao gồm:

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

Hạn chế chỉ cho phép nhân viên hỗ trợ sử dụng các công cụ chỉ đọc trên 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" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Sau khi thao tác này chạy, các công cụ ghi trên corporate-email sẽ trả về 403 PermissionDenied từ IAP REQUEST_AUTHZ; các công cụ chỉ đọc sẽ tiếp tục hoạt động.

Xác minh các liên kết

Chuyển đến thẻ Chính sách, bạn sẽ thấy danh sách Chính sách được tạo dựa trên Điểm cuối và Máy chủ Mcp.

Các trường hợp sử dụng khác:

Cấp quyền vô điều kiện trên mọi máy chủ MCP, phạm vi chỉ giới hạn trong một tác nhân

Chạy lệnh này sau mỗi lần triển khai lại tác nhân. Nếu không có bộ lọc và không có điều kiện, thì tác nhân có tên sẽ nhận được roles/iap.egressor trên mọi máy chủ MCP trong sổ đăng ký:

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

14. Kiểm thử nhân viên hỗ trợ trong bảng điều khiển Nền tảng nhân viên hỗ trợ

Bảng điều khiển Nền tảng tác nhân đi kèm với một Sân chơi cho phép bạn trò chuyện trực tiếp với tác nhân đã triển khai. Đây là cách nhanh nhất để kiểm thử nhanh các lệnh gọi công cụ và kiểm tra dấu vết trước khi kết nối tác nhân với Gemini Enterprise.

1. Mở trang Triển khai nền tảng tác nhân trong bảng điều khiển Google Cloud.
2. Sử dụng trường Bộ lọc nếu bạn cần thu hẹp danh sách thời gian chạy, sau đó nhấp vào thời gian chạy mortgage-agent.
3. Mở thẻ Playground.
4. Nhập câu lệnh để trò chuyện với tác nhân:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Thao tác này sẽ trả về phản hồi từ công cụ Quản lý tài liệu và công cụ Xác minh thu nhập, số An sinh xã hội cũng phải được biên tập trong phản hồi này. 5. Nhập câu hỏi nối tiếp:

Can you send a summary of this to my email [e-mail]

Nhân viên hỗ trợ cần xác định rằng họ không có quyền truy cập vào công cụ send_email và phản hồi cho phù hợp.

Vì tác nhân được triển khai bằng tính năng đo lường OpenTelemetry, nên Playground sẽ hiển thị 4 chế độ xem bảng điều khiển bên mà bạn có thể chuyển đổi khi tác nhân phản hồi:

• Dấu vết – dấu vết đầy đủ của cuộc trò chuyện, bao gồm cả Agent Gateway, IAP REQUEST_AUTHZ và Model Armor CONTENT_AUTHZ
• Sự kiện – biểu đồ về các công cụ được gọi và thông tin chi tiết về sự kiện cho lượt hiện tại
• Trạng thái – trạng thái phiên của tác nhân và đầu vào/đầu ra của công cụ
• Phiên – mọi phiên bạn đã bắt đầu đối với thời gian chạy này

Playground hoàn toàn bỏ qua quy trình xác thực Gemini Enterprise, nhờ đó, đây là nơi nhanh nhất để xác nhận rằng tiện ích REQUEST_AUTHZ IAP đang cấp lệnh gọi công cụ một cách chính xác. Nếu một công cụ trả về 403 ở đây, hãy chạy lại scripts/grant_agent_mcp_egress.sh trước khi gỡ lỗi sâu hơn.

15. Thực thi uỷ quyền IAP

Sau khi xác thực việc triển khai, chúng ta có thể cập nhật Chế độ thực thi IAP thành null để thực thi các chính sách. Mở terraform.tfvars và cập nhật chế độ từ DRY_RUN thành null

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

Áp dụng thay đổi.

terraform apply

Quay lại Playground rồi thử lại cuộc trò chuyện.

1. Mở trang Triển khai nền tảng tác nhân trong bảng điều khiển Google Cloud.
2. Sử dụng trường Bộ lọc nếu bạn cần thu hẹp danh sách thời gian chạy, sau đó nhấp vào thời gian chạy mortgage-agent.
3. Mở thẻ Playground.
4. Nhập câu lệnh để trò chuyện với tác nhân:

I am reviewing the Sterling familys current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?

Thao tác này sẽ trả về phản hồi từ công cụ Quản lý tài liệu và công cụ Xác minh thu nhập, số An sinh xã hội cũng phải được biên tập trong phản hồi này. 5. Nhập câu hỏi nối tiếp:

Can you send a summary of this to my email [e-mail]

Nếu mọi thứ đã được thiết lập chính xác, thì tác nhân sẽ phản hồi rằng không thể gửi email do chính sách uỷ quyền.

16. Thiết lập và thử nghiệm Gemini Enterprise

Thiết lập Gemini Enterprise

Làm theo hướng dẫn bắt đầu sử dụng Gemini Enterprise.

Đăng ký Tác nhân ADK với Gemini Enterprise

Để đăng ký tác nhân của chúng tôi trong Gemini Enterprise, bạn có thể làm theo các bước tại đây.

1. Trong bảng điều khiển Cloud, hãy chuyển đến trang Gemini Enterprise.
2. Chọn Ứng dụng Gemini Enterprise nơi tác nhân được đăng ký.
3. Mở URL xuất hiện trong phần Ứng dụng web Gemini Enterprise của bạn đã sẵn sàng.
4. Chọn thẻ Agent (Đại lý) trên trình đơn bên trái để mở Agent Gallery (Thư viện đại lý).
5. Chọn Mortgage Assistant Agent (Trợ lý thế chấp) rồi bắt đầu trò chuyện.

Hãy thử các câu lệnh tương tự trong Agent Runtime Playground:

Câu lệnh ban đầu:

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?

Câu hỏi nối tiếp:

Can you send a summary of this to my email [e-mail]

Nếu quay lại phần Triển khai tác nhân trong bảng điều khiển, hãy chọn chế độ triển khai tác nhân của chúng tôi rồi chuyển đến thẻ dấu vết. Giờ đây, bạn sẽ thấy tác nhân Trợ lý Gemini trong khoảng thời gian cho thấy lệnh gọi bắt nguồn từ Gemini Enterprise.

17. Khắc phục sự cố và các giải pháp thường gặp

• terraform apply không thành công trên Cổng tác nhân với thông báo "resource is being created and therefore can not be updated" (tài nguyên đang được tạo nên không thể cập nhật) – dự án người thuê của cổng mất khoảng 30 giây để hoàn tất trước khi các chính sách uỷ quyền có thể đính kèm. time_sleep.wait_for_gateway của mô-đun sẽ xử lý việc này; bạn chỉ cần chạy lại terraform apply.
• Tác nhân báo cáo "không tìm thấy máy chủ MCP" hoặc chỉ khởi động bằng các công cụ tiện ích – xác nhận enable_agent_registry_endpoints = true trong terraform.tfvars, sau đó:

  gcloud alpha agent-registry mcp-servers list \
    --project=${PROJECT_ID} --location=${REGION}
  

  Bạn sẽ thấy 3 mục (mỗi mục cho một dịch vụ MCP Cloud Run). Nếu danh sách này trống, hãy kiểm tra để đảm bảo rằng các dịch vụ MCP có thể truy cập được từ bên trong VPC và Agent Gateway đã điền sẵn thông tin vào sổ đăng ký (hệ thống sẽ thực hiện việc này một cách chậm rãi trong danh sách công cụ được uỷ quyền lần đầu tiên).
• Lệnh gọi công cụ trả về 403 PermissionDenied – chạy lại scripts/grant_agent_mcp_egress.sh. Nguyên nhân phổ biến nhất là quên cấp lại sau khi triển khai lại tác nhân (reasoningEngines/ thay đổi mỗi lần triển khai).
• skaffold run không thành công với thông báo "permission denied on service account" (bị từ chối quyền đối với tài khoản dịch vụ) – bạn bị thiếu roles/iam.serviceAccountUser. Chạy lại quy trình tự cấp quyền ở bước trước.
• Lỗi liên kết DNS từ Agent Gateway đến MCP LB – kiểm tra để đảm bảo rằng agent_gateway_dns_peering_config.target_network khớp chính xác với projects/${PROJECT_ID}/global/networks/${VPC_NAME} và mọi mục domains đều kết thúc bằng dấu chấm.
• terraform plan liên tục muốn cập nhật thẻ hình ảnh Cloud Run – điều này không được phép xảy ra do quy tắc lifecycle { ignore_changes }. Nếu có, hãy xác nhận rằng bạn không chỉnh sửa mcp_services[*].image trong terraform.tfvars sau skaffold run.

18. Dọn dẹp

Công cụ suy luận không được Terraform quản lý (SDK ADK sẽ tạo công cụ này). Xoá theo cách thủ công:

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

Xoá mọi thứ mà Terraform đã tạo:

cd terraform
terraform destroy
cd ..

Nếu bạn chỉ tạo vùng DNS công khai cho lớp học lập trình này:

gcloud dns managed-zones delete agw-example-com

Cuối cùng, hãy xoá vùng chứa trạng thái Terraform:

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

19. Xin chúc mừng

Xin chúc mừng! Bạn đã triển khai thành công hoạt động quản trị tác nhân toàn diện cho một tác nhân ADK có nhiều công cụ bằng Agent Gateway. Bằng cách đóng vai trò là lớp kiểm soát mạng tập trung, Agent Gateway cho phép bạn thiết lập một đường dẫn đi ra an toàn đến các công cụ riêng tư, thực thi các chính sách IAM dựa trên danh tính chi tiết thông qua Identity-Aware Proxy và dọn dẹp các tương tác nội dung bằng cách sử dụng các biện pháp bảo vệ Model Armor tích hợp.

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

• Cách triển khai và định cấu hình Agent Gateway làm lớp quản trị trung tâm cho lưu lượng truy cập xuất từ Agent-to-Anywhere.
• Cách tích hợp Sổ đăng ký tác nhân để khám phá công cụ thời gian chạy động có kiểm soát.
• Cách viết và thực thi các chính sách IAM dựa trên điều kiện và theo từng công cụ để kiểm soát chặt chẽ các đường dẫn thực thi của tác nhân.
• Cách tận dụng các tiện ích dịch vụ Agent Gateway để áp dụng chính sách Model Armor, tự động chặn và chỉnh sửa lưu lượng truy cập nhạy cảm của tác nhân.

Tài liệu tham khảo

• Tổng quan về chính sách quản trị đại lý
• Tài liệu về Cổng tác nhân
• Tài liệu nhận dạng nhân viên hỗ trợ
• Tổng quan về Nền tảng tác nhân Gemini Enterprise