Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

管理 Agent Gateway

本文档介绍了 Agent Gateway 资源的部署后维护任务。如果您尚未创建网关，请参阅设置 Agent Gateway。

准备工作

在管理 Agent Gateway 资源之前，请验证以下前提条件：

确保您拥有查看、更新和删除网关、连接模板、授权政策和授权扩展所需的权限。如需查看权限的完整列表，请参阅所需权限。
在项目中启用所需的服务。如需了解详情，请参阅必需的 API。
如果您计划解除工作负载与网关的关联，请确保您还拥有管理 Gemini Enterprise Agent Platform 部署上的 Agent Runtime 或 Gemini Enterprise 应用的权限。

查看和检查网关

您可以列出 Google Cloud项目中的 Agent Gateway 资源，并检查网关的配置、附加的扩展程序和仅限输出的元数据。

控制台

在 Google Cloud 控制台中，前往网关页面。

前往“网关”
查看所选项目中的网关列表。
点击网关的名称以打开其详情页面：
- 在详细信息标签页中，查看概览、访问授权、AI 安全、Service Extensions 和 VPC 配置部分。
- 在可观测性标签页中，查看网关流量和政策指标。如需了解详情，请参阅监控 Agent Gateway 流量。

gcloud

列出特定区域中的所有网关：
```
gcloud network-services agent-gateways list \
  --location=LOCATION \
  --project=PROJECT_ID
```
替换以下内容：
- LOCATION：网关部署到的区域，例如 us-central1。
- PROJECT_ID：托管网关的 Google Cloud项目的 ID。

检查特定网关的配置：

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

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

不可变设置

大多数 Agent Gateway 配置（例如其关联的 Agent Registry 实例以及安全和治理政策）都可以就地修改，如更新 Agent Gateway 中所述。不过，某些核心配置是不可变的，需要您部署替换网关。在修改网关之前，请查看下表：

设置	可变性	要求或限制
网关名称和区域	不可更改	如需更改名称或区域，请部署替换网关。
受控访问路径（`AGENT_TO_ANYWHERE` 或 `CLIENT_TO_AGENT`）	不可更改	在 `googleManaged.governedAccessPath` 中创建时配置。无法就地修改。
Private Service Connect 网络连接（`networkAttachment`）	设置后不可变	将网络连接与网关关联后，便无法更改或移除。
智能体连接模板以及关联的 Cloud DNS 对等互连、TLS 信任配置和 VPC 出站流量设置	有条件可变	您可以更新网关的配置，以引用具有新设置的其他连接模板，只要新模板仍引用同一 `networkAttachment` 即可。

替换网关以更改不可变设置

如果您需要更改不可变设置（例如与网关关联的 PSC 网络连接），则需要部署替换网关并将工作负载迁移到新网关：

创建替换 Agent Gateway，并配置其 Identity and Access Management (IAM) 和授权政策。如需查看相关说明，请参阅设置 Agent Gateway。
更新工作负载以使用替换网关：
- Gemini Enterprise 应用：在应用的安全 > 配置设置中更新网关资源名称。请参阅通过 Agent Gateway 路由 Gemini Enterprise 流量。
- Agent Runtime 智能体：在单个项目和区域内，所有 Agent Runtime 智能体都必须绑定到同一网关。不支持从一个网关直接就地更新到另一个网关。如需迁移代理，请执行以下操作：
  1. 确保每个绑定的代理都将 100% 的流量路由到其最新修订版本 (trafficConfig.trafficSplitAlwaysLatest)。
  2. 使用 reasoningEngines.patch 将 spec.deploymentSpec.agentGatewayConfig 设置为 {}，以解除项目和区域中的所有代理与上一个网关的关联，并等待每个更新操作完成。
  3. 在每个代理上调用 reasoningEngines.patch，以将 spec.deploymentSpec.agentGatewayConfig 设置为替换网关资源名称。如需查看示例请求，请参阅通过 Agent Gateway 路由 Agent Runtime 流量。
在所有工作负载都停止引用之前的网关后，请按照删除 Agent Gateway中的步骤，拆除之前的网关。

更新 Agent Gateway

您可以直接在 Google Cloud 控制台中更新某些 Agent Gateway 配置，也可以使用 gcloud CLI 将网关配置导出到 YAML 文件，进行更改，然后重新导入该文件。

更新 Agent Registry

您可以在Google Cloud 控制台或 gcloud CLI 中更新关联的代理注册表。您的网关应引用与网关区域对应的单个区域注册表。如果网关关联到 Gemini Enterprise 应用，则网关必须保留一个与该应用位置匹配的注册表。

控制台

在 Google Cloud 控制台中，前往网关页面。

前往“网关”
点击要更新的网关的名称。
在详细信息标签页的概览部分中，点击修改注册表。
选择与网关部署区域匹配的区域级 Agent Registry，然后点击保存。

gcloud

使用 gcloud network-services agent-gateways export 将网关配置导出到 agent-gateway.yaml，修改 registries、description 或 labels（移除仅输出字段，例如 createTime、updateTime、agentGatewayCard 和 selfLink），然后使用 gcloud network-services agent-gateways import 重新导入文件，如更新网关的连接模板中所示。

更新连接模板

您可以使用 gcloud CLI 更新 Agent Gateway 资源的连接模板。

gcloud

使用更新后的连接设置创建新的 AgentConnectivityTemplate，确保其使用与现有网关相同的 networkAttachment。如需了解详细的模板语法和配置说明，请参阅设置具有 VPC 连接的 Agent Gateway。
将现有网关配置导出到 YAML 文件：
```
gcloud network-services agent-gateways export AGENT_GATEWAY_NAME \
 --destination="agent-gateway.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID
```
替换以下内容：
- AGENT_GATEWAY_NAME：要更新的网关的名称。
- LOCATION：网关部署所在的区域。
- PROJECT_ID：网关部署所在的项目 ID。
在导出的 agent-gateway.yaml 文件中，保持现有的 protocols、registries、description 和 labels 字段不变，移除仅输出字段（createTime、updateTime、agentGatewayCard、selfLink），并更新 agentConnectivityTemplate 以引用新模板：
```
name: projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_NUMBER/locations/LOCATION
agentConnectivityTemplate: projects/PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/NEW_TEMPLATE_NAME
```
替换以下内容：
- PROJECT_NUMBER：部署网关的项目数字编号（agentConnectivityTemplate 需要项目编号，而不是项目 ID）。
- LOCATION：网关的区域。
- AGENT_GATEWAY_NAME：网关的名称。
- NEW_TEMPLATE_NAME：替换连接模板的名称。

重新导入更新后的 YAML 文件以应用更改：

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

可选：在网关更新完成后删除之前的连接模板：

gcloud network-services agent-connectivity-templates delete OLD_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

修改 IAP 设置或 Model Armor 模板

您可以通过更新附加到网关的授权扩展程序来修改 IAP 强制执行设置和 Model Armor 模板。

控制台

在 Google Cloud 控制台中，前往网关页面。

前往“网关”
点击要更新的网关的名称。
在详细信息标签页上，更新附加的安全扩展程序：
- 更改 IAP 实施模式：在访问授权部分中，点击访问授权旁边的修改访问授权。选择仅审核（试运行模式）或强制执行政策，然后点击保存。
- 更改 Model Armor 模板：在 AI 安全部分中，点击请求模板旁边的修改请求模板，或点击回答模板旁边的修改回答模板。选择替换模板，然后点击保存。
注意：只有在创建网关时启用了访问权限授权和 AI 安全功能， Google Cloud 控制台中才会显示这些部分。如需将新的 IAP、Model Armor 或自定义授权政策附加到现有网关，请按照委托授权中的说明使用 gcloud CLI。

gcloud

列出网关区域中的授权扩展，以确定扩展名称：
```
gcloud service-extensions authz-extensions list \
 --location=LOCATION \
 --project=PROJECT_ID
```
将 LOCATION 替换为网关的区域，将 PROJECT_ID 替换为您的项目 ID。

检查扩展程序的当前配置：

gcloud service-extensions authz-extensions describe AUTHZ_EXTENSION_NAME \
 --location=LOCATION \
 --project=PROJECT_ID \
 --format=yaml

将 AUTHZ_EXTENSION_NAME 替换为您的 IAP 或 Model Armor AuthzExtension 资源的名称。

将更新后的扩展程序规范保存到 authz-extension.yaml，省略 createTime 和 updateTime 等仅限输出的字段：
- 对于 IAP 扩展程序：添加 iamEnforcementMode: "DRY_RUN" 以启用仅审核模式，或移除 iamEnforcementMode 以强制执行政策：
```
name: AUTHZ_EXTENSION_NAME
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
  iamEnforcementMode: "DRY_RUN" # Omit this line to enforce policies
```
- 对于 Model Armor 扩展程序：更新 metadata.model_armor_settings 中的 request_template_id 和 response_template_id：
```
name: AUTHZ_EXTENSION_NAME
service: modelarmor.LOCATION.rep.googleapis.com
failOpen: false
timeout: 1s
metadata:
  model_armor_settings: '[
    {
      "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID",
      "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID"
    }
  ]'
```
  替换以下内容：
  - AUTHZ_EXTENSION_NAME：Model Armor AuthzExtension 资源的名称。
  - LOCATION：网关的区域。
  - MODEL_ARMOR_PROJECT_ID：托管 Model Armor 模板的项目 ID。
  - REQUEST_TEMPLATE_ID 和 RESPONSE_TEMPLATE_ID：请求和响应模板的 ID。
  确保网关服务账号 (agentGatewayCard.serviceExtensionsServiceAccount) 对任何新引用的模板项目具有 roles/modelarmor.user 权限，并对网关项目具有 roles/modelarmor.calloutUser 和 roles/serviceusage.serviceUsageConsumer 权限（请参阅委托授权）。

导入更新后的扩展程序 YAML 文件：

gcloud service-extensions authz-extensions import AUTHZ_EXTENSION_NAME \
 --source="authz-extension.yaml" \
 --location=LOCATION \
 --project=PROJECT_ID

如需在现有 AuthzPolicy 上附加新的授权政策或修改流量匹配规则，请参阅委托授权。

解除工作负载与 Agent Gateway 的关联

您必须先解除每个引用 Agent Gateway 的 Gemini Enterprise 应用和 Agent Runtime 代理的关联，然后才能删除该 Agent Gateway。

解除 Gemini Enterprise 应用的关联

您可以在 Google Cloud 控制台中解除 Agent Gateway 与 Gemini Enterprise 应用的关联：

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

前往 Gemini Enterprise
点击与网关关联的应用的名称。
点击安全。
在配置标签页的Agent Gateway 配置下，清除Agent Gateway 资源名称字段。
点击保存。

解除与 Agent Gateway 的关联后，应用的传出流量将不再通过该网关路由。导入的智能体和 Model Context Protocol (MCP) 服务器仍会在 Agent Registry 中注册，但应用无法访问它们，除非您再次关联网关。请注意，新网关必须引用同一代理注册表。

解除 Agent Runtime 智能体的关联

Google Cloud 控制台和 gcloud CLI 不支持修改 Agent Runtime 网关绑定。如需在保持代理运行的同时，将 Agent Gateway 与已部署的 Agent Runtime 代理取消关联，您可以调用 reasoningEngines.patch REST API 方法来清除 spec.deploymentSpec.agentGatewayConfig：

确保代理将所有流量路由到最新修订版本（trafficConfig.trafficSplitAlwaysLatest 设置为 true，或未配置手动 trafficConfig 拆分）。如果手动修订版本流量分配处于活跃状态，并且不可逆地归档了所有先前的修订版本，则清除或更改网关绑定会失败。如需了解详情，请参阅 Agent Gateway 和修订版本。

使用 updateMask=spec.deploymentSpec.agentGatewayConfig 和空 agentGatewayConfig 对象 ({}) 向推理引擎发送 PATCH 请求：

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

替换以下内容：

REGION：智能体的部署区域。
PROJECT_ID：智能体部署到的项目 ID。
RESOURCE_ID：智能体的资源 ID。

删除 Agent Gateway

Agent Gateway 会强制执行严格的引用跟踪，以防止出现孤立的安全政策和损坏的智能体流量路径。如果存在以下任一情况，则删除网关会失败，并且 Google Cloud 控制台中的删除按钮仍然不可用：

一个或多个 Agent Runtime 代理或 Gemini Enterprise 应用仍引用该网关。
任何 AuthzPolicy（适用于 IAP、Model Armor 或自定义提供方）或 TelemetryPolicy 仍以网关为目标。
VPC 配置更新操作仍在网关上运行。

按顺序完成以下步骤，以删除 Agent Gateway 并清理其关联资源：

控制台

确保没有任何 Gemini Enterprise 应用或 Agent Runtime 智能体引用该网关。按照解除工作负载与 Agent Gateway 的关联中的说明操作。
在 Google Cloud 控制台中，前往网关页面。

前往“网关”
点击要删除的网关的名称。
在详细信息标签页上，移除针对网关的所有政策关联：
- 如果访问权限授权部分出现，请点击移除，然后确认删除。此操作会同时删除 IAP AuthzPolicy 及其 AuthzExtension。
- 如果 AI 安全部分出现，请点击移除，然后确认删除。此操作会同时删除 Model Armor AuthzPolicy 及其 AuthzExtension。
- 查看 Service Extensions 表。如果仍有任何自定义 AuthzPolicy 资源处于附加状态，请使用此过程中的 gcloud 标签页将其删除，然后再继续。
移除所有政策关联且没有正在进行的 VPC 更新后，点击删除，然后确认删除。
确认该网关不再显示在项目的网关列表中。
可选：如果没有其他网关使用未使用的连接资源，请清理这些资源。使用 gcloud 标签页删除 AgentConnectivityTemplate，并删除网络连接。

gcloud

确保没有任何 Gemini Enterprise 应用或 Agent Runtime 智能体引用该网关。按照解除工作负载与 Agent Gateway 的关联中的说明操作。
移除授权政策和授权扩展程序：

重要提示：请务必先删除每个 AuthzPolicy，然后再删除其引用的 AuthzExtension。先删除 AuthzExtension 会失败，因为 AuthzPolicy 包含对扩展程序的有效引用。
1. 列出网关区域中的授权政策，以查找其 target.resources 字段引用您的网关的政策，并记下任何引用的 authzExtensions：
```
gcloud network-security authz-policies list \
  --location=LOCATION \
  --project=PROJECT_ID \
  --format="yaml(name,target.resources,customProvider.authzExtension.resources)"
```
  将 LOCATION 替换为网关的区域，将 PROJECT_ID 替换为您的项目 ID。
2. 删除以该网关为目标的每个 AuthzPolicy：
```
gcloud network-security authz-policies delete AUTHZ_POLICY_NAME \
  --location=LOCATION \
  --project=PROJECT_ID
```
  将 AUTHZ_POLICY_NAME 替换为定位到网关的每个授权政策的 ID（例如，对于控制台创建的政策，为 AGENT_GATEWAY_NAME-iap-authzpolicy 或 AGENT_GATEWAY_NAME-aisecurity-authzpolicy）。
3. 可选：删除引用 AuthzPolicy 资源后，删除其他政策未使用的任何 AuthzExtension 资源：
```
gcloud service-extensions authz-extensions delete AUTHZ_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID
```
  将 AUTHZ_EXTENSION_NAME 替换为未使用的授权扩展的 ID。

删除 Agent Gateway：

gcloud network-services agent-gateways delete AGENT_GATEWAY_NAME \
 --location=LOCATION \
 --project=PROJECT_ID

将 AGENT_GATEWAY_NAME 替换为要删除的网关的名称。

确认该网关不再显示在区域网关列表中：

gcloud network-services agent-gateways list \
 --location=LOCATION \
 --project=PROJECT_ID

可选：如果 Agent Gateway 引用了，则您无法删除该 AgentConnectivityTemplate。删除网关后，请删除所有未使用的连接模板：
```
gcloud network-services agent-connectivity-templates delete CONNECTIVITY_TEMPLATE_NAME \
 --location=LOCATION \
 --project=PROJECT_ID
```
将 CONNECTIVITY_TEMPLATE_NAME 替换为未使用的连接模板的名称。如果您不再需要底层 Private Service Connect 网络连接、专用 Cloud DNS 区域或 Certificate Manager TrustConfig 资源，请参阅删除网络连接。

后续步骤

指南

管理 Agent Gateway

准备工作

查看和检查网关

控制台

gcloud

不可变设置

替换网关以更改不可变设置

更新 Agent Gateway

更新 Agent Registry

控制台

gcloud

更新连接模板

gcloud

修改 IAP 设置或 Model Armor 模板

控制台

gcloud

解除工作负载与 Agent Gateway 的关联

解除 Gemini Enterprise 应用的关联

解除 Agent Runtime 智能体的关联

删除 Agent Gateway

控制台

gcloud

后续步骤

为 Agent Gateway 委托授权

监控 Agent Gateway

设置 Agent Gateway

排查 Agent Gateway 问题

管理 Agent Gateway 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

查看和检查网关

控制台

gcloud

不可变设置

替换网关以更改不可变设置

更新 Agent Gateway

更新 Agent Registry

控制台

gcloud

更新连接模板

gcloud

修改 IAP 设置或 Model Armor 模板

控制台

gcloud

解除工作负载与 Agent Gateway 的关联

解除 Gemini Enterprise 应用的关联

解除 Agent Runtime 智能体的关联

删除 Agent Gateway

控制台

gcloud

后续步骤

为 Agent Gateway 委托授权

监控 Agent Gateway

设置 Agent Gateway

排查 Agent Gateway 问题

管理 Agent Gateway