设置代理网关

为了集中访问权限控制并确保 Agentic Workflows 之间的连接安全，您可以设置 Agent Gateway 资源来管理入站流量或出站流量。

在设置网关之前，请先查看代理网关概览中的概念基础知识和核心组件。

所需权限

您需要具备以下权限才能创建和管理代理网关。您可以使用自定义角色或通过使用其他预定义角色来获取这些权限。

所需权限

  • compute.networkAttachments.list
  • compute.regions.list
  • modelarmor.templates.list
  • modelarmor.templates.list
  • networksecurity.authzPolicies.create
  • networksecurity.authzPolicies.delete
  • networksecurity.authzPolicies.get
  • networksecurity.authzPolicies.list
  • networksecurity.operations.get
  • networkservices.agentGateways.create
  • networkservices.agentGateways.delete
  • networkservices.agentGateways.get
  • networkservices.agentGateways.list
  • networkservices.agentGateways.update
  • networkservices.agentGateways.use
  • networkservices.authzExtensions.create
  • networkservices.authzExtensions.delete
  • networkservices.authzExtensions.get
  • networkservices.authzExtensions.list
  • networkservices.authzExtensions.update
  • networkservices.authzExtensions.use
  • networkservices.operations.get

必需的 API

在您在本指南中使用的 Google Cloud 项目中启用以下 API。通过这些 API，您可以访问 Gemini Enterprise Agent Platform 提供的全套解决方案。

必需的 API

  • Compute Engine API (compute.googleapis.com)
  • Network Security API (networksecurity.googleapis.com)
  • Network Services API (networkservices.googleapis.com)
  • Cloud DNS API (dns.googleapis.com)
  • Identity and Access Management API (iam.googleapis.com)
  • Agent Registry API (agentregistry.googleapis.com)
  • Vertex AI API (aiplatform.googleapis.com)
  • Discovery Engine API (discoveryengine.googleapis.com)
  • Cloud Storage API (storage.googleapis.com)
  • Model Armor API (modelarmor.googleapis.com)
  • Observability API (observability.googleapis.com)
  • Telemetry API (telemetry.googleapis.com)
  • Cloud Monitoring API (monitoring.googleapis.com)
  • Cloud Trace API (cloudtrace.googleapis.com)
  • Cloud Logging API (logging.googleapis.com)
  • App Hub API (apphub.googleapis.com)
  • App Topology API (apptopology.googleapis.com)
  • Cloud API Registry (cloudapiregistry.googleapis.com)
  • Notebooks API (notebooks.googleapis.com)
  • Text-to-Speech API (texttospeech.googleapis.com)
  • Dataform API (dataform.googleapis.com)

规划 Agent Gateway 部署

请使用本部分规划您的 Agent Gateway 部署，并了解设置正常运行的要求。以下各部分概述了基本组件，但不代表严格的步骤顺序。您可以在初始设置期间注册端点和 MCP 服务器，并为代理分配角色，也可以在后续过程中根据不断出现的新要求来执行这些操作。

选择部署模式

Agent Gateway 支持两种部署模式：

  • 客户端到代理（入站流量）：保护从客户端到在 Google Cloud上运行的代理的通信。
  • 智能体到任意位置（出站）：保护智能体与外部目标、公共 API 和 MCP 服务器之间的通信。

选择运行时、项目和部署区域

Agent Gateway 可管理 Gemini Enterprise 和 Runtime 上运行的代理的流量。

  • Agent Runtime：Agent Gateway 同时支持“智能体到任意位置”（出站流量）模式和“客户端到智能体”（入站流量）模式。在“代理到任意位置”模式下，代理可以与网关位于同一项目中，也可以位于不同项目中。在“客户端到代理”模式下，代理必须与网关位于同一项目中。无论采用哪种模式，代理都必须与网关位于同一区域。

  • Gemini Enterprise：Agent Gateway 仅支持代理到任意目的地（出站流量）模式。借助 Gemini Enterprise，每个网关仅在其部署的项目和区域范围内管理智能体互动。

为了集中管理 Gemini Enterprise 和 Runtime 中的智能体，您可以使用单个 Agent Gateway。或者，您也可以为 Gemini Enterprise 和 Runtime 部署独立的代理网关实例。

示例部署模式

以下是一些部署模式示例，供您参考：

针对运行时代理的集中式跨项目治理

在此部署模式中，您可以在专用治理项目中部署 Agent-to-Anywhere（出站）代理网关，以集中控制出站流量。运行时代理部署在与网关相同的区域中的单独项目中，并且可以属于组织内的任何文件夹。

如需设置跨项目出站流量管控，请配置以下资源：

在中央治理项目中：

  • 创建代理网关。确保网关与 Agent Registry 实例相关联。
  • 通过附加到网关的 Agent Registry 注册跨项目代理以及任何工具、服务器或端点。
  • 向运行时服务代理授予跨项目 IAM 权限，以便应用项目中的代理可以绑定到治理项目中的网关。如需查看示例，请参阅通过 Agent Gateway 路由运行时流量。
  • 配置 IAP 政策、主账号访问权限边界和与 SPIFFE 兼容的工作负载身份，以管理和保护出站流量，确保其流向授权端点。
  • 创建您想用于出站的任何 Model Armor 模板。
  • 如果您想出站到 VPC 网络，可以在治理项目中创建 PSC 网络连接和 DNS 对等互连配置。

在 Agent Runtime 项目中：

  • 部署代理，并将其绑定到治理项目中的中央网关。

请注意，跨项目治理仅适用于具有 Agent-to-Anywhere（出站）网关的运行时；不支持 Gemini Enterprise。

Gemini Enterprise 和运行时代理的共享治理

您的 Gemini Enterprise 应用部署为多区域部署（在 us 或 eu 中），而所有其他资源（运行时、代理网关和代理注册表）都部署在与 Gemini Enterprise 多区域设置对应的单个区域内。

在这种部署中，Gemini Enterprise 应用和运行时都会通过单个本地代理网关将流量直接路由到最终目的地。

Gemini Enterprise 应用位置 运行时区域 Agent Gateway 区域 Agent Registry 实例1
global 或 us us-central1 us-central1 单个代理网关必须与 us-central1 注册表相关联。
eu europe-west1 europe-west1 单个代理网关必须与 europe-west1 注册表相关联。
1 为了让代理与端点和服务器（包括 Google Cloud MCP 服务器）通信，您必须手动向区域性 Agent Registry 实例注册它们。
针对 Gemini Enterprise（使用 Google Cloud MCP 服务器）和运行时代理的独立治理

您的 Gemini Enterprise 应用以多区域部署方式（在 global、us 或 eu 中）进行部署，而运行时代理则根据需要在单独的区域中进行部署。代理网关实例部署在运行时所在的每个区域中。

此模式可确保区域隔离，每个区域都有一个专用代理网关来监控和管理代理流量。

Gemini Enterprise 应用位置 运行时区域 Agent Gateway 区域 Agent Registry 实例1
global 任何区域

us-central1 中的一个 Agent Gateway，适用于 Gemini Enterprise

您希望在其中控制运行时代理的每个区域中的 Agent Gateway

Gemini Enterprise 的代理网关必须与 global 注册表相关联。

运行时代理网关必须与相应的区域注册表相关联。
us 任何区域

us-central1 中的一个 Agent Gateway，适用于 Gemini Enterprise

您希望在其中控制运行时代理的每个区域中的 Agent Gateway

Gemini Enterprise 的代理网关必须与 global 注册表相关联。

运行时代理网关必须与相应的区域注册表相关联。
eu 任何区域

europe-west1 中的一个 Agent Gateway，适用于 Gemini Enterprise

您希望在其中控制运行时代理的每个区域中的 Agent Gateway

Gemini Enterprise 的代理网关必须与 global 注册表相关联。

运行时代理网关必须与相应的区域注册表相关联。
1 您必须手动向全局代理注册表实例注册运行时代理，才能管理 Gemini Enterprise 应用与运行时代理之间的连接。
Gemini Enterprise、Google Workspace 和运行时智能体的独立治理

Gemini Enterprise、Google Workspace 和运行时代理会根据需要部署为多区域或区域部署。Agent Gateway 实例部署在运行时所在的每个区域中。

如果您的 Google Workspace 代理是多区域代理，则需要将多区域注册表与代理网关相关联，如下表所示。

Gemini Enterprise 应用和 Google Workspace 位置信息 运行时区域 Agent Gateway 区域 Agent Registry 实例
us 任何区域

us-central1 中适用于 Gemini Enterprise 和 Google Workspace 的一个 Agent Gateway

您希望在其中控制运行时代理的每个区域中的 Agent Gateway

Gemini Enterprise 和 Google Workspace 的代理网关必须与 us 注册表相关联。

运行时代理网关必须与相应的区域注册表相关联。
eu 任何区域

europe-west1 中适用于 Gemini Enterprise 和 Google Workspace 的一个智能体网关

您希望在其中控制运行时代理的每个区域中的 Agent Gateway

Gemini Enterprise 和 Google Workspace 的代理网关必须与 eu 注册表相关联。

运行时代理网关必须与相应的区域注册表相关联。

注册智能体、端点、服务器和工具

如需启用安全通信，您必须确定代理注册表实例并注册网关将管理的资源。

  1. 确定您将使用的 Agent Registry 实例。

    • 对于代理运行时，您可以在代理网关将要部署到的同一项目和区域中引用区域注册表 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION)。
    • 对于 Gemini Enterprise，您可以在部署 Gemini Enterprise 代理和网关的同一项目中引用全球注册表、多区域注册表或区域注册表。如需有关哪种注册表适合您的部署的指南，请参阅规划部署部分。

  2. 在 Agent Registry 中注册代理。如果您尚未创建代理，则必须稍后完成此步骤。如需查看相关说明，请参阅注册代理。

    如果运行时代理与网关位于不同的项目中，则必须向网关项目中的代理注册表注册运行时代理。

  3. 确定并注册您的代理将调用的所有工具、MCP 服务器和 API 端点。必须注册这些资源，因为代理网关会阻止所有流向未在代理注册表中注册的主机的出站流量。

    与网关位于不同项目中的目的地必须在网关项目的代理注册表中注册。此类目的地仅对处于“Agent-to-Anywhere”模式的运行时代理有效。

    如需了解相关说明，请参阅以下指南：

配置访问权限控制机制

每个 Agent Gateway 都需要关联的授权政策。

IAP

默认情况下，代理网关使用 IAP 通过 Identity and Access Management (IAM) 中定义的政策对代理、端点和服务器进行身份验证。

为了在不阻止流量的情况下验证配置，我们建议您最初以试运行模式部署 IAP。

Model Armor

（可选）如果您的部署需要防范提示注入攻击、越狱、有害内容或敏感数据泄露，您应规划 Model Armor 护栏集成，并创建包含所需安全过滤器的模板。

有关详情，请参阅以下文档：

语义治理政策

（可选）您可以选择在代理上添加基于自然语言的上下文感知控制，以防范工具的有害组合。

我们建议您先以试运行模式部署语义治理政策，以便在不屏蔽流量的情况下验证配置。如需了解详情，请参阅配置语义治理政策。

自定义授权引擎

（可选）如果您想使用 Service Extensions 将授权委托给自定义授权引擎或第三方系统，则应确保在部署网关时自定义授权引擎可用。

模型装甲、语义治理政策和任何其他自定义授权引擎都可以在初始代理网关设置期间启用，也可以在部署后作为增量安全政策更新附加。

设置代理身份和权限

如需在代理与已注册的端点和 MCP 服务器之间启用通信，必须执行以下步骤：

  1. 为您的代理创建代理身份。您可以在部署期间或部署代理后执行此操作。如需查看相关说明，请参阅将代理身份与运行时搭配使用。

  2. 为在代理注册表中注册的每个端点和服务器授予代理身份主账号 roles/iap.egressor（受 IAP 保护的出站流量控制器）角色。

    您可以在注册表级层或单个资源级层授予此角色。由于注册表可以是全局的，也可以是区域性的，因此请确保任何注册表范围的绑定都与代理类型匹配：

    • 对于 Gemini Enterprise 代理，请使用全局注册表。
    • 对于 Agent Runtime 代理，请使用区域注册表。

    代理网关专门检查 iap.webServiceVersions.egressViaIAP 权限，该权限仅由 roles/iap.egressor 角色授予。默认情况下，除非此 IAM 政策明确允许，否则所有出站流量都会被拒绝。

    如需查看相关说明，请参阅创建 IAM 代理政策。

以代理到任意目的地（出站流量）模式配置代理网关

本部分介绍了如何为Agent-to-Anywhere通信设置 Agent Gateway。

按照以下步骤创建 Agent Gateway 资源。

Google Cloud 控制台

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

    前往“网关”

  2. 点击添加网关。
  3. 输入名称。
  4. 从区域列表中选择一个区域。
  5. 在部署模式部分，验证是否已选择 Google 管理。
  6. 对于代理注册表，从列表中选择一个注册表。如需有关为部署选择哪个注册表的指南，请参阅规划 Agent Gateway 部署。
  7. 从受控访问路径列表中，选择代理到任意位置（代理出站）。

  8. 在访问权限授权部分，选择 IAP 处理流量的方式：

    • 如需以试运行模式部署网关，让网关允许所有流量通过并仅生成审核日志，请选择仅审核。 在试运行模式下，IAP 不会强制执行您的 IAM 政策。确信无误后，您可以停用试运行模式以强制执行 IAM 政策。
    • 如需阻止没有明确 Allow IAM 政策的请求，请选择强制执行政策。建议在生产环境中使用此选项。

  9. 可选：在 AI 安全部分，配置其他安全设置：

    1. 如需使用 Model Armor 保护 AI 模型互动，请开启启用 Model Armor。
    2. 从列表中选择适用于来自网关的入站请求的模板。

    3. 如需为回答使用其他模板，请取消选中为请求和回答使用相同模板，然后从列表中选择一个模板。

  10. 点击添加网关。

gcloud

您可以使用 YAML 以声明方式定义代理网关。

  1. 定义资源并将配置保存到 YAML 文件。在此示例中，我们使用 my-agent-gateway-egress.yaml。

    name: AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - AGENT_REGISTRY_PATH

    替换以下内容：

    • AGENT_GATEWAY_NAME：代理网关资源的名称。
    • AGENT_REGISTRY_PATH：代理注册表的路径。如需有关为部署选择哪个注册表的指南，请参阅规划代理网关部署。

  2. 运行以下命令，根据 YAML 规范创建 Agent Gateway 资源：

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="my-agent-gateway-egress.yaml" \
 --location=LOCATION

    将 LOCATION 替换为您要创建 Agent Gateway 资源的位置。例如 us-central1。

    请注意，对于 Gemini Enterprise，您必须在与多区域设置对应的区域中部署 Agent Gateway。如需了解支持的位置映射，请参阅通过 Agent Gateway 路由 Gemini Enterprise 流量。

  3. 创建授权政策，以对通过 Agent Gateway 的流量强制执行集中式访问权限控制和治理政策。以下步骤展示了如何配置使用 IAP 的授权政策。

    1. 配置指向 IAP 的授权扩展程序。 在 YAML 文件（例如 iap-request-authz-extension.yaml）中定义扩展程序。

      为了在不中断流量的情况下验证政策配置和路由，我们建议您先以试运行（仅审核）模式部署扩展程序。为此，您需要在 iamEnforcementMode 字段中指定 DRY_RUN，如示例所示。

      cat >iap-request-authz-extension.yaml <<EOF
name: AUTHORIZATION_EXTENSION_NAME
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

    2. 将 YAML 配置文件导入到授权扩展程序。

      gcloud beta service-extensions authz-extensions import AUTHORIZATION_EXTENSION_NAME \
  --source=iap-request-authz-extension.yaml \
  --location=LOCATION

      将 AUTHORIZATION_EXTENSION_NAME 替换为授权扩展服务的名称，例如 my-iap-request-authz-ext。

    3. 在 YAML 文件（例如 iap-request-authz-policy.yaml）中定义授权政策，以将扩展程序与网关相关联：

      cat >iap-request-authz-policy.yaml <<EOF
name: AUTHORIZATION_POLICY_NAME
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHORIZATION_EXTENSION_NAME"
EOF

      替换以下内容：

      • AUTHORIZATION_POLICY_NAME：授权政策的名称，例如 my-iap-request-authz-policy
      • PROJECT_ID：项目 ID

    4. 将 YAML 配置文件导入到授权政策。

      gcloud beta network-security authz-policies import AUTHORIZATION_POLICY_NAME \
  --source=iap-request-authz-policy.yaml \
  --location=LOCATION

  4. 可选：如果您想配置 Model Armor 护栏，以帮助保护部署免遭提示注入攻击和敏感数据泄露的威胁，请参阅向 Model Armor 委托授权。

创建代理网关后，它将成为在项目和所选区域内路由代理流量的主要连接点。现在，您可以使用此端点在代理及其目的地（工具、其他代理或其他端点）之间建立安全、加密且经过身份验证的通信渠道。

接下来，了解如何部署代理并通过 Agent Gateway 路由流量。

可选：配置 VPC 连接

如需了解如何配置 Agent Gateway，使其能够与组织中的 VPC 网络进行私密通信，请参阅为 Agent Gateway 设置 VPC 连接。

在客户端到 Agent Gateway（入站）模式下配置 Agent Gateway

本部分介绍了如何为客户端到代理通信设置代理网关。

按照以下步骤创建 Agent Gateway 资源。

Google Cloud 控制台

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

    前往“网关”

  2. 点击添加网关。
  3. 输入名称。
  4. 从区域列表中选择一个区域。
  5. 在部署模式部分，验证是否已选择 Google 管理。
  6. 保持代理注册表设置不变。注册表不用于入站流量。
  7. 从受监管的访问路径列表中，选择客户端到代理（入站）。

  8. 可选：在 AI 安全部分，配置其他安全设置：

    1. 如需使用 Model Armor 保护 AI 模型互动，请开启启用 Model Armor。

    2. 从列表中选择适用于来自网关的入站请求的模板。

    3. 如需为回答使用其他模板，请取消选中为请求和回答使用相同模板，然后从列表中选择一个模板。

  9. 点击添加网关。

gcloud

您可以使用 YAML 以声明方式定义代理网关。

  1. 定义资源并将配置保存到 YAML 文件。在此示例中，我们使用 my-agent-gateway-ingress.yaml。

    name: AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: CLIENT_TO_AGENT

    将 AGENT_GATEWAY_NAME 替换为 Agent Gateway 资源的名称。

  2. 运行以下命令，根据 YAML 规范创建代理网关资源：

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="my-agent-gateway-ingress.yaml" \
 --location=LOCATION

    将 LOCATION 替换为您要创建代理网关资源的位置。例如 us-central1。

创建 Agent Gateway 后，它将作为主要连接点，用于将流量路由到项目和所选区域中的代理。

接下来，了解如何部署代理并通过 Agent Gateway 路由流量。

部署代理并通过 Agent Gateway 路由流量

如需部署通过 Agent Gateway 路由流量的 Agent Runtime 代理，请参阅通过 Agent Gateway 路由流量。

如需部署通过 Agent Gateway 路由流量的 Gemini Enterprise 智能体，请参阅通过 Agent Gateway 路由 Gemini Enterprise 流量。

Codelab

如需观看有关如何设置和使用 Agent Gateway 的端到端演示，请参阅以下 Codelab：

后续步骤

指南

了解如何通过 Agent Gateway 路由 Agent Runtime 流量，以实现安全且受管控的连接。

指南

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

指南

了解如何监控 Agent Gateway。

问题排查

了解如何排查 Agent Gateway 连接问题。

指南

了解如何通过 Agent Gateway 路由 Gemini Enterprise 流量。