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

Bản xem trước riêng tư – Agent Gateway Để yêu cầu quyền sử dụng Agent Gateway với Agent Runtime, hãy xem trang yêu cầu cấp quyền truy cập.

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.

API này hỗ trợ 2 đường dẫn truy cập được kiểm soát 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 (egress).

Để 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 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 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 của 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 cả 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) cho Cloud Run. Các máy chủ này đóng vai trò là 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 thiết lập 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ụ thời gian chạy thông qua Sổ đăng ký tác nhân.

Để bảo mật quy trình, bạn sẽ định cấu hình Agent Gateway bằng hai tiện ích dịch vụ. Đầu tiên, tiện ích REQUEST_AUTHZ sẽ xác minh Danh tính của Agent dựa trên các chính sách IAM cho từng công cụ, đảm bảo rằng Agent chỉ truy cập vào các công cụ được uỷ quyền. Thứ hai, 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 Agent.

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 trình bao 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 vùng 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 bỏ qua. 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 Cloud 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 cổng vào đượ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 (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 đám mây để 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 và chỉnh sửa:

cp terraform/example.tfvars terraform/terraform.tfvars

Có hai đườ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 tra 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 null để thực thi các chính sách.

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 đủ:

• LB ứ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 quan hệ ngang hàng 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"

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 chống lại chúng.

agent_gateway_subnet_cidr phải có ít nhất /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 Cổng đại lý.

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 động, 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)

Nếu gặp vấn đề với một vùng chứa Cloud Build hiện có như Error 409: The requested bucket name is not available. The bucket namespace is shared by all users of the system, bạn có thể nhập vùng chứa hiện có này vào trạng thái terraform bằng cách chạy lệnh sau: terraform import google_storage_bucket.cloudbuild ${PROJECT_ID}_cloudbuild

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 chạy cho bạn bằng mô-đun agent-registry-endpoints của Terraform. Các thông tin này xuất hiện để bạn có thể xem chính xác quy trình đăng ký một điểm cuối có thể phát hiện MCP trông như thế nào.

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 được trong thời gian chạy. Tác nhân thế chấp sẽ đọc danh mục 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 tác nhân.

Đ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

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ý, 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:
  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 việc cấp 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ụ. Hai hồ sơ chính sách bao gồm bản minh hoạ:

• 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 để làm sạch 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 chứa các mã nhận dạng 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 (loại thông tin tuỳ chỉnh, che phủ một phần, thay thế bằng giá trị thay thế, loại bỏ theo khả năng), hãy trỏ Model Armor đến các mẫu kiểm tra và loại bỏ thông tin 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 mức độ POSSIBLE trở lê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 (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 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 – bạn không cần thay đổi tiện ích. Đả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 tác nhân được triển khai và bạn biết Mã nhận dạng tác nhân. Bước "Grant the agent per-MCP-server egress" (Cấp quyền truy cập cho tác nhân theo từng 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ề lưu lượng truy cập vào Cloud Run). Nguồn MCP_INGRESS từ đầu ra Terraform để các tệp 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 Nối mạng riêng tư)

export MCP_INGRESS=all

Quay lại thư mục gốc của bản minh hoạ:

cd ..

Thay thế các giá trị mẫu:

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ụ mà 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 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 tác nhân thế chấp vào Thời gian chạy tác nhân

Cấp cho tất cả các Agent vai trò IAP Egressor trên tất cả các điểm cuối mà chúng tôi đã đăng ký vào sổ đăng ký. Tác nhân cần có quyền truy cập vào các điểm cuối này vì khi được triển khai, tác nhân cần truy cập vào github.com để lấy các gói, sau đó truy cập vào nhiều API của Google cần thiết để triển khai.

./scripts/grant_agent_mcp_egress.sh --bind-all-agents --endpoints

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 \
  --mcp-invoker-sa=$(terraform -chdir=../../terraform output -raw agent_mcp_invoker_email) \
  --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 (ví dụ: 4262292559201566720):

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

13. Cấp quyền truy cập cho tác nhân trên mỗi 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 chủ thể 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.

Chỉ cho phép đặc vụ 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 || api.getAttribute('iap.googleapis.com/mcp.toolName', '') == ''" \
  --condition-title "ReadOnlyToolsOnly" \
  --condition-description "Restrict ${AGENT_ID} to read-only tools on corporate-email"

Sau khi 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.

Nếu không có chính sách nào chống lại bất kỳ điểm cuối nào, hãy chạy tập lệnh với cấu hình sau. ./scripts/grant_agent_mcp_egress.sh --agent-id $AGENT_ID --endpoints

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 ở 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 Playground (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 Cloud của Google.
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 nhân viên hỗ trợ:

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ợ sẽ gửi được email, vì chính sách có điều kiện không được thực thi do tiện ích IAP đang ở chế độ Chạy thử.

Vì tác nhân được triển khai bằng tính năng đo từ xa 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 của 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 giao dịch mua trong ứng dụng 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 Cloud của Google.
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 nhân viên hỗ trợ:

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 (Trợ lý ảo) trên trình đơn bên trái để mở Thư viện trợ lý ảo.
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.

Nếu đã định cấu hình Model Armor cho Gemini Enterprise, bạn có thể cần sửa đổi cấu hình Bảo vệ dữ liệu nhạy cảm cơ bản, vì mẫu Gemini Enterprise mặc định sẽ chặn infoType thuộc loại FINANCIAL_ACCOUNT_NUMBER. Bạn có thể xem thêm thông tin trong tài liệu.

17. Trang tổng quan về khả năng ghi nhận

Trang tổng quan về gỡ lỗi uỷ quyền cung cấp một chế độ xem duy nhất về lưu lượng truy cập truyền dữ liệu ra của các Agent Runtime Agent.

Trang tổng quan này hiển thị những thông tin sau:

• Tác nhân ➔ Điểm cuối (403 Lỗi từ chối)
• Tác nhân ➔ Máy chủ MCP (403 Từ chối)
• Tác nhân ➔ Tác nhân (403 Từ chối)
• Khối gửi đi chưa đăng ký
• Tổng quan về lưu lượng truy cập và Chế độ thực thi IAP
• GCP API IAM Denials

Mỗi tiện ích hiển thị mã nhận dạng tác nhân, máy chủ lưu trữ được yêu cầu, đường dẫn tài nguyên đã đăng ký và liệu Cổng và IAP có uỷ quyền cho yêu cầu hay không.

• Unregistered Outbound Blocks (Các khối đi ra chưa đăng ký) – Tiện ích này đặc biệt tách biệt lưu lượng truy cập mà Cổng tác nhân đã chặn vì tên máy chủ đích không có trong Sổ đăng ký tác nhân. Vì proxy cổng chặn những yêu cầu này trước khi chúng đến được IAP, nên sẽ không có nhật ký kiểm tra IAP cho những mục này.
• Tổng quan về lưu lượng truy cập và chế độ thực thi IAP – Tiện ích này cung cấp một bảng cho thấy tất cả các mẫu lưu lượng truy cập. Điều quan trọng là tiện ích này bao gồm trạng thái Chạy thử IAP, cho phép người dùng xem liệu các chính sách IAP có đang chặn lưu lượng truy cập hay chỉ quan sát.
• GCP API IAM Denials – Tiện ích này tìm kiếm Nhật ký kiểm tra đám mây tiêu chuẩn (cloudaudit.googleapis.com) để phát hiện các lỗi quyền API cơ bản của Google Cloud cho các Agent.

Bạn có thể tìm thấy trang tổng quan này trong Cloud Console: Monitoring > Dashboards > Agent Platform: Authorization Debugging

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

Gỡ lỗi bằng AI với Gemini CLI

Bạn có thể sử dụng kỹ năng agent-platform-debugger trong Gemini CLI để khắc phục sự cố. Gói kỹ năng này cung cấp kiến thức chuyên biệt để gỡ lỗi bằng AI. Vì Gemini CLI coi .agents/skills/ là một bí danh hạng nhất cho .gemini/skills/ ở phạm vi không gian làm việc, nên bạn có thể sử dụng các kỹ năng này trực tiếp. Cách sử dụng kỹ năng này trong Kho lưu trữ lớp học lập trình:

Chuyển đến thư mục kho lưu trữ và khởi động Gemini CLI:

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

Tin tưởng không gian làm việc khi được nhắc (các kỹ năng trong phạm vi không gian làm việc chỉ tải từ các thư mục đáng tin cậy). Xác nhận kỹ năng đã tải:

/skills list

Bạn sẽ thấy agent-platform-debugger trong danh sách. Nếu thiếu, hãy tải lại các kỹ năng:

/skills reload

Mẹo khắc phục sự cố

• terraform apply không thành công trên Cổng đại lý với thông báo "resource is being created and therefore can not be updated" (tài nguyên đang được tạo và do đó không thể cập nhật) – dự án đối tượng thuê của cổng mất khoảng 30 giây để ổn định 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.
• Nhân viê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 trống, hãy kiểm tra để đảm bảo rằng các dịch vụ MCP có thể truy cập từ bên trong VPC và Agent Gateway đã điền sẵn 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 trên danh sách công cụ được uỷ quyề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ạ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ừ Cổng tác nhân đế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.

19. Dọn dẹp

Công cụ suy luận không được Terraform quản lý (SDK ADK 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

20. 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 thoát 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 hoạt động 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 Agent Registry để 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ụ Cổng đại lý để áp dụng chính sách Model Armor, tự động chặn và biên tập lưu lượng truy cập nhạy cảm của đại lý.

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ề Agent Gateway
• 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