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

Dữ liệu truyền ra của Agent Gateway từ Agent Runtime đến Google MCP

1. Giới thiệu

Lớp học lập trình này khám phá hoạt động quản trị lưu lượng truy cập đi ra của Cổng tác nhân cho các tác nhân AI truy cập vào các máy chủ Giao thức ngữ cảnh mô hình (MCP) từ xa của Google Cloud.

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

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

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

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

Agent Gateway ở chế độ truyền dữ liệu ra (agent-to-anywhere)
Tiện ích uỷ quyền Identity-Aware Proxy (IAP)
Tác nhân ADK Thời gian chạy của tác nhân có danh tính của tác nhân
Sổ đăng ký tác nhân có API của Google và các điểm cuối MCP
Chính sách uỷ quyền có tính năng kiểm soát quyền truy cập IAM
Tập dữ liệu BigQuery để truy vấn bằng MCP

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

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

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

Bạn cần có

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

2. Khái niệm

Trình tự triển khai

Khi triển khai Agent Gateway bằng các chế độ kiểm soát hoạt động quản trị, bạn cần tuân theo một trình tự cấu hình có cấu trúc để các tác nhân có quyền truy cập vào các tài nguyên cần thiết khi khởi tạo và các yêu cầu mạng sẽ thành công.

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

Bắt đầu ở chế độ chạy thử: Nếu bạn định cấu hình một thời gian chạy của tác nhân để định tuyến các cuộc gọi đi đến cổng trước khi cổng được cung cấp đầy đủ, thì tải sẽ không khởi động được. Trước tiên, việc định cấu hình tiện ích uỷ quyền cổng ở chế độ DRY_RUN đảm bảo rằng khi lưu lượng truy cập của tác nhân đến cổng, không có yêu cầu nào bị loại bỏ.
Đăng ký tất cả các dịch vụ: Tất cả các tác nhân, máy chủ MCP và điểm cuối sử dụng Agent Gateway đều phải được đăng ký trong Agent Registry. Yêu cầu sẽ bị từ chối đối với mọi nguồn hoặc đích đến chưa đăng ký. Các tác nhân được triển khai trên Agent Runtime và máy chủ Google MCP sẽ tự động đăng ký. Bạn phải đăng ký thủ công mọi điểm cuối API của Google hoặc máy chủ MCP tuỳ chỉnh.
Thực thi các chính sách uỷ quyền: Các chính sách uỷ quyền được dùng để cho phép các tác nhân đã đăng ký truy cập vào các thành phần dựa trên tác nhân bằng cách cấp vai trò roles/iap.egressor cho đối tượng chính là danh tính của tác nhân và liên kết đối tượng đó với tài nguyên đích của sổ đăng ký. Đánh giá hành vi của tác nhân bằng chế độ chạy thử, sau đó xác định các chính sách để cho phép lưu lượng truy cập xuất cảnh đã chọn đi qua cổng. Sau khi các chính sách được áp dụng, hãy chuyển sang chế độ ENFORCED để cho phép cổng chủ động thực thi các chính sách quản trị.

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

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

Cổng thường quản lý lưu lượng truy cập đến (đầu vào) cho các dịch vụ phụ trợ. Agent Gateway, hoạt động ở chế độ truyền dữ liệu ra (agent-to-anywhere), đóng vai trò là một proxy đi ra tập trung, không tin cậy cho các khối lượng công việc dựa trên tác nhân.

Khi một ứng dụng AI hoặc khối lượng công việc dựa trên tác nhân cố gắng gọi một công cụ hoặc API bên ngoài, yêu cầu gửi đi sẽ bị Agent Gateway chặn và đánh giá dựa trên các chính sách quản trị trước khi được định tuyến đến đích đến:

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

Hình 3. Cấu trúc liên kết định tuyến truyền dữ liệu ra bên ngoài của Agent Gateway

Lớp học lập trình này tập trung vào lưu lượng truy cập đi từ một tác nhân tuỳ chỉnh trên Agent Runtime nhắm đến điểm cuối máy chủ MCP từ xa của Google cho BigQuery.

3. Thiết lập

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

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

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

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

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

Lớp học lập trình này sử dụng một dự án 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 dòng lệnh cục bộ đã cài đặt gcloud CLI

Đặt mã dự án

gcloud config set project SET_YOUR_PROJECT_ID_HERE

Xác thực phiên

# login to gcloud cli
gcloud auth login

# login for gcloud api
gcloud auth application-default login

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

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

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

# create resource vars (automatic)
export AGW_NAME="agw-${SLUG}-${REGION}-ata"
export AGW_URI="projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
export RE_AGENT_NAME="agent-dj"
export RE_AGENT_ID_SET="principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJ_NO}"
export STAGING_BUCKET="agent-staging-${PROJ_NO}"
echo ${AGW_NAME}
echo ${AGW_URI}
echo ${RE_AGENT_NAME}
echo ${RE_AGENT_ID_SET}
echo ${STAGING_BUCKET}

# create local dir for config files
mkdir -p cfg

Bật dịch vụ API

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

# enable google apis (agent platform bundle, part 2)
gcloud services enable \
  securitycenter.googleapis.com \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  discoveryengine.googleapis.com

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

4. Cổng

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

Ở đây, Agent Gateway sử dụng một sổ đăng ký theo khu vực để hỗ trợ các tài nguyên Agent Runtime theo khu vực.

Tạo cổng

# create agent gateway config file (regional registry)
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJ_ID}/locations/${REGION}"
EOF

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

# show agent gateway details (verify deployment state)
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

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

5. Ủy quyền

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

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

Tiện ích uỷ quyền

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

# create authz extension config file (dry run mode)
cat > cfg/${AGW_NAME}-svc-ext-authz-iap-dryrun.yaml << EOF
name: ${AGW_NAME}-svc-ext-authz-iap-dryrun
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

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

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

Chính sách ủy quyền

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

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

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

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

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

Đến đây là kết thúc phần uỷ quyền... tiếp theo là phần toàn bộ mã nguồn.

6. Toàn bộ mã nguồn

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

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

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

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

# copy agent runtime and endpoint definitions to working project dir
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/agent-dj ./agent-dj
cp -r temp_agw_cuj_arun_egress_gmcp/codelabs/agw-cuj-arun-egress-gmcp/endpoints ./endpoints

# remove temporary directory
rm -rf temp_agw_cuj_arun_egress_gmcp

Tạo tập dữ liệu BigQuery

# create bq dataset schema and load data
bq --project_id=${PROJ_ID} query \
  --use_legacy_sql=false < agent-dj/setup.sql

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

# create storage bucket for agent deployment artifacts
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

# verify staging bucket url
gcloud storage buckets list --format="value(storage_url)"

Đến đây là kết thúc phần toàn bộ mã nguồn... tiếp theo là phần Registry (Sổ đăng ký).

7. Đăng ký

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

Để khởi động môi trường và hỗ trợ các tác nhân bằng nhiều API và Dịch vụ của Google, một tập lệnh được dùng để nhanh chóng đăng ký một nhóm điểm cuối API chung bằng cách sử dụng tên máy chủ và vị trí từ endpoints/googleapis.txt.

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

# run python script to register google api endpoints
python3 endpoints/register_endpoints.py \
  --multi-region=${MREGION} \
  --region=${REGION} \
  --mtls-endpoints=include

Xác minh điểm cuối

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

Đến đây là kết thúc phần đăng ký... tiếp theo là phần Thời gian chạy.

8. Thời gian chạy

agent-dj ADK Agent được triển khai cho Agent Runtime được định cấu hình bằng các chế độ cài đặt sau trong tập lệnh triển khai để tích hợp với Agent Platform:

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

Triển khai tác nhân

# deploy agent runtime workload
uv --directory agent-dj run python3 deploy_agent.py \
  --project=${PROJ_ID} \
  --region=${REGION} \
  --src-dir=./agent \
  --staging-bucket=${STAGING_BUCKET} \
  --display-name="${RE_AGENT_NAME}" \
  --description="agent for dj contact info" \
  --enable-telemetry \
  --enable-agent-identity \
  --agent-gateway-egress=${AGW_URI} \
  --allow-token-sharing

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

# fetch agent runtime resource (reasoning engine) id
export RE_ENGINE_ID=$(curl -s -X GET \
  "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" | \
  jq -r --arg name "${RE_AGENT_NAME}" \
  '.reasoningEngines[] | select(.displayName==$name) | .name | split("/") | last')
echo ${RE_ENGINE_ID}

# fetch agent runtime (reasoning engine) agent identity
export RE_AGENT_IDENTITY=$(gcloud agent-registry agents list \
  --location=${REGION} --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(attributes.'agentregistry.googleapis.com/system/RuntimeIdentity'.principal)")
echo ${RE_AGENT_IDENTITY}

# fetch agent registry uid for agent
export AGENT_UID=$(gcloud agent-registry agents list \
  --location=${REGION} \
  --filter="displayName=${RE_AGENT_NAME}" \
  --format="value(uid)")
echo ${AGENT_UID}

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

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

agentId: urn:agent:projects-${PROJ_NO}:projects:${PROJ_NO}:locations:${REGION}:aiplatform:reasoningEngines:${RE_ENGINE_ID}
attributes:
  agentregistry.googleapis.com/system/Framework:
    framework: google-adk
  agentregistry.googleapis.com/system/RuntimeIdentity:
    principal: principal://agents.global.org-${PROJ_NO}.system.id.goog/resources/aiplatform/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
  agentregistry.googleapis.com/system/RuntimeReference:
    uri: //aiplatform.googleapis.com/projects/${PROJ_NO}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}
createTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'
description: agent for dj contact info
displayName: agent-dj
name: projects/${PROJ_ID}/locations/${REGION}/agents/agentregistry-${RE_AGENT_ID}
protocols:
- interfaces:
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:query
  - protocolBinding: HTTP_JSON
    url: https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}:streamQuery
  type: CUSTOM
uid: agentregistry-00000000-0000-0000-1234-4567abcd1234
updateTime: 'YYYY-MM-DDTHH:MM:SS.ssssssZ'

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

# verify agent gateway routing specification
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  | jq '{displayName: .displayName, name: .name, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

Cấp vai trò IAM cho tác nhân đối với tài nguyên

Quyền cấp vai trò IAM cho tài nguyên cho phép danh tính chính của tác nhân truy cập vào BigQuery, các công cụ MCP (cho API của Google) và các dịch vụ nền tảng AI cần thiết khác. Các chính sách này được thực thi bằng cách sử dụng IAM ở cấp tài nguyên.

# grant bigquery query execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.user"

# grant bigquery data viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/bigquery.dataViewer"

# grant mcp tool execution role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/mcp.toolUser"

# grant ai platform user role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.user"

# grant agent default access role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/aiplatform.agentDefaultAccess"

# grant agent registry viewer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/agentregistry.viewer"

# grant cloud logging writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/logging.logWriter"

# grant cloud monitoring writer role
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/monitoring.metricWriter"

# grant browser role for resource manager lookup
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="${RE_AGENT_IDENTITY}" \
  --role="roles/browser"

Xác minh vai trò IAM của nhân viên hỗ trợ đối với tài nguyên

# verify active role bindings for agent identity
gcloud projects get-iam-policy ${PROJ_ID} \
  --flatten="bindings[].members" \
  --filter="bindings.members:${RE_AGENT_IDENTITY}" \
  --format="value(bindings.role)"

Đến đây là kết thúc phần thời gian chạy... tiếp theo là phần Chính sách.

9. Chính sách

Các chính sách uỷ quyền quản trị tác nhân cho phép lưu lượng truy cập từ một tác nhân AI thông qua Agent Gateway và đến đích đến (ví dụ: điểm cuối máy chủ MCP của Google Cloud cho BigQuery). Sau khi lưu lượng truy cập đến đích đến, các quyền IAM thông thường sẽ cho phép truy cập vào dữ liệu (và được bật trong phần trước).

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

Cấp vai trò IAM cho tác nhân để truyền dữ liệu ra khỏi Agent Gateway

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

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

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

Định cấu hình chính sách IAM cho sổ đăng ký theo khu vực của IAP

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

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

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

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

# verify iap iam policy for regional registry
gcloud beta iap web get-iam-policy --resource-type=agent-registry --region=${REGION}

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

10. Kiểm tra

Tiện ích uỷ quyền Agent Gateway đang hoạt động ở chế độ DRY_RUN. Các yêu cầu gửi đi sẽ được theo dõi và ghi nhật ký nhưng không bị chặn.

Kiểm thử các câu hỏi cho nhân viên hỗ trợ

Mở cửa sổ trình duyệt đến giao diện người dùng bảng điều khiển Cloud rồi chuyển đến:

Agent Platform → Agents → Deployments → agent-dj
Chọn thẻ Playground (Sân chơi)

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

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

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

How many DJs do we have on file?
What is the phone number of DJ Cosmopup?

Xác minh rằng các truy vấn trả về phản hồi hợp lệ (ví dụ: "Có 12 DJ trong tệp").

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

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

# query gateway logs for dry run
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND httpRequest.requestUrl:*" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=IAP_AUTHZ,
    jsonPayload.agentGatewayInfo.mcpInfo.method:label=MCP_METHOD,
    httpRequest.requestUrl:label=URL
  )"

TIMESTAMP            METHOD  STATUS  IAP_AUTHZ  MCP_METHOD  URL
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://telemetry.googleapis.com/v1/traces
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}/sessions/${RE_SESSION_ID}:appendEvent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED                https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJ_ID}/locations/${REGION}/publishers/google/models/gemini-2.5-flash:generateContent
YYYY-MM-DDTHH:MM:SS  POST    200     ALLOWED    tools/call  https://bigquery.googleapis.com/mcp

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

11. Thi hành

Tác nhân đã có thể thực hiện các yêu cầu thành công thông qua cổng ở chế độ DRY_RUN. Chuyển tiện ích uỷ quyền IAP của Agent Gateway sang chế độ ENFORCE bằng cách cập nhật chính sách uỷ quyền.

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

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

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

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

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

# re-write authz policy config file (pointing to enforced authz extension)
cat > cfg/${AGW_NAME}-authz-policy-profile-iap.yaml << EOF
name: ${AGW_NAME}-authz-policy-profile-iap
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AGW_NAME}-svc-ext-authz-iap-enforced"
EOF

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

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

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

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

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

What DJ Fishfry's credit card number?

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

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

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

# show gateway logs for authz denies
gcloud logging read \
  "resource.type=\"networkservices.googleapis.com/Gateway\" \
  AND (jsonPayload.authzPolicyInfo.result=\"DENIED\" OR httpRequest.status=403)" \
  --project=${PROJ_ID} \
  --limit=10 \
  --format="table(
    timestamp.date(tz=LOCAL):label=TIMESTAMP,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.enforcedGatewaySecurityPolicy.serverNameIndication:label=SNI,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ_RESULT,
    jsonPayload.authzPolicyInfo.policies[0].name.basename():label=DENYING_POLICY
  )"

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

12. Dọn dẹp

# delete agent
curl -s -X DELETE "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJ_ID}/locations/${REGION}/reasoningEngines/${RE_ENGINE_ID}?force=true" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

# next

# remove agent resource iam bindings
for ROLE in \
  "roles/bigquery.user" \
  "roles/bigquery.dataViewer" \
  "roles/mcp.toolUser" \
  "roles/aiplatform.user" \
  "roles/aiplatform.agentDefaultAccess" \
  "roles/agentregistry.viewer" \
  "roles/logging.logWriter" \
  "roles/monitoring.metricWriter" \
  "roles/browser"; do
  gcloud -q projects remove-iam-policy-binding ${PROJ_ID} \
    --member="${RE_AGENT_IDENTITY}" \
    --role="${ROLE}"
done

# next

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

# delete bigquery dataset and contents
bq rm -r -f -d ${PROJ_ID}:dj_ds

# next

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

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

# next

# delete gateway resources
gcloud -q beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap --location=${REGION}

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

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

# next

# clean up local working directories and generated configs
rm -rf cfg agent-dj endpoints

# end

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

13. Kết luận

Xin chúc mừng! Bạn đã triển khai và quản lý thành công thông tin liên lạc gửi đi cho một nhân viên hỗ trợ truy cập vào các công cụ bằng Cổng nhân viên hỗ trợ!

cosmopup

Cosmopup cho rằng Codelabs là tuyệt nhất!

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

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

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

Cảm ơn bạn!