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

透過 Agent Gateway 轉送 Agent Runtime 流量

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

事前準備

請務必熟悉在 Agent Runtime 上部署代理程式。
瞭解 Agent Gateway。您可以在 Agent-to-Anywhere (輸出) 模式下使用 Agent Gateway，確保所有輸出通訊安全無虞，並控管輸出流量，包括傳送至工具、模型、API 和其他代理的流量。您可以在「用戶端到代理程式」(輸入) 模式中使用閘道，控管哪些用戶端可以存取代理程式。您可以透過閘道選擇要將哪些 IAP 政策和 Model Armor 範本套用至這些互動。

單一 Runtime 執行個體可同時繫結至 Agent-to-Anywhere (輸出) 閘道和 Client-to-Agent (輸入) 閘道。

限制

Agent Gateway 無法繫結至 2026 年 4 月 29 日前建立的 Runtime Reasoning Engine。
單一專案和區域可代管多個 Agent-to-Anywhere (輸出) 和 Client-to-Agent (輸入) 代理程式閘道執行個體，但部署在相同專案和區域內的所有代理程式執行階段代理程式，都必須繫結至相同的特定輸出和輸入代理程式閘道執行個體。

舉例來說，如果專案和區域包含 egress-gateway-X 和 egress-gateway-Y，則該專案和區域中的所有代理程式都必須設定為使用相同的閘道進行輸出。也就是說，所有代理程式都使用 egress-gateway-X，或所有代理程式都使用 egress-gateway-Y。您無法將 agent-A 設為使用 egress-gateway-X，也無法將 agent-B 設為使用 egress-gateway-Y。

這項繫結規則也適用於專案和區域內的 Ingress 閘道。
為代理程式啟用 Agent Gateway 時，Security Command Center Agent Engine Threat Detection 服務無法使用。
在「用戶端到代理程式」(輸入) 模式中，Agent Gateway 只能控管 Agent Runtime 的 query 和 streamQuery 方法。如要保護其他不支援的方法 (例如 asyncQuery)，您可以直接從應用程式或代理程式套用 Model Armor 範本。請參閱「清除提示和回應」或「使用 Model Armor 建構安全的代理系統」程式碼研究室。

透過 Agent Gateway 轉送 Agent Runtime 流量

如要透過 Agent Gateway 轉送 Agent Runtime 流量，請執行下列步驟：

建立 Agent Gateway 資源，並視需要附加授權政策。您可以在「Agent-to-Anywhere」(輸出) 模式或「Client-to-Agent」(輸入) 模式中建立閘道。請注意，代理程式和閘道必須在相同專案和區域中建立。如需操作說明，請參閱「設定 Agent Gateway」。

請確認閘道已設定完成，可滿足部署需求。舉例來說，如果代理程式需要存取 LLM，請設定閘道允許這項存取權，避免發生 Agent Runtime 部署失敗的問題。

設定代理，透過 Agent Gateway 轉送流量。

新代理

部署代理時，請指定閘道資源。舉例來說，如要在 Agent Runtime 上部署代理程式，請使用 client.agent_engines.create 傳遞 local_agent 物件和任何選用設定。

如要搭配這個代理程式使用閘道中介平台功能，例如Model Armor或語意控管政策，請在建立呼叫中設定 agent_gateway_config 和 identity_type=AGENT_IDENTITY，如以下範例所示。如果沒有 identity_type=AGENT_IDENTITY，Runtime 執行個體的 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 替換為您在 Agent-to-Anywhere (輸出) 模式中建立的 Agent Gateway 名稱。

如果您在「用戶端到 Agent Gateway」(輸入) 模式中建立閘道，請改用 client_to_agent_config 欄位，並將 AGENT_GATEWAY_CLIENT_TO_AGENT_NAME 替換為您為輸入建立的 Agent Gateway 名稱。

現有代理商

代理至任意目的地

使用下列 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 名稱
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
- 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
注意： 為方便起見，您可以註冊基本 URI (例如 https://REGION-aiplatform.googleapis.com/)，但這樣做會提供廣泛的存取權政策，讓代理程式存取該網域下的任何服務。請注意，即使您註冊了基本 URI，仍須註冊所有區域和 mTLS 變體。

如要瞭解如何註冊端點，請參閱「註冊端點」。此外，請務必確保代理程式具有這些端點的 IAP Egressor 角色。如需操作說明，請參閱「建立從代理程式到端點的出站政策」。
驗證代理程式設定。
控制台
1. 前往 Google Cloud 控制台的 Agent Platform「Deployments」頁面。
  
  前往「Deployments」(部署作業)
2. 按一下您部署的代理程式名稱。
3. 按一下「服務設定」。代理程式的「可觀測性」窗格隨即開啟。
4. 按一下「部署詳細資料」。您可以在「Deployment spec」欄位下方找到代理程式閘道傳入和傳出設定。
gcloud
使用下列 REST API 要求，驗證代理程式現在是否已與閘道建立關聯。如果輸出內容為 null，表示 Runtime 無法繫結至閘道。
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：輸出 Agent Gateway 的名稱
REGION：部署閘道的區域
PROJECT_ID：專案 ID

更新 Dockerfile 以信任 CA 憑證。

在 Dockerfile 中加入 AGENT_GATEWAY_ROOT_CERTIFICATES 建構引數。建構指令會將憑證分割成個別檔案，使用 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 存放區和映像檔名稱。

部署容器化代理程式。

在部署要求中，指定建構的容器映像檔 URI，以及 Agent Gateway 設定 (使用 agent_gateway_config 下的 spec.deploymentSpec 或使用 SDK 部署呼叫)。

將 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 分鐘才會生效。

用戶端至代理

如要為「Client-to-Agent」模式 (傳入) 定義自訂限制，請建立名為 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 分鐘才會生效。

如要進一步瞭解如何使用自訂組織政策限制，請參閱「建立自訂限制」。

後續步驟

程式碼研究室

透過 Agent Gateway 轉送 Agent Runtime 流量

事前準備

限制

透過 Agent Gateway 轉送 Agent Runtime 流量

代理至任意目的地

用戶端至代理

控制台

gcloud

為 Agent Gateway 設定自訂容器 (BYOC) 代理程式

將 Agent Runtime 限制為僅限核准的代理閘道

建立自訂組織政策限制

代理至任意目的地

用戶端至代理

後續步驟

程式碼研究室：使用 Agent Platform 管理代理程式工作負載

將代理閘道的授權委派給服務帳戶

Agent Gateway

排解 Agent Gateway 問題

透過 Agent Gateway 轉送 Agent Runtime 流量 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

限制

透過 Agent Gateway 轉送 Agent Runtime 流量

代理至任意目的地

用戶端至代理

控制台

gcloud

為 Agent Gateway 設定自訂容器 (BYOC) 代理程式

將 Agent Runtime 限制為僅限核准的代理閘道

建立自訂組織政策限制

代理至任意目的地

用戶端至代理

後續步驟

程式碼研究室：使用 Agent Platform 管理代理程式工作負載

將代理閘道的授權委派給服務帳戶

Agent Gateway

排解 Agent Gateway 問題

透過 Agent Gateway 轉送 Agent Runtime 流量