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

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

准备工作

• 确保您熟悉在 Agent Runtime 上部署智能体。

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

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

• 查看与 Agent Gateway 关联的运行时部署相关的限制。

通过 Agent Gateway 路由 Agent Runtime 流量

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

1. 创建 Agent Gateway

   创建 Agent Gateway 资源，并根据需要附加任何授权政策。您可以在“代理到任意位置”（出站流量）模式或“客户端到代理”（入站流量）模式下创建网关。

   • 对于“客户端到代理”（入站流量）模式，代理和网关必须在同一项目和区域中创建。
   • 对于“代理到任意位置”（出站流量）模式，网关可以在与代理不同的项目中创建，但必须在同一区域中创建。请注意，任何关联的 Agent Registry 注册和 IAM 政策绑定都必须在 Agent Gateway 所在的同一项目中创建。

   如需查看相关说明，请参阅设置 Agent Gateway。

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

2. 可选：配置跨项目出站网关访问权限

   如果您的 Agent-to-Anywhere（出站流量）网关与 Runtime 代理位于不同的项目中，请执行以下步骤，向 Runtime 服务代理授予对出站流量网关项目的访问权限：

   gcloud

   1. 在 Agent Gateway 项目中创建自定义 IAM 角色：

   gcloud iam roles create ar_agw_cross_project_sa \
       --project=AGENT_GATEWAY_PROJECT_ID \
       --title="Runtime Agent Gateway Cross-Project SA" \
       --description="Custom role for the cross-project service agent to access Agent Gateway" \
       --permissions="networkservices.agentGateways.get,networkservices.operations.get"

   将 AGENT_GATEWAY_PROJECT_ID 替换为部署了 Agent Gateway 的项目的 ID。

   1. 将网关项目中的自定义角色分配给代理项目的 Agent Runtime 服务代理：

   gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
       --member="serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com" \
       --role="projects/AGENT_GATEWAY_PROJECT_ID/roles/ar_agw_cross_project_sa"

   将 AGENT_RUNTIME_PROJECT_NUMBER 替换为部署了 Runtime 代理的项目的项目编号。

   Terraform

   如需以声明方式向多个 Runtime 工作负载项目授予对中央 Agent Gateway 项目的跨项目访问权限，请在中央网关项目中创建自定义 IAM 角色，并将其授予每个工作负载项目的 Runtime 服务代理：

   variable "runtime_project_numbers" {
     type        = set(string)
     description = "Project numbers hosting cross-project Agent Runtime workloads"
     default     = ["AGENT_RUNTIME_PROJECT_NUMBER"]
   }
   
   resource "google_project_iam_custom_role" "ar_agw_cross_project_sa" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     role_id     = "ar_agw_cross_project_sa"
     title       = "Runtime Agent Gateway Cross-Project SA"
     description = "Custom role for cross-project service agents to access Agent Gateway"
     permissions = [
       "networkservices.agentGateways.get",
       "networkservices.operations.get",
     ]
   }
   
   resource "google_project_iam_member" "ar_agw_cross_project_binding" {
     for_each = var.runtime_project_numbers
   
     project = "AGENT_GATEWAY_PROJECT_ID"
     role    = google_project_iam_custom_role.ar_agw_cross_project_sa.name
     member  = "serviceAccount:service-${each.value}@gcp-sa-aiplatform.s3ns-system.iam.gserviceaccount.com"
   }
   

3. 将智能体配置为通过 Agent Gateway 路由流量

   根据您是要部署新代理还是要配置现有代理，选择以下选项之一：

   • 对于使用 Python SDK 的新代理

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

     如果您想在此智能体中使用 Model Armor 或语义治理政策等网关介导的平台功能，请在创建调用中同时设置 agent_gateway_config 和 identity_type=AGENT_IDENTITY，如本示例所示。只要指定了 agent_gateway_config，后端就会在 API 级别强制执行 identity_type = "AGENT_IDENTITY"，如果运行时实例的身份被省略或配置错误，则会导致部署验证失败。

     代理到任意目的地

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "agent_to_anywhere_config": {"agent_gateway": projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_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_PROJECT_ID：Agent Gateway 部署到的项目 ID
     • REGION：代理和网关部署到的区域
     • AGENT_GATEWAY_TO_ANYWHERE_NAME：您在“代理到任意目的地（出站流量）”模式下创建的 Agent Gateway 的名称

     客户端到代理

     remote_agent = client.runtimes.create(
       agent=local_agent,
       config={
           "agent_gateway_config": {
             "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,
           }
       },
     )

     替换以下内容：

     • PROJECT_ID：代理和网关部署到的项目的 ID
     • REGION：代理和网关部署到的区域
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME：您在客户端到代理（入站流量）模式下创建的 Agent Gateway 的名称

   • 对于使用 Terraform 的新代理

     使用 Terraform 预配代理时，请使用 google-beta 提供程序，并在 google_vertex_ai_reasoning_engine 资源中配置 agent_gateway_config 块。如需详细了解 Terraform 设置，请参阅使用 Terraform 预配代理。

     代理到任意目的地

     使用以下 Terraform 配置将代理与 Agent-to-Anywhere 网关关联，以实现出站流量。

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "AGENT_RUNTIME_PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/AGENT_RUNTIME_PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           agent_to_anywhere_config {
             agent_gateway = "projects/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
           }
         }
       }
     }
     }

     替换以下内容：

     • AGENT_RUNTIME_PROJECT_ID：智能体部署到的项目 ID
     • REGION：代理和网关部署所在的区域
     • AGENT_DISPLAY_NAME：代理的显示名称
     • AGENT_DESCRIPTION：代理的说明
     • REPOSITORY：包含容器映像的 Artifact Registry 代码库
     • IMAGE：容器映像名称
     • TAG：容器映像标记
     • AGENT_GATEWAY_PROJECT_ID：Agent Gateway 部署到的项目 ID
     • AGENT_GATEWAY_TO_ANYWHERE_NAME：您在“代理到任意目的地（出站流量）”模式下创建的 Agent Gateway 的名称

     客户端到代理

     使用以下 Terraform 配置将代理与客户端到代理网关相关联，以实现入站流量。

     resource "google_vertex_ai_reasoning_engine" "agent" {
     provider = google-beta
     
     project      = "PROJECT_ID"
     region       = "REGION"
     display_name = "AGENT_DISPLAY_NAME"
     description  = "AGENT_DESCRIPTION"
     
     spec {
       identity_type = "AGENT_IDENTITY"
     
       container_spec {
         image_uri = "REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG"
       }
     
       deployment_spec {
         agent_gateway_config {
           client_to_agent_config {
             agent_gateway = "projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_CLIENT_TO_AGENT_NAME"
           }
         }
       }
     }
     }

     替换以下内容：

     • PROJECT_ID：代理和网关部署到的项目 ID
     • REGION：代理和网关部署所在的区域
     • AGENT_DISPLAY_NAME：代理的显示名称
     • AGENT_DESCRIPTION：代理的说明
     • REPOSITORY：包含容器映像的 Artifact Registry 代码库
     • IMAGE：容器映像名称
     • TAG：容器映像标记
     • AGENT_GATEWAY_CLIENT_TO_AGENT_NAME：您在客户端到代理（入站流量）模式下创建的 Agent Gateway 的名称

   • 对于使用 REST API 的现有智能体

     代理到任意目的地

     使用以下 REST API 请求将现有代理与代理到任意位置网关关联，以实现出站流量。

     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/AGENT_GATEWAY_PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_TO_ANYWHERE_NAME"
             }
           }
         }
       }
     }' \
     "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

     替换以下内容：

     • AGENT_GATEWAY_PROJECT_ID：网关部署到的项目 ID
     • AGENT_RUNTIME_PROJECT_ID：智能体部署到的项目 ID
     • REGION：代理和网关部署到的区域
     • AGENT_GATEWAY_TO_ANYWHERE_NAME：您在“代理到任意目的地（出站流量）”模式下创建的 Agent Gateway 的名称
     • RESOURCE_ID：智能体的资源 ID

     客户端到代理

     使用以下 REST API 请求将现有智能体与客户端到智能体网关相关联，以实现入站流量。

     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/v1/projects/PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID?updateMask=spec.deploymentSpec.agentGatewayConfig"

     替换以下内容：

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

4. 在 Agent Registry 中注册智能体

   确保智能体已在与 Agent Gateway 位于同一项目和区域的 Agent Registry 实例中注册。

   gcloud

   gcloud agent-registry services create RUNTIME_AGENT_SERVICE_NAME \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --location=REGION \
    --display-name="RUNTIME_AGENT_DISPLAY_NAME" \
    --endpoint-spec-type=no-spec \
    --interfaces=url="https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID",protocolBinding="jsonrpc" \
    --format="value(registryResource)"
   

   替换以下内容：

   • RUNTIME_AGENT_SERVICE_NAME：您要为注册表中的代理条目指定的名称
   • AGENT_GATEWAY_PROJECT_ID：部署网关的项目 ID
   • REGION：代理和网关的部署区域
   • RUNTIME_AGENT_DISPLAY_NAME：注册表中智能体条目的人类可读显示名称
   • RUNTIME_AGENT_PROJECT_NUMBER：部署 Runtime 代理的项目的项目编号
   • ENGINE_ID：智能体的资源 ID

   Terraform

   resource "google_agent_registry_service" "runtime_agent_entry" {
     project      = "AGENT_GATEWAY_PROJECT_ID"
     location     = "REGION"
     service_id   = "RUNTIME_AGENT_SERVICE_NAME"
     display_name = "RUNTIME_AGENT_DISPLAY_NAME"
   
     endpoint_spec {
       no_spec {}
     }
   
     interfaces {
       url              = "https://REGION-aiplatform.mtls.googleapis.com/v1/projects/RUNTIME_AGENT_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID"
       protocol_binding = "jsonrpc"
     }
   }
   

   如需了解详情，请参阅注册代理。 如需了解如何在多项目设置中手动注册代理，请参阅从其他项目注册代理。

5. 创建智能体到注册表的 IAM 政策绑定

   在 Agent Gateway 所在的同一项目和区域中执行此步骤。

   gcloud

   gcloud iap web add-iam-policy-binding \
    --resource-type=agent-registry \
    --endpoint=AGENT_ENDPOINT_ID \
    --region=REGION \
    --project=AGENT_GATEWAY_PROJECT_ID \
    --member=MEMBER \
    --role=roles/iap.egressor
   

   Terraform

   resource "google_iap_agent_registry_endpoint_iam_member" "egress_binding" {
     project     = "AGENT_GATEWAY_PROJECT_ID"
     location    = "REGION"
     endpoint_id = "AGENT_ENDPOINT_ID"
     role        = "roles/iap.egressor"
     member      = "MEMBER"
   }
   

   替换以下内容：

   • AGENT_ENDPOINT_ID：已注册代理的服务端点 ID。您可以从上一步的输出中获取此信息。

   • 代理身份主账号 MEMBER：要向其授予角色的代理身份主账号。单个推理引擎的格式为：principal://TRUST_DOMAIN/resources/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER/locations/REGION/reasoningEngines/ENGINE_ID。

     如果您想向项目或整个组织中的所有代理授予出站流量访问权限，而不是绑定单个实例，则可以将 IAM 政策绑定到主账号集：

     • 如需向项目中的所有代理授予访问权限，请执行以下操作： principalSet://TRUST_DOMAIN/attribute.platformContainer/aiplatform/projects/AGENT_RUNTIME_PROJECT_NUMBER
     • 如需向整个组织中的所有代理授予访问权限，请执行以下操作： principalSet://TRUST_DOMAIN/*

     在这些主账号字符串中，TRUST_DOMAIN 通常为 agents.global.org-ORGANIZATION_ID.system.id.goog。

6. 将运行时操作所需的基本 API 列入许可清单

   此时，您的智能体流量现在会通过 Agent Gateway 进行定向。不过，Agent Gateway 采用默认拒绝政策。如需启用某些 Agent Platform 功能，您必须确保代理可以与以下端点通信：

   Agent Gateway 中的主机名匹配是精确匹配。不支持通配符（例如 *.googleapis.com）或前缀形式。您必须注册代理 SDK 或客户端应用解析到的每个标准、区域和安全 (mTLS) 主机名变体。

   如需启用某些 Agent Platform 功能并确保成功初始化和遥测，您必须允许流量访问 Agent Registry 中的以下端点：

   基本平台端点

   下表列出了代理执行标准操作、跟踪、日志记录和元数据解析所需的基本平台端点：

   服务名称	标准主机名	mTLS 主机名	区域变体和其他变体
   智能体注册表	agentregistry.googleapis.com	—	—
   Cloud Logging	logging.googleapis.com	logging.mtls.googleapis.com	—
   Cloud Trace / 遥测	telemetry.googleapis.com	telemetry.mtls.googleapis.com	—
   Trace API	cloudtrace.googleapis.com	cloudtrace.mtls.googleapis.com	—
   Cloud Monitoring	monitoring.googleapis.com	monitoring.mtls.googleapis.com	—
   Secret Manager	secretmanager.googleapis.com	secretmanager.mtls.googleapis.com	—
   Resource Manager	cloudresourcemanager.googleapis.com	cloudresourcemanager.mtls.googleapis.com	—
   IAM 凭证	iamcredentials.googleapis.com	iamcredentials.mtls.googleapis.com	—
   Agent Platform (aiplatform)	aiplatform.googleapis.com	aiplatform.mtls.googleapis.com	REGION-aiplatform.googleapis.com REGION-aiplatform.mtls.googleapis.com aiplatform.REGION.rep.googleapis.com

   特定于功能的端点

   此外，如果您的智能体使用会话或记忆库等功能，您必须确保智能体可以与这些服务使用的特定端点进行通信：

   • 对于会话：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

   如需了解如何注册端点，请参阅注册端点。如果您采用多项目设置，则可以在单个 Agent Registry 服务中注册多个核心 Google API 端点。如需了解详情，请参阅注册复合 Google API 端点。您还必须确保代理对这些端点具有 iap.resources.egressViaIAP 权限。如需了解相关说明，请参阅创建代理到端点出站流量政策。

7. 验证代理配置

   控制台

   1. 在 Cloud de Confiance 控制台中，前往 Agent Platform 部署页面。
      

      前往“部署”页面

   2. 点击您部署的代理的名称。

   3. 点击服务配置。系统会打开智能体的可观测性窗格。

   4. 点击部署详情。Agent Gateway 入站和出站配置位于部署规范字段下。

   gcloud

   使用以下 REST API 请求验证代理现在是否已与网关关联。如果返回的输出为 null，则表示运行时未能绑定到网关。

   curl -s -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://REGION-aiplatform.googleapis.com/v1/projects/AGENT_RUNTIME_PROJECT_ID/locations/REGION/reasoningEngines/RESOURCE_ID" \
     | jq '.spec.deploymentSpec.agentGatewayConfig'

   替换以下内容：

   • AGENT_RUNTIME_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 容器映像，请执行以下步骤：

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

   替换以下内容：

   • AGENT_GATEWAY_NAME：出站 Agent Gateway 的名称
   • REGION：网关部署到的区域
   • AGENT_GATEWAY_PROJECT_ID：网关部署到的项目 ID

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

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

4. 部署容器化智能体。

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

将 Agent Runtime 限制为仅使用已获批准的 Agent Gateway

您可以创建自定义组织政策限制条件，以定义可在部署智能体时使用的符合条件的 Agent Gateway 资源集。

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

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

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

限制

• 跨项目治理具有以下限制：

  • 仅在“代理到任意位置”（出站流量）模式下支持代理与网关之间的跨项目绑定。在“客户端到智能体”（入站流量）模式下，智能体和 Agent Gateway 必须位于同一项目中。
  • 您必须使用 REST API 或 gcloud 来配置端到端跨项目治理。 Cloud de Confiance Cloud de Confiance 控制台不支持创建跨项目 IAM 政策绑定或代理注册表条目。

• Agent Gateway 无法绑定到 2026 年 4 月 29 日之前创建的运行时推理引擎。

• 虽然单个项目和区域可以托管多个 Agent-to-Anywhere（出站流量）和 Client-to-Agent（入站流量）Agent Gateway 实例，但部署在同一项目和区域内的所有 Agent Runtime 代理都必须绑定到相同的特定出站流量和入站流量 Agent Gateway 实例。

  例如，如果某个项目和区域包含 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 Gateway 只能管理 Agent Runtime 的 query 和 streamQuery 方法。如需保护其他不受支持的方法（例如 asyncQuery），您可以直接从应用或代理应用 Model Armor 模板。请参阅对提示词和回答进行清理或使用 Model Armor 构建安全的智能体系统 Codelab。

• 更改运行时代理上的 Agent Gateway 绑定会归档该代理的所有现有修订版本。归档操作无法撤消。请参阅 Agent Gateway 和修订版本。

  如需在不更改代理的推理引擎 ID 或不破坏政策绑定的情况下更新代理，请按照更新 Agent Runtime 实例中的说明就地更新代理实例。

后续步骤