通过代理网关路由 Gemini Enterprise 流量

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

准备工作

  • 确保您熟悉 Gemini Enterprise 概念
  • 了解Agent Gateway。请注意，Agent Gateway 仅支持以“Agent-to-Anywhere”（出站）模式使用 Gemini Enterprise。不支持入站流量。
  • 部署 Gemini Enterprise 应用（也称为引擎）。 本页面中的过程假定您已部署应用。如需了解详情，请参阅创建应用。

所需权限

向 Discovery Engine 服务代理（即项目的 Gemini Enterprise 实例的 Google 代管式服务账号）授予以下权限，以便 Discovery Engine 服务代理可以发现资源并路由流量。

  • 对于 Agent Registry：

    • agentregistry.agents.list
    • agentregistry.agents.search
    • agentregistry.agents.get
    • agentregistry.mcpServers.list
    • agentregistry.mcpServers.search
    • agentregistry.mcpServers.get

  • 对于 Agent Gateway：

    • networkservices.agentGateways.list
    • networkservices.agentGateways.get
    • networkservices.agentGateways.use

请按照以下步骤向 Discovery Engine 服务代理授予权限。

  1. 创建具有这些权限的自定义角色。

    gcloud iam roles create AGENT_GATEWAY_ROLE_NAME \
--project=PROJECT_ID \
--title="Custom Agent Gateway and Agent Registry access role" \
--description="Custom role for Agent Gateway and Agent Registry access" \
--permissions="agentregistry.agents.list,agentregistry.agents.search,agentregistry.agents.get,agentregistry.mcpServers.list,agentregistry.mcpServers.search,agentregistry.mcpServers.get,networkservices.agentGateways.list,networkservices.agentGateways.get,networkservices.agentGateways.use"

    替换以下内容：

    • AGENT_GATEWAY_ROLE_NAME：自定义角色的名称。
    • PROJECT_ID：部署了代理的项目对应的项目 ID。

  2. 将角色分配给 Gemini Enterprise 服务账号。

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine." \
  --role="projects/PROJECT_ID/roles/AGENT_GATEWAY_ROLE_NAME"

    替换以下内容：

    • PROJECT_ID：您的项目 ID。
    • PROJECT_NUMBER：您的项目编号。
    • AGENT_GATEWAY_ROLE_NAME：您创建的自定义角色的名称。

规划位置和 Agent Registry 映射

在部署代理网关之前，请选择部署网关的区域和注册资源的代理注册表。请注意以下要求：

  • 位置映射：在与 Gemini Enterprise 应用的多区域设置对应的特定区域中部署 Agent Gateway，以确保正确路由。

  • 注册表映射：为您的部署选择全局、多区域或区域注册表。如需详细了解部署模式和注册表选择，请参阅规划 Agent Gateway 部署。

表格：Gemini Enterprise 应用位置和代理注册表映射
Gemini Enterprise 应用位置 必需的 Agent Gateway 区域 代理网关支持的代理注册表实例
global us-central1

选择以下一项：

  • global（//agentregistry.googleapis.com/projects/PROJECT_ID/locations/global)
  • us (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us)
  • us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
us us-central1

选择以下一项：

  • global（//agentregistry.googleapis.com/projects/PROJECT_ID/locations/global)
  • us (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us)
  • us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
eu europe-west1

选择以下一项：

  • global（//agentregistry.googleapis.com/projects/PROJECT_ID/locations/global)
  • eu (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/eu)
  • europe-west1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/europe-west1)

通过 Agent Gateway 路由 Gemini Enterprise 流量

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

  1. 创建代理网关资源，并确保您遵循上一部分中选择的区域和注册表。如需查看相关说明，请参阅设置 Agent Gateway。

    验证网关配置。使用 Network Services API 检索 Agent Gateway 配置并检查设置。

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://networkservices.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"

    以下是配置正确的网关的输出示例：

    {
  "name": "projects/my-ge-project/locations/us-central1/agentGateways/my-egress-gateway",
  "description": "A full configuration for Agent Gateway for Gemini Enterprise egress",
  "googleManaged": {
    "governedAccessPath": "AGENT_TO_ANYWHERE"
  },
  "protocols": [
    "MCP"
  ],
  "registries": [
    "//agentregistry.googleapis.com/projects/my-ge-project/locations/global"
  ]
}

  2. 使用 UpdateEngine API 将网关绑定到 Gemini Enterprise 应用。请注意，完成此步骤后，所有现有代理流量都会立即通过指定的 Agent Gateway 进行路由。

    控制台

    1. 在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

      Gemini Enterprise

    2. 点击要与 Agent Gateway 关联的应用的名称。

    3. 点击安全。

    4. 在配置 Tab 下的Agent Gateway 配置下，输入 Agent Gateway 的完整资源名称。请使用以下格式：projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME。

    5. 点击保存。

    REST

    1. 使用以下请求更新您的应用。

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
-d '{
  "agentGatewaySetting": {
    "defaultEgressAgentGateway": {
      "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
    }
  }
}' \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID?updateMask=agentGatewaySetting.defaultEgressAgentGateway.name"

      替换以下内容：

      • PROJECT_ID：项目 ID。
      • AGENT_GATEWAY_REGION：Agent Gateway 的区域。
      • AGENT_GATEWAY_NAME：Agent Gateway 的名称。
      • PROJECT_NUMBER：项目编号。
      • GE_APP_LOCATION：Gemini Enterprise 应用的位置（例如 us 或 global）。
      • GE_APP_ID：Gemini Enterprise 应用的 ID。

    2. 如需验证应用配置，请使用以下命令检索配置并检查设置：

      curl -s -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_LOCATION/collections/default_collection/engines/GE_APP_ID" \
| jq '{name: .name, displayName: .displayName, agentGatewaySetting: .agentGatewaySetting}'

      以下是正确配置的应用的示例输出：

      {
"name": "projects/PROJECT_NUMBER/locations/GE_LOCATION/collections/default_collection/engines/GE_APP_ID",
"displayName": "GE_APP_ID",
"agentGatewaySetting": {
  "defaultEgressAgentGateway": {
    "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
  }
}
}

  3. 虽然 Gemini Enterprise 应用现已启用出站流量管控，但您的应用不会自动知道它可以与代理注册表中的哪些外部资源进行交互。

    您必须将所选的代理、端点和 MCP 服务器明确导入到 Gemini Enterprise 应用中。导入的资源必须使用其基于注册表的精确资源名称进行引用。如需查看相关说明，请参阅以下指南：

  4. 如需验证出站流量是否正常运行，请执行以下步骤：

    1. 打开 Gemini Enterprise Web 应用。
    2. 提交旨在触发外部工具的查询（例如“给我列出 GitHub 上最近的问题”）。
    3. 监控执行情况，确保成功检索到响应。 在幕后，Gemini Enterprise 代理会打包请求，通过代理网关（用于强制执行任何已配置的授权政策）路由请求，并从目标位置检索响应。

将 Gemini Enterprise 绑定限制为仅限已获批准的代理网关

您可以创建自定义组织政策限制条件，以限制 Gemini Enterprise 应用是否可以绑定到任何或所有代理网关。

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

此示例创建了一个自定义限制条件，用于阻止 Gemini Enterprise 应用与代理网关之间的所有绑定。

代理到任意目的地

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

    以下示例展示了如何通过禁止任何绑定来强制执行严格的网络隔离。condition 字段指定，如果指定了 Agent Gateway 资源（字段存在且不为空），则拒绝该操作。

    name: organizations/ORGANIZATION_ID/customConstraints/custom.disallowGeminiEnterpriseAgentGatewayBinding
resource_types:
– discoveryengine.googleapis.com/Engine
condition: >-
has(resource.agentGatewaySetting.defaultEgressAgentGateway.name) &&
resource.agentGatewaySetting.defaultEgressAgentGateway.name != ''
actionType: DENY
displayName: "Disallow all Agent Gateway Bindings for Discovery Engines"
description: "To enforce strict network isolation, Discovery Engines are not permitted to bind to any Agent Gateway."

    替换以下内容：

    • ORGANIZATION_ID：您的组织 ID。
    • PROJECT_ID：您的项目 ID。
    • REGION：网关的创建区域。
    • AGENT_GATEWAY_NAME：网关名称。

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

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

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

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

    name: projects/PROJECT_ID/policies/custom.disallowGeminiEnterpriseAgentGatewayBinding
spec:
rules:
– enforce: true

    将 PROJECT_ID 替换为您的项目 ID。

  4. 强制执行组织政策。

    gcloud org-policies set-policy EGRESS_POLICY_PATH

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

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

后续步骤

Codelab

了解如何在 Gemini Enterprise Agent Platform 上使用 Agent Gateway 来监管智能体工作负载。

指南

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

指南

了解如何监控 Agent Gateway。

问题排查

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