Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Gemini Enterprise có cổng ra Agent Gateway đến máy chủ MCP tuỳ chỉnh riêng tư bằng cách sử dụng Agent Registry

1. Giới thiệu

Lớp học lập trình này khám phá khả năng kết nối đi ra riêng tư, có kiểm soát cho Gemini Enterprise bằng cách sử dụng Cổng tác nhân ở chế độ tác nhân-đến-mọi nơi (đi ra). Bạn sẽ định cấu hình một ứng dụng Gemini Enterprise để gọi một cách an toàn máy chủ Giao thức ngữ cảnh mô hình (MCP) tuỳ chỉnh được lưu trữ trên Cloud Run bằng cách định tuyến lưu lượng truy cập thông qua Agent Gateway bằng cách sử dụng giao diện Private Service Connect (PSC) để kết nối với một điểm cuối PSC cho các API của Google trong mạng VPC.

Trong môi trường doanh nghiệp, việc cấp cho các tác nhân tự trị quyền truy cập trực tiếp vào mạng có nguy cơ dẫn đến hành vi đánh cắp dữ liệu và thực thi công cụ chưa được kiểm duyệt. Agent Gateway cung cấp một điểm thực thi không tin cậy ở cấp nền tảng và tập trung, có khả năng kiểm tra linh hoạt các tải trọng công cụ MCP HTTP có thể truyền trực tuyến. Các yêu cầu đi ra được xác thực bằng Danh tính của tác nhân có thể xác minh bằng mật mã và được uỷ quyền thông qua Proxy nhận biết danh tính (IAP) bằng cách sử dụng Chính sách truy cập hợp nhất (UAP) của IAM với các quy tắc Ngôn ngữ biểu thức chung (CEL). Điều này cho phép kiểm soát quyền truy cập chi tiết đối với các công cụ và phương thức MCP cụ thể mà không làm lộ các khối lượng công việc phụ trợ ra Internet công cộng.

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

Agent Gateway hoạt động ở chế độ truyền dữ liệu ra (agent-to-anywhere) với quy trình xác minh điểm cuối Agent Registry
Dịch vụ Cloud Run lưu trữ một máy chủ MCP HTTP riêng tư có thể truyền trực tuyến (--ingress=internal) đã đăng ký thông số kỹ thuật của công cụ trong Agent Registry
Tiện ích uỷ quyền Identity-Aware Proxy (IAP) cho Agent Gateway
Chính sách hợp nhất về quyền truy cập (UAP) của IAM với các điều kiện CEL để uỷ quyền cho công cụ MCP
Ứng dụng Gemini Enterprise được liên kết với Agent Gateway và kết nối với kho lưu trữ dữ liệu MCP tuỳ chỉnh được nhập từ Agent Registry
Tài nguyên mạng VPC, vùng DNS Cloud DNS và điểm cuối PSC cho các API của Google
Tệp đính kèm mạng PSC cho lưu lượng truy cập đi ra từ VPC riêng tư của Agent Gateway
Quy tắc chính sách Tường lửa thế hệ mới (NGFW) trên đám mây để bảo mật lưu lượng truy cập VPC

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

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

Cách triển khai một máy chủ MCP HTTP có thể truyền trực tuyến riêng tư từ nguồn trên Cloud Run và đăng ký điểm cuối cũng như giản đồ công cụ của máy chủ đó trong Agent Registry
Cách định cấu hình Agent Gateway bằng các mục nhập sổ đăng ký tuân thủ và định tuyến các lệnh gọi công cụ ứng dụng Gemini Enterprise thông qua cổng
Cách thiết lập lưu lượng truy cập riêng tư ra khỏi VPC bằng cách sử dụng các tệp đính kèm và giao diện mạng PSC
Cách uỷ quyền Cổng đại lý cho Identity-Aware Proxy (IAP)
Cách tạo và liên kết Chính sách truy cập hợp nhất (UAP) của IAM bằng cách sử dụng các thuộc tính destination.agent_registry.* và destination.is_registered CEL để hạn chế việc thực thi công cụ MCP
Cách xác thực việc thực thi chính sách và truyền dữ liệu ra khỏi mạng bằng Cloud Logging

Bạn cần có

Một dự án trên Google Cloud đã bật tính năng thanh toán
Giấy phép Gemini Enterprise đang hoạt động hoặc chương trình dùng thử 30 ngày
Quyền IAM để cung cấp các dịch vụ mạng, Gemini Enterprise và tài nguyên Nền tảng tác nhân
Một trình bao tương thích với POSIX (bash hoặc zsh) đã cài đặt Google Cloud CLI (gcloud), curl và jq

Đến đây là kết thúc phần giới thiệu... tiếp theo là phần Khái niệm.

2. Khái niệm

Trình tự triển khai

Lớp học lập trình này triển khai cơ sở hạ tầng trước để các đường dẫn mạng riêng tư và chế độ kiểm soát hoạt động quản trị có thể hoạt động trước khi đăng ký và kết nối các công cụ MCP với Gemini Enterprise:

Cơ sở hạ tầng mạng: Cung cấp các mạng con VPC, một điểm cuối PSC, một tệp đính kèm mạng PSC, các quy tắc chính sách Cloud NGFW và các vùng Cloud DNS riêng tư.
Agent Gateway: Triển khai Agent Gateway ở chế độ truyền dữ liệu ra ngoài với tính năng tích hợp Agent Registry (registries) và truyền dữ liệu ra ngoài VPC riêng tư (networkAttachment).
Chính sách uỷ quyền: Thiết lập tiện ích uỷ quyền IAP, chính sách Gateway Authz và Chính sách truy cập hợp nhất (UAP) IAM bằng cách sử dụng các điều kiện CEL destination.is_registered và destination.agent_registry.*.
Triển khai và đăng ký máy chủ MCP: Triển khai máy chủ MCP toán học từ nguồn đến Cloud Run (--ingress=internal) và đăng ký các thông số kỹ thuật về dịch vụ và công cụ (add và subtract) trong Sổ đăng ký tác nhân.
Ứng dụng Gemini Enterprise: Tạo ứng dụng Gemini Enterprise (Engine), định cấu hình chế độ cài đặt danh tính và khả năng quan sát, đồng thời liên kết lưu lượng truy cập đi ra với Agent Gateway (agentGatewaySetting).
Nhập trình kết nối dữ liệu MCP tuỳ chỉnh: Tạo và kích hoạt trình kết nối dữ liệu REGISTRY_MCP (:setUpDataConnector) để liên kết kho lưu trữ dữ liệu hỗ trợ của máy chủ MCP đã đăng ký với ứng dụng Gemini Enterprise.
Xác thực: Kiểm thử các lệnh thực thi công cụ được phép và bị từ chối trong cuộc trò chuyện, đồng thời xác minh việc thực thi chính sách trên các nhật ký của Cổng đại lý, DNS, Tường lửa và Cloud Run.

Dữ liệu đầu ra của Gemini Enterprise

Gemini Enterprise định tuyến các yêu cầu tuỳ chỉnh về công cụ máy chủ MCP đến Agent Gateway khi cả agentGatewaySetting trên Engine và use_agent_gateway_egress: true trên DataConnector đều được định cấu hình.

Hình 2. Cấu trúc truyền dữ liệu ra bên ngoài của Gemini Enterprise

Ứng dụng Gemini Enterprise sắp xếp việc định tuyến công cụ theo 4 lĩnh vực chính:

Tiện ích (default_search_widget_config):
- Phục vụ giao diện ứng dụng web. Tiện ích này nhận câu lệnh từ người dùng và bắt đầu các phiên trò chuyện với công cụ cơ bản.
Trợ lý cốt lõi (assistants/default_assistant/agents/default/core_assistant):
- Tác nhân suy luận đàm thoại gốc trong công cụ. Khi đánh giá một câu hỏi của người dùng, Trợ lý cốt lõi sẽ xác định xem có cần tính toán số học hay không, kiểm tra các công cụ hiện có và uỷ quyền thực thi cho tác nhân phụ Cổng tác nhân tổng hợp.
Kho dữ liệu và Trình kết nối dữ liệu:
- DataStore: Được cung cấp trong một Collection chuyên dụng khi :setUpDataConnector chạy, nó liên kết (dataStoreIds) các giản đồ công cụ Agent Registry (add, subtract), các loại đối số và hướng dẫn về tác nhân đã nhập với Engine của Gemini Enterprise.
- DataConnector: Quản lý kết nối hành động REGISTRY_MCP (createBapConnection: true) đến máy chủ MCP từ xa (instance_uri), phân giải tài nguyên máy chủ MCP của Sổ đăng ký tác nhân (registry_mcp_server_name) và cho phép lưu lượng truy cập đi của Cổng tác nhân (use_agent_gateway_egress: true).
Danh tính của tác nhân, Sổ đăng ký tác nhân và Agent Gateway:
- Khi Data Connector gửi lệnh gọi công cụ đi, lệnh gọi này sẽ định tuyến lưu lượng truy cập đến cổng được chỉ định trong agentGatewaySetting. Trợ lý cốt lõi tạo mã thông báo danh tính SPIFFE để xác nhận danh tính của chính mình: principal://agents.global.org-.../agents/default/core_assistant.
- Agent Gateway tích hợp với Agent Registry bằng cách sử dụng trường registries để tự động phân giải các điểm cuối đích và giản đồ công cụ đã đăng ký. Thao tác này sẽ điền sẵn các thuộc tính destination.is_registered và destination.agent_registry.*, đồng thời truyền các thuộc tính đó đến IAP phiên bản 2 để đánh giá theo các quy tắc CEL của Chính sách truy cập hợp nhất (UAP) IAM trước khi cho phép chuyển đổi vào mạng VPC.

Khả năng kết nối VPC của cổng

Agent Gateway cho phép khả năng kết nối mạng VPC riêng tư bằng cách sử dụng 2 trường YAML:

networkConfig.egress.networkAttachment: Chỉ đạo lưu lượng truy cập IP riêng tư được định tuyến thông qua tệp đính kèm mạng PSC vào mạng VPC.
dnsPeeringConfig.domains: Phân giải DNS ngang hàng với vùng DNS trên đám mây của mạng VPC để tên máy chủ đích (*.run.app) phân giải thành địa chỉ IP điểm cuối PSC riêng tư được xác định trong mạng VPC.

Giới hạn và yêu cầu

Chỉ StreamableHTTP: Cơ chế truyền Sự kiện được gửi bởi máy chủ (SSE) cũ không được hỗ trợ. Máy chủ MCP phải sử dụng StreamableHTTP.
Bắt buộc phải có TLS CA công khai: Các điểm cuối MCP phải sử dụng chứng chỉ TLS do một CA được tin cậy công khai ký, ngay cả khi được truy cập riêng tư qua PSC.
Ghi đè chính sách của tổ chức: Bạn phải ghi đè chính sách của tổ chức một cách rõ ràng đối với các kho dữ liệu MCP tuỳ chỉnh trước khi đăng ký kho dữ liệu.

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

3. Thiết lập

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

Bạn phải có các vai trò sau để hoàn tất Lớp học lập trình:

Miền	Các vai trò IAM bắt buộc
Dự án và IAM	`roles/orgpolicy.policyAdmin` `roles/resourcemanager.projectIamAdmin` `roles/iam.accessPolicyAdmin` `roles/serviceusage.serviceUsageAdmin` `roles/iam.serviceAccountUser`
Mạng và Cổng	`roles/networkservices.admin` `roles/networksecurity.admin` `roles/serviceextensions.admin` `roles/compute.networkAdmin` `roles/dns.admin`
Gemini Enterprise và Registry	`roles/discoveryengine.admin` `roles/agentregistry.admin` (hoặc `roles/apphub.admin`)
Tải công việc và bản dựng	`roles/run.admin` `roles/cloudbuild.builds.editor` `roles/artifactregistry.writer` `roles/storage.admin`
Khả năng ghi nhận	`roles/logging.viewer` `roles/logging.logWriter`

Hoặc sử dụng một vai trò cơ bản rộng như roles/owner kết hợp với roles/orgpolicy.policyAdmin (vì chỉ có roles/owner không thể sửa đổi chính sách của tổ chức).

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

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

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

Cloud Shell tại shell.cloud.google.com, hoặc
Một thiết bị đầu cuối cục bộ đã cài đặt CLI gcloud

Đặt mã dự án

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Xác thực phiên

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

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

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

echo ${SLUG}
echo ${REGION}

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

echo ${PROJ_ID}
echo ${PROJ_NO}
echo ${ORG_ID}
echo ${USER_IDENTITY}

# create resource vars for agent platform (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export UAP_POLICY_NAME="uap-policy-${SLUG}"
export UAP_BINDING_NAME="uap-binding-${SLUG}"
export MCP_NAME="math-wizard"
export MCP_URL="https://${MCP_NAME}-${PROJ_NO}.${REGION}.run.app/mcp"

echo ${AGW_NAME}
echo ${AGW_URI}
echo ${UAP_POLICY_NAME}
echo ${UAP_BINDING_NAME}
echo ${MCP_NAME}
echo ${MCP_URL}

# create resource vars for gemini enterprise (automatic)
export GE_APP_DISPLAY_NAME="Codelab app"
export GE_APP_ORG_NAME="${SLUG}, Inc."
export GE_LOCATION="global"
export GE_APP_NAME="app-${SLUG}-${GE_LOCATION}"
export GE_APP_INIT="${GE_APP_NAME}_$(date +%s)"

echo ${GE_APP_DISPLAY_NAME}
echo ${GE_APP_ORG_NAME}
echo ${GE_LOCATION}
echo ${GE_APP_NAME}
echo ${GE_APP_INIT}

Thiết lập các miền tin cậy danh tính của tác nhân

Câu lệnh if-then-else kiểm tra xem dự án có thuộc về một tổ chức hay không để đặt miền tin cậy chính xác cho danh tính của tác nhân chính.

# set var for trust domain
if [[ -n "${ORG_ID}" ]]; then
  export TRUST_DOMAIN="agents.global.org-${ORG_ID}.system.id.goog"
else
  export TRUST_DOMAIN="agents.global.proj-${PROJ_NO}.system.id.goog"
fi

echo "trust domain: ${TRUST_DOMAIN}"

Đặt dự án thanh toán và hạn mức

# set cli quota project
gcloud config set billing/quota_project ${PROJ_ID}

# set api quota project
gcloud auth application-default set-quota-project ${PROJ_ID}

Tạo thư mục cục bộ cho tệp cấu hình

# create config folder
mkdir -p cfg

Cập nhật `gcloud cli` (nên dùng)

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

# update gcloud cli
gcloud components update

Bật các dịch vụ API

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

# enable google apis (part 2)
gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  discoveryengine.googleapis.com \
  dns.googleapis.com \
  orgpolicy.googleapis.com \
  run.googleapis.com \
  saasservicemgmt.googleapis.com \
  securitycenter.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com

Chính sách của tổ chức

Các quy tắc hạn chế mặc định trong chính sách tổ chức do Google Cloud quản lý sẽ hạn chế các tính năng được dùng trong Lớp học lập trình này:

discoveryengine.managed.disableCustomMcpServerConnector:
- Hạn chế việc tạo trình kết nối dữ liệu sử dụng máy chủ MCP tuỳ chỉnh (custom_mcp) làm nguồn dữ liệu (được thực thi theo mặc định).
iam.managed.disableAccessPolicyBinding:
- Hạn chế các liên kết chính sách truy cập IAM phiên bản 3 đối với các tài nguyên (được thực thi theo mặc định).
discoveryengine.managed.allowedEgressFqdns:
- Hạn chế các miền truyền dữ liệu đi (instance_uri FQDN) cho các trình kết nối dữ liệu khi VPC Service Controls (VPC-SC) đang hoạt động hoặc dự án được liệt kê trong tham số enforcedProjects của tổ chức.
discoveryengine.managed.allowedDataSources:
- Hạn chế các loại trình kết nối dữ liệu được phép (dataSource) khi VPC-SC đang hoạt động hoặc dự án được liệt kê trong tham số enforcedProjects của tổ chức.

Ghi đè mọi quy định hạn chế của chính sách tổ chức được kế thừa ở cấp dự án bằng cách đặt enforce: false một cách rõ ràng.

Tắt chế độ ràng buộc MCP tuỳ chỉnh

# disable data connector constraint (allow custom mcp servers)
gcloud org-policies set-policy /dev/stdin << EOF
name: projects/${PROJ_NO}/policies/discoveryengine.managed.disableCustomMcpServerConnector
spec:
  rules:
  - enforce: false
EOF

# verify org policy constraint on project
gcloud org-policies describe discoveryengine.managed.disableCustomMcpServerConnector \
  --project=${PROJ_ID} --effective

Tắt chế độ hạn chế chính sách truy cập

# disable iam v3 constraint (allow v3 access policies)
gcloud org-policies set-policy /dev/stdin << EOF
name: projects/${PROJ_NO}/policies/iam.managed.disableAccessPolicyBinding
spec:
  rules:
  - enforce: false
EOF

# verify org policy constraint on project
gcloud org-policies describe iam.managed.disableAccessPolicyBinding \
  --project=${PROJ_ID} --effective

Kiểm tra và tắt các ràng buộc của trình kết nối dữ liệu có điều kiện

Theo mặc định, discoveryengine.managed.allowedEgressFqdns và discoveryengine.managed.allowedDataSources chỉ chặn việc tạo trình kết nối nếu dự án của bạn nằm trong phạm vi VPC Service Controls (VPC SC) hoặc nếu quản trị viên tổ chức đã thêm dự án của bạn vào enforcedProjects.

Trước tiên, hãy kiểm tra các chính sách có hiệu lực trong dự án của bạn:

# check effective egress fqdn constraint on project
gcloud org-policies describe discoveryengine.managed.allowedEgressFqdns \
  --project=${PROJ_ID} --effective

# check effective data source constraint on project
gcloud org-policies describe discoveryengine.managed.allowedDataSources \
  --project=${PROJ_ID} --effective

~~IF~~ các ràng buộc này được thực thi, để đảm bảo các ràng buộc này không chặn quá trình thiết lập trình kết nối custom_mcp trong một VPC SC hoặc tổ chức bị hạn chế theo chính sách, hãy đặt enforce: false trên cả hai chính sách cho dự án của bạn:

# disable egress fqdn constraint on project
gcloud org-policies set-policy /dev/stdin << EOF
name: projects/${PROJ_NO}/policies/discoveryengine.managed.allowedEgressFqdns
spec:
  rules:
  - enforce: false
EOF

# disable allowed data sources constraint on project
gcloud org-policies set-policy /dev/stdin << EOF
name: projects/${PROJ_NO}/policies/discoveryengine.managed.allowedDataSources
spec:
  rules:
  - enforce: false
EOF

# verify both constraints are disabled on project
gcloud org-policies describe discoveryengine.managed.allowedEgressFqdns \
  --project=${PROJ_ID} --effective

gcloud org-policies describe discoveryengine.managed.allowedDataSources \
  --project=${PROJ_ID} --effective

Quyền IAM

Cấp các vai trò IAM bắt buộc cho tài khoản người dùng và tài khoản dịch vụ mặc định của Compute Engine mà Cloud Build sử dụng:

Tài khoản người dùng (${USER_IDENTITY}):
- Cần có quyền triển khai và gọi các dịch vụ Cloud Run (roles/run.admin, roles/run.invoker, roles/iam.serviceAccountUser), tạo các hình ảnh vùng chứa (roles/cloudbuild.builds.editor), quản lý Gemini Enterprise (roles/discoveryengine.admin) và tạo Chính sách truy cập hợp nhất (roles/iam.accessPolicyAdmin).
Tài khoản dịch vụ mặc định của Compute Engine(${PROJ_NO}-compute@developer.gserviceaccount.com):
- Được Cloud Build dùng để dàn dựng mã nguồn trong Cloud Storage (roles/storage.admin), đẩy hình ảnh vào Artifact Registry (roles/artifactregistry.writer) và ghi nhật ký bản dựng (roles/logging.logWriter).

Thực thi các lệnh sau để chỉ định các liên kết vai trò:

# grant roles to user account
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.admin"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/run.invoker"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/discoveryengine.admin"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/iam.accessPolicyAdmin"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="user:${USER_IDENTITY}" \
  --role="roles/cloudbuild.builds.editor"

# grant roles to default compute (cloud build) service account
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:${PROJ_NO}-compute@developer.gserviceaccount.com" \
  --role="roles/logging.logWriter"

Xác minh quyền IAM

Kiểm tra 6 (6) mối liên kết vai trò trên tài khoản người dùng.

# show iam policy on project for user account
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${USER_IDENTITY}" \
  --format="table(bindings.role:label=ROLE, bindings.members:label=PRINCIPAL_IDENTITY)"

Kiểm tra 3 (3) liên kết vai trò trên tài khoản dịch vụ mặc định của Compute Engine.

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

Xác minh các liên kết của nhân viên hỗ trợ dịch vụ (thận trọng)

Trong một dự án mới, Google Cloud sẽ tự động cung cấp tác nhân dịch vụ Cổng tác nhân và cấp cho tác nhân này roles/agentgateway.serviceAgent khi networkservices.googleapis.com được bật lần đầu tiên. Nếu bạn đang sử dụng lại một dự án hiện có mà quá trình dọn dẹp trước đó có thể đã xoá các liên kết tác nhân dịch vụ mặc định, hãy chạy các lệnh sau để đảm bảo rằng danh tính và liên kết vai trò vẫn còn nguyên vẹn:

# ensure network services service account has been created
gcloud beta services identity create \
  --service=networkservices.googleapis.com \
  --project="${PROJ_ID}"

# ensure network services service account has service agent roles applied
gcloud projects add-iam-policy-binding "${PROJ_ID}" \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-agentgateway.iam.gserviceaccount.com" \
  --role="roles/agentgateway.serviceAgent"

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

4. Mạng

Trong phần này, bạn sẽ triển khai một mạng VPC bằng chế độ tuỳ chỉnh với một mạng con /28 chuyên dụng (192.168.10.0/28) hỗ trợ phần đính kèm mạng PSC để lưu lượng truy cập mạng đi ra của Agent Gateway vào mạng VPC.

Điểm cuối PSC cho các API của Google được triển khai bằng một /32địa chỉ IPv4 nội bộ toàn cầu (172.16.20.20) duy nhất để hỗ trợ quyền truy cập nội bộ riêng tư vào các API và dịch vụ của Google. Trong Lớp học lập trình này, Agent Gateway nhắm đến Cloud Run bằng cách sử dụng điểm cuối PSC bằng cách phân giải miền run.app. bằng tính năng ngang hàng Cloud DNS.

Tạo mạng

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

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

Tạo mạng con cho tệp đính kèm mạng PSC của Cổng đại lý:

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

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

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

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

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

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

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

Tạo một tệp đính kèm mạng Private Service Connect (PSC) được định cấu hình để tự động chấp nhận các kết nối từ Agent Gateway. Tệp đính kèm mạng thiết lập phía mạng VPC bên sử dụng của kết nối để liên kết an toàn với phía bên cung cấp Cổng tác nhân cho lưu lượng truy cập đi ra. Để biết thêm thông tin về các yêu cầu đối với mạng con và quy cách về dải IP, hãy xem bài viết Định cấu hình khả năng kết nối VPC.

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

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

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

Truy xuất URI tài nguyên của tệp đính kèm mạng PSC và lưu trữ URI đó trong biến môi trường PSC_NA_URI. URI này sẽ được tham chiếu trong cấu hình Agent Gateway (networkConfig.egress.networkAttachment) để cung cấp Giao diện PSC cho lưu lượng truy cập mạng đi ra vào mạng VPC:

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

Tạo điểm cuối PSC

Điểm cuối Private Service Connect (PSC) cho các API của Google được Agent Gateway dùng để thiết lập kết nối riêng tư với máy chủ MCP Cloud Run qua một đường dẫn mạng nội bộ mà không để lộ lưu lượng truy cập ra Internet công cộng. Các lệnh gọi công cụ đi ra từ Agent Gateway vào mạng VPC sẽ phân giải URL dịch vụ Cloud Run mục tiêu (*.run.app) thành địa chỉ IP điểm cuối riêng tư này.

Đặt trước một địa chỉ IPv4 nội bộ trên toàn cầu cho điểm cuối PSC. Địa chỉ IP bạn chọn phải là địa chỉ /32 và không trùng lặp với bất kỳ mạng con hiện có nào trong mạng VPC của bạn:

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

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

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

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

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

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

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

Cloud DNS được dùng để cho phép Agent Gateway giao tiếp riêng tư với máy chủ MCP được lưu trữ trên Cloud Run. Khi Agent Gateway đánh giá các yêu cầu về công cụ gửi đi nhắm đến Cloud Run, Agent Gateway sẽ sử dụng tính năng kết nối ngang hàng DNS (dnsPeeringConfig.domains) để phân giải các truy vấn DNS cho *.run.app bằng cách sử dụng vùng DNS riêng tư trên Cloud DNS được liên kết với mạng VPC của bạn. Bản ghi DNS riêng tư trả về truy vấn bằng địa chỉ IP điểm cuối PSC nội bộ (172.16.20.20), cho phép các yêu cầu của công cụ MCP được định tuyến thông qua đường dẫn mạng riêng tư.

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

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

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

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

Tạo một chính sách Cloud DNS để bật tính năng ghi nhật ký truy vấn DNS. Nhật ký DNS ghi lại các yêu cầu phân giải miền bắt nguồn từ Agent Gateway trong mạng VPC của bạn, giúp bạn có thể kiểm tra và xác minh rằng các yêu cầu của công cụ *.run.app phân giải chính xác thành điểm cuối PSC nội bộ:

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

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

5. Agent Gateway

Agent Gateway chỉ định registries cho các phiên bản Agent Registry cùng với các trường networkConfig định cấu hình chế độ cài đặt DNS và tệp đính kèm mạng PSC cho khả năng kết nối VPC riêng tư:

registries: Liên kết cổng với tối đa 2 phiên bản Agent Registry: một phiên bản theo khu vực (../locations/${REGION}) và một phiên bản trên toàn cầu (../locations/global). Thao tác này tích hợp Agent Gateway với Agent Registry để giải quyết cả việc triển khai theo khu vực (chẳng hạn như các máy chủ MCP Cloud Run trong ${REGION}) và các tài nguyên trên toàn cầu (chẳng hạn như các tác nhân Gemini Enterprise và các điểm cuối trên toàn cầu) để thực thi chính sách IAP phiên bản 2 một cách chi tiết. Các mục theo khu vực được ưu tiên hơn các mục trên toàn cầu khi phân giải URL đích.
networkAttachment: Chỉ đến tệp đính kèm mạng PSC (psc-na-${REGION}-agw), kết nối Agent Gateway vào mạng VPC của bạn để truyền dữ liệu riêng tư.
dnsPeeringConfig.domains: Định cấu hình run.app. để các truy vấn DNS bắt nguồn từ Agent Gateway cho các dịch vụ Cloud Run sử dụng tính năng ngang hàng DNS để phân giải tên máy chủ thành địa chỉ IP điểm cuối PSC của Google API riêng tư (172.16.20.20) được định cấu hình trong vùng riêng tư Cloud DNS.

Triển khai Agent Gateway

Tạo và nhập tệp cấu hình Agent Gateway.

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

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

Xác minh việc triển khai Cổng nhân viên hỗ trợ

Xác nhận cấu hình Mạng và Sổ đăng ký tác nhân:

# show agent gateway registries and network config
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION} \
  --format="yaml(registries,networkConfig)"

Kết quả đầu ra dự kiến:

networkConfig:
  dnsPeeringConfig:
    domains:
    - run.app.
    targetNetwork: projects/${PROJ_ID}/global/networks/vnet-${SLUG}
    targetProject: ${PROJ_ID}
  egress:
    networkAttachment: projects/${PROJ_ID}/regions/${REGION}/networkAttachments/psc-na-${REGION}-agw
registries:
- //agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}

Xác minh rằng đầu ra hiển thị thông tin chi tiết về cấu hình bắt buộc:

registries: Liệt kê URI của Sổ đăng ký tác nhân theo khu vực (${REGION}) được liên kết với cổng.
egress.networkAttachment: Chỉ định URI đính kèm mạng PSC cho lưu lượng truy cập ra khỏi VPC.
dnsPeeringConfig.domains: Chứa run.app. trỏ đến targetNetwork để phân giải miền riêng tư.

Kiểm tra tệp đính kèm mạng PSC để xác nhận kết nối cổng:

# show psc network attachment details
gcloud compute network-attachments describe psc-na-${REGION}-agw \
  --region=${REGION} \
  --format="yaml(connectionEndpoints)"

Kiểm tra xem có điểm cuối kết nối nào được chấp nhận hay không:

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

Uỷ quyền

Agent Gateway bảo mật và quản lý lưu lượng truy cập công cụ gửi đi bằng cách sử dụng Chính sách uỷ quyền (networksecurity.authzPolicies) được tích hợp với Chính sách truy cập hợp nhất (UAP) của Identity-Aware Proxy (IAP).

Mặc dù Agent Gateway hỗ trợ các quy tắc cơ bản ALLOW và DENY, nhưng môi trường doanh nghiệp yêu cầu quản trị tập trung, lấy danh tính làm trung tâm. Với Chính sách truy cập hợp nhất của IAM (hoặc Chính sách truy cập), bạn quản lý các quy tắc truy cập xuất bằng cách sử dụng các chính sách truy cập IAM phiên bản 3 tiêu chuẩn.

Hình 3. Cấu trúc uỷ quyền

Quy trình uỷ quyền kết nối 3 thành phần:

Chính sách uỷ quyền cổng thanh toán (authzPolicy):
- Một tài nguyên theo khu vực nhắm đến Agent Gateway.
- Được định cấu hình bằng policyProfile: REQUEST_AUTHZ và action: CUSTOM để định tuyến tất cả các lượt kiểm tra uỷ quyền đi đến Tiện ích Authz IAP.
Tiện ích dịch vụ IAP (authzExtension):
- Một tài nguyên theo khu vực uỷ quyền yêu cầu cho Identity-Aware Proxy (iap.googleapis.com).
- Đánh giá các chính sách ở chế độ ENFORCE bằng cách sử dụng phiên bản chính sách V2.
Chính sách và mối liên kết về quyền truy cập hợp nhất của IAM (accessPolicy & policyBinding):
- Tài nguyên IAM phiên bản 3 trên toàn cầu có chứa các quy tắc truy cập chi tiết.
- Xác thực danh tính chính SPIFFE của tác nhân gọi, xác minh quyền iap.googleapis.com/resources.egressViaIAP phổ biến và đánh giá các điều kiện Ngôn ngữ biểu thức thông thường (CEL) dựa trên các thuộc tính đích.

Triển khai tiện ích uỷ quyền

Tạo cấu hình tiện ích uỷ quyền service-extensions để uỷ quyền các quyết định uỷ quyền cho dịch vụ IAP:

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

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

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

Kiểm tra xem tiện ích uỷ quyền có đang hoạt động hay không:

# list authz extensions
gcloud service-extensions authz-extensions list \
  --location=${REGION} \
  --format="table(
    name.basename():label=NAME,
    createTime.date(tz=LOCAL):label=CREATED,
    updateTime.date(tz=LOCAL):label=MODIFIED,
    service:label=SERVICE,
    metadata:label=METADATA,
    timeout:label=TIMEOUT
  )"

Triển khai chính sách uỷ quyền

Tạo cấu hình chính sách uỷ quyền network-security nhắm đến Agent Gateway và uỷ quyền xác minh yêu cầu cho tiện ích uỷ quyền cho IAP:

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

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

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

Kiểm tra xem chính sách uỷ quyền có đang hoạt động hay không:

# list authz policies
gcloud network-security authz-policies list \
  --location=${REGION} \
  --format="table(
    name.basename():label=NAME,
    action:label=ACTION,
    customProvider.list().sub('\W.*', ''):label=CUSTOM_PROVIDER_TYPE,
    policyProfile:label=POLICY_PROFILE,
    customProvider.authzExtension.resources[0].basename():label=CUSTOM_PROVIDER_RESOURCE
  )"

Tạo chính sách truy cập IAM

Giờ đây, Agent Gateway uỷ quyền kiểm tra việc uỷ quyền cho IAP và phân giải siêu dữ liệu đích đến từ Agent Registry. Tiếp theo, hãy xác định một quy tắc Chính sách truy cập thống nhất IAM để điều chỉnh việc thực thi công cụ gửi đi.

IAP đánh giá biểu thức thuộc tính CEL dựa trên các thuộc tính đích của Sổ đăng ký tác nhân sau:

Trạng thái đã đăng ký (destination.is_registered):
- Giá trị Boolean (true/false) cho biết liệu đích đến có được lập danh mục trong Sổ đăng ký tác nhân hay không.
Tên máy chủ MCP (destination.agent_registry.mcp_server.name):
- Tên tài nguyên máy chủ MCP chuẩn được đăng ký trong Agent Registry.
Phương thức MCP (destination.agent_registry.mcp_server.method):
- Phương thức MCP đang được gọi (ví dụ: tools/call, tools/list, initialize).
Tên công cụ (destination.agent_registry.mcp_server.tool.name):
- Tên công cụ cụ thể được gọi (ví dụ: subtract hoặc add), cho phép uỷ quyền ở cấp công cụ, chi tiết trên các máy chủ MCP đã đăng ký.

Xác định quy tắc chính sách truy cập IAM

Tệp kê khai quy tắc chính sách IAM chỉ định:

Chủ thể: Danh tính chủ thể SPIFFE đại diện cho tác nhân trợ lý cốt lõi của Gemini Enterprise.
Quyền: Quyền iap.googleapis.com/resources.egressViaIAP chung bắt buộc đối với tất cả lưu lượng truy cập đi ra do IAP chi phối.
Điều kiện: Biểu thức CEL (destination.is_registered == true) đảm bảo rằng chỉ có thể gọi các điểm cuối được lập danh mục trong Agent Registry.

Tạo tệp kê khai quy tắc chính sách:

# create access policy rule file
cat > cfg/${UAP_POLICY_NAME}-rules.json << EOF
[
  {
    "description": "allow ge assistant to any registered service",
    "effect": "ALLOW",
    "principals": [
      "principal://${TRUST_DOMAIN}/resources/discoveryengine/projects/${PROJ_NO}/locations/global/engines/${GE_APP_INIT}/assistants/default_assistant/agents/default/core_assistant"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true"
      }
    }
  }
]
EOF

Triển khai chính sách truy cập IAM

Tạo chính sách truy cập IAM chung bằng các quy tắc được xác định trong tệp kê khai:

# create iam access policy
gcloud iam access-policies create ${UAP_POLICY_NAME} \
  --details-rules=cfg/${UAP_POLICY_NAME}-rules.json \
  --project=${PROJ_ID} \
  --location=global

Xác minh chính sách truy cập IAM

Kiểm tra để đảm bảo chính sách truy cập IAM đã được tạo thành công và kiểm tra thông tin chi tiết về quy tắc:

# show iam access policy details
gcloud iam access-policies describe ${UAP_POLICY_NAME} \
  --project=${PROJ_ID} \
  --location=global

Kết quả đầu ra dự kiến:

details:
  rules:
  - conditions:
      iap.googleapis.com:
        expression: destination.is_registered == true
    description: allow ge assistant to any registered service
    effect: ALLOW
    operation:
      permissions:
      - iap.googleapis.com/resources.egressViaIAP
    principals:
    - principal://agents.global.org-${ORG_ID}.system.id.goog/resources/discoveryengine/projects/${PROJ_NO}/locations/global/engines/${GE_APP_INIT}/assistants/default_assistant/agents/default/core_assistant
name: projects/${PROJ_ID}/locations/global/accessPolicies/${UAP_POLICY_NAME}

Liên kết chính sách truy cập IAM với dự án

Để kích hoạt việc thực thi trên tất cả Cổng tác nhân trong dự án, hãy tạo một liên kết chính sách để đính kèm chính sách truy cập IAM vào tài nguyên dự án:

# bind iam access policy to project resource
gcloud iam policy-bindings create ${UAP_BINDING_NAME} \
  --policy="projects/${PROJ_ID}/locations/global/accessPolicies/${UAP_POLICY_NAME}" \
  --target-resource="//cloudresourcemanager.googleapis.com/projects/${PROJ_ID}" \
  --project=${PROJ_ID} \
  --location=global

Xác minh việc liên kết chính sách truy cập IAM

Kiểm tra các điểm liên kết chính sách đang hoạt động với chính sách và mục tiêu phù hợp:

# show policy binding details
gcloud iam policy-bindings describe ${UAP_BINDING_NAME} \
  --project=${PROJ_ID} \
  --location=global

Kết quả đầu ra dự kiến:

name: projects/${PROJ_ID}/locations/global/policyBindings/${UAP_BINDING_NAME}
policy: projects/${PROJ_ID}/locations/global/accessPolicies/${UAP_POLICY_NAME}
policyKind: ACCESS
target:
  resource: //cloudresourcemanager.googleapis.com/projects/${PROJ_ID}

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

6. Máy chủ MCP

Trong phần này, bạn sẽ tạo một máy chủ FastMCP tuỳ chỉnh để hiển thị các công cụ add và subtract, đồng thời triển khai máy chủ đó lên Cloud Run ngay từ nguồn. Trong quá trình triển khai nguồn (--source), Cloud Build sẽ đóng gói hình ảnh vùng chứa bằng cách sử dụng Dockerfile và uv (thao tác này sẽ cài đặt các phần phụ thuộc được xác định trong pyproject.toml và khởi chạy server.py).

Sau khi triển khai dịch vụ Cloud Run, bạn sẽ đăng ký máy chủ MCP trong Agent Registry cùng với quy cách công cụ (toolspec.json) để Gemini Enterprise có thể khám phá và gọi các công cụ của máy chủ này.

Tạo ứng dụng máy chủ MCP

Tạo thư mục dự án math-wizard cho mã xử lý ứng dụng:

# create directory for code
mkdir -p math-wizard

Viết tệp kê khai dự án Python:

# create python project manifest file
cat > math-wizard/pyproject.toml << 'EOF'
[project]
name = "math-wizard"
version = "0.1.0"
description = "math wizard mcp server"
requires-python = ">=3.12"
dependencies = [
    "fastmcp==2.13.1",
]
EOF

Một số hàm đo lường bổ sung được đưa vào mã để ghi lại các tiêu đề HTTP đến (mcp-session-id, x-forwarded-for, user-agent và x-cloud-trace-context) cho hoạt động xác thực Cloud Logging và Cloud Trace.

Viết tệp mã xử lý ứng dụng:

# create mcp server application code
cat > math-wizard/server.py << 'EOF'
import asyncio
import json
import logging
import os
from fastmcp import FastMCP
from fastmcp.server.dependencies import get_http_headers
from mcp.types import ToolAnnotations

logger = logging.getLogger(__name__)
logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO)

mcp = FastMCP("math wizard mcp server")

def log_network_context(tool_name: str, a: int, b: int) -> None:
    headers = get_http_headers()
    print(json.dumps({
        "severity": "INFO",
        "message": f">>> 🛠️ Tool: '{tool_name}' called with numbers '{a}' and '{b}'",
        "tool": tool_name,
        "mcp_session_id": headers.get("mcp-session-id"),
        "x_forwarded_for": headers.get("x-forwarded-for"),
        "user_agent": headers.get("user-agent"),
        "trace_header": headers.get("x-cloud-trace-context"),
    }), flush=True)

@mcp.tool(
    annotations=ToolAnnotations(
        readOnlyHint=True,
    )
)
def add(a: int, b: int) -> int:
    """Use this to add two numbers together.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The sum of the two numbers.
    """
    logger.info(f">>> 🛠️ Tool: 'add' called with numbers '{a}' and '{b}'")
    log_network_context("add", a, b)
    return a + b

@mcp.tool(
    annotations=ToolAnnotations(
        readOnlyHint=True,
    )
)
def subtract(a: int, b: int) -> int:
    """Use this to subtract two numbers.

    Args:
        a: The first number.
        b: The second number.

    Returns:
        The difference of the two numbers.
    """
    logger.info(f">>> 🛠️ Tool: 'subtract' called with numbers '{a}' and '{b}'")
    log_network_context("subtract", a, b)
    return a - b

if __name__ == "__main__":
    logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}")
    asyncio.run(
        mcp.run_async(
            transport="streamable-http",
            host="0.0.0.0",
            port=int(os.getenv("PORT", 8080)),
        )
    )
EOF

Viết Dockerfile để xác định hướng dẫn tạo hình ảnh vùng chứa và các lệnh khởi động:

# create dockerfile
cat > math-wizard/Dockerfile << 'EOF'
# use official python 3.12 image
FROM python:3.12-slim

# install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# install the project into /app
COPY . /app
WORKDIR /app

# allow statements and log messages to immediately appear in the logs
ENV PYTHONUNBUFFERED=1

# install dependencies
RUN uv sync

EXPOSE 8080

# run the mcp server
CMD ["uv", "run", "server.py"]
EOF

Triển khai dịch vụ lên Cloud Run

Triển khai máy chủ MCP từ nguồn bằng Cloud Build (sử dụng tài khoản dịch vụ điện toán mặc định của dự án ${PROJ_NO}-compute@developer.gserviceaccount.com):

# deploy cloud run service
gcloud run deploy ${MCP_NAME} \
  --source math-wizard \
  --region=${REGION} \
  --no-invoker-iam-check \
  --ingress=internal \
  --quiet

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

Kiểm tra thông tin chi tiết về dịch vụ Cloud Run để xác minh cấu hình đang hoạt động của dịch vụ:

# show cloud run service details
gcloud run services describe ${MCP_NAME} --region=${REGION}

Kết quả đầu ra dự kiến:

<snip>
✔ Service math-wizard in region ${REGION}

URL:     https://math-wizard-${PROJ_NO}.${REGION}.run.app
Ingress: internal
Traffic:
  100% LATEST (currently math-wizard-00001-<id>)
</snip>

Đăng ký máy chủ MCP trong Sổ đăng ký tác nhân

Để Gemini Enterprise khám phá chính xác những công cụ có trên máy chủ MCP, bạn phải cung cấp một tệp thông số kỹ thuật công cụ (toolspec.json) trong quá trình đăng ký với Sổ đăng ký tác nhân.

Tạo quy cách công cụ MCP

# create tool spec file
cat > cfg/toolspec.json << 'EOF'
{
  "tools": [
    {
      "name": "add",
      "description": "Use this to add two numbers together.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "a": { "type": "integer", "description": "The first number." },
          "b": { "type": "integer", "description": "The second number." }
        },
        "required": ["a", "b"]
      },
      "isReadOnly": true,
      "isDestructive": false,
      "isIdempotent": true,
      "isOpenWorld": false
    },
    {
      "name": "subtract",
      "description": "Use this to subtract two numbers.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "a": { "type": "integer", "description": "The first number." },
          "b": { "type": "integer", "description": "The second number." }
        },
        "required": ["a", "b"]
      },
      "isReadOnly": true,
      "isDestructive": false,
      "isIdempotent": true,
      "isOpenWorld": false
    }
  ]
}
EOF

Đăng ký máy chủ MCP trong Sổ đăng ký tác nhân

# register mcp server in agent registry
gcloud agent-registry services create ${MCP_NAME} \
  --project=${PROJ_ID} \
  --location=${REGION} \
  --display-name="${MCP_NAME}-${PROJ_NO}.${REGION}.run.app" \
  --description="MANDATORY MATH & ARITHMETIC AGENT: You MUST ALWAYS invoke \
this tool for ANY mathematical calculation, addition (+), subtraction (-), \
sum, difference, or arithmetic question (including simple questions like \
'what is 67 + 345?'). NEVER compute arithmetic yourself and NEVER transfer \
math queries to file_and_coding_agent / code interpreter. Always delegate \
every math question to this tool." \
  --mcp-server-spec-type=tool-spec \
  --mcp-server-spec-content=cfg/toolspec.json \
  --interfaces=protocolBinding=JSONRPC,url="${MCP_URL}"

Xác minh máy chủ MCP trong Agent Registry

Xác minh rằng dịch vụ Cloud Run đã triển khai được liệt kê là một máy chủ MCP đã đăng ký trong khu vực cùng với URL điểm cuối và các công cụ có sẵn:

# list registered mcp servers in agent registry
gcloud agent-registry mcp-servers list \
  --location=${REGION} \
  --project=${PROJ_ID} \
  --format="table(
    name.basename():label=REGISTRY_ID,
    displayName:label=DISPLAY_NAME,
    interfaces[0].url:label=ENDPOINT_URL,
    tools[].name.list():label=TOOLS
  )"

Kết quả đầu ra dự kiến:

REGISTRY_ID                                         DISPLAY_NAME                                  ENDPOINT_URL                                              TOOLS
agentregistry-00000000-0000-0000-0012-3456789abcde  math-wizard-${PROJ_NO}.${REGION}.run.app      https://math-wizard-${PROJ_NO}.${REGION}.run.app/mcp      add,subtract

Xem quy cách cấu hình dịch vụ để biết rằng dịch vụ này đăng ký chính xác các định nghĩa công cụ, giản đồ đầu vào và chú thích hành vi cho từng công cụ:

# describe mcp server tool specs
gcloud agent-registry services describe ${MCP_NAME} \
  --location=${REGION} \
  --project=${PROJ_ID} \
  --format="yaml(mcpServerSpec.content.tools)"

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

7. Gemini Enterprise

Trong phần này, bạn sẽ tạo và định cấu hình một ứng dụng Gemini Enterprise và một tài nguyên kho lưu trữ dữ liệu MCP tuỳ chỉnh được liên kết.

Mô hình tài nguyên Discovery Engine

Ứng dụng Gemini Enterprise (được biểu thị dưới dạng tài nguyên Engine trong Discovery Engine API) là lớp điều phối trung tâm và giao diện đàm thoại cho người dùng cuối. Nền tảng này quản lý các phiên trò chuyện của người dùng, dựa trên các mô hình tạo sinh về dữ liệu doanh nghiệp và điều phối việc thực thi công cụ linh động.

Các ứng dụng Gemini Enterprise tương tác với dữ liệu và hệ thống thông qua kho dữ liệu:

Kho dữ liệu kiến thức: Nhập và lập chỉ mục nội dung tĩnh (ví dụ: Cloud Storage, Google Drive, BigQuery) để tạo thông tin tăng cường khả năng truy xuất (RAG).
Trình kết nối dữ liệu (nhà cung cấp hành động): Kết nối với API tuỳ chỉnh hoặc API linh động của bên thứ ba. Kho dữ liệu máy chủ MCP tuỳ chỉnh cung cấp các công cụ do Giao thức ngữ cảnh mô hình (MCP) xác định, cho phép mô hình gọi các hàm bên ngoài một cách linh hoạt trong cuộc trò chuyện.

Định tuyến lưu lượng truy cập đi qua Agent Gateway

Theo mặc định, Gemini Enterprise định tuyến lưu lượng truy cập thực thi công cụ và trình kết nối qua các mạng công cộng. Tuy nhiên, đối với các tải công việc VPC riêng tư và hoạt động quản trị theo nguyên tắc không tin tưởng, bạn có thể định cấu hình công cụ này để định tuyến lưu lượng truy cập đi ra thông qua Agent Gateway:

Khi tạo kho dữ liệu máy chủ MCP tuỳ chỉnh sau trong phòng thí nghiệm này, bạn sẽ bật Route egress through Agent Gateway (Định tuyến lưu lượng truy cập đi qua Cổng đại lý) trong phần cài đặt kho dữ liệu.
Thao tác này liên kết các lệnh gọi công cụ đi ra của công cụ với Agent Gateway theo khu vực của bạn, đảm bảo tất cả các yêu cầu MCP đều mang Agent Identity của ứng dụng, trải qua quá trình uỷ quyền thời gian chạy bằng cách sử dụng Chính sách truy cập hợp nhất (UAP) của IAP và IAM, đồng thời đi qua tệp đính kèm mạng PSC vào VPC riêng tư của bạn.

Tạo ứng dụng Gemini Enterprise

Phương thức sau đây sử dụng API discoveryengine.googleapis.com để tạo tài nguyên và cấu hình ứng dụng Gemini Enterprise. Để định cấu hình bằng giao diện người dùng Google Cloud Console, hãy xem phần Tạo ứng dụng để biết hướng dẫn.

# create engine (ge app)
curl -s -X POST "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines?engineId=${GE_APP_INIT}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "displayName": "${GE_APP_DISPLAY_NAME}",
  "dataStoreIds": [],
  "solutionType": "SOLUTION_TYPE_SEARCH",
  "industryVertical": "GENERIC",
  "appType": "APP_TYPE_INTRANET",
  "searchEngineConfig": {
    "searchTier": "SEARCH_TIER_ENTERPRISE",
    "searchAddOns": [
      "SEARCH_ADD_ON_LLM"
    ]
  },
  "commonConfig": {
    "companyName": "${GE_APP_ORG_NAME}"
  }
}
EOF

Xác minh việc tạo ứng dụng

# fetch engine (ge app) id
export GE_APP_ID=$(curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq -r --arg name "${GE_APP_DISPLAY_NAME}" '.engines[] | select(.displayName==$name) | .name | split("/") | last')

echo "engine (ge app) id: ${GE_APP_ID}"

Xem thông tin chi tiết về công cụ để xem cấu hình đã tạo:

# get engine (ge app) details
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

Xin lưu ý đến các thuộc tính do máy chủ điền sẵn sau đây trong phản hồi JSON:

name: Đường dẫn tài nguyên chuẩn (projects/${PROJ_NO}/locations/global/collections/default_collection/engines/${GE_APP_ID}).
sessionConfig.sessionManagementPolicy: Mặc định là "VERTEX_AI_MANAGED", duy trì trạng thái trò chuyện nhiều lượt và trạng thái gọi công cụ trong Nền tảng tác nhân (trước đây gọi là Vertex AI).
observabilityConfig.observabilityEnabled: Mặc định là true cho các chỉ số cơ sở (bạn sẽ bật tính năng ghi nhật ký chi tiết về tải trọng của công cụ và lời nhắc ở bước sau).

Bật nhà cung cấp danh tính

Bật Google Identity làm nhà cung cấp danh tính để xác thực người dùng cuối trên ứng dụng Gemini Enterprise.

Phương thức sau đây sử dụng API discoveryengine.googleapis.com để định cấu hình trình nhận dạng ứng dụng Gemini Enterprise. Để định cấu hình bằng giao diện người dùng Google Cloud Console, hãy xem phần Định cấu hình nhà cung cấp danh tính để biết hướng dẫn.

# set identity provider
curl -s -X PATCH "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/aclConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "idpConfig": {
    "idpType": "GSUITE"
  }
}
EOF

Xác minh nhà cung cấp danh tính

# show identity provider
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/aclConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

Đầu ra "idpType": "GSUITE" tương ứng với Google Identity.

(Không bắt buộc) Bật giấy phép dùng thử Gemini Enterprise

Nếu đang sử dụng một dự án đã được cấp giấy phép Gemini Enterprise, bạn có thể bỏ qua bước này. Nếu bạn đang sử dụng một dự án mới mà không có giấy phép, hãy tiếp tục và làm theo các bước sau.

Tạo một tài nguyên cấu hình giấy phép để cấp quyền sử dụng Gemini Enterprise cho người dùng trong 30 ngày. Thao tác này sẽ đặt giấy phép mặc định cho bản dùng thử mới, vì vậy, mọi người dùng đăng nhập đều được tự động cấp một chỗ:

# configure free trial subscription
curl -s -X POST "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/licenseConfigs?licenseConfigId=free_trial_gemini" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "subscriptionTier": "SUBSCRIPTION_TIER_SEARCH_AND_ASSISTANT",
  "freeTrial": true
}
EOF

Xác minh rằng giấy phép đã được áp dụng

# show license config
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/licenseConfigs/free_trial_gemini" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

Kiểm tra "subscriptionTerm": "SUBSCRIPTION_TERM_ONE_MONTH" và "freeTrial": true.

# verify auto-registration enabled on default user store
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/userStores/default_user_store" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

Kiểm tra ../free_trial_gemini" và "enableLicenseAutoRegister": true.

Bật chế độ cài đặt khả năng ghi nhận

Việc bật tính năng khả năng quan sát ở cấp ứng dụng (công cụ) Gemini Enterprise cho phép bạn xem các lượt tương tác của trợ lý cốt lõi với dữ liệu chỉ số trong Trình khám phá chỉ số và tương quan các dấu vết từ đầu đến cuối trong Cloud Trace.

# set observability on engine (ge app)
curl -s -X PATCH "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}?updateMask=observabilityConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "observabilityConfig": {
    "observabilityEnabled": true,
    "sensitiveLoggingEnabled": true
  }
}
EOF

Xác minh chế độ cài đặt về khả năng quan sát

# verify observability is enabled on engine (ge app)
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq '{observabilityConfig: .observabilityConfig}'

Kiểm tra "sensitiveLoggingEnabled": true.

Liên kết với Agent Gateway

Việc định tuyến lưu lượng truy cập đi ra từ Gemini Enterprise thông qua Agent Gateway sẽ thiết lập một ranh giới thực thi bảo mật và quản trị tập trung theo mô hình không tin cậy cho tất cả các lệnh gọi công cụ của tác nhân AI:

Thực thi chính sách tập trung: Agent Gateway hoạt động như một proxy nội tuyến, đánh giá các yêu cầu về công cụ gửi đi dựa trên các chính sách uỷ quyền và chế độ kiểm soát hoạt động quản trị trước khi lưu lượng truy cập rời khỏi môi trường của tác nhân.
Lưu lượng truy cập đi ra từ mạng riêng tư: Việc liên kết Gemini Enterprise với Agent Gateway đảm bảo các lệnh gọi công cụ nhắm đến máy chủ MCP riêng tư trên Cloud Run được định tuyến một cách an toàn thông qua Private Service Connect (PSC), bỏ qua Internet công cộng.
Khả năng kiểm tra hợp nhất: Cung cấp nhật ký yêu cầu, dữ liệu đo từ xa và nhật ký kiểm tra tập trung trên tất cả các máy chủ MCP được kết nối và công cụ bên ngoài.

Bằng cách định cấu hình agentGatewaySetting trên ứng dụng Gemini Enterprise, các lệnh gọi công cụ và lệnh gọi tác nhân đi do các truy vấn của người dùng cuối khởi tạo (chẳng hạn như các lệnh gọi đến máy chủ MCP tuỳ chỉnh được nhập từ Agent Registry và các tác nhân A2A) sẽ tự động định tuyến thông qua Agent Gateway.

Hãy vá công cụ agentGatewaySetting để bật:

# bind engine (ge app) to agent gateway
curl -s -X PATCH "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}?updateMask=agentGatewaySetting.defaultEgressAgentGateway.name" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "agentGatewaySetting": {
    "defaultEgressAgentGateway": {
      "name": "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
    }
  }
}
EOF

Xác minh mối liên kết Agent Gateway

Truy xuất cấu hình ứng dụng để xác nhận liên kết agentGatewaySetting:

# verify engine (ge app) agent gateway configuration
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq '{name: .name, displayName: .displayName, agentGatewaySetting: .agentGatewaySetting}'

Kết quả đầu ra dự kiến:

{
  "name": "projects/${PROJ_NO}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}",
  "displayName": "${GE_APP_DISPLAY_NAME}",
  "agentGatewaySetting": {
    "defaultEgressAgentGateway": {
      "name": "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
    }
  }
}

Tạo kho lưu trữ dữ liệu máy chủ MCP tuỳ chỉnh

Trong phần này, bạn sẽ kết nối máy chủ MCP với Gemini Enterprise bằng cách tạo một kho dữ liệu MCP tuỳ chỉnh.

Khi sử dụng Discovery Engine API, đây là quy trình gồm 2 bước:

Tạo (:setUpDataConnector): Tạo một tài nguyên Collection chuyên dụng (${MCP_NAME}-%timestamp-collection), đính kèm DataConnector (custom_mcp) và cung cấp DataStore hỗ trợ (..._mcp_data).
Kích hoạt (PATCH .../dataConnector?updateMask=actionConfig): Kích hoạt thời gian chạy hành động của trình kết nối (actionState: "ACTIVE") bằng cách sử dụng thông số kỹ thuật của công cụ Đăng ký tác nhân và liên kết DataStore (dataStoreIds) với Engine Gemini Enterprise của bạn.

# fetch mcp server agent registry resource name
export MCP_REGISTRY_URI=$(gcloud agent-registry mcp-servers list \
  --location=${REGION} \
  --project=${PROJ_ID} \
  --filter="displayName:${MCP_NAME}" \
  --format="value(name)")

echo "mcp registry name: ${MCP_REGISTRY_URI}"
echo "mcp url: ${MCP_URL}"

Tạo trình kết nối dữ liệu

# create custom mcp data connector from agent registry and link to engine
curl -s -X POST "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}:setUpDataConnector" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "collectionId": "${MCP_NAME}-$(date +%s)-collection",
  "collectionDisplayName": "${MCP_NAME}-collection",
  "dataConnector": {
    "dataSource": "custom_mcp",
    "dataSourceVersion": 1,
    "params": {
      "oauth_access_token": "unused"
    },
    "refreshInterval": "86400s",
    "entities": [
      {
        "entityName": "mcp_data"
      }
    ],
    "connectorModes": [
      "FEDERATED"
    ],
    "actionConfig": {
      "isActionConfigured": true,
      "createBapConnection": true,
      "actionParams": {
        "auth_type": "NO_AUTH",
        "instance_uri": "${MCP_URL}",
        "mcp_server_source": "REGISTRY_MCP",
        "registry_mcp_server_name": "${MCP_REGISTRY_URI}",
        "mcp_agent_instructions": "MANDATORY MATH & ARITHMETIC AGENT: Always invoke this tool for any mathematical calculation, addition (+), subtraction (-), sum, or difference.",
        "use_agent_gateway_egress": true,
        "agent_gateway_engine": "projects/${PROJ_ID}/locations/global/collections/default_collection/engines/${GE_APP_ID}"
      }
    }
  }
}
EOF

Xác minh việc tạo trình kết nối dữ liệu

# fetch collection id
export GE_COLLECTION_ID=$(curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq -r --arg dname "${MCP_NAME}-collection" '.collections[] | select(.displayName == $dname) | .name | split("/") | last' | head -n 1)

echo "ge collection id: ${GE_COLLECTION_ID}"

Kiểm tra xem trường "registry_mcp_server_name" có được điền sẵn UUID của Sổ đăng ký tác nhân cho máy chủ MCP hay không:

# show data connector details
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/${GE_COLLECTION_ID}/dataConnector" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq '{name, state, actionState, connectorModes, bapConfig, registry_mcp_server_name: .actionConfig.actionParams.registry_mcp_server_name}'

Xem mục đăng ký máy chủ MCP trong giao diện người dùng Google Cloud Console:

echo "mcp server registry page url: https://console.cloud.google.com/agent-platform/agent-registry/mcp-servers/${REGION}/${MCP_REGISTRY_URI##*/}/overview?project=${PROJ_ID}"

Kích hoạt trình kết nối dữ liệu

# activate and bind data connector
curl -s -X PATCH "https://discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/global/collections/${GE_COLLECTION_ID}/dataConnector?updateMask=actionConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "name": "projects/${PROJ_ID}/locations/global/collections/${GE_COLLECTION_ID}/dataConnector",
  "actionConfig": {
    "isActionConfigured": true,
    "createBapConnection": true,
    "actionParams": {
      "auth_type": "NO_AUTH",
      "instance_uri": "${MCP_URL}",
      "mcp_server_source": "REGISTRY_MCP",
      "registry_mcp_server_name": "${MCP_REGISTRY_URI}",
      "mcp_agent_instructions": "MANDATORY MATH & ARITHMETIC AGENT: Always invoke this tool for any mathematical calculation, addition (+), subtraction (-), sum, or difference.",
      "use_agent_gateway_egress": true,
      "agent_gateway_engine": "projects/${PROJ_ID}/locations/global/collections/default_collection/engines/${GE_APP_ID}"
    }
  }
}
EOF

Xác minh các mối liên kết máy chủ MCP tuỳ chỉnh

# show engine (ge app) details
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq '{name: .name, dataStoreIds: .dataStoreIds, agentGatewaySetting: .agentGatewaySetting}'

Kiểm tra kho dữ liệu được liên kết "dataStoreIds": "collection-math-wizard-_mcp_data".

# show collection details
curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  | jq --arg app "${GE_APP_ID}" '.collections[] | select(.dataConnector.actionConfig.actionParams.agent_gateway_engine // "" | endswith($app)) | .dataConnector | {name: .name, state: .state, actionState: .actionState, connectorModes: .connectorModes, actionParams: .actionConfig.actionParams}'

Kiểm tra "state": "ACTIVE" khi tất cả các tham số được điền sẵn.

Thao tác đối với công cụ

Khi kiểm tra kho dữ liệu math-wizard-collection trong trang tổng quan Gemini Enterprise, bạn sẽ nhận thấy rằng thẻ Actions (Hành động) không được dùng và nút ↻ Reload custom actions (Tải lại hành động tuỳ chỉnh) bị vô hiệu hoá. Đây là hành vi dự kiến.

Xem trang thông tin chi tiết về kho dữ liệu trong giao diện người dùng Google Cloud Console:

echo "data store details page url: https://console.cloud.google.com/gemini-enterprise/locations/${GE_LOCATION}/collections/${GE_COLLECTION_ID}/connector/details?project=${PROJ_ID}"

Tuỳ thuộc vào cách bạn kết nối máy chủ MCP tuỳ chỉnh với Gemini Enterprise, quá trình khám phá và quản trị công cụ sẽ được xử lý theo một trong hai cách sau:

MCP tuỳ chỉnh trực tiếp (BYO_MCP quy trình ): Khi bạn định cấu hình một máy chủ MCP tuỳ chỉnh ngay trong Gemini Enterprise mà không cần Agent Registry, kho dữ liệu sẽ tự quản lý danh mục công cụ (connectorModes: ["FEDERATED", "ACTIONS"]). Bạn phải mở thẻ Hành động, nhấp vào ↻ Tải lại các hành động tuỳ chỉnh để tìm nạp giản đồ tools/list và bật hoặc tắt từng công cụ (add và subtract) theo cách thủ công trong giao diện người dùng.
Nhập Sổ đăng ký tác nhân (REGISTRY_MCP quy trình được dùng trong lớp học lập trình này): Khi bạn nhập một máy chủ MCP từ Sổ đăng ký tác nhân, Sổ đăng ký tác nhân sẽ đóng vai trò là nguồn thông tin chính xác cho điểm cuối MCP, siêu dữ liệu giao diện và danh mục công cụ (connectorModes: ["FEDERATED"]). Gemini Enterprise tự động bật các công cụ MCP đã đăng ký trong thời gian chạy thông qua Cổng tác nhân của công cụ mà không yêu cầu bạn tải lại hoặc bật/tắt các thao tác theo cách thủ công trong giao diện người dùng kho dữ liệu.

Đến đây là kết thúc phần ứng dụng Gemini Enterprise... tiếp theo là phần Xác thực.

8. Xác thực

Trong phần này, bạn sẽ kích hoạt các lệnh gọi công cụ MCP trực tiếp từ ứng dụng web Gemini Enterprise và theo dõi luồng yêu cầu trên Agent Gateway, Cloud DNS, tường lửa VPC và nhật ký Cloud Run. Sau đó, bạn sẽ thắt chặt Chính sách truy cập hợp nhất IAM để cho phép subtract trong khi chặn add, xác minh việc thực thi mô hình không tin tưởng tại cổng.

Quyền truy cập của người dùng

Tạo URL cho ứng dụng web Gemini Enterprise:

# fetch app user url
export GE_WIDGET_ID=$(curl -s "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}/widgetConfigs/default_search_widget_config" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  -H "Content-Type: application/json" \
  | jq -r '.configId')

export GE_APP_USER_URL="https://vertexaisearch.cloud.google.com/home/cid/${GE_WIDGET_ID}"

echo "app user url: ${GE_APP_USER_URL}"

Truy cập vào đường liên kết để mở giao diện trò chuyện của ứng dụng web Gemini Enterprise trong trình duyệt rồi nhấp vào Bắt đầu.

Kiểm thử các câu hỏi của tác nhân trong cuộc trò chuyện

Trong giao diện người dùng trò chuyện, hãy xác nhận rằng trình kết nối dữ liệu math-wizard-collection đã được bật bằng cách nhấp vào biểu tượng mảnh ghép cho Trình kết nối ở cuối hộp trò chuyện. Bạn sẽ thấy một nút bật/tắt xuất hiện (có màu).

Hãy thử các cụm từ tìm kiếm kiểm thử sau:

what is 2342345 - 98234798324?

what is 72347234 + 234234?

Xác minh rằng trợ lý trả về câu trả lời chính xác và hiển thị một huy hiệu trích dẫn hành động có tính tương tác (chẳng hạn như Math Calculation (8s) 🤖 Agentgateway Agent) bên dưới mỗi câu trả lời, xác nhận rằng công cụ đã được thực thi.

Kiểm tra nhật ký trong Cloud Logging

Xác minh rằng Gemini Enterprise đã định tuyến các lệnh gọi công cụ thông qua Agent Gateway và mạng VPC riêng tư bằng cách kiểm tra nhật ký trong Cloud Logging.

1. Xác minh việc uỷ quyền cho Agent Gateway và IAP

Xác nhận rằng Agent Gateway đã chặn yêu cầu, phân giải mục tiêu trong Agent Registry, uỷ quyền cho IAP và cho phép lệnh gọi công cụ:

# show agent gateway logs
gcloud logging read 'resource.type="networkservices.googleapis.com/Gateway"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    httpRequest.serverIp:label=SERVER_IP, \
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD, \
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    jsonPayload.agentGatewayInfo.agentRegistryResource.basename():label=REGISTRY_MCP
  )"

Xác minh rằng đầu ra chứa:

STATUS: 200 (thực thi thành công) và 202 (bắt tay notifications/initialized).
SERVER_IP: IP điểm cuối PSC của Các API của Google (172.16.20.20:443).
MCP_METHOD và TOOL: Trình tự giao thức MCP (notifications/initialized, tools/list và tools/call với add hoặc subtract).
AUTHZ: ALLOWED (cho phép uỷ quyền IAP).
REGISTRY_MCP: Mã nhận dạng tài nguyên đã phân giải của Sổ đăng ký tác nhân (agentregistry-...).

2. Xác minh quá trình chuyển tiếp DNS và tường lửa

Xác nhận rằng Cloud DNS đã phân giải tên máy chủ thành điểm cuối PSC và tường lửa cho phép lưu lượng truy cập từ giao diện Cổng đại lý:

# show dns logs
gcloud logging read 'resource.type="dns_query"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    jsonPayload.queryName:label=QUERY_NAME, \
    jsonPayload.queryType:label=TYPE, \
    jsonPayload.responseCode:label=RCODE, \
    jsonPayload.rdata:label=RDATA
  )"

# show firewall logs
gcloud logging read 'logName:"compute.googleapis.com%2Ffirewall"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    jsonPayload.connection.src_ip:label=SRC_IP, \
    jsonPayload.connection.dest_ip:label=DEST_IP, \
    jsonPayload.connection.dest_port:label=PORT, \
    jsonPayload.rule_details.reference.basename():label=RULE, \
    jsonPayload.disposition:label=DISPOSITION
  )"

Xác minh các giá trị sau:

DNS QUERY_NAME và RDATA: Phân giải math-wizard-...run.app. (bản ghi A, NOERROR) thành 172.16.20.20.
Tường lửa SRC_IP và DEST_IP: 192.168.10.2 (IP giao diện PSC của Cổng tác nhân) đến 172.16.20.20:443.
Tường lửa RULE và DISPOSITION: firewallPolicy:fw-policy-... đã được ghép với ALLOWED.

3. Xác minh việc thực thi công cụ Cloud Run

Xác nhận rằng vùng chứa Cloud Run đã nhận và xử lý lệnh gọi công cụ:

# show cloud run logs
gcloud logging read 'resource.type="cloud_run_revision"
  AND textPayload:"Tool:"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="value(timestamp.date(tz=LOCAL), textPayload)"

Xác minh rằng textPayload hiển thị các mục thực thi công cụ (ví dụ: >>> 🛠️ Tool: 'subtract' called with numbers '[x]' and '[y]').

Kiểm thử việc thực thi chính sách đặc quyền tối thiểu

Trong chính sách truy cập IAM ban đầu, mọi phương thức hoặc công cụ đều được phép miễn là đích đến đã được đăng ký (destination.is_registered == true). Trong bước này, hãy cập nhật chính sách để thực thi đặc quyền tối thiểu bằng cách chỉ cho phép công cụ subtract trong khi chặn add.

Cập nhật chính sách truy cập IAM

Khi hạn chế việc thực thi công cụ MCP, hãy sử dụng mẫu hai quy tắc:

Quy tắc 1 (Phát hiện và bắt tay MCP): Cho phép các phương thức vòng đời MCP không phải là lệnh gọi công cụ (destination.is_registered == true và destination.agent_registry.mcp_server.method != 'tools/call'). Vì Gemini Enterprise thương lượng việc thiết lập luồng và phát hiện (initialize, notifications/initialized, tools/list) trước khi gọi một công cụ và destination.agent_registry.mcp_server.tool.name chỉ được điền sẵn trong tools/call, nên Quy tắc 1 là cần thiết để duy trì hoạt động khởi tạo phiên và phát hiện danh mục.
Quy tắc 2 (Hạn chế ở cấp công cụ): Hạn chế việc thực thi tools/call để chỉ cho phép công cụ subtract (destination.is_registered == true, destination.agent_registry.mcp_server.method == 'tools/call' và destination.agent_registry.mcp_server.tool.name == 'subtract').

Cập nhật tệp kê khai quy tắc chính sách truy cập bằng cả hai quy tắc:

# create access policy rule file (update: allow subtract only)
cat > cfg/${UAP_POLICY_NAME}-rule-update.json << EOF
[
  {
    "description": "allow ge assistant to any registered endpoint to perform mcp discovery and handshake",
    "effect": "ALLOW",
    "principals": [
      "principal://${TRUST_DOMAIN}/resources/discoveryengine/projects/${PROJ_NO}/locations/global/engines/${GE_APP_ID}/assistants/default_assistant/agents/default/core_assistant"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true && \
         destination.agent_registry.mcp_server.method != 'tools/call'"
      }
    }
  },
  {
    "description": "allow ge assistant to any registered mcp server with tool call subtract",
    "effect": "ALLOW",
    "principals": [
      "principal://${TRUST_DOMAIN}/resources/discoveryengine/projects/${PROJ_NO}/locations/global/engines/${GE_APP_ID}/assistants/default_assistant/agents/default/core_assistant"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true && \
         destination.agent_registry.mcp_server.method == 'tools/call' && \
         destination.agent_registry.mcp_server.tool.name == 'subtract'"
      }
    }
  }
]
EOF

Áp dụng các quy tắc mới cập nhật cho chính sách truy cập IAM:

# update iam access policy
gcloud iam access-policies update ${UAP_POLICY_NAME} \
  --details-rules=cfg/${UAP_POLICY_NAME}-rule-update.json \
  --project=${PROJ_ID} \
  --location=global

Xác minh chính sách truy cập IAM

Kiểm tra xem chính sách truy cập IAM mới đã được áp dụng và chỉ công cụ trừ được cho phép:

# show iam access policy details
gcloud iam access-policies describe ${UAP_POLICY_NAME} \
  --project=${PROJ_ID} \
  --location=global \
  --flatten="details.rules[]" \
  --format="table( \
    details.rules.principals[0].scope(engines).sub('assistants/default_assistant/agents/default', '...'):label=PRINCIPAL, \
    details.rules.effect:label=EFFECT, \
    details.rules.conditions.'iap.googleapis.com'.expression.sub('\s*&&\s*', '\n&& ').sub('\s*\|\|\s*', '\n|| '):label=EXPRESSION
  )"

Kiểm thử một lệnh gọi công cụ bị cấm

Quay lại giao diện người dùng trò chuyện của ứng dụng web Gemini Enterprise rồi thử một câu hỏi kiểm thử khác:

what is 100 plus 20?

Trợ lý cố gắng gọi add, nhưng Agent Gateway và IAP đánh giá điều kiện chính sách IAM là false và từ chối yêu cầu truyền dữ liệu ra ngoài bằng HTTP 403 Forbidden. Trong giao diện người dùng trò chuyện, bạn sẽ thấy trợ lý hiển thị biểu tượng Calculate Sum và xoay biểu tượng 🤖 Agentgateway Agent ... Working on it. khi trợ lý thử lại lệnh gọi công cụ bị chặn. Đây là hành vi dự kiến. Điều này xác nhận rằng Agent Gateway và IAP đang chủ động chặn và từ chối việc thực thi công cụ không được phép ở cấp độ mạng.

Kiểm tra lại nhật ký trong Cloud Logging

Xem các mục nhật ký Agent Gateway và lưu ý các mục 403 mới tương ứng với lệnh gọi công cụ add không được phép:

# show agent gateway logs
gcloud logging read 'resource.type="networkservices.googleapis.com/Gateway"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="table( \
    timestamp.date(tz=LOCAL):label=TIMESTAMP, \
    httpRequest.status:label=STATUS, \
    httpRequest.serverIp:label=SERVER_IP, \
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD, \
    jsonPayload.agentGatewayInfo.mcpInfo.parameter:label=TOOL, \
    jsonPayload.authzPolicyInfo.result:label=AUTHZ, \
    jsonPayload.agentGatewayInfo.agentRegistryResource.basename():label=REGISTRY_MCP
  )"

Kết quả đầu ra dự kiến:

TIMESTAMP            STATUS  SERVER_IP         MCP_METHOD                 TOOL  AUTHZ    REGISTRY_MCP
YYYY-MM-DDTHH:MM:SS  403                       tools/call                 add   DENIED   agentregistry-00000000-0000-0000-0012-3456789abcde
YYYY-MM-DDTHH:MM:SS  403
YYYY-MM-DDTHH:MM:SS  202     172.16.20.20:443  notifications/initialized        ALLOWED  agentregistry-00000000-0000-0000-0012-3456789abcde
YYYY-MM-DDTHH:MM:SS          172.16.20.20:443                                   ALLOWED  agentregistry-00000000-0000-0000-0012-3456789abcde
YYYY-MM-DDTHH:MM:SS  200     172.16.20.20:443  initialize                       ALLOWED  agentregistry-00000000-0000-0000-0012-3456789abcde

Kiểm tra để đảm bảo rằng yêu cầu bổ sung không bao giờ đến được phần phụ trợ Cloud Run:

# show cloud run logs
gcloud logging read 'resource.type="cloud_run_revision"
  AND textPayload:"Tool:"' \
  --project=${PROJ_ID} \
  --limit=5 \
  --format="value(timestamp.date(tz=LOCAL), textPayload)"

Lệnh này không trả về mục nhập mới nào, xác nhận rằng Agent Gateway đã thực thi thành công chính sách truy cập IAM.

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

9. Dọn dẹp

Làm theo các bước sau để xoá các tài nguyên và cấu hình đã tạo trong phòng thí nghiệm này.

Xoá các thành phần của Gemini Enterprise

# delete gemini enterprise engine (app)
curl -s -X DELETE "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/default_collection/engines/${GE_APP_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

# delete custom mcp collection, data connector, and backing data store
curl -s -X DELETE "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1alpha/projects/${PROJ_ID}/locations/${GE_LOCATION}/collections/${GE_COLLECTION_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}"

# reset identity provider configuration
curl -s -X PATCH "https://${GE_LOCATION}-discoveryengine.googleapis.com/v1/projects/${PROJ_ID}/locations/${GE_LOCATION}/aclConfig" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: ${PROJ_ID}" \
  -H "Content-Type: application/json" \
  -d '{"idpConfig":{"idpType":"IDP_TYPE_UNSPECIFIED"}}'

Xoá các thành phần máy chủ MCP

# delete agent registry service
gcloud -q agent-registry services delete ${MCP_NAME} \
  --location=${REGION} \
  --project=${PROJ_ID}

# delete cloud run service, source-deploy artifact registry repo, and staging bucket
gcloud -q run services delete ${MCP_NAME} \
  --region=${REGION} \
  --project=${PROJ_ID}

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

gcloud -q storage rm --recursive gs://run-sources-${PROJ_ID}-${REGION} \
  --project=${PROJ_ID}

Xoá Cổng tác nhân và các chính sách truy cập IAM

# delete gateway authorization policy, iap extension, and agent gateway
gcloud -q network-security authz-policies delete ${AGW_NAME}-authz-policy-iap \
  --location=${REGION} \
  --project=${PROJ_ID}

gcloud -q service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap \
  --location=${REGION} \
  --project=${PROJ_ID}

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

# delete iam policy binding and access policy
gcloud -q iam policy-bindings delete ${UAP_BINDING_NAME} \
  --location=global \
  --project=${PROJ_ID}

gcloud -q iam access-policies delete ${UAP_POLICY_NAME} \
  --location=global \
  --project=${PROJ_ID}

Xoá các thành phần DNS và tường lửa

# delete dns record set, managed zone, and policy
gcloud -q dns record-sets delete "*.run.app." \
  --type=A \
  --zone=priv-zone-run \
  --project=${PROJ_ID}

gcloud -q dns managed-zones delete priv-zone-run \
  --project=${PROJ_ID}

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

gcloud -q dns policies delete dns-policy-${SLUG} \
  --project=${PROJ_ID}

# delete firewall policy association, rule, and policy
gcloud -q compute network-firewall-policies associations delete \
  --name=fw-policy-bind-${SLUG} \
  --firewall-policy=fw-policy-${SLUG} \
  --global-firewall-policy \
  --project=${PROJ_ID}

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

gcloud -q compute network-firewall-policies delete fw-policy-${SLUG} \
  --global \
  --project=${PROJ_ID}

Xoá các thành phần PSC và mạng VPC

# delete psc forwarding rule and internal ip address
gcloud -q compute forwarding-rules delete psc2gapis \
  --global \
  --project=${PROJ_ID}

gcloud -q compute addresses delete ip-psc2gapis \
  --global \
  --project=${PROJ_ID}

# delete psc network attachment, subnet, and vpc network
gcloud -q compute network-attachments delete psc-na-${REGION}-agw \
  --region=${REGION} \
  --project=${PROJ_ID}

gcloud -q compute networks subnets delete subnet-${REGION}-agw \
  --region=${REGION} \
  --project=${PROJ_ID}

gcloud -q compute networks delete vnet-${SLUG} \
  --project=${PROJ_ID}

Xoá các chế độ ghi đè chính sách của tổ chức và tệp cục bộ

# delete project-level organization policy overrides
gcloud -q org-policies delete discoveryengine.managed.disableCustomMcpServerConnector --project=${PROJ_ID}
gcloud -q org-policies delete iam.managed.disableAccessPolicyBinding --project=${PROJ_ID}

# remove local project files
rm -rf cfg math-wizard

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

10. Kết luận

Xin chúc mừng! Bạn đã xây dựng một cấu trúc toàn diện cho phép ứng dụng Gemini Enterprise khám phá và gọi các công cụ một cách an toàn trên máy chủ MCP tuỳ chỉnh riêng tư:

Máy chủ MCP tuỳ chỉnh và Sổ đăng ký tác nhân: Triển khai một dịch vụ FastMCP riêng tư trên Cloud Run (--ingress=internal) và đăng ký điểm cuối cũng như giản đồ công cụ (add và subtract) của dịch vụ đó trong Sổ đăng ký tác nhân.
Tích hợp Gemini Enterprise: Cung cấp một ứng dụng Gemini Enterprise, liên kết lưu lượng truy cập công cụ đi ra với Agent Gateway và đính kèm máy chủ MCP đã đăng ký làm trình kết nối dữ liệu REGISTRY_MCP.
Lưu lượng truy cập đi ra từ VPC riêng tư và hoạt động quản trị dựa trên nguyên tắc không tin tưởng: Thực thi công cụ được định tuyến một cách riêng tư qua PSC (172.16.20.20) và thực thi đặc quyền tối thiểu ở cấp công cụ bằng cách sử dụng IAP và Chính sách truy cập hợp nhất IAM (destination.agent_registry.*).

cosmopup

Cosmpup cho rằng Codelabs là một nền tảng tuyệt vời!

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

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

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

Cảm ơn bạn!

Gemini Enterprise có cổng ra Agent Gateway đến máy chủ MCP tuỳ chỉnh riêng tư bằng cách sử dụng Agent Registry

1. Giới thiệu

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

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

Bạn cần có

2. Khái niệm

Trình tự triển khai

Dữ liệu đầu ra của Gemini Enterprise

Khả năng kết nối VPC của cổng

Giới hạn và yêu cầu

3. Thiết lập

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

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

Đặt mã dự án

Xác thực phiên

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

Thiết lập các miền tin cậy danh tính của tác nhân

Đặt dự án thanh toán và hạn mức

Tạo thư mục cục bộ cho tệp cấu hình

Cập nhật gcloud cli (nên dùng)

Bật các dịch vụ API

Chính sách của tổ chức

Tắt chế độ ràng buộc MCP tuỳ chỉnh

Tắt chế độ hạn chế chính sách truy cập

Kiểm tra và tắt các ràng buộc của trình kết nối dữ liệu có điều kiện

Quyền IAM

Xác minh quyền IAM

Xác minh các liên kết của nhân viên hỗ trợ dịch vụ (thận trọng)

4. Mạng

Tạo mạng

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

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

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

Tạo điểm cuối PSC

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

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

5. Agent Gateway

Triển khai Agent Gateway

Xác minh việc triển khai Cổng nhân viên hỗ trợ

Uỷ quyền

Triển khai tiện ích uỷ quyền

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

Triển khai chính sách uỷ quyền

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

Tạo chính sách truy cập IAM

Xác định quy tắc chính sách truy cập IAM

Triển khai chính sách truy cập IAM

Xác minh chính sách truy cập IAM

Liên kết chính sách truy cập IAM với dự án

Xác minh việc liên kết chính sách truy cập IAM

6. Máy chủ MCP

Tạo ứng dụng máy chủ MCP

Triển khai dịch vụ lên Cloud Run

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

Đăng ký máy chủ MCP trong Sổ đăng ký tác nhân

Tạo quy cách công cụ MCP

Đăng ký máy chủ MCP trong Sổ đăng ký tác nhân

Xác minh máy chủ MCP trong Agent Registry

7. Gemini Enterprise

Mô hình tài nguyên Discovery Engine

Định tuyến lưu lượng truy cập đi qua Agent Gateway

Tạo ứng dụng Gemini Enterprise

Xác minh việc tạo ứng dụng

Bật nhà cung cấp danh tính

Xác minh nhà cung cấp danh tính

(Không bắt buộc) Bật giấy phép dùng thử Gemini Enterprise

Xác minh rằng giấy phép đã được áp dụng

Bật chế độ cài đặt khả năng ghi nhận

Xác minh chế độ cài đặt về khả năng quan sát

Liên kết với Agent Gateway

Xác minh mối liên kết Agent Gateway

Tạo kho lưu trữ dữ liệu máy chủ MCP tuỳ chỉnh

Tạo trình kết nối dữ liệu

Xác minh việc tạo trình kết nối dữ liệu

Kích hoạt trình kết nối dữ liệu

Xác minh các mối liên kết máy chủ MCP tuỳ chỉnh

Thao tác đối với công cụ

8. Xác thực

Quyền truy cập của người dùng

Kiểm thử các câu hỏi của tác nhân trong cuộc trò chuyện

Cập nhật `gcloud cli` (nên dùng)