透過 Agent Gateway 轉送 Agent Runtime 流量

本頁面說明如何透過 Agent Gateway 轉送 Agent Runtime 流量。Agent Gateway 是 Gemini Enterprise Agent Platform 生態系統的核心網路和安全元件，無論是使用者與代理、代理與工具，還是代理之間的互動，都能確保連線安全無虞且受到控管。

事前準備

• 請務必熟悉在 Agent Runtime 部署代理。

• 瞭解 Agent Gateway。您可以在 Agent-to-Anywhere (輸出) 模式下使用 Agent Gateway，保護及控管所有傳出通訊，包括傳送至工具、模型、API 和其他代理的傳出流量。您可以使用用戶端對代理 (輸入) 模式的閘道，控管哪些用戶端可以存取代理。您可以透過閘道，選擇要對這些互動套用哪些 IAP 政策和 Model Armor 範本。

  單一執行階段執行個體可同時繫結至代理到任何位置 (egress) 閘道，以及用戶端到代理 (ingress) 閘道。

• 請查看與 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 (輸出) 閘道與執行階段代理程式位於不同專案，請按照下列步驟，將輸出閘道專案的存取權授予執行階段服務代理：

   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 替換為部署執行階段代理程式的專案編號。

   Terraform

   如要以宣告方式，從多個執行階段工作負載專案，向中央 Agent Gateway 專案授予跨專案存取權，請在中央閘道專案中建立自訂 IAM 角色，並授予各個工作負載專案的執行階段服務代理：

   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 要求，將現有代理與 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/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 Registry 執行個體註冊，且該執行個體與 Agent Gateway 位於相同專案和區域。

   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：部署執行階段代理程式的專案編號
   • 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 主機名稱	區域和其他變化版本
   Agent Registry	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
   • Memory Bank：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

   如要瞭解如何註冊端點，請參閱「註冊端點」。如果您採用多專案設定，可以在單一代理程式註冊資料庫服務中，註冊多個核心 Google API 端點。詳情請參閱「註冊複合 Google API 端點」。您也必須確保代理程式具備這些端點的 iap.resources.egressViaIAP 權限。如需操作說明，請參閱「建立代理到端點輸出政策」。

7. 驗證代理設定

   控制台

   1. 前往 Cloud de Confiance 控制台的 Agent Platform「Deployments」(部署作業) 頁面。
      

      前往「Deployments」(部署作業) 頁面

   2. 按一下您部署的代理名稱。

   3. 按一下「服務設定」。代理的「Observability」(觀測能力) 窗格隨即開啟。

   4. 按一下「Deployment details」。Agent Gateway 的輸入和輸出設定位於「Deployment spec」(部署規格) 欄位下方。

   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) 代理

如果代理是使用自訂容器映像檔 (Bring Your Own Container / BYOC) 部署，且您想透過 Agent-to-Anywhere (egress) Agent Gateway 轉送其傳出流量，則必須將閘道的根憑證授權單位 (CA) 憑證，嵌入自訂容器映像檔的信任存放區。

由於 Agent Gateway 會對傳出的代理通訊執行 TLS 解密和檢查，因此非 BYOC (來源型) 代理部署作業會在建立映像檔時，自動插入 CA 憑證。如果是自訂容器映像檔，您必須明確擷取閘道的 CA 憑證，將其安裝到 Dockerfile 內的系統 CA 信任存放區，並設定 Python SDK、HTTP 用戶端程式庫和 gRPC 所需的憑證套件環境變數。

如要設定 BYOC 容器映像檔，用於 Agent Gateway egress，請按照下列步驟操作：

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 建構引數新增至 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 Threat Detection 服務。

• 在用戶端到代理 (輸入) 模式中，Agent Gateway 只能控管 Agent Runtime 的 query 和 streamQuery 方法。如要保護其他不支援的方法 (例如 asyncQuery)，可以直接從應用程式或代理套用 Model Armor 範本。請參閱「清理提示和回覆」，或這個程式碼實驗室，瞭解如何使用 Model Armor 建構安全的代理系統。

• 變更執行階段代理的 Agent Gateway 繫結，會封存代理的所有現有修訂版本。封存後無法復原。請參閱「Agent Gateway 和修訂版本」。

  如要更新代理，但不變更推論引擎 ID 或破壞政策繫結，請按照「更新 Agent Runtime 執行個體」一文所述，就地更新代理執行個體。

後續步驟