使用 Agent Gateway 治理智能体

Agent Gateway 可让您管理在 Cloud Run 上构建和托管的 AI 智能体的出站流量。通过将 Cloud Run 服务的出站流量路由到在Secure Web Proxy上运行的自行管理的 Agent Gateway，您可以强制执行集中式访问权限政策、检查载荷的内容安全性，并收集智能体工作负载的可观测性遥测数据。

本文档介绍了如何为 Cloud Run 上的 Agent Gateway 配置集中式架构，并介绍了如何执行以下操作：

架构

在集中式自行管理部署中，Secure Web Proxy 充当政策执行点，并在 Virtual Private Cloud (VPC) 网络中运行。Ambient Networking 边车容器会拦截来自 Cloud Run 代理的出站流量，并通过直接 VPC 出站流量将其路由到 Secure Web Proxy 实例。Secure Web Proxy 会强制执行来自 Identity-Aware Proxy (IAP) 和 Model Armor 等政策决策点的访问和内容规则。

架构图，展示了 Cloud Run 服务，其中包含智能体容器和环境边车代理容器，通过直接 VPC 出站流量将流量路由到 VPC 网络中由 Secure Web Proxy 支持的自行管理的 Agent Gateway。
图 1. Cloud Run 智能体的自行管理 Agent Gateway 架构。

如需在此架构中路由和治理流量，您需要配置以下组件：

  • 直接 VPC 出站流量和 Ambient Networking：您的 Cloud Run 服务通过 --vpc-egress=all 和 --ambient-networking 连接到 VPC 网络，默认情况下使用区域范围，并将所有出站流量路由到 VPC 网络。
  • 自行管理的 Agent Gateway：自行管理模式下的逻辑 Agent Gateway 资源指向 VPC 网络中的 Secure Web Proxy 实例。
  • 出站流量路由政策：Network Services API EgressRouting 政策会将出站流量从 Cloud Run 服务定向到 Secure Web Proxy 实例。

准备工作

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Install the Google Cloud CLI.

  4. Configure the gcloud CLI to use your federated identity.

    For more information, see Sign in to the gcloud CLI with your federated identity.

  5. To initialize the gcloud CLI, run the following command: 

    gcloud init

  6. 启用 Cloud Run Admin API、Network Services API、网络安全 API、Service Extensions API、Model Armor API、Certificate Authority Service API、Certificate Manager API、Cloud Resource Manager API、App Hub API、Identity and Access Management API、Identity-Aware Proxy API、Compute Engine API、Traffic Director API、Cloud DNS API、Network Connectivity API 和 Agent Registry API（如果尚未启用）。

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    启用 API

  7. 创建 VPC 网络和子网，并在子网上启用专用 Google 访问通道。
  8. 在您的项目或组织中设置 Agent Registry。
  9. 安装并初始化 Google Cloud CLI。
  10. 更新 gcloud CLI 组件： 
    gcloud components update

所需的角色

如需获得为 Cloud Run 配置 Agent Gateway 所需的权限，请让管理员向您授予项目的以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如果您使用共享 VPC 配置跨项目部署，请让管理员在组织或文件夹级层向您授予 roles/compute.xpnAdmin。

创建自行管理的 Agent Gateway

在创建 Agent Gateway 资源之前，请按照将 Secure Web Proxy 部署为 Agent Gateway 中的说明，在 VPC 网络中部署和配置 Secure Web Proxy 实例：

  1. 设置 TLS 检查并创建网关安全政策，以附加您的 TlsInspectionPolicy。您不需要 Secure Web Proxy 安全政策规则或网址列表。
  2. 使用 allowOpen: false 和 mtlsPolicy.clientValidationMode: ALLOW_INVALID_OR_MISSING_CLIENT_CERT 创建 ServerTlsPolicy 资源。 请勿设置 clientValidationTrustConfig。
  3. 在显式代理路由模式下部署 Secure Web Proxy 实例，并在创建网关时配置 addresses、ports、certificateUrls、gatewaySecurityPolicy 和 serverTlsPolicy，以便 Cloud Run 通过 mTLS 将代理的 Workload Identity 传递给 Secure Web Proxy 和 IAP。

Secure Web Proxy 实例准备就绪后，创建一个指向 Secure Web Proxy 实例的自行管理的 Agent Gateway 资源：

  1. 创建一个名为 my-agent-gateway.yaml 的 YAML 配置文件：

    name: AGENT_GATEWAY_NAME
registries:
  - "//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION"
selfManaged:
  resourceUris:
    - "projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME"

    替换以下内容：

    • AGENT_GATEWAY_NAME：您要分配给 Agent Gateway 资源的名称。
    • PROJECT_ID：托管 Secure Web Proxy 实例的项目 ID。
    • REGION：您的 Secure Web Proxy 实例的区域，例如 us-central1。
    • SWP_NAME：Secure Web Proxy 实例的名称。

  2. 导入 Agent Gateway 配置：

    gcloud beta network-services agent-gateways import AGENT_GATEWAY_NAME \
   --source="my-agent-gateway.yaml" \
   --location=REGION \
   --project=PROJECT_ID

  3. 验证 Agent Gateway 资源：

    gcloud beta network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID

    在继续执行下一部分之前，请确认输出显示您的 selfManaged 配置和 Secure Web Proxy 实例的资源 URI。

配置 Cloud Run Ambient Networking 以访问 Traffic Director API

当您为 Cloud Run 服务配置直接 VPC 出站流量和 --vpc-egress=all 时，来自容器实例的所有出站连接都会通过 VPC 网络进行路由。这包括与 trafficdirector.REGION.rep.googleapis.com 的 Envoy 边车连接。

如需让边车解析并访问 Traffic Director API，请根据您的环境是否使用 VPC Service Controls，在 VPC 网络中配置专用 Cloud DNS 区域：

不使用 VPC Service Controls

如果您的项目不使用 VPC Service Controls，请创建一个专用 Cloud DNS 区域，将对 trafficdirector.REGION.rep.googleapis.com 的请求路由到 Secure Web Proxy 网关 IP 地址，以便 Secure Web Proxy 允许流量通过：

  1. 检索 Secure Web Proxy 网关的内部 IP 地址：

    SWP_IP=$(gcloud network-services gateways describe SWP_NAME \
 --project="PROJECT_ID" \
 --location="REGION" \
 --format="value(addresses[0])")

    替换以下内容：

    • SWP_NAME：Secure Web Proxy 实例的名称。
    • PROJECT_ID：您的 Google Cloud 项目 ID。
    • REGION：部署所在的区域。

  2. 为 Traffic Director API 创建专用 Cloud DNS 托管式区域：

    gcloud dns managed-zones create td-swp-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone routing control plane traffic to SWP" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

    将 VPC_NETWORK_NAME 替换为您的 VPC 网络名称。

  3. 添加一条 A 记录，将 Traffic Director API 区域网域指向您的 Secure Web Proxy IP 地址：

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-swp-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${SWP_IP}"

  4. 验证 DNS 记录集在专用区域中是否处于活跃状态：

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-swp-zone"

    确认 trafficdirector.REGION.rep.googleapis.com. 的 A 记录解析为您的 Secure Web Proxy IP 地址。

使用 VPC Service Controls

对于 VPC Service Controls 环境，请在 VPC 子网内预配一个以区域级 Traffic Director API 为目标的 Private Service Connect 区域级端点，并使用专用 Cloud DNS 区域映射网域：

  1. 创建以区域级 Traffic Director API 为目标的 Private Service Connect 区域级端点：

    gcloud network-connectivity regional-endpoints create td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --network="projects/PROJECT_ID/global/networks/VPC_NETWORK_NAME" \
 --subnetwork="projects/PROJECT_ID/regions/REGION/subnetworks/VPC_SUBNET_NAME" \
 --target-google-api="trafficdirector.REGION.rep.googleapis.com"

    替换以下内容：

    • PROJECT_ID：您的 Google Cloud 项目 ID。
    • REGION：部署所在的区域。
    • VPC_NETWORK_NAME：您的 VPC 网络的名称。
    • VPC_SUBNET_NAME：您的 VPC 子网的名称。

  2. 检索区域端点的内部 IP 地址：

    TD_ENDPOINT_IP=$(gcloud network-connectivity regional-endpoints describe td-rep-endpoint \
 --project="PROJECT_ID" \
 --region="REGION" \
 --format="value(address)")

  3. 为 Traffic Director API 创建专用 Cloud DNS 托管式区域：

    gcloud dns managed-zones create td-psc-zone \
 --project="PROJECT_ID" \
 --dns-name="trafficdirector.REGION.rep.googleapis.com." \
 --description="Private DNS zone for regional endpoint" \
 --visibility="private" \
 --networks="VPC_NETWORK_NAME"

  4. 添加一条 A 记录，用于将 Traffic Director API 区域网域解析为区域端点 IP 地址：

    gcloud dns record-sets create "trafficdirector.REGION.rep.googleapis.com." \
 --project="PROJECT_ID" \
 --zone="td-psc-zone" \
 --type="A" \
 --ttl=300 \
 --rrdatas="${TD_ENDPOINT_IP}"

  5. 验证您的区域端点和 DNS 记录集：

    gcloud dns record-sets list \
 --project="PROJECT_ID" \
 --zone="td-psc-zone"

    确认 trafficdirector.REGION.rep.googleapis.com. 的 A 记录指向区域端点 IP 地址。

部署或更新具有 Ambient Networking 和直接 VPC 出站流量的 Cloud Run 服务

如需将 Cloud Run 代理连接到 VPC 网络中的 Secure Web Proxy 实例，请同时启用直接 VPC 出站流量和区域级环境网络，并为服务配置代理身份。使用 --functional-type=agent 和 --identity-type=agent-identity 进行部署时，Cloud Run 会授予 roles/run.agentDefaultAccess，其中包括 roles/trafficdirector.client 和 roles/cloudtrace.agent 权限：

  1. 部署新的 Cloud Run 代理服务或更新现有服务，以启用区域级 Ambient Networking、适用于所有出站流量的直接 VPC 出站流量以及代理身份：

    新建服务

    gcloud beta run deploy SERVICE_NAME \
 --image=IMAGE_URL \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    现有服务

    gcloud beta run services update SERVICE_NAME \
 --network=VPC_NETWORK_NAME \
 --subnet=VPC_SUBNET_NAME \
 --vpc-egress=all \
 --functional-type=agent \
 --identity-type=agent-identity \
 --ambient-networking \
 --update-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
 --region=REGION \
 --project=PROJECT_ID

    替换以下内容：

    • SERVICE_NAME：Cloud Run 代理服务的名称。
    • IMAGE_URL：对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址采用 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 格式。
    • VPC_NETWORK_NAME：托管 Secure Web Proxy 实例的 VPC 网络的名称。如需了解如何创建 VPC 网络和子网，请参阅创建和管理 VPC 网络。
    • VPC_SUBNET_NAME：Secure Web Proxy 实例可访问的 VPC 子网的名称。
    • REGION：服务所在的区域。
    • PROJECT_ID：您的 Google Cloud 项目 ID。

  2. 验证您的 Cloud Run 服务是否使用 Ambient Networking、直接 VPC 出站流量和代理身份：

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID

    确认输出显示直接 VPC 出站流量子网、all-traffic 出站流量、区域级 Ambient Networking 以及分配的代理身份主账号。

将 Cloud Run 智能体配置为信任 Agent Gateway

为了让 Secure Web Proxy 检查 HTTPS 载荷并强制执行政策，它必须终止来自代理的出站 TLS 会话。您的 Cloud Run 代理容器必须信任 CA Service 或您的私有企业 PKI 中与 Secure Web Proxy TLS 检查政策关联的根证书授权机构 (CA) 证书或从属 CA 证书：

  1. 从 CA Service 池中导出 Secure Web Proxy 实例的 PEM 编码 CA 证书：

    gcloud privateca pools get-ca-certs CA_POOL_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --output-file=agent-gateway-root.crt

    替换以下内容：

    • CA_POOL_NAME：与 Secure Web Proxy TLS 检查政策关联的 CA 池的名称。
    • REGION：CA 池的区域。
    • PROJECT_ID：您的 Google Cloud 项目 ID。

  2. 更新 Cloud Run 服务，以在环境变量中传递证书内容：

    gcloud beta run services update SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --update-env-vars="AGENT_GATEWAY_ROOT_CERT=$(cat agent-gateway-root.crt)"

    替换以下内容：

    • SERVICE_NAME：Cloud Run 代理服务的名称。
    • REGION：服务所在的区域。
    • PROJECT_ID：您的 Google Cloud 项目 ID。

    例如，以下 Debian 或 Ubuntu 容器入口点脚本 entrypoint.sh 会在启动应用之前将 AGENT_GATEWAY_ROOT_CERT 安装到系统受信任证书存储区中，并导出 Python 和 gRPC 客户端的 CA 软件包路径：

    #!/usr/bin/env bash
set -e
if [ -n "${AGENT_GATEWAY_ROOT_CERT}" ]; then
 printf '%s\n' "${AGENT_GATEWAY_ROOT_CERT}" > /usr/local/share/ca-certificates/agent-gateway.crt
 update-ca-certificates
 export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
 export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
 export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/certs/ca-certificates.crt
fi
exec "$@"

  3. 验证您的服务是否设置了 AGENT_GATEWAY_ROOT_CERT 环境变量：

    gcloud beta run services describe SERVICE_NAME \
   --region=REGION \
   --project=PROJECT_ID \
   --format="yaml(spec.template.spec.containers[0].env)"

将出站流量路由到 Agent Gateway

配置 Cloud Run 服务和 Agent Gateway 后，创建一个 Network Services API EgressRouting 政策，以将出站流量从 Cloud Run 服务定向到 Secure Web Proxy 网关：

  1. 创建 EgressRouting 资源：

    gcloud alpha network-services egress-routings create my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME"

    替换以下内容：

    • REGION：Cloud Run 服务和网关所在的区域。
    • PROJECT_ID：您的 Google Cloud 项目 ID。
    • SWP_NAME：底层 Secure Web Proxy Gateway 资源的名称，而不是 AgentGateway 资源的名称。
    • SERVICE_NAME：Cloud Run 代理服务的名称。如需通过具有单一政策的网关路由项目中的所有 Cloud Run 服务，请将 workloadUri 设置为 //run.googleapis.com/projects/PROJECT_ID 或 //run.googleapis.com/projects/PROJECT_NUMBER。

    EgressRouting 生效后，来自 Cloud Run 服务的所有出站流量都会通过 Secure Web Proxy 进行路由。在下一部分中配置政策，以允许和管理出站请求。

  2. 验证 EgressRouting 资源是否处于活跃状态：

    gcloud alpha network-services egress-routings describe my-run-egress-routing \
   --location=REGION \
   --project=PROJECT_ID

    确认 sources 列出了您的 Cloud Run 工作负载 URI，并且 gateway 引用了您的 Secure Web Proxy 网关资源。

在 Agent Gateway 上配置政策

通过 Agent Gateway 路由出站流量后，您可以通过将授权政策和 Service Extensions 扩展程序绑定附加到 Agent Gateway 资源，来管理智能体的出站请求：

  • 基准流量和 MCP 工具过滤：使用 ALLOW 授权政策允许模型端点以及已获批准的 Model Context Protocol (MCP) 方法和工具。
  • 基于身份的访问权限控制：将 IAP 与 ExtensionBinding 资源绑定，并配置 IAM Unified Access Policy，以控制哪些智能体可以调用特定 MCP 服务器、工具或端点。
  • 内容安全：将 Model Armor 与 ExtensionBinding 资源绑定，以检查和清理提示词和回答，防止提示词注入、敏感数据泄露或违反政策。

系统会忽略附加到底层 Secure Web Proxy Gateway 资源的任何授权政策或网关安全政策规则。创建或更新 ExtensionBinding 资源后，更改最多可能需要 5 分钟才能传播到网关。如需了解网络规则、TLS 检查、扩展程序绑定和 HTTP 规则的规则评估顺序，请参阅授权规则的评估顺序。

允许基准出站流量和 MCP 流量

默认情况下，Secure Web Proxy 会拒绝所有出站流量并显示 403 Forbidden 错误，直到 Agent Gateway 资源上的 ALLOW AuthzPolicy 允许该流量。

由于您的 Cloud Run 服务使用 --vpc-egress=all，因此所有出站容器流量（包括 MCP 工具调用和 LLM 请求）都会通过网关路由。为两种流量类型将 ALLOW 授权政策附加到 Agent Gateway 资源：

  • MCP 服务器和工具：按照使用授权政策限制 MCP 工具中的说明，允许使用已获授权的 MCP 方法和工具。
  • 模型和非 MCP 端点：允许使用第 4 层 SNI 规则或第 7 层 httpRules 主机规则向 REGION-aiplatform.googleapis.com 处的 Vertex AI 等模型端点发送请求。第 4 层 SNI 规则会跳过 TLS 检查，如使用 SNI 匹配绕过 TLS 拦截中所示。如果您使用 Model Armor 检查模型载荷，则第 7 层 httpRules 主机规则会使 TLS 检查保持有效，如为代理目的地配置授权政策中所述。

配置 IAP 出站流量政策

Agent Gateway 使用 IAP 作为其违规认定引擎，来评估 IAM 统一访问权限政策。如需强制执行代理身份政策，请在 IAM 统一访问权限政策中定义访问规则，并将 IAP 绑定到网关：

  1. 使用 Cloud Run 服务的Agent Identity主账号 principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME 创建 IAM Unified Access Policies，然后按照创建 IAM 访问权限政策和将 Unified Access Policy 绑定到项目中的说明，将该政策绑定到您的项目或网关。
  2. 按照将 IAP 绑定到 Agent Gateway 中的说明，使用 ExtensionBinding 将 IAP (iap.googleapis.com) 绑定到 Agent Gateway。

由于 --vpc-egress=all 会通过网关发送模型调用（例如 REGION-aiplatform.googleapis.com），因此请将 IAP ExtensionBinding 中的 matchConditions 范围限定为 prefix: "urn:mcp"，以便模型调用绕过 IAP 评估。如需同时管理代理间流量，请添加 prefix: "urn:agent"。如果您的扩展程序绑定与其他主机匹配，请在 IAM Unified Access Policy 中为每个主机添加一条允许规则，例如 destination.unregistered.host == 'REGION-aiplatform.googleapis.com'。如需查看示例，请参阅创建代理到未注册端点政策。

配置 Model Armor 政策

如需检查和清理通过 Agent Gateway 的提示和回答，请创建 Model Armor 模板并将其绑定到网关：

  1. 按照在网关上配置 Model Armor 中的说明，创建区域级 Model Armor 请求和响应模板，并向 Service Extensions 服务代理授予所需角色。
  2. 按照绑定 Model Armor 以清理提示和回答中的说明，使用 ExtensionBinding 将模板附加到 Agent Gateway。

使用共享 VPC 配置集中式跨项目部署

在多项目组织中，您可以使用共享 VPC，在一个或多个服务项目中部署 Cloud Run 代理，同时在专用网络宿主项目中托管 Agent Gateway、Secure Web Proxy 实例和 Agent Registry：

  • 项目 A，代理服务项目：托管 Cloud Run 代理服务和本地 EgressRouting 政策。
  • 项目 B，网关和网络宿主项目：充当共享 VPC 宿主项目，必须托管 Agent Gateway、Secure Web Proxy 实例、Agent Registry、ExtensionBinding 资源和 IAM 政策绑定。
跨项目架构图，显示项目 A 托管 Cloud Run 服务和出站流量路由政策，通过共享 VPC 网络连接到项目 B，后者托管 Agent Gateway、Secure Web Proxy 和 Agent Registry。
图 2. 使用共享 VPC 的跨项目 Agent Gateway 部署。

在开始这些步骤之前，请在项目 A 中启用 run.googleapis.com、compute.googleapis.com、networkservices.googleapis.com 和 trafficdirector.googleapis.com，如果您的智能体调用 Vertex AI，还需启用 aiplatform.googleapis.com。在项目 B 中，按照创建自行管理的 Agent Gateway 中的说明，在共享 VPC 网络上部署 Secure Web Proxy 实例和 Agent Gateway 资源，并按照配置 Cloud Run Ambient Networking 以访问 Traffic Director API 中的说明配置 DNS 或 Private Service Connect 路由，以便项目 A 中的 Ambient Networking 边车可以访问 Traffic Director API。

如需配置跨项目部署，请完成以下步骤：

  1. 将项目 B 配置为共享 VPC 宿主项目，将项目 A 关联为服务项目，并共享托管 Secure Web Proxy 实例的子网。启用共享 VPC 并附加服务项目需要在组织或文件夹级层拥有 roles/compute.xpnAdmin。如需查看相关说明，请参阅使用直接 VPC 出站流量将流量发送到共享 VPC 网络和预配共享 VPC。

  2. 在项目 B 中，向项目 A 中的 Cloud Run 服务代理授予对共享子网的 roles/compute.networkUser 权限：

    gcloud compute networks subnets add-iam-policy-binding SHARED_SUBNET_NAME \
   --project=PROJECT_B_ID \
   --region=REGION \
   --member="serviceAccount:service-PROJECT_A_NUMBER@serverless-robot-prod." \
   --role="roles/compute.networkUser"

    替换以下内容：

    • SHARED_SUBNET_NAME：项目 B 中共享子网的名称。
    • PROJECT_B_ID：项目 B（网关和共享 VPC 宿主项目）的项目 ID。
    • REGION：共享子网的区域。
    • PROJECT_A_NUMBER：项目 A（智能体服务项目）的项目编号。

  3. 在项目 A 中部署 Cloud Run 代理服务，并指向项目 B 中的共享子网：

    gcloud beta run deploy SERVICE_NAME \
   --project=PROJECT_A_ID \
   --image=IMAGE_URL \
   --subnet=projects/PROJECT_B_ID/regions/REGION/subnetworks/SHARED_SUBNET_NAME \
   --vpc-egress=all \
   --functional-type=agent \
   --identity-type=agent-identity \
   --ambient-networking \
   --set-env-vars="GOOGLE_API_USE_CLIENT_CERTIFICATE=false,GOOGLE_API_USE_MTLS_ENDPOINT=never" \
   --region=REGION

    替换以下内容：

    • SERVICE_NAME：项目 A 中 Cloud Run 代理服务的名称。
    • PROJECT_A_ID：项目 A（代理服务项目）的项目 ID。
    • IMAGE_URL：对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址采用 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 格式。

    部署服务后，请按照将 Cloud Run 代理配置为信任 Agent Gateway 中的步骤，将项目 A 中的代理配置为信任项目 B 中 Secure Web Proxy 实例的根 CA 证书。

  4. 在项目 A 中创建引用项目 B 中的 Secure Web Proxy 网关的 EgressRouting 政策。您必须在项目 A 中拥有 roles/networkservices.admin：

    gcloud alpha network-services egress-routings create my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID \
   --gateway="//networkservices.googleapis.com/projects/PROJECT_B_ID/locations/REGION/gateways/CENTRAL_SWP_NAME" \
   --sources="workloadUri=//run.googleapis.com/projects/PROJECT_A_ID/locations/REGION/services/SERVICE_NAME"

    将 CENTRAL_SWP_NAME 替换为项目 B 中的 Secure Web Proxy 网关的名称。如需通过项目 B 的网关路由项目 A 中的所有 Cloud Run 服务，请将 workloadUri 设置为 //run.googleapis.com/projects/PROJECT_A_ID 或 //run.googleapis.com/projects/PROJECT_A_NUMBER。

  5. 确认跨项目 EgressRouting 资源在项目 A 中处于活跃状态：

    gcloud alpha network-services egress-routings describe my-central-egress-routing \
   --location=REGION \
   --project=PROJECT_A_ID

  6. 按照在 Agent Gateway 上配置政策中的说明，在项目 B 的 Agent Gateway 资源上配置集中式基准、IAP 和 Model Armor 政策：

    • 按照允许基准出站流量和 MCP 流量中的说明，允许项目 B 中的 Agent Gateway 资源上的基准 MCP 和模型流量。
    • 如需授权项目 A 中的智能体调用项目 B 中注册的 MCP 服务器，请在项目 B 中创建一个 IAM Unified Access Policies，其 principals 列表引用项目 A 的项目编号 principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_A_NUMBER/locations/REGION/services/SERVICE_NAME，将该政策绑定到项目 B 或其 Agent Gateway 资源，并在项目 B 中附加 IAP ExtensionBinding。
    • 如需在项目 B 中应用集中式 Model Armor 护栏，请创建区域级 Model Armor 模板，向项目 B 的 Service Extensions 服务代理授予所需角色，并将 Model Armor ExtensionBinding 附加到项目 B 中的 Agent Gateway 资源。

查看日志和跟踪记录

通过 Agent Gateway 路由的出站智能体互动会生成日志和分布式跟踪记录，以便您监控政策决策并调试智能体行为：

如果出站请求失败或绕过网关，请参阅排查 Agent Gateway 问题。

支持的区域

您可以在以下区域的 Cloud Run 上使用 Agent Gateway：

  • europe-west1
  • us-central1

限制

除了Ambient Networking 限制和将 Secure Web Proxy 部署为 Agent Gateway 中的 Secure Web Proxy 注意事项之外，将 Agent Gateway 与 Cloud Run 搭配使用时，还存在以下限制：

  • 通过 TLS 检查安全 Web 代理实例路由到 *.mtls.googleapis.com 和 *.mtls.run.app 端点的出站代理请求会失败，并显示 503 错误，因为安全 Web 代理会终止并重新发起 TLS 会话，而不会转发客户端证书。
  • 每个区域级自管理 Agent Gateway 在其 registries 列表中最多支持一个区域级 Agent Registry。
  • 默认情况下，每个项目在每个区域最多支持 10 个区域级 AgentGateway 资源和 10 个区域级 EgressRouting 资源。新项目最初可能每个区域只能有 2 个。如需申请增加配额，请与您的客户支持团队联系。
  • 您必须从 CA Service 池或私有企业 PKI 中导出根证书或从属证书，并配置代理容器以信任该证书。

后续步骤