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

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

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

准备工作

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

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

限制

代理网关无法绑定到 2026 年 4 月 29 日之前创建的运行时推理引擎。
虽然单个项目和区域可以托管多个“从代理到任意位置”（出站）和“从客户端到代理”（入站）代理网关实例，但部署在同一项目和区域内的所有代理运行时代理都必须绑定到同一特定的出站和入站代理网关实例。

例如，如果某个项目和区域包含 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 Runtime 流量

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

创建代理网关资源，并根据需要附加任何授权政策。您可以在“代理到任意位置”（出站流量）模式或“客户端到代理”（入站流量）模式下创建网关。请注意，代理和网关必须在同一项目和区域中创建。如需查看相关说明，请参阅设置代理网关。

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

配置代理以通过代理网关路由流量。

对于新代理

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

如果您想使用此代理启用网关介导的平台功能（例如 Model Armor 或 Semantic Governance Policies），请在创建调用中同时设置 agent_gateway_config 和 identity_type=AGENT_IDENTITY，如本示例所示。如果没有 identity_type=AGENT_IDENTITY，运行时实例的 effectiveIdentity 会回退到默认的 Vertex AI 服务账号，并且语义治理政策会以静默方式从政策创建选择器中过滤掉该代理。
```
remote_agent = client.agent_engines.create(
  agent=local_agent,
  config={
      "agent_gateway_config": {
        "agent_to_anywhere_config": {"agent_gateway": projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME},
        # "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,
      }
  },
)
```
将 AGENT_GATEWAY_TO_ANYWHERE_NAME 替换为您在“代理到任意位置”（出站）模式下创建的代理网关的名称。

如果您以“客户端到代理”（入站流量）模式创建了网关，请改用 client_to_agent_config 字段，并将 AGENT_GATEWAY_CLIENT_TO_AGENT_NAME 替换为您为入站流量创建的代理网关的名称。

对于现有代理

代理到任意目的地

使用以下 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/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
        }
      }
    }
  }
}' \
"https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

替换以下内容：

PROJECT_ID：项目 ID
REGION：部署代理的区域
AGENT_GATEWAY_TO_ANYWHERE_NAME：您在“代理到任意目的地（出站流量）”模式下创建的代理网关的名称
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/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

替换以下内容：

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

在与代理和网关相同的项目和区域中向 Agent Registry 实例注册。
```
gcloud agent-registry services create SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --endpoint-spec-type=no-spec \
  --interfaces='[{url="https://REGION-aiplatform.mtls.googleapis.com",protocolBinding="jsonrpc"}]' \
  --format="value(registryResource)"
```
替换以下内容：
- SERVICE_NAME：您要为资源指定的名称，例如 allow-aiplatform-region-eu3。
- PROJECT_ID：项目 ID。
- REGION：注册区域。
- DISPLAY_NAME：端点的直观易懂的名称。
如需了解详情，请参阅注册代理。
为代理创建代理到注册表的 IAM 政策绑定。
```
gcloud iap web add-iam-policy-binding \
  --resource-type=agent-registry \
  --endpoint=ENDPOINT_ID \
  --region=REGION \
  --project=PROJECT_ID \
  --member=MEMBER \
  --role=roles/iap.egressor
```
替换以下内容：
- ENDPOINT_ID：已注册代理的服务端点 ID。您可以从上一步的输出中获取此值。
- MEMBER：要向其授予角色的代理身份主账号。格式通常为：principal://TRUST_DOMAIN/resources/aiplatform/projects/PROJECT_ID/locations/REGION/reasoningEngines/ENGINE_ID。
  
  注意：如果您想将项目中的所有代理（包括所有运行时代理、Gemini Enterprise 代理以及未来创建的任何其他代理）绑定到注册表，可以将 IAM 政策绑定到 principal://TRUST_DOMAIN/attribute.container/projects/PROJECT_ID。
此时，代理流量将通过 Agent Gateway 进行路由。不过，代理网关采用默认拒绝政策。如需启用某些代理平台功能，您必须确保代理可以与以下端点通信：
- 如果启用了 Cloud Trace，代理网关必须允许流量流向端点 https://telemetry.googleapis.com/。
  
  如果已设置 GOOGLE_API_USE_CLIENT_CERTIFICATE 和 GOOGLE_API_USE_MTLS_ENDPOINT 环境变量，请确保也允许向 https://telemetry.mtls.googleapis.com/ 发送流量。
- 如果启用了 Cloud Logging，代理网关必须允许流量流向端点 https://logging.googleapis.com/。
  
  如果已设置 GOOGLE_API_USE_CLIENT_CERTIFICATE 和 GOOGLE_API_USE_MTLS_ENDPOINT 环境变量，请确保也允许向 https://logging.mtls.googleapis.com/ 发送流量。
此外，如果您的代理调用 LLM 或使用会话和记忆库等功能，您必须确保代理可以与这些服务使用的端点通信。例如：
- 对于会话：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
注意：虽然您可以注册基本 URI（例如 https://REGION-aiplatform.googleapis.com/）以方便操作，但这样做会提供广泛的访问权限政策，让代理可以访问该网域下的任何服务。请注意，即使您注册了基本 URI，仍需注册其所有区域变体和 mTLS 变体。

如需了解如何注册端点，请参阅注册端点。您还必须确保代理具有这些端点的 IAP Egressor 角色。如需了解相关说明，请参阅创建从代理到端点的出站流量政策。
验证代理配置。
控制台
1. 在 Google Cloud 控制台中，前往代理平台部署页面。
  
  前往“部署”页面
2. 点击您部署的代理的名称。
3. 点击服务配置。系统会打开代理的可观测性窗格。
4. 点击部署详情。代理网关的入站和出站配置位于部署规范字段下。
gcloud
使用以下 REST API 请求验证代理是否已与网关关联。如果返回的输出为 null，则表示运行时未能绑定到网关。
curl -s -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \ | jq '.spec.deploymentSpec.agentGatewayConfig'
替换以下内容：
- PROJECT_ID：项目 ID
- REGION：部署代理的区域
- RESOURCE_ID：代理的资源 ID

将 Agent Runtime 限制为仅限经批准的代理网关

您可以创建自定义组织政策限制条件，以定义部署代理时可使用的一组符合条件的代理网关资源。

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

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

代理到任意目的地

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

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

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。

应用自定义限制条件。
```
gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH
```
将 EGRESS_CONSTRAINT_PATH 替换为上一步中创建的自定义限制条件文件的完整路径。
创建组织政策以强制执行限制条件。如需定义组织政策，请创建一个名为 policy-agent-gateway-egress.yaml 的 YAML 政策文件。在此示例中，我们在项目级层强制执行此限制条件，但您也可以在组织或文件夹级层设置此限制条件。
```
name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedEgressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true
```
将 AGENT_PROJECT_ID 替换为您的项目 ID。
强制执行组织政策。
```
gcloud org-policies set-policy EGRESS_POLICY_PATH
```
将 EGRESS_POLICY_PATH 替换为在上一步中创建的组织政策 YAML 文件的完整路径。该政策最长需要 15 分钟才能生效。

客户端到代理

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

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

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。

应用自定义限制条件。
```
gcloud org-policies set-custom-constraint INGRESS_CONSTRAINT_PATH
```
将 INGRESS_CONSTRAINT_PATH 替换为上一步中创建的自定义限制条件文件的完整路径。
创建组织政策以强制执行限制条件。如需定义组织政策，请创建一个名为 policy-agent-gateway-ingress.yaml 的 YAML 政策文件。在此示例中，我们在项目级层强制执行此限制条件，但您也可以在组织或文件夹级层设置此限制条件。
```
name: projects/AGENT_PROJECT_ID/policies/custom.allowlistedIngressAgentGatewaysForAgentEngine
spec:
  rules:
  - enforce: true
```
将 AGENT_PROJECT_ID 替换为您的项目 ID。
强制执行组织政策。
```
gcloud org-policies set-policy INGRESS_POLICY_PATH
```
将 INGRESS_POLICY_PATH 替换为在上一步中创建的组织政策 YAML 文件的完整路径。该政策最长需要 15 分钟才能生效。

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

后续步骤

Codelab

Codelab：使用 Agent Platform 管理代理工作负载

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

指南

为代理网关委托授权

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

指南

Monitor Agent Gateway

了解如何监控代理网关。

问题排查

排查 Agent Gateway 问题

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

通过代理网关路由 Agent Runtime 流量 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

限制

通过 Agent Gateway 路由 Agent Runtime 流量

代理到任意目的地

客户端到代理

控制台

gcloud

将 Agent Runtime 限制为仅限经批准的代理网关

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

代理到任意目的地

客户端到代理

后续步骤

Codelab：使用 Agent Platform 管理代理工作负载

为代理网关委托授权

Monitor Agent Gateway

排查 Agent Gateway 问题

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