通过代理网关路由 Agent Runtime 流量

本页介绍了如何通过 Agent Gateway 路由 Agent Runtime 流量。Agent Gateway 是 Gemini Enterprise Agent Platform 生态系统的核心网络和安全组件。它为所有智能体交互提供安全且可管控的连接，无论这些交互是发生在用户与智能体之间、智能体与工具之间，还是智能体之间。

准备工作

  • 确保您熟悉在 Agent Runtime 上部署智能体。

  • 了解代理网关。 您可以在“智能体到任意位置”（出站）模式下使用 Agent Gateway，以保护和管理所有出站通信，包括与工具、模型、API 和其他智能体的出站流量。您可以在“客户端到智能体”（入站流量）模式下使用网关，以控制哪些客户端可以访问您的智能体。借助网关，您可以选择必须将哪些 IAP 政策和 Model Armor 模板应用于这些互动。

    单个 Runtime 实例可以同时绑定到 Agent-to-Anywhere（出站）网关和 Client-to-Agent（入站）网关。

  • 查看与关联到 Agent Gateway 的运行时部署相关的限制。

通过 Agent Gateway 路由 Agent Runtime 流量

如需通过 Agent Gateway 路由 Agent Runtime 流量，请执行以下步骤：

  1. 创建 Agent Gateway

    创建 Agent Gateway 资源，并根据需要附加任何授权政策。您可以在“代理到任意位置”（出站）模式或“客户端到代理”（入站）模式下创建网关。

    • 对于“客户端到代理”（入站）模式，代理和网关必须在同一项目和区域中创建。
    • 对于“代理到任意位置”（出站流量）模式，网关可以在与代理不同的项目中创建，但必须在同一区域中创建。请注意，任何关联的 Agent Registry 注册和 IAM 政策绑定都必须在与 Agent Gateway 相同的项目中创建。

    如需查看相关说明，请参阅设置代理网关。

    确保网关配置符合部署需求。例如，如果您的代理需要大语言模型访问权限，请配置网关以允许此访问权限，以防止潜在的 Agent Runtime 部署失败。

  2. 可选：配置跨项目出站网关访问权限

    如果您的 Agent-to-Anywhere（出站流量）网关与 Runtime 代理位于不同的项目中，请执行以下步骤，向 Runtime 服务代理授予对出站流量网关项目的访问权限：

    1. 在 Agent Gateway 项目中创建自定义 IAM 角色：

      gcloud iam roles create ar_agw_cross_project_sa \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --title="Runtime Agent Gateway Cross-Project SA" \
  --description="Custom role for the cross-project service agent to access Agent Gateway" \
  --permissions="networkservices.agentGateways.get,networkservices.operations.get"

      将 AGENT_GATEWAY_PROJECT_ID 替换为部署 Agent Gateway 的项目 ID。

    2. 在网关项目中，向代理项目的 Agent Runtime 服务代理分配自定义角色：

      gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
  --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

      将 AGENT_RUNTIME_PROJECT_NUMBER 替换为部署了 Runtime 代理的项目的项目编号。

  3. 配置智能体以通过 Agent Gateway 路由流量

    根据您是部署新代理还是配置现有代理，选择以下选项之一：

    • 对于使用 Python SDK 的新代理

      在部署代理时指定网关资源。例如，如需在 Agent Runtime 上部署智能体，请使用 client.runtimes.create 传入 local_agent 对象以及任何可选配置。

      如果您想在此智能体中使用 Model Armor 或语义治理政策等网关介导的平台功能，请在创建调用中同时设置 agent_gateway_config 和 identity_type=AGENT_IDENTITY，如本示例所示。如果指定了 agent_gateway_config，后端会在 API 级别强制执行 identity_type = "AGENT_IDENTITY"，如果省略或错误配置了运行时实例的身份，则会导致部署验证失败。

      代理到任意目的地

      remote_agent = client.runtimes.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME}
      },
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      # Other optional configuration ...
      # "requirements": requirements,
      # "gcs_dir_name": gcs_dir_name,
      # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
      "env_vars": {
        "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
      }
  },
)

      替换以下内容：

      • AGENT_GATEWAY_PROJECT_ID：Agent Gateway 部署到的项目 ID
      • REGION：部署代理和网关的区域
      • AGENT_GATEWAY_TO_ANYWHERE_NAME：您在“代理到任意目的地（出站流量）”模式下创建的 Agent Gateway 的名称

      客户端到代理

      remote_agent = client.runtimes.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "client_to_agent_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME}
      },
      "identity_type": types.IdentityType.AGENT_IDENTITY,
      # Other optional configuration ...
      # "requirements": requirements,
      # "gcs_dir_name": gcs_dir_name,
      # https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity#opt-out-caa
      "env_vars": {
        "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
      }
  },
)

      替换以下内容：

      • PROJECT_ID：代理和网关部署到的项目的 ID
      • REGION：部署代理和网关的区域
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME：您在“客户端到 Agent Gateway”（入站流量）模式下创建的 Agent Gateway 的名称

    • 对于使用 Terraform 的新代理

      使用 Terraform 预配代理时，请使用 google-beta 提供程序，并在 google_vertex_ai_reasoning_engine 资源内配置 agent_gateway_config 块。如需详细了解 Terraform 设置，请参阅使用 Terraform 预配代理。

      代理到任意目的地

      使用以下 Terraform 配置将代理与出站流量的“代理到任意位置”网关相关联。

      resource "google_vertex_ai_reasoning_engine" "agent" {
provider = google-beta

project      = "AGENT_RUNTIME_PROJECT_ID"
region       = "REGION"
display_name = "AGENT_DISPLAY_NAME"
description  = "AGENT_DESCRIPTION"

spec {
  identity_type = "AGENT_IDENTITY"

  container_spec {
    image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
  }

  deployment_spec {
    agent_gateway_config {
      agent_to_anywhere_config {
        agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
      }
    }
  }
}
}

      替换以下内容：

      • AGENT_RUNTIME_PROJECT_ID：部署代理的项目 ID
      • REGION：部署代理和网关的区域
      • AGENT_DISPLAY_NAME：智能体的显示名称
      • AGENT_DESCRIPTION：代理的说明
      • REPOSITORY：包含容器映像的 Artifact Registry 代码库
      • IMAGE：容器映像名称
      • TAG：容器映像标记
      • AGENT_GATEWAY_PROJECT_ID：部署 Agent Gateway 的项目 ID
      • AGENT_GATEWAY_TO_ANYWHERE_NAME：您在“代理到任意目的地（出站流量）”模式下创建的 Agent Gateway 的名称

      客户端到代理

      使用以下 Terraform 配置将代理与入站流量的客户端到代理网关相关联。

      resource "google_vertex_ai_reasoning_engine" "agent" {
provider = google-beta

project      = "PROJECT_ID"
region       = "REGION"
display_name = "AGENT_DISPLAY_NAME"
description  = "AGENT_DESCRIPTION"

spec {
  identity_type = "AGENT_IDENTITY"

  container_spec {
    image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
  }

  deployment_spec {
    agent_gateway_config {
      client_to_agent_config {
        agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
      }
    }
  }
}
}

      替换以下内容：

      • PROJECT_ID：部署代理和网关的项目 ID
      • REGION：部署代理和网关的区域
      • AGENT_DISPLAY_NAME：智能体的显示名称
      • AGENT_DESCRIPTION：代理的说明
      • REPOSITORY：包含容器映像的 Artifact Registry 代码库
      • IMAGE：容器映像名称
      • TAG：容器映像标记
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME：您在“客户端到 Agent Gateway”（入站流量）模式下创建的 Agent Gateway 的名称

    • 对于使用 REST API 的现有代理

      代理到任意目的地

      使用以下 REST API 请求将现有代理与 Agent-to-Anywhere 网关相关联，以实现出站流量。

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "spec": {
    "deploymentSpec": {
      "agentGatewayConfig": {
        "agentToAnywhereConfig": {
          "agentGateway": "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      替换以下内容：

      • AGENT_GATEWAY_PROJECT_ID：部署网关的项目 ID
      • AGENT_RUNTIME_PROJECT_ID：部署代理的项目 ID
      • REGION：部署代理和网关的区域
      • AGENT_GATEWAY_TO_ANYWHERE_NAME：您在“代理到任意目的地（出站流量）”模式下创建的 Agent Gateway 的名称
      • RESOURCE_ID：代理的资源 ID

      客户端到代理

      使用以下 REST API 请求将现有代理与用于入站流量的 Client-to-Agent 网关相关联。

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
  "spec": {
    "deploymentSpec": {
      "agentGatewayConfig": {
        "clientToAgentConfig": {
          "agentGateway": "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

      替换以下内容：

      • PROJECT_ID：代理和网关部署到的项目的 ID
      • REGION：部署代理和网关的区域
      • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME：您在“客户端到 Agent Gateway（入站流量）”中创建的 Agent Gateway 的名称
      • RESOURCE_ID：代理的资源 ID

  4. 在 Agent Registry 中注册智能体

    确保代理已在与 Agent Gateway 位于同一项目和区域中的 Agent Registry 实例中注册。

    gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --location=REGION \
  --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
  --format="value(registryResource)"

    替换以下内容：

    • RUNTIME_AGENT_SERVICE_NAME：您要为注册表中的代理条目指定的名称
    • AGENT_GATEWAY_PROJECT_ID：网关部署到的项目 ID
    • REGION：代理和网关的部署区域
    • RUNTIME_AGENT_DISPLAY_NAME：注册表中代理条目的用户易于理解的显示名称
    • RUNTIME_AGENT_PROJECT_NUMBER：部署了运行时代理的项目的项目编号
    • ENGINE_ID：代理的资源 ID

    如需了解详情，请参阅注册代理。 如需了解如何在多项目设置中手动注册代理，请参阅注册来自其他项目的代理。

  5. 创建智能体到注册表的 IAM 政策绑定

    在 Agent Gateway 所在的同一项目和区域中执行此步骤。

    gcloud iap web add-iam-policy-binding \
  --resource-type=agent-registry \
  --endpoint=AGENT_ENDPOINT_ID \
  --region=REGION \
  --project=AGENT_GATEWAY_PROJECT_ID \
  --member=MEMBER \
  --role=roles/iap.egressor

    替换以下内容：

    • AGENT_ENDPOINT_ID：已注册代理的服务端点 ID。您可以从上一步的输出中获取此信息。

    • MEMBER：要向其授予角色的代理身份主账号。单个推理引擎的格式为：principal://TRUST_DOMAIN/resources/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID。

      如果您想向项目或整个组织中的所有代理授予出站访问权限，而不是绑定单个实例，则可以将 IAM 政策绑定到主账号集：

      • 如需向项目中的所有代理授予访问权限，请执行以下操作： principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
      • 如需向组织中的所有代理授予访问权限，请执行以下操作： principalSet://TRUST_DOMAIN/*

      在这些主账号字符串中，TRUST_DOMAIN 通常为 agents.global.org-ORGANIZATION_ID.system.id.goog。

  6. 将必需的 API 列入许可名单，以用于运行时操作

    此时，您的代理流量将通过 Agent Gateway 路由。不过，Agent Gateway 采用的是默认拒绝政策。如需启用某些 Agent Platform 功能，您必须确保代理可以与以下端点通信：

    Agent Gateway 中的主机名匹配是精确匹配。不支持通配符（例如 *.googleapis.com）或前缀形式。您必须注册代理 SDK 或客户端应用解析到的每个标准、区域和安全 (mTLS) 主机名变体。

    如需启用某些 Agent Platform 功能并确保成功进行初始化和遥测，您必须允许流量流向 Agent Registry 中的以下端点：

    基本平台端点

    下表列出了代理在执行标准操作、跟踪、日志记录和元数据解析时所需的基本平台端点：

    服务名称 标准主机名 mTLS 主机名 区域变体和其他变体
    Agent Registry agentregistry.googleapis.com — —
    Cloud Logging logging.googleapis.com logging.mtls.googleapis.com —
    Cloud Trace / 遥测 telemetry.googleapis.com telemetry.mtls.googleapis.com —
    Trace API cloudtrace.googleapis.com cloudtrace.mtls.googleapis.com —
    Cloud Monitoring monitoring.googleapis.com monitoring.mtls.googleapis.com —
    Secret Manager secretmanager.googleapis.com secretmanager.mtls.googleapis.com —
    Resource Manager cloudresourcemanager.googleapis.com cloudresourcemanager.mtls.googleapis.com —
    IAM 凭据 iamcredentials.googleapis.com iamcredentials.mtls.googleapis.com —
    Agent Platform (aiplatform) aiplatform.googleapis.com aiplatform.mtls.googleapis.com REGION-aiplatform.googleapis.com
    REGION-aiplatform.mtls.googleapis.com
    aiplatform.REGION.rep.googleapis.com

    特定于功能的端点

    此外，如果您的智能体使用会话或记忆库等功能，您必须确保智能体可以与这些服务使用的特定端点通信：

    • 对于会话：https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/sessions
    • 对于记忆库：https://REGION-aiplatform.googleapis.com/API_VERSION/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID/memories

    出于安全考虑，我们建议您仅注册代理访问的特定 URI 并将其列入许可名单。由于网关会直接匹配主机名，因此您必须确保注册代理 SDK 使用的所有变体。例如，根据 SDK 版本、区域客户端配置或 mTLS 使用情况，Google API 可以通过以下端点主机名进行解析：

    • https://REGION-aiplatform.googleapis.com
    • https://REGION-aiplatform.mtls.googleapis.com
    • https://aiplatform.REGION.rep.googleapis.com

    如需了解如何注册端点，请参阅注册端点。如果您采用多项目设置，则可以在单个 Agent Registry 服务中注册多个核心 Google API 端点。如需了解详情，请参阅注册复合 Google API 端点。您还必须确保代理对这些端点具有 iap.resources.egressViaIAP 权限。如需了解相关说明，请参阅创建从代理到端点的出站流量政策。

  7. 验证代理配置

    控制台

    1. 在 Google Cloud 控制台中，前往 Agent Platform 部署页面。

      前往“部署”页面

    2. 点击您部署的代理的名称。

    3. 点击服务配置。系统会打开智能体的可观测性窗格。

    4. 点击部署详情。Agent Gateway 的入站和出站配置位于 Deployment spec 字段下。

    gcloud

    使用以下 REST API 请求验证代理现在是否已与网关关联。如果返回的输出为 null，则表示运行时未能绑定到网关。

    curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
  | jq '.spec.deploymentSpec.agentGatewayConfig'

    替换以下内容：

    • AGENT_RUNTIME_PROJECT_ID：项目 ID
    • REGION：智能体的部署区域
    • RESOURCE_ID：代理的资源 ID

为 Agent Gateway 配置自定义容器 (BYOC) 代理

如果您想通过“代理到任意位置”（出口）代理网关路由出站流量，但代理是使用自定义容器映像（自带容器 / BYOC）部署的，则必须将网关的根证书授权机构 (CA) 证书烘焙到自定义容器映像的信任库中。

由于 Agent Gateway 会对出站智能体通信执行 TLS 解密和检查，因此非 BYOC（基于源代码）智能体部署会在映像创建期间自动注入 CA 证书。对于自定义容器映像，您必须明确检索网关的 CA 证书，将其安装到 Dockerfile 内的系统 CA 受信任证书存储区中，并设置 Python SDK、HTTP 客户端库和 gRPC 所需的证书捆绑包环境变量。

如需为 Agent Gateway 出站流量配置 BYOC 容器映像，请执行以下步骤：

  1. 从 Agent Gateway 资源中检索根证书。

    直接从 Agent Gateway 资源的 agentGatewayCard.rootCertificates 字段导出 CA 根证书 PEM 字符串：

    export AGW_CERT=$(gcloud network-services agent-gateways describe AGENT_GATEWAY_NAME \
   --location=REGION \
   --project=PROJECT_ID \
   --format="value[delimiter=\\n](agentGatewayCard.rootCertificates)")

    或者，您也可以使用 REST API 检索网关资源：

    curl -s -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://networkservices.googleapis.com/v1/projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
   | jq -r '.agentGatewayCard.rootCertificates[]'

    替换以下内容：

    • AGENT_GATEWAY_NAME：您的出口代理网关的名称
    • REGION：网关部署到的区域
    • AGENT_GATEWAY_PROJECT_ID：网关部署到的项目 ID

  2. 更新 Dockerfile 以信任 CA 证书。

    将 AGENT_GATEWAY_ROOT_CERTIFICATES build 实参添加到 Dockerfile。构建命令将证书拆分为单独的文件，使用 update-ca-certificates 安装这些文件，并设置环境变量，以便 OpenSSL、Python HTTP 客户端库（requests、httpx）和 gRPC 识别自定义 CA：

    # Install root certificates under root user
USER root

ARG AGENT_GATEWAY_ROOT_CERTIFICATES
RUN if [ -n "$AGENT_GATEWAY_ROOT_CERTIFICATES" ]; then \
     echo "Installing Agent Gateway root certificates..."; \
     printf "%b" "$AGENT_GATEWAY_ROOT_CERTIFICATES" | awk 'BEGIN {c=0} /BEGIN CERTIFICATE/ {c++} c > 0 { print > "/usr/local/share/ca-certificates/agw-" c ".crt" }'; \
     update-ca-certificates; \
   fi

# Configure SSL/TLS trust paths for Python HTTP libraries, OpenSSL, and gRPC
ENV GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV REQUESTS_CA_BUNDLE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV SSL_CERT_FILE=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}
ENV AGENT_GATEWAY_ROOT_CERT_302034098528=${AGENT_GATEWAY_ROOT_CERTIFICATES:+/etc/ssl/certs/ca-certificates.crt}

# Switch back to application execution user
USER 1000

  3. 使用 Cloud Build 构建容器映像。

    创建一个 cloudbuild.yaml 文件，以便使用替代变量将根证书字符串传递给 Cloud Build：

    steps:
- name: 'gcr.io/cloud-builders/docker'
  args:
  - 'build'
  - '--build-arg'
  - 'AGENT_GATEWAY_ROOT_CERTIFICATES=${_AGW_CERT}'
  - '-t'
  - '$_IMAGE_URI'
  - '.'

images:
- '$_IMAGE_URI'

    将容器映像构建提交到 Cloud Build：

    export IMAGE_URI="REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest"

gcloud builds submit \
   --project=PROJECT_ID \
   --region=REGION \
   --config=cloudbuild.yaml \
   --substitutions=_IMAGE_URI="$IMAGE_URI",_AGW_CERT="$AGW_CERT" \
   .

    将 REPOSITORY_NAME 和 IMAGE_NAME 替换为您的 Artifact Registry 代码库和映像名称。

  4. 部署容器化智能体。

    在部署请求中指定已构建的容器映像 URI 以及 Agent Gateway 配置（使用 spec.deploymentSpec 下的 agent_gateway_config 或使用 SDK 部署调用）。

将 Agent Runtime 限制为仅使用已获批准的 Agent Gateway

您可以创建自定义组织政策限制条件，以定义可在部署智能体时使用的符合条件的 Agent Gateway 资源集。

创建自定义组织政策限制条件

此示例会创建自定义限制条件，仅允许进出预先批准的网关列表的流量。

代理到任意目的地

  1. 如需为“代理到任何位置”模式（出站流量）定义自定义限制条件，请创建一个名为 constraint-agent-gateway-egress.yaml 的文件。

    在以下示例中，condition 字段指定仅当指定了 Agent Gateway 资源（字段存在且不为空）且指定的网关位于预批准列表中时，才允许执行相应操作。

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedEgressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.agentToAnywhereConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Egress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    替换以下内容：

    • ORGANIZATION_ID：您的组织 ID。
    • AGENT_PROJECT_ID：您的项目 ID。
    • REGION：创建网关的区域。
    • AGENT_GATEWAY_ID：您的网关 ID。

  2. 应用自定义限制条件。

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    将 EGRESS_CONSTRAINT_PATH 替换为上一步中创建的自定义限制条件文件的完整路径。

  3. 创建组织政策以强制执行限制条件。如需定义组织政策，请创建一个名为 policy-agent-gateway-egress.yaml 的 YAML 政策文件。在此示例中，我们在项目级层强制执行此限制条件，但您也可以在组织或文件夹级层设置此限制条件。

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    将 AGENT_PROJECT_ID 替换为您的项目 ID。

  4. 强制执行组织政策。

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    将 EGRESS_POLICY_PATH 替换为上一步中创建的组织政策 YAML 文件的完整路径。该政策最长需要 15 分钟才能生效。

客户端到代理

  1. 如需为客户端到代理模式（入站流量）定义自定义限制条件，请创建一个名为 constraint-agent-gateway-ingress.yaml 的文件。

    在以下示例中，condition 字段指定仅当指定了 Agent Gateway 资源（字段存在且不为空）且指定的网关位于预批准列表中时，才允许执行相应操作。

    name: organizations/ORGANIZATION_ID/customConstraints/custom.allowlistedIngressAgentGatewaysForAgentEngine
resource_types:
- aiplatform.googleapis.com/ReasoningEngine
condition: >-
has(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway) &&
resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway != '' &&
(resource.spec.deploymentSpec.agentGatewayConfig.clientToAgentConfig.agentGateway in [
  'projects/AGENT_PROJECT_ID_1/locations/REGION_1/agentGateways/AGENT_GATEWAY_ID_1',
  'projects/AGENT_PROJECT_ID_2/locations/REGION_2/agentGateways/AGENT_GATEWAY_ID_2',
])
method_types:
- CREATE
- UPDATE
action_type: ALLOW
display_name: Restrict Reasoning Engine Ingress to Approved Agent Gateways
description: Reasoning Engines can only be bound to a pre-approved list of
Agent Gateway instances. Binding to any other gateway is denied.

    替换以下内容：

    • ORGANIZATION_ID：您的组织 ID。
    • AGENT_PROJECT_ID：您的项目 ID。
    • REGION：创建网关的区域。
    • AGENT_GATEWAY_ID：您的网关 ID。

  2. 应用自定义限制条件。

    gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH

    将 INGRESS_CONSTRAINT_PATH 替换为上一步中创建的自定义限制条件文件的完整路径。

  3. 创建组织政策以强制执行限制条件。如需定义组织政策，请创建一个名为 policy-agent-gateway-ingress.yaml 的 YAML 政策文件。在此示例中，我们在项目级层强制执行此限制条件，但您也可以在组织或文件夹级层设置此限制条件。

    name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true

    将 AGENT_PROJECT_ID 替换为您的项目 ID。

  4. 强制执行组织政策。

    gcloud org-policies set-policy INGRESS_POLICY_PATH

    将 INGRESS_POLICY_PATH 替换为上一步中创建的组织政策 YAML 文件的完整路径。该政策最长需要 15 分钟才能生效。

如需详细了解如何使用自定义组织政策限制条件，请参阅创建自定义限制条件。

限制

  • 跨项目治理具有以下限制：

    • 仅在“代理到任意位置”（出站流量）模式下支持代理和网关之间的跨项目绑定。在“客户端到代理”（入站流量）模式下，代理和 Agent Gateway 必须位于同一项目中。
    • 您必须使用 REST API 或 gcloud 来配置端到端跨项目治理。 Google Cloud Google Cloud 控制台不支持创建跨项目 IAM 政策绑定或 Agent Registry 条目。

  • Agent Gateway 无法绑定到 2026 年 4 月 29 日之前创建的运行时推理引擎。

  • 虽然单个项目和区域可以托管多个 Agent-to-Anywhere（出站）和 Client-to-Agent（入站）Agent Gateway 实例，但部署在同一项目和区域中的所有 Agent Runtime 代理都必须绑定到同一特定的出站和入站 Agent Gateway 实例。

    例如，如果某个项目和区域包含 egress-gateway-X 和 egress-gateway-Y，则该项目和区域中的所有代理都必须配置为使用同一网关进行出站。也就是说，所有代理要么使用 egress-gateway-X，要么使用 egress-gateway-Y。您无法将 agent-A 配置为使用 egress-gateway-X，也无法将 agent-B 配置为使用 egress-gateway-Y。

    此相同的绑定规则也适用于项目和区域内的入站网关。

  • 为代理启用 Agent Gateway 时，Security Command Center Agent Engine 威胁检测服务不可用。

  • 在客户端到代理（入站）模式下，代理网关只能管理代理运行时的 query 和 streamQuery 方法。如需保护其他不受支持的方法（例如 asyncQuery），您可以直接从应用或代理应用 Model Armor 模板。请参阅清理提示和回答或有关使用 Model Armor 构建安全的智能体系统的 Codelab。

  • 更改运行时代理的 Agent Gateway 绑定会归档代理的所有预先存在的修订版本。归档操作无法撤消。请参阅Agent Gateway 和修订版本。

    如需在不更改代理的推理引擎 ID 或不破坏政策绑定的情况下更新代理，请按照更新 Agent Runtime 实例中的说明就地更新代理实例。

后续步骤

Codelab

了解如何使用 Gemini Enterprise Agent Platform 上的 Agent Gateway 治理智能体工作负载。

指南

了解如何将 Agent Gateway 的授权委托给 IAP、Model Armor 或您自己的自定义授权服务。

指南

了解如何监控 Agent Gateway。

问题排查

了解如何排查代理网关连接问题。