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 khối xây dựng 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 tác nhân là thành phần mạng của bộ công cụ Quản trị tác nhân 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 từ xa): 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 (egress).

Kiểm soát quyền truy cập bằng Agent Gateway

Để 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 riêng biệ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 gọi đến các công cụ cụ thể.
  • Model Armor: Một biện pháp bảo vệ bằng AI được tích hợp thông qua Tiện ích dịch vụ để làm sạch 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)

Để 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 Bộ cân bằng tải ứng dụng nội bộ bằng NEG không máy chủ. Bạn cần sở hữu một miền DNS công khai để cấp một 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 từ đầu đến cuối 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 Chủ sở hữu
  • Quyền IAM ở cấp tổ chức (lớp học lập trình cấp 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 của lớp học lập trình

Kiến trúc toàn diện: Gemini Enterprise đến Thời gian chạy tác nhân đến Cổng tác nhân đến máy chủ MCP trên Cloud Run

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 VPC và 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 ~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á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 trình bao của bạn.

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"

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

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 Load Balancer 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

Luồng cấp cao của lựa chọn kết nối 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.

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ó hai đường dẫ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:admin@example.com"]

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

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
  • Kết nối ngang DNS của Agent Gateway.
enable_cloud_run_private_networking = true

# DNS — must end with a trailing dot, must match a Cloud DNS zone you own
dns_zone_domain            = "agw.example.com."
enable_certificate_manager = true

# mcp_internal_dns_zone.domain MUST be a real subdomain of dns_zone_domain so
# Certificate Manager can issue a Google-managed cert.
mcp_internal_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

# Must match mcp_internal_dns_zone.domain so Agent Engine resolves MCP
# hostnames over the PSC interface peering.
psc_interface_dns_zone = {
  name   = "mcp-server-internal"
  domain = "mcp.agw.example.com."
}

mcp_lb_protocol = "HTTPS"

7. 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 -out=tfplan
terraform apply tfplan

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). Lệnh này sẽ tạo:

  • Nền tảng dự án (API, danh tính dịch vụ, hạn mức)
  • VPC, mạng con (chính, chỉ dùng 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ụ (đầu vào = all theo mặc định; 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
  • Tiện ích Agent Gateway, PSC-I network attachment, IAP và Model Armor, cả hai chính sách uỷ 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 tính năng kết nối 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 A DNS 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 giao diện PSC (không có máy chủ lưu trữ khi không có tên máy chủ riêng tư nào cần phân giải, vì vậy, vùng này cũng được kiểm soát bằng cờ chính)
  • Hoạt động ngang hàng DNS của Agent Gateway 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ý

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 hoạt – 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, Terraform đã đă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

Agent Gateway là một lớp quản trị do Google quản lý, nằm 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: