Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

准备工作

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

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

限制

Agent Gateway 无法绑定到 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 威胁检测服务不可用。
在客户端到 Agent（入站）模式下，Agent Gateway 只能管理 Agent Runtime 的 query 和 streamQuery 方法。如需保护其他不受支持的方法（例如 asyncQuery），您可以直接从应用或代理应用 Model Armor 模板。请参阅清理提示和回答或这篇关于使用 Model Armor 构建安全的智能体系统的 Codelab。
Agent Gateway 不支持 VPC Service Controls。

通过 Agent Gateway 路由 Agent Runtime 流量

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

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

确保网关配置符合部署需求。例如，如果您的代理需要 LLM 访问权限，请配置网关以允许此访问权限，以防止潜在的 Agent Runtime 部署失败。
配置您的代理以通过 Agent Gateway 路由流量。
- 对于新代理
  
  在部署代理时指定网关资源。例如，如需在 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 替换为您为入站流量创建的 Agent Gateway 的名称。
- 对于现有代理
  
  注意：更新现有推理引擎以设置 agentGatewayConfig 不会更改其 identity_type。如果引擎最初创建时没有 identity_type=AGENT_IDENTITY，您无法通过修补引擎来使其追溯性地符合 Semantic Governance Policies 的条件。您必须重新部署新的推理引擎，并在创建代理时同时设置 agent_gateway_config 和 identity_type=AGENT_IDENTITY。
  代理到任意目的地
  使用以下 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：您在“代理到任意目的地（出站流量）”模式下创建的 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/v1beta1/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
在与代理和网关相同的项目和区域中向 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 进行路由。不过，Agent Gateway 采用默认拒绝政策。如需启用某些 Agent Platform 功能，您必须确保代理可以与以下端点通信：
- 如果启用了 Cloud Trace，Agent Gateway 必须允许流量流向端点 https://telemetry.googleapis.com/。
  
  如果已设置 GOOGLE_API_USE_CLIENT_CERTIFICATE 和 GOOGLE_API_USE_MTLS_ENDPOINT 环境变量，请确保也允许向 https://telemetry.mtls.googleapis.com/ 发送流量。
- 如果启用了 Cloud Logging，Agent Gateway 必须允许流量流向端点 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 控制台中，前往 Agent Platform 部署页面。
  前往“部署”页面
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 Gateway 配置自定义容器 (BYOC) 代理

如果您想通过 Agent-to-Anywhere（出站）Agent Gateway 来路由使用自定义容器映像（自带容器 / BYOC）部署的代理的出站流量，则必须将网关的根证书授权机构 (CA) 证书烘焙到自定义容器映像的受信任证书存储区中。

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

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

从 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/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" \
   | jq -r '.agentGatewayCard.rootCertificates[]'

替换以下内容：

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

更新 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

使用 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 代码库和映像名称。

部署容器化代理。

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

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

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

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

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

代理到任意目的地

如需为“代理到任意位置”模式（出站）定义自定义限制条件，请创建一个名为 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。

应用自定义限制条件。
```
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 字段指定仅当指定了 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。

应用自定义限制条件。
```
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

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

准备工作

限制

通过 Agent Gateway 路由 Agent Runtime 流量

代理到任意目的地

客户端到代理

控制台

gcloud

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

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

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

代理到任意目的地

客户端到代理

后续步骤

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

为 Agent Gateway 委托授权

Monitor Agent Gateway

排查 Agent Gateway 问题

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

准备工作

限制

通过 Agent Gateway 路由 Agent Runtime 流量

代理到任意目的地

客户端到代理

控制台

gcloud

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

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

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

代理到任意目的地

客户端到代理

后续步骤

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

为 Agent Gateway 委托授权

Monitor Agent Gateway

排查 Agent Gateway 问题

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