Quản trị tập trung Agent Gateway bằng Agent Registry trên nhiều dự án cho Agent Runtime

1. Giới thiệu

Khi các tổ chức doanh nghiệp áp dụng AI tạo sinh, các cấu trúc đang nhanh chóng phát triển từ chatbot độc lập, nguyên khối thành hệ thống đa tác nhân phân tán (Agent-to-Agent / A2A). Trong các cấu trúc liên kết hiện đại này, các tác nhân điều phối cấp cao sẽ điều phối các quy trình công việc phức tạp của doanh nghiệp bằng cách uỷ quyền các tác vụ cho các tác nhân chuyên biệt của miền, máy chủ công cụ Giao thức ngữ cảnh mô hình (MCP) và cơ sở dữ liệu doanh nghiệp phụ trợ trên các dự án độc lập của Google Cloud.

Tuy nhiên, việc vận hành hệ thống nhiều tác nhân ở quy mô lớn sẽ gây ra những thách thức nghiêm trọng về bảo mật, quản trị và vận hành:

  • Shadow Agent và Tool Sprawl: Khi các nhóm phát triển triển khai các tác nhân trong các dự án riêng biệt mà không có danh mục tập trung, các tổ chức sẽ không biết được những công cụ và tác nhân phụ nào đang tồn tại.
  • Đường truyền ra ngoài giữa các dự án không được giám sát: Việc cho phép các tác nhân sử dụng các tuyến mạng trực tiếp, không được kiểm tra sẽ tạo ra rủi ro trích xuất dữ liệu và bỏ qua các biện pháp bảo mật.
  • Tích hợp mã hoá cứng dễ bị lỗi: Việc mã hoá cứng URL của tác nhân hạ nguồn và mã nhận dạng của Công cụ suy luận sẽ tạo ra các phần phụ thuộc dễ bị lỗi và có thể bị hỏng trong quá trình nâng cấp hoặc triển khai lại.
  • Thiếu danh tính có đặc quyền tối thiểu: Tài khoản dịch vụ dùng chung không cung cấp khả năng chống chối bỏ bằng mật mã ở cấp phiên bản tác nhân riêng lẻ.

Để giải quyết những thách thức này, Nền tảng Gemini Enterprise Agent cung cấp một tầng điều khiển thống nhất về hoạt động quản trị và kết nối, bao gồm 4 trụ cột cốt lõi:

  1. Cổng đại lý (networkservices.googleapis.com): Một mạng lưới được quản lý theo khu vực và proxy thực thi chính sách. Hoạt động ở chế độ truyền ra AGENT_TO_ANYWHERE, chế độ này chặn lưu lượng truy cập đi ra của tác nhân, uỷ quyền đánh giá uỷ quyền cho các tiện ích bảo mật và định tuyến các yêu cầu trên các ranh giới dự án.
  2. Sổ đăng ký tác nhân (agentregistry.googleapis.com): Danh mục dịch vụ duy nhất của doanh nghiệp. Thư viện này cung cấp một danh mục tập trung, được kiểm duyệt về tất cả các công cụ, máy chủ MCP và tác nhân ngang hàng có sẵn trong tổ chức, cho phép tự động khám phá thời gian chạy linh hoạt mà không cần điểm cuối được mã hoá cứng.
  3. Quy tắc quản trị về danh tính và IAP phiên bản 2 của tác nhân (iap.googleapis.com và iam.googleapis.com): Một khuôn khổ về danh tính và quyền truy cập bằng mật mã. Các tác nhân thực thi nhận được URN máy SPIFFE duy nhất, được chứng thực (principal://...). Lưu lượng truy cập đi ra được đánh giá dựa trên Chính sách truy cập thống nhất (UAP / IAP phiên bản 2) của IAM tập trung để xác minh quyền phổ quát iap.googleapis.com/resources.egressViaIAP bằng cách sử dụng các điều kiện danh mục Ngôn ngữ biểu thức chung (CEL) phong phú (destination.agent_registry.*).
  4. Thời gian chạy của tác nhân (Công cụ suy luận): Một nền tảng thực thi hoàn toàn được quản lý, không máy chủ cho các ứng dụng dựa trên Python, có các liên kết cấu hình gốc (agent_gateway_config) đến các cổng trung tâm.

Tình huống kinh doanh trong lớp học lập trình: Mua thực phẩm và đồ uống cho nhiều dự án

Trong lớp học lập trình này, bạn sẽ xây dựng và quản lý một hệ sinh thái mua hàng thực tế gồm nhiều dự án trải rộng trên 3 dự án riêng biệt của Google Cloud:

  • Dự án Quản trị tập trung (PROJECT_GOVERNANCE): Do Nhóm CNTT và SecOps trung tâm sở hữu, lưu trữ Cổng tác nhân trung tâm, Sổ đăng ký tác nhân trung tâm và Chính sách truy cập hợp nhất IAM.
  • Dự án Điều phối viên người tiêu dùng (PROJECT_CONCIERGE): Thuộc sở hữu của nhóm mua sắm, lưu trữ Tác nhân hỗ trợ mua hàng để tự động phát hiện nhà cung cấp và định tuyến đơn đặt hàng của khách hàng.
  • Dự án Nhà cung cấp miền (PROJECT_SELLERS): Thuộc sở hữu của các nhà cung cấp bên ngoài hoặc theo phòng ban, lưu trữ Tác nhân bán bánh mì kẹp thịt và Tác nhân bán bánh pizza.

figure1

Hình 1. Cấu trúc quản trị tập trung cho nhiều dự án

Tại sao cần có hoạt động quản trị tập trung trên nhiều dự án?

Trong các tổ chức doanh nghiệp lớn, các nhóm sản phẩm và nhóm khoa học dữ liệu xây dựng các tác nhân AI trên hàng chục dự án độc lập trên Google Cloud. Việc cho phép mỗi nhóm kiểm soát trực tiếp việc đăng ký công cụ, các tuyến mạng lưu lượng truy cập đi và các biện pháp bảo vệ an ninh sẽ tạo ra tình trạng sử dụng tràn lan các công cụ chưa được kiểm duyệt, các chính sách DLP không nhất quán, lưu lượng truy cập đi VPC không được giám sát và nhật ký kiểm tra rời rạc.

Hoạt động quản trị tập trung trên nhiều dự án tách biệt việc tạo chính sách với việc thực thi tác nhân:

  • Nhóm CNTT và SecOps tập trung có thể tạo chính sách bảo mật, kiểm tra công cụ và giám sát lưu lượng truy cập đi trong một Dự án quản trị tập trung.
  • Nhóm Sản phẩm và Ứng dụng chỉ tập trung vào logic nghiệp vụ trong Dự án Thời gian chạy của tác nhân độc lập, liên kết trực tiếp với cổng trung tâm mà không cần phải quản lý VPC cục bộ, kết nối liên kết hoặc các công cụ chính sách phân mảnh.

figure2

Hình 2. Cấu trúc và ranh giới quản trị dự án chéo gồm 3 cấp

Mô hình phân cấp danh tính gồm 2 cấp trong Chính sách truy cập hợp nhất

Khi các tác nhân giao tiếp thông qua Cổng tác nhân trung tâm, Proxy nhận biết danh tính (IAP phiên bản 2) sẽ đánh giá quyền truy cập dựa trên Danh tính tác nhân của người gọi (một danh tính dựa trên SPIFFE, được chứng thực bằng mật mã và tự động cấp cho vùng chứa thời gian chạy) so với Chính sách truy cập IAM toàn cầu:

  • Cấp 1: Các Cloud API cơ bản của Google Cloud (Được phân loại thô qua principalSet:// trong Quy tắc 1): Uỷ quyền truyền dữ liệu ra bên ngoài trên toàn dự án, cho phép tất cả thời gian chạy của tác nhân trên các dự án vệ tinh truy cập vào các API tiêu chuẩn của Google (aiplatform, iamcredentials, telemetry, agentregistry) để khám phá, tạo mã thông báo và suy luận.
  • Cấp 2: Công cụ kinh doanh và dịch vụ A2A (Chi tiết thông qua principal:// trong Quy tắc 2 và 3): Quyền truy cập theo nguyên tắc nghiêm ngặt về đặc quyền tối thiểu được liên kết với từng phiên bản Reasoning Engine, được thực thi bằng các điều kiện Ngôn ngữ diễn đạt thông thường (CEL) nhắm đến các dịch vụ cụ thể đã đăng ký trong Agent Registry (destination.agent_registry.agent.name).

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

  • Agent Gateway (centralized-agw) tập trung ở PROJECT_GOVERNANCE
  • Tiện ích Dịch vụ uỷ quyền IAP phiên bản 2 và Chính sách uỷ quyền ở chế độ THỰC THI nghiêm ngặt (failOpen: false)
  • Chính sách truy cập hợp nhất IAM cơ bản (uap-rules.json) và Liên kết chính sách của dự án
  • Quyền IAM của tác nhân dịch vụ trên nhiều dự án (ar_agw_cross_project_sa)
  • Bộ chứa dàn xếp trung tâm dùng chung trên Google Cloud Storage (GCS)
  • Isolated Burger and Pizza Seller Agents in PROJECT_SELLERS
  • Tác nhân hỗ trợ mua hàng có tính năng tự động phát hiện REST linh động trong PROJECT_CONCIERGE
  • Đăng ký dịch vụ trong Central Agent Registry bằng các URL mTLS trên nhiều dự án
  • Cập nhật chính sách lưu lượng truy cập đi của IAP phiên bản 2 một cách linh động bằng tính năng xác minh trực tiếp và kiểm tra bằng Cloud Logging

figure3

Hình 3. Trình tự triển khai từng bước

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

  • Cách định cấu hình quyền IAM của tác nhân dịch vụ trên nhiều dự án cho các cổng tập trung
  • Cách định tuyến lưu lượng truy cập ra của Thời gian chạy tác nhân thông qua Cổng tác nhân trung tâm trên nhiều môi trường dự án
  • Cách uỷ quyền Agent Gateway cho Identity-Aware Proxy (IAP phiên bản 2) bằng cách sử dụng Tiện ích dịch vụ (iapPolicyVersion: "V2")
  • Cách tạo và liên kết Chính sách truy cập thống nhất (UAP) của IAM với các quy tắc Ngôn ngữ diễn đạt thông thường (CEL) chi phối các đích đến đã đăng ký của Sổ đăng ký tác nhân (destination.agent_registry.*)
  • Cách loại bỏ các URL và mã nhận dạng tác nhân được mã hoá cứng bằng tính năng tự động phát hiện thời gian chạy đối với Sổ đăng ký tác nhân
  • Cách kiểm thử tính năng chặn dựa trên mô hình không tin cậy thực tế (HTTP 403 Forbidden) và xác minh các bản cập nhật chính sách trực tiếp trong Cloud Logging

Bạn cần có

  • 3 dự án trên Google Cloud đã bật tính năng thanh toán:
    • PROJECT_GOVERNANCE: Cơ chế quản trị, cổng, sổ đăng ký và chính sách truy cập IAM tập trung
    • PROJECT_CONCIERGE: Tác nhân điều phối dịch vụ hỗ trợ mua hàng
    • PROJECT_SELLERS: Nhân viên bán hàng chuyên về bánh mì kẹp và pizza
  • Một người dùng IAM hoặc tài khoản dịch vụ có roles/owner hoặc quyền quản trị trên cả 3 dự án
  • Một tổ chức trên Google Cloud (để lập bản đồ miền tin cậy SPIFFE)
  • Google Cloud Shell hoặc một máy cục bộ có cài đặt gcloud CLI, python (3.11 trở lên) và uv

Đến đây là kết thúc phần giới thiệu... tiếp theo là phần Thiết lập và môi trường.

2. Thiết lập

Mặc dù cấu trúc này trải rộng trên 3 dự án riêng biệt của Google Cloud, nhưng bạn có thể thực hiện 100% các lệnh triển khai trên thiết bị đầu cuối, tải kho lưu trữ xuống và các thao tác dàn dựng từ một thiết bị đầu cuối Cloud Shell duy nhất được đặt thành PROJECT_GOVERNANCE. Mọi tập lệnh triển khai và lệnh gcloud đều nhắm đến dự án đích thích hợp một cách rõ ràng thông qua cờ CLI (--project).

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

Thiết lập bối cảnh dự án

# set terminal project context to Central Governance Project
gcloud config set project SET_YOUR_GOVERNANCE_PROJECT_ID_HERE

# login to gcloud cli
gcloud auth login

# login for application default credentials
gcloud auth application-default login

# update gcloud components
gcloud components update --quiet

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

Nhập giá trị nhận dạng cụ thể của dự án.

# 1. Project Identifiers
export PROJECT_GOVERNANCE="SET_YOUR_GOVERNANCE_PROJECT_ID_HERE"
export PROJECT_CONCIERGE="SET_YOUR_CONCIERGE_PROJECT_ID_HERE"
export PROJECT_SELLERS="SET_YOUR_SELLERS_PROJECT_ID_HERE"

Các biến shell này sẽ được suy ra tự động.

# 2. Regional & Gateway Settings
export REGION="us-central1"
export AGW_NAME="centralized-agw"
export UAP_POLICY_NAME="uap-policy-${AGW_NAME}"
export UAP_BINDING_NAME="uap-binding-${AGW_NAME}"

# 3. Retrieve Project Numbers
export PROJECT_NUMBER_GOVERNANCE=$(gcloud projects describe ${PROJECT_GOVERNANCE} --format="value(projectNumber)")
export PROJECT_NUMBER_CONCIERGE=$(gcloud projects describe ${PROJECT_CONCIERGE} --format="value(projectNumber)")
export PROJECT_NUMBER_SELLERS=$(gcloud projects describe ${PROJECT_SELLERS} --format="value(projectNumber)")

# 4. Obtain Organization ID
export ORG_ID=$(gcloud projects get-ancestors ${PROJECT_GOVERNANCE} --format="value(id, type)" | grep organization | awk '{print $1}')

# 5. Set Application Default Credentials (ADC) Quota Project
gcloud auth application-default set-quota-project ${PROJECT_GOVERNANCE}

echo "Governance Project: ${PROJECT_GOVERNANCE} (${PROJECT_NUMBER_GOVERNANCE})"
echo "Concierge Project:  ${PROJECT_CONCIERGE} (${PROJECT_NUMBER_CONCIERGE})"
echo "Sellers Project:    ${PROJECT_SELLERS} (${PROJECT_NUMBER_SELLERS})"
echo "Organization ID:    ${ORG_ID}"
echo "UAP Policy Name:    ${UAP_POLICY_NAME}"
echo "UAP Binding Name:   ${UAP_BINDING_NAME}"

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

# create config folder
mkdir -p cfg

Chỉ định vai trò Quản trị viên chính sách truy cập cho Chính sách truy cập hợp nhất

# grant Access Policy Admin and Project IAM Admin to current user in Governance Project
for ROLE in "roles/iam.accessPolicyAdmin" "roles/resourcemanager.projectIamAdmin"; do
  gcloud projects add-iam-policy-binding ${PROJECT_GOVERNANCE} \
    --member="user:$(gcloud config get-value account)" \
    --role="${ROLE}" \
    --condition=None
done

Bật Nhật ký truy cập dữ liệu kiểm tra trên đám mây cho IAP phiên bản 2

Theo mặc định, Google Cloud sẽ tắt nhật ký kiểm tra Quyền truy cập vào dữ liệu để tránh phát sinh chi phí lưu trữ ngoài ý muốn. Vì IAP phiên bản 2 phát ra các quyết định uỷ quyền (granted=true và granted=false) dưới dạng nhật ký kiểm tra quyền truy cập dữ liệu, hãy bật tính năng ghi nhật ký ADMIN_READ, DATA_READ và DATA_WRITE cho iap.googleapis.com trong PROJECT_GOVERNANCE:

# 1. export current IAM policy for PROJECT_GOVERNANCE
gcloud projects get-iam-policy ${PROJECT_GOVERNANCE} \
  --format=json > cfg/gov_iam_policy.json

# 2. append auditConfigs for iap.googleapis.com
python3 -c "
import json
with open('cfg/gov_iam_policy.json') as f:
    policy = json.load(f)
audit_configs = [c for c in policy.get('auditConfigs', []) if c.get('service') != 'iap.googleapis.com']
audit_configs.append({
    'service': 'iap.googleapis.com',
    'auditLogConfigs': [
        {'logType': 'ADMIN_READ'},
        {'logType': 'DATA_READ'},
        {'logType': 'DATA_WRITE'}
    ]
})
policy['auditConfigs'] = audit_configs
with open('cfg/gov_iam_policy.json', 'w') as f:
    json.dump(policy, f, indent=2)
"

# 3. apply updated policy
gcloud projects set-iam-policy ${PROJECT_GOVERNANCE} cfg/gov_iam_policy.json

# 4. verify auditConfigs applied
gcloud projects get-iam-policy ${PROJECT_GOVERNANCE} --format="yaml(auditConfigs)"

Bật các API bắt buộc của Google Cloud

# enable google apis (agent platform & security bundle, part 1)
for PROJ in ${PROJECT_GOVERNANCE} ${PROJECT_CONCIERGE} ${PROJECT_SELLERS}; do
  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 \
    agentidentity.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 \
    --project=${PROJ}
done

# enable google apis (agent platform bundle, part 2)
for PROJ in ${PROJECT_GOVERNANCE} ${PROJECT_CONCIERGE} ${PROJECT_SELLERS}; do
  gcloud services enable \
    securitycenter.googleapis.com \
    saasservicemgmt.googleapis.com \
    storage.googleapis.com \
    telemetry.googleapis.com \
    texttospeech.googleapis.com \
    --project=${PROJ}
done

# enable google apis (foundational & agent runtime build bundle, part 3)
for PROJ in ${PROJECT_GOVERNANCE} ${PROJECT_CONCIERGE} ${PROJECT_SELLERS}; do
  gcloud services enable \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    cloudresourcemanager.googleapis.com \
    iamcredentials.googleapis.com \
    serviceusage.googleapis.com \
    run.googleapis.com \
    orgpolicy.googleapis.com \
    --project=${PROJ}
done

Xác thực việc bật API trên tất cả các dự án

Việc đảm bảo cả 3 dự án (PROJECT_GOVERNANCE, PROJECT_CONCIERGE và PROJECT_SELLERS) đều bật cùng một API sẽ thiết lập tính nhất quán trong hoạt động và ngăn chặn lỗi tạo mã thông báo trong thời gian chạy, lỗi lập danh mục lược đồ hoặc lỗi truyền dữ liệu đo từ xa.

Chạy tập lệnh xác thực sau trong Cloud Shell để xác minh tính tương đồng của API trên cả 3 dự án:

# validate that all required APIs are enabled across all 3 projects
python3 - << 'EOF'
import subprocess
import os
import sys

REQUIRED_APIS = [
    "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",
    "agentidentity.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",
    "securitycenter.googleapis.com",
    "saasservicemgmt.googleapis.com",
    "storage.googleapis.com",
    "telemetry.googleapis.com",
    "texttospeech.googleapis.com",
    "artifactregistry.googleapis.com",
    "cloudbuild.googleapis.com",
    "cloudresourcemanager.googleapis.com",
    "iamcredentials.googleapis.com",
    "serviceusage.googleapis.com",
    "run.googleapis.com",
    "orgpolicy.googleapis.com"
]

projects = {
    "GOVERNANCE": os.environ.get("PROJECT_GOVERNANCE", ""),
    "CONCIERGE": os.environ.get("PROJECT_CONCIERGE", ""),
    "SELLERS": os.environ.get("PROJECT_SELLERS", "")
}

enabled = {}
for role, proj in projects.items():
    if not proj:
        print(f"Error: Environment variable for {role} is not set.")
        sys.exit(1)
    res = subprocess.run(
        ["gcloud", "services", "list", "--enabled", f"--project={proj}", "--format=value(config.name)"],
        capture_output=True, text=True, check=True
    )
    enabled[role] = set(res.stdout.strip().splitlines())

print(f"\n{'API Name':<36} | {'GOVERNANCE':<12} | {'CONCIERGE':<12} | {'SELLERS':<12}")
print("-" * 78)

all_synced = True
for api in REQUIRED_APIS:
    g_status = "ENABLED" if api in enabled["GOVERNANCE"] else "MISSING"
    c_status = "ENABLED" if api in enabled["CONCIERGE"] else "MISSING"
    s_status = "ENABLED" if api in enabled["SELLERS"] else "MISSING"
    if "MISSING" in (g_status, c_status, s_status):
        all_synced = False
    print(f"{api:<36} | {g_status:<12} | {c_status:<12} | {s_status:<12}")

print("-" * 78)
if all_synced:
    print("✅ All 29 required APIs are ENABLED and synchronized across all three projects.\n")
else:
    print("❌ Discrepancies detected. Please re-run the enablement commands for missing services.\n")
    sys.exit(1)
EOF

Kết quả xác thực mẫu:

Bạn sẽ thấy tất cả API đã bật.

✅ All 30 required APIs are ENABLED and synchronized across all three projects.

Định cấu hình chính sách tổ chức

Các chính sách tổ chức mặc định của Google Cloud thực thi các giới hạn hạn chế việc liên kết chính sách truy cập IAM phiên bản 3 với các tài nguyên (constraints/iam.managed.disableAccessPolicyBinding).

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 thành cho phép một cách rõ ràng.

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

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

Đến đây là kết thúc phần thiết lập... tiếp theo là phần Đăng ký các API cốt lõi của Google.

3. Sổ đăng ký tác nhân

Đăng ký dịch vụ điểm cuối API cốt lõi của Google

Agent Gateway yêu cầu các URL API của Google phải được đăng ký trong Central Agent Registry để các tác nhân được định cấu hình bằng agent_gateway_config có thể định tuyến lưu lượng truy cập xuất một cách an toàn đến các dịch vụ phụ trợ cốt lõi của Google Cloud (chẳng hạn như aiplatform, IAM Credentials và Telemetry).

Tạo core-gapi-services trong Sổ đăng ký tác nhân

# register core google api endpoints in agent registry with standard and :443 port variants
gcloud agent-registry services create core-gapi-services \
  --project=${PROJECT_GOVERNANCE} \
  --location=${REGION} \
  --display-name="gapi.core.services" \
  --description="Core Google Cloud APIs and Service Endpoints" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://telemetry.mtls.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.googleapis.com:443 \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.mtls.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.mtls.googleapis.com:443 \
  --interfaces=protocolBinding=JSONRPC,url=https://aiplatform.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://aiplatform.googleapis.com:443 \
  --interfaces=protocolBinding=JSONRPC,url=https://aiplatform.mtls.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://aiplatform.mtls.googleapis.com:443 \
  --interfaces=protocolBinding=JSONRPC,url=https://cloudresourcemanager.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://iamcredentials.mtls.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://agentregistry.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://agentregistry.mtls.googleapis.com \
  --interfaces=protocolBinding=JSONRPC,url=https://agentregistry.googleapis.com:443 \
  --interfaces=protocolBinding=JSONRPC,url=https://agentregistry.mtls.googleapis.com:443

Lấy mã nhận dạng tài nguyên điểm cuối của Capture Core API

# capture the underlying Agent Registry endpoint ID
export ENDPOINT_ID=$(gcloud agent-registry services describe core-gapi-services \
  --project=${PROJECT_GOVERNANCE} \
  --location=${REGION} \
  --format="value(registryResource)" | awk -F'/' '{print $NF}')
echo "Core APIs Endpoint ID: ${ENDPOINT_ID}"

Tìm hiểu về principalSet so với principal trong Danh tính của tác nhân

Trong Google Cloud IAM và Nền tảng tác nhân Gemini Enterprise, danh tính máy được cấp cho các vùng chứa tác nhân thực thi sẽ sử dụng URN SPIFFE được chứng thực bằng mật mã do Identity-Aware Proxy (IAP phiên bản 2) đánh giá. Khi định cấu hình Chính sách truy cập thống nhất IAM, bạn có thể nhắm đến một principal duy nhất cụ thể hoặc một principalSet dựa trên thuộc tính:

Phương diện

principal:// (Single Machine Identity)

principalSet:// (Nhóm dựa trên thuộc tính)

Cú pháp IAM

principal://...

principalSet://...

Độ chi tiết

Chi tiết (cấp phiên bản): Xác định một phiên bản vùng chứa Reasoning Engine cụ thể.

Mức độ chi tiết thấp (Cấp dự án): Xác định tất cả các công cụ suy luận dùng chung một thuộc tính dự án.

Mẫu URN

principal://agents.global.org-${ORG_ID}.system.id.goog/resources/aiplatform/projects/${PROJECT_NUMBER}/locations/${REGION}/reasoningEngines/${ENGINE_ID}

principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER}

Trường hợp sử dụng trong nền tảng tác nhân

Cấp 2 (Công cụ kinh doanh và A2A): Cho phép các tác nhân điều phối cụ thể gọi các công cụ miền mục tiêu (ví dụ: Tác nhân hỗ trợ mua hàng $\rightarrow$ Người bán bánh hamburger).

Cấp 1 (Cơ sở hạ tầng nền tảng): Cấp cho tất cả các tác nhân trong một dự án quyền truy cập xuất dữ liệu vào các API của Google Cloud (core-gapi-services).

Tác động trong vòng đời

Nếu một tác nhân bị xoá và tạo lại, thì mã nhận dạng công cụ mới của tác nhân đó cần có một mối liên kết chính sách IAM mới.

Tự động áp dụng cho các tác nhân mới được triển khai trong dự án đó mà không cần cập nhật thêm IAM.

Quản trị khai báo bằng Chính sách truy cập hợp nhất (UAP / IAP phiên bản 2)

Trong IAP phiên bản 1 cũ, các chính sách truyền dữ liệu ra bên ngoài được đính kèm trực tiếp vào từng tài nguyên trong Sổ đăng ký tác nhân bằng cách sử dụng gcloud beta iap web add-iam-policy-binding. Trong phần IAP phiên bản 2 và Chính sách truy cập hợp nhất, các liên kết theo tài nguyên sẽ bị loại bỏ để chuyển sang Chính sách truy cập IAM duy nhất, tập trung (cfg/uap-rules.json).

Quyền uỷ quyền cơ bản cho core-gapi-services sẽ được định cấu hình thành Quy tắc 1 trong Chính sách truy cập thống nhất ở Mục 5, đảm bảo rằng tất cả vùng chứa tác nhân đều có các tuyến cơ bản được thiết lập trước khi triển khai.

Để biết thêm thông tin kỹ thuật chuyên sâu về giá trị nhận dạng chính và cơ chế danh tính tải, hãy xem:

Đến đây là kết thúc quá trình đăng ký điểm cuối API cốt lõi... tiếp theo là phần Triển khai Cổng tác nhân tập trung.

4. Agent Gateway

Triển khai Agent Gateway tập trung

Triển khai Agent Gateway (centralized-agw) tập trung ở chế độ truyền dữ liệu ra AGENT_TO_ANYWHERE bên trong dự án $PROJECT_GOVERNANCE.

Xác định tệp kê khai cấu hình cổng

Tạo cfg/${AGW_NAME}.yaml để quản lý lưu lượng truy cập đi:

# generate agent gateway config yaml
cat > cfg/${AGW_NAME}.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - "//agentregistry.googleapis.com/projects/${PROJECT_GOVERNANCE}/locations/${REGION}"
EOF

Nhập cấu hình Agent Gateway

# import and create agent gateway
gcloud network-services agent-gateways import ${AGW_NAME} \
  --source="cfg/${AGW_NAME}.yaml" \
  --location=${REGION} \
  --project=${PROJECT_GOVERNANCE}

Xác minh thông tin chi tiết về Cổng nhân viên hỗ trợ

# show agent gateway status
gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION} \
  --project=${PROJECT_GOVERNANCE}

Kết quả mẫu:

agentGatewayCard:
  mtlsEndpoint: projects/${AGW_TP_ID}/regions/us-central1/serviceAttachments/unitkind1-swp-mtls-psc-sa
  rootCertificates:
  - |
    -----BEGIN CERTIFICATE-----
    MIIDwzCCAqugAwIBAgITNQuWGopdOZaHdcK7r7AYFhonqDANBgkqhkiG9w0BAQsF
    ...
    -----END CERTIFICATE-----
  serviceExtensionsServiceAccount: service-${PROJ_NO}@gcp-sa-dep.iam.gserviceaccount.com
createTime: 'YYYY-MM-DDT12:34:56.789098765Z'
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
name: projects/${PROJECT_GOVERNANCE}/locations/us-central1/agentGateways/centralized-agw
protocols:
- MCP
registries:
- //agentregistry.googleapis.com/projects/${PROJECT_GOVERNANCE}/locations/us-central1
updateTime: 'YYYY-MM-DDT12:34:56.789098765Z'

Đến đây là kết thúc quá trình triển khai cổng... tiếp theo là phần Định cấu hình uỷ quyền.

5. Ủy quyền

Định cấu hình uỷ quyền cổng tác nhân và UAP cơ bản

Agent Gateway bảo mật và quản lý lưu lượng truy cập công cụ và tác nhân gửi đi bằng cách sử dụng Authorization Policies (networksecurity.authzPolicies) được tích hợp với Identity-Aware Proxy (IAP phiên bản 2) Unified Access Policies (UAP).

Tổng quan về cấu trúc uỷ quyền

figure4

Hình 4. Tổng quan về cấu trúc uỷ quyền

Cấu trúc uỷ quyền bao gồm 3 lớp kết nối với nhau:

  1. Tiện ích dịch vụ IAP (authzExtension): Tài nguyên theo khu vực được định cấu hình bằng service: iap.googleapis.com, metadata: iapPolicyVersion: "V2" và failOpen: false để thực thi nghiêm ngặt chế độ không tin tưởng bất cứ nguồn nào.
  2. Chính sách uỷ quyền cổng (authzPolicy): Nhắm đến tài nguyên theo khu vực cho Cổng tác nhân của bạn bằng policyProfile: REQUEST_AUTHZ và action: CUSTOM, định tuyến các quy trình kiểm tra uỷ quyền đến Tiện ích uỷ quyền IAP.
  3. Chính sách và liên kết truy cập hợp nhất IAM (accessPolicy & policyBinding): Tài nguyên IAM v3 trên toàn cầu do IAP đánh giá. Nó xác minh quyền phổ quát iap.googleapis.com/resources.egressViaIAP dựa trên danh tính SPIFFE của người gọi và các điều kiện trong danh mục CEL.

Bước 1: Tạo và nhập tiện ích Uỷ quyền IAP phiên bản 2

Tạo tệp kê khai Tiện ích dịch vụ bằng iapPolicyVersion: "V2" và failOpen: false ở chế độ ENFORCE nghiêm ngặt:

# create authz extension config file in ENFORCE mode
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

Nhập Tiện ích Authz:

# import IAP v2 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} \
  --project=${PROJECT_GOVERNANCE}

Xác minh rằng Tiện ích Authz đang hoạt động:

# describe authz extension
gcloud service-extensions authz-extensions describe ${AGW_NAME}-svc-ext-authz-iap \
  --location=${REGION} \
  --project=${PROJECT_GOVERNANCE}

Kết quả mẫu:

createTime: 'YYYY-MM-DDT12:34:56.789098765Z'
failOpen: false
metadata:
  iapPolicyVersion: V2
name: projects/${PROJECT_GOVERNANCE}/locations/us-central1/authzExtensions/centralized-agw-svc-ext-authz-iap
service: iap.googleapis.com
timeout: 1s

Bước 2: Tạo và nhập Chính sách uỷ quyền cổng

Tạo một cấu hình Chính sách uỷ quyền gắn với Cổng đại lý và uỷ quyền xác minh yêu cầu cho Tiện ích uỷ quyền IAP:

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

Nhập Chính sách uỷ quyền:

# import 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} \
  --project=${PROJECT_GOVERNANCE}

Xác minh Chính sách uỷ quyền đang hoạt động:

# describe authz policy
gcloud beta network-security authz-policies describe ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION} \
  --project=${PROJECT_GOVERNANCE}

Bước 3: Tạo Chính sách truy cập hợp nhất ban đầu (Quy tắc 1: Các API cốt lõi của Google)

Tạo cfg/uap-rules.json bằng Quy tắc 1 cho phép 3 dự án principalSet đạt được core-gapi-services:

# create initial unified access policy rules manifest
cat > cfg/uap-rules.json << EOF
[
  {
    "description": "Rule 1: Allow agent runtimes across all 3 projects to reach Core Google APIs",
    "effect": "ALLOW",
    "principals": [
      "principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_GOVERNANCE}",
      "principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_CONCIERGE}",
      "principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_SELLERS}"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true && \
         destination.agent_registry.resource_type == 'ENDPOINT' && ( \
         destination.agent_registry.endpoint.name == 'projects/${PROJECT_GOVERNANCE}/locations/${REGION}/endpoints/core-gapi-services' || \
         destination.agent_registry.endpoint.name == 'projects/${PROJECT_GOVERNANCE}/locations/${REGION}/endpoints/${ENDPOINT_ID}' || \
         destination.agent_registry.endpoint.name == 'projects/${PROJECT_NUMBER_GOVERNANCE}/locations/${REGION}/endpoints/${ENDPOINT_ID}')"
      }
    }
  }
]
EOF

Bước 4: Tạo và liên kết chính sách truy cập IAM

Tạo Chính sách truy cập IAM toàn cầu:

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

Liên kết Chính sách truy cập với PROJECT_GOVERNANCE:

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

Xác minh rằng Policy Binding đang hoạt động:

# verify policy binding
gcloud iam policy-bindings describe ${UAP_BINDING_NAME} \
  --project=${PROJECT_GOVERNANCE} \
  --location=global

Kết quả mẫu:

name: projects/${PROJECT_GOVERNANCE}/locations/global/policyBindings/uap-binding-centralized-agw
policy: projects/${PROJECT_GOVERNANCE}/locations/global/accessPolicies/uap-policy-centralized-agw
policyKind: ACCESS_POLICY
target:
  resource: //cloudresourcemanager.googleapis.com/projects/${PROJECT_GOVERNANCE}

Giờ đây, lưu lượng truy cập API cơ bản của Google Cloud được uỷ quyền một cách an toàn trên cả 3 dự án ở chế độ ENFORCE nghiêm ngặt.

Đến đây là kết thúc quá trình thiết lập uỷ quyền cổng... tiếp theo là phần Định cấu hình quyền IAM trên nhiều dự án.

6. IAM trên nhiều dự án

Định cấu hình quyền IAM trên nhiều dự án

Trong cấu trúc liên kết nhiều dự án này, Agent Runtime nằm trong các dự án vệ tinh (PROJECT_CONCIERGE và PROJECT_SELLERS), trong khi Central Agent Gateway và Agent Registry nằm trong PROJECT_GOVERNANCE.

Vì các dự án trên Google Cloud là những ranh giới bảo mật riêng biệt, nên bạn phải cấp quyền truy cập giữa các dự án một cách rõ ràng trên 2 lớp hoạt động:

  1. Control Plane (Thời gian triển khai): Khi triển khai một vùng chứa tác nhân được định cấu hình bằng --agent-gateway-config, Tác nhân dịch vụ thời gian chạy tác nhân (service-@gcp-sa-aiplatform.iam.gserviceaccount.com) của dự án spoke phải đính kèm vùng chứa vào cổng trung tâm. Chúng tôi tạo một vai trò tuỳ chỉnh tối thiểu (ar_agw_cross_project_sa) cấp quyền networkservices.agentGateways.use, get và operations.get trong PROJECT_GOVERNANCE.
  2. Lớp dữ liệu (Thực thi thời gian chạy):
    • Khám phá danh mục: Danh tính Spoke cần roles/agentregistry.viewer trong PROJECT_GOVERNANCE để giải quyết các điểm cuối của tác nhân mục tiêu một cách linh động.
    • Lời gọi mục tiêu: Concierge agent cần roles/aiplatform.user trong PROJECT_SELLERS để thực thi các truy vấn đối với công cụ suy luận của người bán.

Tạo vai trò IAM tuỳ chỉnh trong PROJECT_GOVERNANCE

# create custom role in central governance project
gcloud iam roles create ar_agw_cross_project_sa \
  --project=${PROJECT_GOVERNANCE} \
  --title="Runtime Agent Gateway Cross-Project SA" \
  --description="Custom role for cross-project service agents to access Central Agent Gateway" \
  --permissions="networkservices.agentGateways.get,networkservices.agentGateways.use,networkservices.operations.get" \
  --stage="GA"

Chỉ định vai trò tuỳ chỉnh cho các tác nhân Dịch vụ thời gian chạy của tác nhân

# 1. ensure aiplatform service identities are provisioned across all projects
for PROJ in ${PROJECT_GOVERNANCE} ${PROJECT_CONCIERGE} ${PROJECT_SELLERS}; do
  gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJ}
done

# 2. derive aiplatform service agent emails
export CONCIERGE_AI_SA="service-${PROJECT_NUMBER_CONCIERGE}@gcp-sa-aiplatform.iam.gserviceaccount.com"
export CONCIERGE_RE_SA="service-${PROJECT_NUMBER_CONCIERGE}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
export CONCIERGE_COMPUTE_SA="${PROJECT_NUMBER_CONCIERGE}-compute@developer.gserviceaccount.com"

export SELLERS_AI_SA="service-${PROJECT_NUMBER_SELLERS}@gcp-sa-aiplatform.iam.gserviceaccount.com"
export SELLERS_RE_SA="service-${PROJECT_NUMBER_SELLERS}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
export SELLERS_COMPUTE_SA="${PROJECT_NUMBER_SELLERS}-compute@developer.gserviceaccount.com"

# 3. grant custom role & network viewer to Concierge and Sellers Service Agents
for SA in ${CONCIERGE_AI_SA} ${SELLERS_AI_SA}; do
  gcloud projects add-iam-policy-binding ${PROJECT_GOVERNANCE} \
    --member="serviceAccount:${SA}" \
    --role="projects/${PROJECT_GOVERNANCE}/roles/ar_agw_cross_project_sa" \
    --condition=None

  gcloud projects add-iam-policy-binding ${PROJECT_GOVERNANCE} \
    --member="serviceAccount:${SA}" \
    --role="roles/networkservices.viewer" \
    --condition=None
done

# 4. grant agent registry viewer on Governance Project for dynamic autodiscovery
for MEMBER in "serviceAccount:${CONCIERGE_AI_SA}" "serviceAccount:${CONCIERGE_RE_SA}" "serviceAccount:${CONCIERGE_COMPUTE_SA}" "serviceAccount:${SELLERS_AI_SA}" "serviceAccount:${SELLERS_RE_SA}" "serviceAccount:${SELLERS_COMPUTE_SA}" "principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_CONCIERGE}" "principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_SELLERS}"; do
  gcloud projects add-iam-policy-binding ${PROJECT_GOVERNANCE} \
    --member="${MEMBER}" \
    --role="roles/agentregistry.viewer" \
    --condition=None
done

# 5. grant agent project viewer on Governance Project for dynamic autodiscovery
for SA in ${CONCIERGE_COMPUTE_SA} ${CONCIERGE_AI_SA}; do
  gcloud projects add-iam-policy-binding ${PROJECT_GOVERNANCE} \
    --member="serviceAccount:${SA}" \
    --role="roles/viewer" \
    --condition=None
done

# 6. grant aitplatform user on Sellers project to Concierge for cross-project A2A invocation
for MEMBER in "serviceAccount:${CONCIERGE_AI_SA}" "serviceAccount:${CONCIERGE_RE_SA}" "serviceAccount:${CONCIERGE_COMPUTE_SA}" "principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_CONCIERGE}"; do
  gcloud projects add-iam-policy-binding ${PROJECT_SELLERS} \
    --member="${MEMBER}" \
    --role="roles/aiplatform.user" \
    --condition=None
done

Đến đây là kết thúc quá trình thiết lập IAM trên nhiều dự án... tiếp theo là phần Triển khai các Đặc vụ bán hàng và Đặc vụ hỗ trợ.

7. Thời gian chạy của tác nhân

Triển khai Người bán và Nhân viên hỗ trợ

Cơ sở mã ứng dụng đa tác nhân và các tập lệnh triển khai đượ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, dọn dẹp các tệp tạm thời và cài đặt các phần phụ thuộc bằng uv.

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_multiproject

# copy multi-agent application files to current working directory
cp -r temp_agw_cuj_arun_multiproject/codelabs/agw-cuj-arun-multiproject ./cross-project-multiagent

# remove temporary directory
rm -rf temp_agw_cuj_arun_multiproject

# install dependencies
uv sync --directory ./cross-project-multiagent

Tạo Nhóm lưu trữ trung tâm dùng chung

# create shared central staging bucket
gcloud storage buckets create gs://${PROJECT_GOVERNANCE}-shared-staging \
  --project=${PROJECT_GOVERNANCE} \
  --location=${REGION}

# grant cross-project read/write access to runtime service agents
gcloud storage buckets add-iam-policy-binding gs://${PROJECT_GOVERNANCE}-shared-staging \
  --member="serviceAccount:service-${PROJECT_NUMBER_CONCIERGE}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

gcloud storage buckets add-iam-policy-binding gs://${PROJECT_GOVERNANCE}-shared-staging \
  --member="serviceAccount:service-${PROJECT_NUMBER_SELLERS}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

Cách hoạt động của tính năng liên kết Agent Gateway trên nhiều dự án

Ở bước này, bạn sẽ triển khai Seller Agent vào dự án vệ tinh (PROJECT_SELLERS) trong khi định cấu hình các Seller Agent để định tuyến lưu lượng truy cập đi qua Cổng Trung tâm của Agent trong PROJECT_GOVERNANCE:

# !-- for example purposes -- NOT a command to execute --!
# snippet from deploy_burger.py
burger_config = {
    "staging_bucket": staging_bucket_uri,
    "gcs_dir_name": "burger_agent",
    "display_name": "burger-seller-agent-adk",
    "identity_type": "AGENT_IDENTITY",
    "agent_gateway_config": {
        "agent_to_anywhere_config": {
            "agent_gateway": f"projects/{args.governance_project}/locations/{args.region}/agentGateways/{args.gateway}"
        }
    },
}
deployed_burger = client.agent_engines.create(agent=burger_playground, config=burger_config)

Vì Quy tắc 1 được thiết lập trước đó trong Chính sách truy cập hợp nhất của chúng tôi, nên các yêu cầu khởi tạo vùng chứa đối với Google Cloud API được phép thông qua cổng mà không bị gián đoạn.

Triển khai tác nhân bán bánh mì kẹp thịt và pizza cho PROJECT_SELLERS

# 1. deploy Burger Seller Agent to PROJECT_SELLERS
uv run --directory ./cross-project-multiagent python deploy_burger.py \
  --project=${PROJECT_SELLERS} \
  --region=${REGION} \
  --governance-project=${PROJECT_GOVERNANCE} \
  --gateway=projects/${PROJECT_GOVERNANCE}/locations/${REGION}/agentGateways/${AGW_NAME}

# 2. deploy Pizza Seller Agent to PROJECT_SELLERS
uv run --directory ./cross-project-multiagent python deploy_pizza.py \
  --project=${PROJECT_SELLERS} \
  --region=${REGION} \
  --governance-project=${PROJECT_GOVERNANCE} \
  --gateway=projects/${PROJECT_GOVERNANCE}/locations/${REGION}/agentGateways/${AGW_NAME}

Xác thực việc định tuyến Cổng người bán

# retrieve deployed seller reasoning engine IDs
export BURGER_ENGINE_ID=$(grep BURGER_SELLER_AGENT_ID cross-project-multiagent/burger_agent.env | awk -F'/' '{print $NF}')
export PIZZA_ENGINE_ID=$(grep PIZZA_SELLER_AGENT_ID cross-project-multiagent/pizza_agent.env | awk -F'/' '{print $NF}')

echo "Burger Engine ID: ${BURGER_ENGINE_ID}"
echo "Pizza Engine ID:  ${PIZZA_ENGINE_ID}"

# inspect runtime configuration for both Seller Agents
for ENGINE_ID in ${BURGER_ENGINE_ID} ${PIZZA_ENGINE_ID}; do
  curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_SELLERS}/locations/${REGION}/reasoningEngines/${ENGINE_ID}" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    | jq '{displayName: .displayName, identityType: .spec.identityType, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'
done

Triển khai Trợ lý mua hàng cho PROJECT_CONCIERGE

# deploy Purchasing Concierge to PROJECT_CONCIERGE
uv run --directory ./cross-project-multiagent python deploy_concierge_adk.py \
  --project=${PROJECT_CONCIERGE} \
  --region=${REGION} \
  --staging-bucket=gs://${PROJECT_GOVERNANCE}-shared-staging \
  --gateway-name=${AGW_NAME} \
  --gateway-project=${PROJECT_GOVERNANCE}

Xác thực hoạt động định tuyến cổng mua hàng

# retrieve Concierge engine ID
export CONCIERGE_ENGINE_ID=$(grep CONCIERGE_AGENT_ID cross-project-multiagent/concierge_agent.env | awk -F'/' '{print $NF}')
echo "Concierge Engine ID: ${CONCIERGE_ENGINE_ID}"

# inspect runtime configuration for Purchasing Concierge
curl -s -X GET "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  | jq '{displayName: .displayName, identityType: .spec.identityType, effectiveIdentity: .spec.effectiveIdentity, agentGatewayConfig: .spec.deploymentSpec.agentGatewayConfig}'

Đầu ra phải cho thấy danh tính thời gian chạy của Concierge agent và dự án cũng như mối liên kết với Agent Gateway của dự án Governance.

{
  "displayName": "purchasing-concierge-adk",
  "identityType": "AGENT_IDENTITY",
  "effectiveIdentity": "agents.global.org-${ORG_ID}.system.id.goog/resources/aiplatform/projects/${PROJECT_CONCIERGE}/locations/us-central1/reasoningEngines/${CONCIERGE_ENGINE_ID}",
  "agentGatewayConfig": {
    "agentToAnywhereConfig": {
      "agentGateway": "projects/${PROJECT_GOVERNANCE}/locations/us-central1/agentGateways/centralized-agw"
    }
  }
}

Đến đây là kết thúc phần triển khai tác nhân... tiếp theo là phần Đăng ký tác nhân trong Sổ đăng ký tác nhân trung tâm.

8. Sổ đăng ký trên nhiều dự án

Đăng ký tác nhân trong Sổ đăng ký tác nhân trung tâm

Đăng ký cả 3 tác nhân trong Central Agent Registry (Sổ đăng ký tác nhân trung tâm) ở PROJECT_GOVERNANCE bằng cách sử dụng các điểm cuối mTLS theo khu vực trên nhiều dự án và mã số dự án.

Đăng ký các dịch vụ làm tác nhân không phải A2A trong sổ đăng ký tác nhân

# 1. register Burger Seller Agent
gcloud agent-registry services create burger-seller-agent \
  --project=${PROJECT_GOVERNANCE} \
  --location=${REGION} \
  --display-name="Burger Seller Agent" \
  --description="Specialist agent that sells burgers and fries" \
  --agent-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.mtls.googleapis.com/v1/projects/${PROJECT_NUMBER_SELLERS}/locations/${REGION}/reasoningEngines/${BURGER_ENGINE_ID}:query \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.mtls.googleapis.com/v1beta1/projects/${PROJECT_NUMBER_SELLERS}/locations/${REGION}/reasoningEngines/${BURGER_ENGINE_ID}:query

# 2. register Pizza Seller Agent
gcloud agent-registry services create pizza-seller-agent \
  --project=${PROJECT_GOVERNANCE} \
  --location=${REGION} \
  --display-name="Pizza Seller Agent" \
  --description="Specialist agent that sells pizzas and pasta" \
  --agent-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.mtls.googleapis.com/v1/projects/${PROJECT_NUMBER_SELLERS}/locations/${REGION}/reasoningEngines/${PIZZA_ENGINE_ID}:query \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.mtls.googleapis.com/v1beta1/projects/${PROJECT_NUMBER_SELLERS}/locations/${REGION}/reasoningEngines/${PIZZA_ENGINE_ID}:query

# 3. register Purchasing Concierge Agent
gcloud agent-registry services create purchasing-concierge-adk \
  --project=${PROJECT_GOVERNANCE} \
  --location=${REGION} \
  --display-name="Purchasing Concierge Agent" \
  --description="Orchestrator concierge agent that routes purchasing requests" \
  --agent-spec-type=no-spec \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.mtls.googleapis.com/v1/projects/${PROJECT_NUMBER_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}:query \
  --interfaces=protocolBinding=JSONRPC,url=https://${REGION}-aiplatform.mtls.googleapis.com/v1beta1/projects/${PROJECT_NUMBER_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}:query

Lấy mã nhận dạng sổ đăng ký tác nhân cơ bản

# capture underlying Agent Registry Agent UUIDs
export BURGER_AGENT_ID=$(gcloud agent-registry services describe burger-seller-agent --project=${PROJECT_GOVERNANCE} --location=${REGION} --format="value(registryResource)" | awk -F'/' '{print $NF}')
export PIZZA_AGENT_ID=$(gcloud agent-registry services describe pizza-seller-agent --project=${PROJECT_GOVERNANCE} --location=${REGION} --format="value(registryResource)" | awk -F'/' '{print $NF}')
export CONCIERGE_AGENT_ID=$(gcloud agent-registry services describe purchasing-concierge-adk --project=${PROJECT_GOVERNANCE} --location=${REGION} --format="value(registryResource)" | awk -F'/' '{print $NF}')

echo "Burger Agent ID:    ${BURGER_AGENT_ID}"
echo "Pizza Agent ID:     ${PIZZA_AGENT_ID}"
echo "Concierge Agent ID: ${CONCIERGE_AGENT_ID}"

Đến đây là kết thúc phần cấu hình sổ đăng ký... tiếp theo là phần Định cấu hình chính sách truyền dữ liệu ra ngoài A2A.

9. Chính sách về UAP

Định cấu hình chính sách truyền dữ liệu ra bên ngoài A2A trong Chính sách truy cập hợp nhất

Trong cấu trúc Từ chối theo mặc định của Agent Gateway ở chế độ THI HÀNH nghiêm ngặt:

  1. Quy tắc 1 (API cơ bản của Google Cloud): Cho phép các vùng chứa tác nhân trên cả 3 dự án truy cập vào core-gapi-services.
  2. Quy tắc 2 (Tác nhân bán bánh kẹp: CHO PHÉP): Cho phép phiên bản Tác nhân hỗ trợ mua hàng cụ thể gọi Tác nhân bán bánh kẹp.
  3. Pizza Seller Agent (BỊ TỪ CHỐI theo mặc định): Cố ý không đưa vào các quy tắc của chính sách. Ở chế độ ENFORCE (failOpen: false), mọi nỗ lực của Concierge nhằm gọi Pizza Seller sẽ bị chấm dứt ngay lập tức tại chu vi cổng bằng HTTP 403 Forbidden.

Xây dựng danh tính của nhân viên hỗ trợ

# formulate the exact SPIFFE machine identity for the Concierge Agent
export CONCIERGE_SPIFFE_PRINCIPAL="principal://agents.global.org-${ORG_ID}.system.id.goog/resources/aiplatform/projects/${PROJECT_NUMBER_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}"
echo "Concierge SPIFFE Principal: ${CONCIERGE_SPIFFE_PRINCIPAL}"

Cập nhật tệp kê khai bằng quy tắc 1 và 2

Tạo cfg/uap-rules-update-2.json mới để thêm Quy tắc 1 (API cốt lõi) và giờ là Quy tắc 2 (Tác nhân bán bánh hamburger):

# create addendum to update policy manifest with Rule 2 for Burger Agent
cat > cfg/uap-rules-update-2.json << EOF
[
  {
    "description": "Rule 2: Allow Purchasing Concierge to invoke Burger Seller Agent via Central Gateway",
    "effect": "ALLOW",
    "principals": [
      "${CONCIERGE_SPIFFE_PRINCIPAL}"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true && \
         destination.agent_registry.resource_type == 'AGENT' && ( \
         destination.agent_registry.agent.name == 'projects/${PROJECT_GOVERNANCE}/locations/${REGION}/agents/burger-seller-agent' || \
         destination.agent_registry.agent.name == 'projects/${PROJECT_GOVERNANCE}/locations/${REGION}/agents/${BURGER_AGENT_ID}' || \
         destination.agent_registry.agent.name == 'projects/${PROJECT_NUMBER_GOVERNANCE}/locations/${REGION}/agents/${BURGER_AGENT_ID}')"
      }
    }
  }
]
EOF

Áp dụng chính sách truy cập mới

# update IAM access policy with Burger rule
gcloud iam access-policies update ${UAP_POLICY_NAME} \
  --add-details-rules=cfg/uap-rules-update-2.json \
  --project=${PROJECT_GOVERNANCE} \
  --location=global

Xác minh thông tin chi tiết về chính sách truy cập IAM

# inspect updated access policy
gcloud iam access-policies describe ${UAP_POLICY_NAME} \
  --project=${PROJECT_GOVERNANCE} \
  --location=global

Kết quả mẫu:

details:
  rules:
  - conditions:
      iap.googleapis.com:
        expression: destination.is_registered == true && destination.agent_registry.resource_type
          == 'ENDPOINT' && (destination.agent_registry.endpoint.name == 'projects/${PROJECT_GOVERNANCE}/locations/us-central1/endpoints/core-gapi-services'
          || destination.agent_registry.endpoint.name == 'projects/${PROJECT_NUMBER_GOVERNANCE}/locations/us-central1/endpoints/${ENDPOINT_ID}')
    description: 'Rule 1: Allow agent runtimes across all 3 projects to reach Core
      Google APIs'
    effect: ALLOW
    operation:
      permissions:
      - iap.googleapis.com/resources.egressViaIAP
    principals:
    - principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_GOVERNANCE}
    - principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_CONCIERGE}
    - principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_SELLERS}
  - conditions:
      iap.googleapis.com:
        expression: (destination.is_registered == true) && (destination.agent_registry.resource_type
          == 'AGENT') && (destination.agent_registry.agent.name == 'projects/${PROJECT_GOVERNANCE}/locations/us-central1/agents/burger-seller-agent'
          || destination.agent_registry.agent.name == 'projects/${PROJECT_NUMBER_GOVERNANCE}/locations/us-central1/agents/${BURGER_AGENT_ID}')
    description: 'Rule 2: Allow Purchasing Concierge to invoke Burger Seller Agent
      via Central Gateway'
    effect: ALLOW
    operation:
      permissions:
      - iap.googleapis.com/resources.egressViaIAP
    principals:
    - principal://agents.global.org-${ORG_ID}.system.id.goog/resources/aiplatform/projects/${PROJECT_NUMBER_CONCIERGE}/locations/us-central1/reasoningEngines/${CONCIERGE_ENGINE_ID}
name: projects/${PROJECT_GOVERNANCE}/locations/global/accessPolicies/uap-policy-centralized-agw

Đến đây là kết thúc phần thiết lập chính sách... tiếp theo là phần Kiểm thử và xác minh các chính sách quản trị.

10. Xác minh chính sách

Kiểm thử và xác minh các chính sách quản trị thông qua Cloud Logging

Trong phần này, bạn sẽ kiểm thử các hoạt động tương tác giữa các dự án (A2A) trong Agent Runtime AI Playground, quan sát hoạt động chặn HTTP 403 Forbidden theo chu vi thực ở chế độ ENFORCE nghiêm ngặt, sửa đổi Chính sách truy cập hợp nhất trực tiếp và xác thực việc phê duyệt đơn đặt hàng ngay lập tức.

Bước 1: Mở Agent Runtime AI Playground trong PROJECT_CONCIERGE

  1. Mở Google Cloud Console.
  2. Trong thanh bộ chọn dự án ở trên cùng, hãy chuyển sang PROJECT_CONCIERGE.
  3. Trong trình đơn điều hướng, hãy chuyển đến Agent Platform > Agents > Deployments (Nền tảng tác nhân > Tác nhân > Triển khai).
  4. Nhấp vào biểu tượng purchasing-concierge-adk.
  5. Chọn Sân chơi để mở giao diện trò chuyện tương tác ở bên phải màn hình.

Bước 2: Kiểm thử đơn đặt hàng bánh kẹp (Quy tắc 2 trùng khớp -> 200 OK)

Trong cửa sổ trò chuyện của Playground, hãy gửi câu lệnh đặt hàng sau:

I would like 10 Classic Cheeseburgers. Place this order now.

Nếu cần có phản hồi xác nhận, hãy gửi câu trả lời sau:

Confirmed, please place the order.

Ngoài ra, hãy kiểm thử theo phương thức lập trình từ Cloud Shell / thiết bị đầu cuối:

uv run --directory ./cross-project-multiagent python -c "
import vertexai
from vertexai.preview import reasoning_engines
vertexai.init(project='${PROJECT_CONCIERGE}', location='${REGION}')
agent = reasoning_engines.ReasoningEngine('projects/${PROJECT_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}')
response = agent.query(input={'message': 'I would like 22 Spicy Cajun Burgers please. Place this order now.'})
print(response)
"

Nếu cần phản hồi xác nhận, hãy dùng lệnh sau:

uv run --directory ./cross-project-multiagent python -c "
import vertexai
from vertexai.preview import reasoning_engines
vertexai.init(project='${PROJECT_CONCIERGE}', location='${REGION}')
agent = reasoning_engines.ReasoningEngine('projects/${PROJECT_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}')
response = agent.query(input='Yes please place the order now.')
print(response['text'])
"

Điều gì xảy ra ở hậu trường:

  1. Khám phá linh hoạt: Trong quá trình khởi động phiên, Trợ lý mua hàng đã truy vấn Sổ đăng ký tác nhân trung tâm trong PROJECT_GOVERNANCE (thông qua core-gapi-services thông qua Cổng tác nhân được uỷ quyền theo Quy tắc 1) để khám phá điểm cuối mTLS theo khu vực cho burger-seller-agent.
  2. Phân giải ý định và lệnh gọi A2A: Gemini trong Trợ lý mua hàng sẽ phân tích ý định đặt món ăn và gọi Tác nhân bán bánh hamburger thông qua một RPC đi ra https://${REGION}-aiplatform.mtls.googleapis.com/.../reasoningEngines/${BURGER_ENGINE_ID}.
  3. Chặn cổng và truyền SPIFFE: Lưu lượng truy cập đi ra được agent_gateway_config ghi lại và chuyển đến Cổng tác nhân trung tâm trong PROJECT_GOVERNANCE, mang theo danh tính SPIFFE mã hoá của Concierge (principal://...).
  4. Đánh giá chính sách IAP phiên bản 2: Central Agent Gateway gọi tiện ích uỷ quyền IAP (authzExtension). IAP phiên bản 2 đánh giá Quy tắc 2 trong Chính sách truy cập thống nhất IAM. Vì phương thức gọi khớp với ${CONCIERGE_SPIFFE_PRINCIPAL} và đích khớp với burger-seller-agent, nên IAP trả về ALLOW (granted: true).
  5. Thực thi trên nhiều dự án: Agent Gateway sẽ uỷ quyền yêu cầu trên nhiều dự án vào PROJECT_SELLERS, nơi Burger Seller Reasoning Engine xử lý đơn đặt hàng và trả về thông tin xác nhận.

Phản hồi dự kiến:

Your order for 10 Classic Cheeseburger(s) has been placed!
Here is a summary of your order:
- 10x Classic Cheeseburger @ IDR 85,000/each = IDR 850,000

Total: IDR 850,000
Your Order ID is: e8f9c732-f347-4cc4-acff-cfe09ccbeddd

Bước 3: Kiểm tra Nhật ký kiểm tra Cổng đại lý và IAP phiên bản 2 (HTTP 200 / ALLOWED)

Truy vấn nhật ký yêu cầu Agent Gateway trong PROJECT_GOVERNANCE:

# query Agent Gateway logs for successful 200 OK requests
gcloud logging read "
  logName=\"projects/${PROJECT_GOVERNANCE}/logs/networkservices.googleapis.com%2Fgateway_requests\"
  AND jsonPayload.authzPolicyInfo.result=\"ALLOWED\"
" \
  --project="${PROJECT_GOVERNANCE}" \
  --limit=10 \
  --format="table(
    timestamp.date('%H:%M:%S'):label=TIME,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ,
    httpRequest.requestUrl:label=URL
  )"

Nhật ký phải ghi lại lưu lượng truy cập đi bắt nguồn từ cả hai dự án vệ tinh (PROJECT_CONCIERGE và PROJECT_SELLERS) có các trường xuất dữ liệu cho các lệnh gọi suy luận của Gemini (generateContent), số liệu đo từ xa của Cloud Trace (/v1/traces) và các lệnh tra cứu thông tin đăng nhập IAM – được Quy tắc 1 (core-gapi-services) chặn và uỷ quyền một cách minh bạch.

Truy vấn nhật ký kiểm tra quyền truy cập dữ liệu trên Cloud IAP phiên bản 2 để xác minh phiên bản chính sách POLICY_VERSION_V2:

# query IAP v2 audit logs with shortened principal and resource fields
gcloud logging read "
  logName=\"projects/${PROJECT_GOVERNANCE}/logs/cloudaudit.googleapis.com%2Fdata_access\"
  AND protoPayload.serviceName=\"iap.googleapis.com\"
" \
  --project="${PROJECT_GOVERNANCE}" \
  --limit=5 \
  --format="table(
    timestamp.date('%H:%M:%S'):label=TIME,
    protoPayload.authenticationInfo.principalSubject.sub('\.global\..*\/reasoningEngines\/', '.[...]/reasoningEngines/'):label=CALLER,
    protoPayload.authorizationInfo[0].granted:label=GRANTED,
    protoPayload.metadata.destination.agent_registry.resource_type.basename():label=TYPE,
    protoPayload.metadata.destination.agent_registry.resource_id.basename():label=RESOURCE_ID,
    protoPayload.authorizationInfo[0].permission.basename():label=PERMISSION
  )"

Kết quả mẫu:

TIME      CALLER                                                            GRANTED  TYPE      RESOURCE_ID     PERMISSION
HH:MM:SS  principal://agents.[...]/reasoningEngines/${CONCIERGE_ENGINE_ID}  True     Endpoint  ${ENDPOINT_ID}  resources.egressViaIAP
HH:MM:SS  principal://agents.[...]/reasoningEngines/${BURGER_ENGINE_ID}     True     Endpoint  ${ENDPOINT_ID}  resources.egressViaIAP
HH:MM:SS  principal://agents.[...]/reasoningEngines/${CONCIERGE_ENGINE_ID}  True     Endpoint  ${ENDPOINT_ID}  resources.egressViaIAP
HH:MM:SS  principal://agents.[...]/reasoningEngines/${BURGER_ENGINE_ID}     True     Endpoint  ${ENDPOINT_ID}  resources.egressViaIAP

Bước 4: Kiểm thử Đặt hàng pizza (Từ chối theo mặc định -> HTTP 403 BỊ CẤM)

Trong cùng cửa sổ trò chuyện của Playground, hãy gửi câu lệnh đặt hàng pizza sau:

I would like 10 BBQ Chicken Pizzas. Place this order now.

Nếu cần có phản hồi xác nhận, hãy gửi câu trả lời sau:

Confirmed, please place the order.

Ngoài ra, hãy kiểm thử theo phương thức lập trình từ Cloud Shell / thiết bị đầu cuối:

uv run --directory ./cross-project-multiagent python -c "
import vertexai
from vertexai.preview import reasoning_engines
vertexai.init(project='${PROJECT_CONCIERGE}', location='${REGION}')
agent = reasoning_engines.ReasoningEngine('projects/${PROJECT_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}')
response = agent.query(input='I would like 8 Hawaiian pizzas, please. Place this order now.')
print(response)
"

Nếu cần phản hồi xác nhận, hãy dùng lệnh sau:

uv run --directory ./cross-project-multiagent python -c "
import vertexai
from vertexai.preview import reasoning_engines
vertexai.init(project='${PROJECT_CONCIERGE}', location='${REGION}')
agent = reasoning_engines.ReasoningEngine('projects/${PROJECT_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}')
response = agent.query(input='Yes please place the order now.')
print(response['text'])
"

Phản hồi dự kiến:

I apologize, but I am unable to process that request at the moment. It seems
there was an issue connecting to the pizza seller agent. Please try again later.

Điều gì xảy ra ở hậu trường:

  1. Khám phá linh động: Tác nhân hỗ trợ mua hàng đã phân giải điểm cuối pizza-seller-agent từ Central Agent Registry trong quá trình khởi động.
  2. Phân giải ý định và lệnh gọi A2A: Gemini trong Trợ lý mua hàng sẽ cố gắng gửi yêu cầu đặt hàng bánh pizza đến điểm cuối của Người bán bánh pizza trong PROJECT_SELLERS.
  3. Chặn cổng: RPC đi ra được agent_gateway_config ghi lại và chuyển đến Cổng tác nhân trung tâm.
  4. Đánh giá chính sách IAP phiên bản 2 (Từ chối theo mặc định): Central Agent Gateway sẽ gọi IAP phiên bản 2. Vì không có quy tắc nào trong Chính sách truy cập thống nhất khớp với pizza-seller-agent, nên IAP sẽ trả về DENY (granted: false).
  5. Chặn nghiêm ngặt theo chu vi: Vì Tiện ích Authz ở chế độ THỰC THI (failOpen: false), nên Cổng tác nhân trung tâm sẽ ngay lập tức chấm dứt kết nối đi và trả về HTTP 403 Forbidden. Lưu lượng truy cập không bao giờ rời khỏi cổng và không bao giờ đến được PROJECT_SELLERS.

Bước 5: Kiểm tra nhật ký Cổng đại lý để biết các yêu cầu bị chặn (HTTP 403 / DENIED)

# query Agent Gateway logs for blocked 403 requests
gcloud logging read "
  logName=\"projects/${PROJECT_GOVERNANCE}/logs/networkservices.googleapis.com%2Fgateway_requests\"
  AND httpRequest.status=403
" \
  --project="${PROJECT_GOVERNANCE}" \
  --limit=5 \
  --format="table(
    timestamp.date('%H:%M:%S'):label=TIME,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ,
    httpRequest.requestUrl:label=URL
  )"

Đầu ra nhật ký bị từ chối mẫu:

TIME      METHOD  STATUS  AUTHZ   URL
HH:MM:SS  POST    403     DENIED  https://us-central1-aiplatform.mtls.googleapis.com/v1beta1/projects/${PROJECT_SELLERS}/locations/us-central1/reasoningEngines/${PIZZA_ENGINE_ID}:query

Truy vấn nhật ký kiểm tra quyền truy cập dữ liệu IAP phiên bản 2 cho quyết định bị từ chối:

# query IAP v2 audit logs with shortened principal and resource fields
gcloud logging read "
  logName=\"projects/${PROJECT_GOVERNANCE}/logs/cloudaudit.googleapis.com%2Fdata_access\"
  AND protoPayload.serviceName=\"iap.googleapis.com\"
" \
  --project="${PROJECT_GOVERNANCE}" \
  --limit=5 \
  --format="table(
    timestamp.date('%H:%M:%S'):label=TIME,
    protoPayload.authenticationInfo.principalSubject.sub('\.global\..*\/reasoningEngines\/', '.[...]/reasoningEngines/'):label=CALLER,
    protoPayload.authorizationInfo[0].granted:label=GRANTED,
    protoPayload.metadata.destination.agent_registry.resource_type.basename():label=TYPE,
    protoPayload.metadata.destination.agent_registry.resource_id.basename():label=RESOURCE_ID,
    protoPayload.authorizationInfo[0].permission.basename():label=PERMISSION
  )"

Đầu ra mẫu của Nhật ký kiểm tra bị từ chối:

TIME      CALLER                                                            GRANTED  TYPE      RESOURCE_ID     PERMISSION
HH:MM:SS  principal://agents.[...]/reasoningEngines/${PIZZA_ENGINE_ID}      True     Endpoint  ${REGISTRY_ID}  resources.egressViaIAP
HH:MM:SS  principal://agents.[...]/reasoningEngines/${PIZZA_ENGINE_ID}      True     Endpoint  ${REGISTRY_ID}  resources.egressViaIAP
HH:MM:SS  principal://agents.[...]/reasoningEngines/${CONCIERGE_ENGINE_ID}  False    Agent     ${REGISTRY_ID}  resources.egressViaIAP
HH:MM:SS  principal://agents.[...]/reasoningEngines/${PIZZA_ENGINE_ID}      True     Endpoint  ${REGISTRY_ID}  resources.egressViaIAP

Bước 6: Cấp quyền truy cập đầu ra cho Pizza Agent một cách linh hoạt

Tạo cfg/uap-rules-update-3.json mới để thêm Quy tắc 1 (API cốt lõi), Quy tắc 2 (Tác nhân bán bánh kẹp) và giờ là Quy tắc 3 (Tác nhân bán bánh pizza)

# create addendum to update policy manifest with Rule 3 for Pizza Agent
cat > cfg/uap-rules-update-3.json << EOF
[
  {
    "description": "Rule 3: Allow Purchasing Concierge to invoke Pizza Seller Agent via Central Gateway",
    "effect": "ALLOW",
    "principals": [
      "${CONCIERGE_SPIFFE_PRINCIPAL}"
    ],
    "operation": {
      "permissions": [
        "iap.googleapis.com/resources.egressViaIAP"
      ]
    },
    "conditions": {
      "iap.googleapis.com": {
        "expression": \
        "destination.is_registered == true && \
         destination.agent_registry.resource_type == 'AGENT' && ( \
         destination.agent_registry.agent.name == 'projects/${PROJECT_GOVERNANCE}/locations/${REGION}/agents/pizza-seller-agent' || \
         destination.agent_registry.agent.name == 'projects/${PROJECT_GOVERNANCE}/locations/${REGION}/agents/${PIZZA_AGENT_ID}' || \
         destination.agent_registry.agent.name == 'projects/${PROJECT_NUMBER_GOVERNANCE}/locations/${REGION}/agents/${PIZZA_AGENT_ID}')"
      }
    }
  }
]
EOF

Áp dụng nội dung cập nhật chính sách ngay lập tức:

# update IAM access policy with Pizza rule
gcloud iam access-policies update ${UAP_POLICY_NAME} \
  --add-details-rules=cfg/uap-rules-update-3.json \
  --project=${PROJECT_GOVERNANCE} \
  --location=global

Bước 7: Truy vấn lại Pizza Agent (Thành công ngay lập tức với mã 200 OK)

Trong cửa sổ trò chuyện của Playground, hãy gửi lại câu lệnh đặt bánh pizza:

I would like 10 BBQ Chicken Pizzas. Place this order now.

Nếu cần có phản hồi xác nhận, hãy gửi câu trả lời sau:

Confirmed, please place the order.

Ngoài ra, hãy kiểm thử theo phương thức lập trình từ Cloud Shell / thiết bị đầu cuối:

uv run --directory ./cross-project-multiagent python -c "
import vertexai
from vertexai.preview import reasoning_engines
vertexai.init(project='${PROJECT_CONCIERGE}', location='${REGION}')
agent = reasoning_engines.ReasoningEngine('projects/${PROJECT_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}')
response = agent.query(input='I would like 11 Veggie pizzas, please. Place this order now.')
print(response)
"

Nếu cần phản hồi xác nhận, hãy dùng lệnh sau:

uv run --directory ./cross-project-multiagent python -c "
import vertexai
from vertexai.preview import reasoning_engines
vertexai.init(project='${PROJECT_CONCIERGE}', location='${REGION}')
agent = reasoning_engines.ReasoningEngine('projects/${PROJECT_CONCIERGE}/locations/${REGION}/reasoningEngines/${CONCIERGE_ENGINE_ID}')
response = agent.query(input='Yes please place the order now.')
print(response['text'])
"

Phản hồi dự kiến:

Your order has been placed!

**Order ID:** 8d6c13d7-31dc-4d80-b6a7-80d1e50b6411

**Order Details:**
*   10 x BBQ Chicken Pizza @ IDR 130,000 each = IDR 1,300,000

**Total: IDR 1,300,000**

Điều gì xảy ra ở hậu trường:

  1. Làm mới chính sách linh hoạt: Việc cập nhật Chính sách truy cập hợp nhất IAM có hiệu lực ngay lập tức trong công cụ đánh giá IAP mà không bị thời gian ngừng hoạt động và không cần triển khai lại bất kỳ vùng chứa nào.
  2. Lời gọi A2A: Concierge gửi yêu cầu thông qua Cổng tác nhân trung tâm.
  3. Đánh giá chính sách IAP phiên bản 2 (Phê duyệt): IAP phiên bản 2 khớp với Quy tắc 3, xác minh danh tính của phương thức gọi và biểu thức CEL mục tiêu, đồng thời trả về ALLOW (granted: true).
  4. Thực thi trên nhiều dự án: Central Agent Gateway chuyển lưu lượng truy cập được uỷ quyền vào PROJECT_SELLERS, nơi Pizza Seller xử lý đơn đặt hàng.

Bước 8: Kiểm tra nhật ký Cổng đại lý để biết các yêu cầu được cấp về pizza

# query Agent Gateway logs for successful 200 OK requests
gcloud logging read "
  logName=\"projects/${PROJECT_GOVERNANCE}/logs/networkservices.googleapis.com%2Fgateway_requests\"
  AND jsonPayload.authzPolicyInfo.result=\"ALLOWED\"
" \
  --project="${PROJECT_GOVERNANCE}" \
  --limit=10 \
  --format="table(
    timestamp.date('%H:%M:%S'):label=TIME,
    httpRequest.requestMethod:label=METHOD,
    httpRequest.status:label=STATUS,
    jsonPayload.authzPolicyInfo.result:label=AUTHZ,
    httpRequest.requestUrl:label=URL
  )"

Đầu ra nhật ký được cấp mẫu:

TIME      METHOD  STATUS  AUTHZ    URL
HH:MM:SS  POST    200     ALLOWED  https://us-central1-aiplatform.mtls.googleapis.com/v1beta1/projects/${PROJECT_SELLERS}/locations/us-central1/publishers/google/models/gemini-2.5-flash:generateContent
HH:MM:SS  POST    200     ALLOWED  https://us-central1-aiplatform.mtls.googleapis.com/v1beta1/projects/${PROJECT_SELLERS}/locations/us-central1/reasoningEngines/${PIZZA_ENGINE_ID}:query

Đến đây là kết thúc quá trình kiểm thử và xác minh... tiếp theo là phần Dọn dẹp.

11. Dọn dẹp

Để tránh phát sinh phí cho tài khoản Google Cloud của bạn đối với các tài nguyên được dùng trong Lớp học lập trình này, hãy thực hiện các bước tháo dỡ theo đúng thứ tự phụ thuộc ngược:

1. Dọn dẹp các hoạt động triển khai Reasoning Engine

Thực thi tập lệnh cleanup_old_deployments.py đi kèm trên cả hai dự án thời gian chạy để xoá các công cụ suy luận và chờ các thao tác diễn ra trong thời gian dài của chúng:

# delete all Reasoning Engines deployed in Concierge and Sellers projects
uv run --directory ./cross-project-multiagent python cleanup_old_deployments.py --project=${PROJECT_CONCIERGE} --region=${REGION}
uv run --directory ./cross-project-multiagent python cleanup_old_deployments.py --project=${PROJECT_SELLERS} --region=${REGION}

Ngoài ra, bạn có thể liệt kê và xoá các công cụ suy luận nội tuyến:

uv run --directory ./cross-project-multiagent python -c '
import vertexai
import os
from vertexai.preview import reasoning_engines

region = os.environ.get("REGION", "us-central1")
for proj in [os.environ.get("PROJECT_CONCIERGE"), os.environ.get("PROJECT_SELLERS")]:
    if not proj:
        continue
    print(f"Cleaning reasoning engines in {proj}...")
    vertexai.init(project=proj, location=region)
    for eng in reasoning_engines.ReasoningEngine.list():
        print(f"  Deleting {eng.resource_name} ({eng.display_name})...")
        eng.delete()
'

2. Xoá các dịch vụ đăng ký tác nhân

# delete agent registry services in Central Governance Project
for SERVICE in burger-seller-agent pizza-seller-agent purchasing-concierge-adk core-gapi-services; do
  gcloud agent-registry services delete ${SERVICE} \
    --project=${PROJECT_GOVERNANCE} \
    --location=${REGION} \
    --quiet || true
done

3. Xoá Liên kết chính sách truy cập hợp nhất và Chính sách truy cập IAM

# 1. delete IAM policy binding
gcloud -q iam policy-bindings delete ${UAP_BINDING_NAME} \
  --project=${PROJECT_GOVERNANCE} \
  --location=global || true

# 2. delete IAM access policy
gcloud -q iam access-policies delete ${UAP_POLICY_NAME} \
  --project=${PROJECT_GOVERNANCE} \
  --location=global || true

4. Xoá Cổng tác nhân và Chính sách bảo mật

# 1. delete authorization policy
gcloud beta network-security authz-policies delete ${AGW_NAME}-authz-policy-profile-iap \
  --location=${REGION} \
  --project=${PROJECT_GOVERNANCE} --quiet || true

# 2. delete authorization extension
gcloud service-extensions authz-extensions delete ${AGW_NAME}-svc-ext-authz-iap \
  --location=${REGION} \
  --project=${PROJECT_GOVERNANCE} --quiet || true

# 3. delete agent gateway
gcloud network-services agent-gateways delete ${AGW_NAME} \
  --project=${PROJECT_GOVERNANCE} \
  --location=${REGION} --quiet || true

5. Xoá các mối liên kết IAM trên nhiều dự án và vai trò tuỳ chỉnh

# 1. remove custom role and network viewer bindings for spoke service agents
for NUM in "${PROJECT_NUMBER_CONCIERGE}" "${PROJECT_NUMBER_SELLERS}"; do
  SA="service-${NUM}@gcp-sa-aiplatform.iam.gserviceaccount.com"
  
  gcloud projects remove-iam-policy-binding ${PROJECT_GOVERNANCE} \
    --member="serviceAccount:${SA}" \
    --role="projects/${PROJECT_GOVERNANCE}/roles/ar_agw_cross_project_sa" --quiet || true

  gcloud projects remove-iam-policy-binding ${PROJECT_GOVERNANCE} \
    --member="serviceAccount:${SA}" \
    --role="roles/networkservices.viewer" --quiet || true
done

# 2. remove registry viewer permissions across both spoke projects
for NUM in "${PROJECT_NUMBER_CONCIERGE}" "${PROJECT_NUMBER_SELLERS}"; do
  for MEMBER in \
    "serviceAccount:service-${NUM}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
    "serviceAccount:service-${NUM}@gcp-sa-aiplatform-re.iam.gserviceaccount.com" \
    "serviceAccount:${NUM}-compute@developer.gserviceaccount.com" \
    "principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${NUM}"; do
      gcloud projects remove-iam-policy-binding ${PROJECT_GOVERNANCE} \
        --member="${MEMBER}" \
        --role="roles/agentregistry.viewer" --quiet || true
  done
done

# 3. remove project viewer permissions
for MEMBER in \
  "serviceAccount:${PROJECT_NUMBER_CONCIERGE}-compute@developer.gserviceaccount.com" \
  "serviceAccount:service-${PROJECT_NUMBER_CONCIERGE}@gcp-sa-aiplatform.iam.gserviceaccount.com"; do
    gcloud projects remove-iam-policy-binding ${PROJECT_GOVERNANCE} \
      --member="${MEMBER}" \
      --role="roles/viewer" --quiet || true
done

# 4. remove spoke-to-spoke delegation in Sellers project
for MEMBER in \
  "serviceAccount:service-${PROJECT_NUMBER_CONCIERGE}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  "serviceAccount:service-${PROJECT_NUMBER_CONCIERGE}@gcp-sa-aiplatform-re.iam.gserviceaccount.com" \
  "serviceAccount:${PROJECT_NUMBER_CONCIERGE}-compute@developer.gserviceaccount.com" \
  "principalSet://agents.global.org-${ORG_ID}.system.id.goog/attribute.platformContainer/aiplatform/projects/${PROJECT_NUMBER_CONCIERGE}"; do
    gcloud projects remove-iam-policy-binding ${PROJECT_SELLERS} \
      --member="${MEMBER}" \
      --role="roles/aiplatform.user" --quiet || true
done

# 5. delete custom IAM role after all bindings have been unlinked
gcloud iam roles delete ar_agw_cross_project_sa \
  --project=${PROJECT_GOVERNANCE} --quiet || true

Nếu bạn đã chỉ định roles/iam.accessPolicyAdmin và roles/resourcemanager.projectIamAdmin trong giai đoạn Thiết lập, hãy xoá các quyền này khỏi tài khoản người dùng đang hoạt động để khôi phục đặc quyền tối thiểu:

# 6. remove Access Policy Admin and Project IAM Admin roles from user
for ROLE in "roles/iam.accessPolicyAdmin" "roles/resourcemanager.projectIamAdmin"; do
  gcloud projects remove-iam-policy-binding ${PROJECT_GOVERNANCE} \
    --member="user:$(gcloud config get-value account)" \
    --role="${ROLE}" \
    --condition=None --quiet || true
done

6. Quay lại chế độ ghi nhật ký Dữ liệu kiểm tra và các ràng buộc về Chính sách của tổ chức

# 1. Export current Central Governance IAM policy
gcloud projects get-iam-policy ${PROJECT_GOVERNANCE} --format=json > cfg/gov_iam_policy.json

# 2. Filter out iap.googleapis.com from auditConfigs
python3 -c "
import json
with open('cfg/gov_iam_policy.json') as f:
    policy = json.load(f)

if 'auditConfigs' in policy:
    # Remove iap.googleapis.com; if nothing else remains, clear the list
    policy['auditConfigs'] = [
        ac for ac in policy['auditConfigs'] if ac.get('service') != 'iap.googleapis.com'
    ]

with open('cfg/gov_iam_policy.json', 'w') as f:
    json.dump(policy, f, indent=2)
"

# 3. Apply the updated policy to revert audit logging to default
gcloud projects set-iam-policy ${PROJECT_GOVERNANCE} cfg/gov_iam_policy.json

7. Huỷ bỏ các giới hạn của Chính sách tổ chức

# revert iam v3 access policy binding org policy on project to org level setting
gcloud org-policies delete iam.managed.disableAccessPolicyBinding --project=${PROJECT_GOVERNANCE}

8. Xoá Nhóm lưu trữ tạm thời GCS dùng chung và các cấu phần phần mềm cục bộ

# delete central staging bucket
gcloud storage rm -r gs://${PROJECT_GOVERNANCE}-shared-staging

# remove local configuration manifests, environment files, and application
rm -rf cfg/ cross-project-multiagent/ *.env

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

12. Kết luận

Xin chúc mừng! Bạn đã triển khai và quản lý một kiến trúc Agent-to-Agent (A2A) gồm nhiều dự án trên Google Cloud bằng cách sử dụng Vertex AI Agent Runtime, Central Agent Gateway, Agent Registry và Chính sách truy cập hợp nhất (UAP) của IAM.

Tóm tắt các khái niệm chính

  • Ranh giới thoát tập trung: Định tuyến các vùng chứa thời gian chạy của nhánh (PROJECT_CONCIERGE, PROJECT_SELLERS) thông qua một Cổng đại lý trung tâm trong PROJECT_GOVERNANCE bằng cách sử dụng agentGatewayConfig.
  • Quản trị khai báo (UAP): Thay thế các liên kết rời rạc theo từng tài nguyên bằng một Chính sách truy cập IAM duy nhất, có thể kiểm tra được và được IAP phiên bản 2 đánh giá tại cổng.
  • Danh tính mật mã: Thực thi quyền truy cập tối thiểu bằng cách sử dụng danh tính SPIFFE của vùng chứa (principal://...) thay vì các khoá tồn tại lâu dài.
  • Khám phá dịch vụ linh động: Giải quyết các điểm cuối của tác nhân ngang hàng tại thời gian chạy thông qua Central Agent Registry, loại bỏ các URL và mã dự án được cố định giá trị trong mã.
  • Tính linh hoạt của chính sách thời gian chạy: Chuyển đổi pizza-seller-agent từ Từ chối theo mặc định (403 Forbidden) sang Cho phép (200 OK) theo thời gian thực thông qua việc cập nhật chính sách mà không cần khởi động lại vùng chứa.

cosmopup

Cosmopup nói: "Các tác nhân rất hữu ích. Chúng thực hiện mọi công việc trên nhiều dự án trong khi tôi tập trung vào mục tiêu chính của mình: ngủ trưa!"

Các bước tiếp theo và tài liệu