設定代理閘道

如要集中控管存取權，並確保代理工作流程的連線安全，您可以設定代理閘道資源來管理輸入或輸出流量。

設定閘道前，請先參閱 Agent Gateway 總覽，瞭解基本概念和核心元件。

所需權限

您必須具備下列權限，才能建立及管理 Agent Gateway。您可以透過自訂角色或其他預先定義的角色取得這些權限。

所需權限

  • compute.networkAttachments.list
  • compute.regions.list
  • modelarmor.templates.list
  • modelarmor.templates.list
  • networksecurity.authzPolicies.create
  • networksecurity.authzPolicies.delete
  • networksecurity.authzPolicies.get
  • networksecurity.authzPolicies.list
  • networksecurity.operations.get
  • networkservices.agentGateways.create
  • networkservices.agentGateways.delete
  • networkservices.agentGateways.get
  • networkservices.agentGateways.list
  • networkservices.agentGateways.update
  • networkservices.agentGateways.use
  • networkservices.authzExtensions.create
  • networkservices.authzExtensions.delete
  • networkservices.authzExtensions.get
  • networkservices.authzExtensions.list
  • networkservices.authzExtensions.update
  • networkservices.authzExtensions.use
  • networkservices.operations.get

必要 API

在您用於本指南的 Google Cloud 專案中，啟用下列 API。透過這些 API，您可以存取 Gemini Enterprise Agent Platform 提供的完整套件功能。

必要 API

  • Compute Engine API (compute.googleapis.com)
  • Network Security API (networksecurity.googleapis.com)
  • Network Services API (networkservices.googleapis.com)
  • Cloud DNS API (dns.googleapis.com)
  • Identity and Access Management API (iam.googleapis.com)
  • Agent Registry API (agentregistry.googleapis.com)
  • Vertex AI API (aiplatform.googleapis.com)
  • Discovery Engine API (discoveryengine.googleapis.com)
  • Cloud Storage API (storage.googleapis.com)
  • Model Armor API (modelarmor.googleapis.com)
  • Observability API (observability.googleapis.com)
  • Telemetry API (telemetry.googleapis.com)
  • Cloud Monitoring API (monitoring.googleapis.com)
  • Cloud Trace API (cloudtrace.googleapis.com)
  • Cloud Logging API (logging.googleapis.com)
  • App Hub API (apphub.googleapis.com)
  • App Topology API (apptopology.googleapis.com)
  • Cloud API Registry (cloudapiregistry.googleapis.com)
  • Notebooks API (notebooks.googleapis.com)
  • Text-to-Speech API (texttospeech.googleapis.com)
  • Dataform API (dataform.googleapis.com)

規劃 Agent Gateway 部署作業

請參閱本節，規劃 Agent Gateway 部署作業，並瞭解設定運作的相關規定。以下各節將說明基本元件，但不代表嚴格的步驟順序。您可以在初始設定期間註冊端點和 MCP 伺服器，並指派角色給代理程式，也可以在日後因應更多需求持續進行這項作業。

選擇部署模式

Agent Gateway 支援兩種部署模式：

  • 用戶端至代理 (輸入)：確保用戶端與在 Google Cloud上執行的代理程式之間的通訊安全。
  • 代理至任何位置 (輸出)：確保代理與外部目標、公開 API 和 MCP 伺服器之間的通訊安全。

選取執行階段、專案和部署區域

Agent Gateway 會控管從 Gemini Enterprise 和 Runtime 執行的代理流量。

  • Agent Runtime：Agent Gateway 支援「代理至任意目的地」(輸出) 和「用戶端至代理」(輸入) 模式。在「代理程式到任何位置」模式中，代理程式可以與閘道位於同一專案，也可以位於不同專案。在「用戶端到代理程式」模式中，代理程式必須與閘道位於同一專案。無論是哪種模式，代理程式都必須與閘道位於相同區域。

  • Gemini Enterprise：Agent Gateway 僅支援「代理至任意目的地」(輸出) 模式。有了 Gemini Enterprise，每個閘道只會控管部署專案和區域範圍內的代理互動。

如要集中管理 Gemini Enterprise 和 Runtime 中的代理，可以使用單一 Agent Gateway。或者，您也可以為 Gemini Enterprise 和 Runtime 部署獨立的 Agent Gateway 執行個體。

範例部署模式

以下列舉幾個可考慮的部署模式：

集中管理跨專案的 Runtime 代理

在這個部署模式中，您會在專屬控管專案中部署 Agent-to-Anywhere (輸出) Agent Gateway，集中控管輸出作業。執行階段代理會部署在與閘道相同的區域，且位於機構內的任何資料夾中。

如要設定跨專案輸出管理，請設定下列資源：

在中央控管專案中：

  • 建立 Agent Gateway。確認閘道已與 Agent Registry 執行個體建立關聯。
  • 透過附加至閘道的 Agent Registry，註冊跨專案代理，以及任何工具、伺服器或端點。
  • 將跨專案 IAM 權限授予每個專案的 Runtime 服務代理程式 (代理程式所在專案)，以便這些專案中的代理程式繫結至控管專案中的閘道。如需範例，請參閱透過 Agent Gateway 傳送執行階段流量。
  • 設定 IAP 政策、主體存取邊界和與 SPIFFE 相容的工作負載身分，控管及保護授權端點的出站流量。
  • 建立要用於輸出內容的 Model Armor 範本。
  • 如要輸出至虛擬私有雲網路，您可以在控管專案中建立 PSC 網路連結和 DNS 對等互連設定。

在「Agent Runtime projects」中：

  • 部署代理程式，並在控管專案中將其繫結至中央閘道。

請注意，跨專案控管僅適用於搭配 Agent-to-Anywhere (輸出) 閘道的執行階段；不支援 Gemini Enterprise。

Gemini Enterprise 和 Runtime 代理的共用控管機制

您的 Gemini Enterprise 應用程式會以多地區部署的形式 (us 或 eu) 部署，而所有其他資源 (執行階段、代理程式閘道和代理程式登錄) 則會部署在與 Gemini Enterprise 多地區設定對應的單一地區中。

在這種部署方式中，Gemini Enterprise 應用程式和 Runtime 會透過單一的本機代理閘道，將流量直接傳送至最終目的地。

Gemini Enterprise 應用程式位置 執行階段區域 Agent Gateway 區域 Agent Registry 執行個體1
global或us us-central1 us-central1 單一代理程式閘道必須與us-central1登錄檔建立關聯。
eu europe-west1 europe-west1 單一代理程式閘道必須與europe-west1登錄檔建立關聯。
1 如要讓代理程式與端點和伺服器 (包括 Google Cloud MCP 伺服器) 通訊，您必須手動向區域 Agent Registry 執行個體註冊。
獨立管理 Gemini Enterprise (使用 Google Cloud MCP 伺服器) 和 Runtime 代理

您的 Gemini Enterprise 應用程式會部署為多區域部署 (位於 global、us 或 eu)，而 Runtime 代理程式則會視需要部署在不同區域。Agent Gateway 執行個體會部署在執行階段所在的每個區域。

這個模式可確保區域隔離，每個區域都有專屬的代理閘道，用於監控及控管代理流量。

Gemini Enterprise 應用程式位置 執行階段區域 Agent Gateway 區域 Agent Registry 執行個體1
global 不限地區

Gemini Enterprise 的 us-central1 中有一個 Agent Gateway

每個要控管 Runtime 代理的區域都必須有 Agent Gateway

Gemini Enterprise 的代理閘道必須與 global 登錄檔建立關聯。

Runtime 的 Agent Gateway 必須與對應的區域登錄檔建立關聯。
us 不限地區

Gemini Enterprise 的 us-central1 中有一個 Agent Gateway

每個要控管 Runtime 代理的區域都必須有 Agent Gateway

Gemini Enterprise 的代理閘道必須與 global 登錄檔建立關聯。

Runtime 的 Agent Gateway 必須與對應的區域登錄檔建立關聯。
eu 不限地區

Gemini Enterprise 的 europe-west1 中有一個 Agent Gateway

在要控管 Runtime 代理的每個區域中，都必須有 Agent Gateway

Gemini Enterprise 的代理閘道必須與 global 登錄檔建立關聯。

Runtime 的 Agent Gateway 必須與對應的區域登錄檔建立關聯。
1 您必須手動向全域 Agent Registry 執行個體註冊 Runtime 代理，才能控管 Gemini Enterprise 應用程式與 Runtime 代理之間的連線。
獨立管理 Gemini Enterprise、Google Workspace 和 Runtime 代理

視需要，Gemini Enterprise、Google Workspace 和 Runtime 代理程式會以多區域或區域部署的形式部署。Agent Gateway 執行個體會部署在執行階段所在的每個區域。

如果 Google Workspace 代理程式是多區域，您需要將多區域登錄檔與 Agent Gateway 建立關聯，如下表所示。

Gemini Enterprise 應用程式和 Google Workspace 所在位置 執行階段區域 Agent Gateway 區域 Agent Registry 執行個體
us 不限地區

us-central1 中的單一 Agent Gateway，適用於 Gemini Enterprise 和 Google Workspace

每個要控管 Runtime 代理的區域都必須有 Agent Gateway

Gemini Enterprise 和 Google Workspace 的 Agent Gateway 必須與 us 註冊資料庫建立關聯。

Runtime 的 Agent Gateway 必須與對應的區域登錄檔建立關聯。
eu 不限地區

europe-west1 中的單一 Agent Gateway，適用於 Gemini Enterprise 和 Google Workspace

在要控管 Runtime 代理的每個區域中，都必須有 Agent Gateway

Gemini Enterprise 和 Google Workspace 的 Agent Gateway 必須與 eu 註冊資料庫建立關聯。

Runtime 的 Agent Gateway 必須與對應的區域登錄檔建立關聯。

註冊代理程式、端點、伺服器和工具

如要啟用安全通訊，您必須識別 Agent Registry 執行個體，並註冊閘道管理的資源。

  1. 找出您要使用的 Agent Registry 執行個體。

    • 如果是 Agent Runtime，請在 Agent Gateway 部署所在的專案和區域中，參照區域登錄檔 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/REGION)。

      注意：如果區域代理程式需要存取全域自動註冊的 Google 管理 MCP 伺服器 (位於 locations/global 下方)，您必須將區域和全域登錄路徑繫結至閘道。Agent Gateway 最多支援兩個繫結的登錄檔，其中一個必須是 global。如果省略全域登錄檔，對 Google 代管 MCP 伺服器的要求會失敗，並顯示 NOT_FOUND 錯誤。

    • 如果是 Gemini Enterprise，請在部署 Gemini Enterprise 代理程式和閘道的專案中，參照全球、多區域或區域登錄檔。如要瞭解適合您部署作業的登錄檔，請參閱「規劃部署作業」一節。

  2. 向 Agent Registry 註冊代理。如果您尚未建立代理程式，稍後必須完成這個步驟。如需操作說明，請參閱「註冊代理程式」一文。

    如果執行階段代理與閘道位於不同專案，則必須向閘道專案中的 Agent Registry 註冊。

  3. 找出並註冊代理會呼叫的所有工具、MCP 伺服器和 API 端點。您必須註冊這些資源，因為 Agent Gateway 會封鎖所有傳送至未在 Agent Registry 中註冊主機的輸出流量。

    如果目的地與閘道位於不同專案，則必須向閘道專案中的代理程式登錄服務註冊。這類目的地僅適用於「代理程式到任何位置」模式的執行階段代理程式。

    如需操作說明，請參閱下列指南：

設定存取控管機制

每個 Agent Gateway 都需要相關聯的授權政策。

IAP

根據預設，Agent Gateway 會使用 IAP，透過 Identity and Access Management (IAM) 中定義的政策，驗證代理程式、端點和伺服器。

如要在不封鎖流量的情況下驗證設定，建議您先以模擬測試模式部署 IAP。

Model Armor

(選用) 如果部署作業需要防範提示詞注入攻擊、越獄、有害內容或敏感資料外洩，您應規劃 Model Armor 護欄整合，並使用所需安全篩選器建立範本。

如需詳細資訊，請參閱下列文件：

語意管理政策

(選用) 您可以選擇在代理程式中新增以自然語言為基礎的脈絡感知控制項，防範工具的有害組合。

建議您先以試執行模式部署語意控管政策，以便驗證設定，同時不會封鎖流量。詳情請參閱「設定語意控管政策」。

自訂授權引擎

(選用) 如果您想使用 Service Extensions，將授權委派給自訂授權引擎或第三方系統，請確保部署閘道時可使用自訂授權引擎。

您可以在初始設定 Agent Gateway 時啟用 Model Armor、語意管理政策和任何其他自訂授權引擎，也可以在部署後附加這些項目，做為增量安全政策更新。

設定代理程式身分和權限

如要啟用代理程式與已註冊端點和 MCP 伺服器之間的通訊，請按照下列步驟操作：

  1. 為代理建立代理身分。您可以在部署期間或部署代理程式後執行這項操作。如需操作說明，請參閱「搭配執行階段使用代理程式身分」。

  2. 為您在 Agent Registry 中註冊的每個端點和伺服器，授予代理身分主體 roles/iap.egressor (IAP 安全外送者) 角色。

    您可以在登錄層級或個別資源層級授予這個角色。由於登錄檔可以是全域或區域，請確保任何登錄檔範圍的繫結都符合代理程式類型：

    • 如果是 Gemini Enterprise 代理，請使用全域登錄。
    • 如果是 Agent Runtime 代理程式，請使用區域登錄檔。

    Agent Gateway 會特別檢查 iap.webServiceVersions.egressViaIAP 權限，而這項權限只會由 roles/iap.egressor 角色授予。根據預設，除非這項 IAM 政策明確允許，否則所有輸出流量都會遭到拒絕。

    如需操作說明，請參閱「建立 IAM 代理程式政策」。

在「Agent-to-Anywhere (輸出)」模式下設定 Agent Gateway

本節說明如何設定 Agent Gateway，以進行「代理程式到任何位置」通訊。

請按照下列步驟建立 Agent Gateway 資源。

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Agent Gateway」頁面。

    前往「閘道」頁面

  2. 按一下「新增閘道」。
  3. 輸入名稱。
  4. 從「Region」(區域) 清單中選取區域。
  5. 確認「部署模式」已選取「Google 管理」。
  6. 在「Agent Registry」部分，從清單中選取登錄檔。如需為部署作業選擇登錄檔的指引，請參閱「規劃代理閘道部署作業」。
  7. 從「受管理的存取路徑」清單中，選取「代理程式到任何位置 (代理程式輸出)」。

  8. 在「存取授權」專區中，選擇 IAP 處理流量的方式：

    • 如要在模擬測試模式下部署閘道，允許所有流量通過閘道，並僅產生稽核記錄，請選取「僅限稽核」。 在模擬測試模式下，IAP 不會強制執行 IAM 政策。確認政策運作正常後，即可停用模擬測試模式，強制執行 IAM 政策。
    • 如要封鎖沒有明確 Allow IAM 政策的要求，請選取「強制執行政策」。建議在正式環境中使用這個選項。

  9. 選用步驟：在「AI Security」(AI 安全性) 部分，設定其他安全性措施：

    1. 如要使用 Model Armor 保護 AI 模型互動，請開啟「啟用 Model Armor」。
    2. 從清單中選取適用於從閘道傳送至伺服器的要求範本。

    3. 如要為回覆使用其他範本，請取消勾選「要求和回覆使用相同的範本」，然後從清單中選取範本。

  10. 按一下「新增閘道」。

gcloud

您可以使用 YAML 宣告式地定義 Agent Gateway。

  1. 定義資源，並將設定儲存至 YAML 檔案。本範例使用的是 my-agent-gateway-egress.yaml。

    name: AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - AGENT_REGISTRY_PATH

    更改下列內容：

    • AGENT_GATEWAY_NAME：Agent Gateway 資源的名稱。
    • AGENT_REGISTRY_PATH：Agent Registry 的路徑。如要瞭解部署作業應選擇哪個登錄檔，請參閱「規劃 Agent Gateway 部署作業」。

    如果您設定需要將流量路由至全球自動註冊的 Google 管理 MCP 伺服器的區域閘道 (例如 us-central1)，則必須在 registries 清單中指定區域和全域登錄路徑：

    name: my-agent-gateway
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
registries:
  - //agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1
  - //agentregistry.googleapis.com/projects/PROJECT_ID/locations/global

  2. 執行下列指令，根據 YAML 規格建立 Agent Gateway 資源：

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="my-agent-gateway-egress.yaml" \
 --location=LOCATION

    將 LOCATION 替換為要建立 Agent Gateway 資源的位置。例如：us-central1。

    請注意，如果是 Gemini Enterprise，您必須在與多區域設定對應的區域中部署 Agent Gateway。如要瞭解支援的位置對應，請參閱「透過 Agent Gateway 轉送 Gemini Enterprise 流量」。

  3. 建立授權政策，對通過 Agent Gateway 的流量強制執行集中式存取控管和管理政策。下列步驟說明如何設定使用 IAP 的授權政策。

    1. 設定指向 IAP 的授權擴充功能。 在 YAML 檔案中定義擴充功能，例如 iap-request-authz-extension.yaml。

      為驗證政策設定和路由，同時不中斷流量，建議您先以模擬測試 (僅稽核) 模式部署擴充功能。如要執行這項操作，請在 iamEnforcementMode 欄位中指定 DRY_RUN，如範例所示。

      cat >iap-request-authz-extension.yaml <<EOF
name: AUTHORIZATION_EXTENSION_NAME
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
  iapPolicyVersion: "V1"
EOF

    2. 將 YAML 設定檔匯入授權擴充功能。

      gcloud beta service-extensions authz-extensions import AUTHORIZATION_EXTENSION_NAME \
  --source=iap-request-authz-extension.yaml \
  --location=LOCATION

      將 AUTHORIZATION_EXTENSION_NAME 替換為授權擴充功能的名稱，例如 my-iap-request-authz-ext。

    3. 在 YAML 檔案 (例如 iap-request-authz-policy.yaml) 中定義授權政策，將擴充功能與閘道建立關聯：

      cat >iap-request-authz-policy.yaml <<EOF
name: AUTHORIZATION_POLICY_NAME
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/AUTHORIZATION_EXTENSION_NAME"
EOF

      更改下列內容：

      • AUTHORIZATION_POLICY_NAME：授權政策的名稱，例如 my-iap-request-authz-policy
      • PROJECT_ID：專案 ID

    4. 將 YAML 設定檔匯入授權政策。

      gcloud network-security authz-policies import AUTHORIZATION_POLICY_NAME \
  --source=iap-request-authz-policy.yaml \
  --location=LOCATION

  4. 選用：如要設定 Model Armor 防護機制，防範提示詞注入攻擊和敏感資料外洩，請參閱「將授權委派給 Model Armor」。

建立 Agent Gateway 後，該 Agent Gateway 會成為專案和所選區域內代理流量的主要連線點。您現在可以使用這個端點，在代理和目的地 (工具、其他代理或其他端點) 之間建立安全、加密及經過驗證的通訊管道。

接下來，請瞭解如何部署代理程式，並透過 Agent Gateway 轉送流量。

選用：設定虛擬私有雲連線

如要瞭解如何設定 Agent Gateway，使其能與貴機構的虛擬私有雲網路進行私下通訊，請參閱「為 Agent Gateway 設定虛擬私有雲連線」。

在用戶端至 Agent Gateway (輸入) 模式中設定 Agent Gateway

本節說明如何設定 Agent Gateway，以進行「用戶端到代理程式」通訊。

請按照下列步驟建立 Agent Gateway 資源。

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Agent Gateway」頁面。

    前往「閘道」頁面

  2. 按一下「新增閘道」。
  3. 輸入名稱。
  4. 從「Region」(區域) 清單中選取區域。
  5. 確認「部署模式」已選取「Google 管理」。
  6. 維持「代理程式登錄」設定的現狀。登錄檔不會用於 Ingress。
  7. 從「Governed Access Path」清單中，選取「Client-to-Agent (ingress)」。

  8. 選用步驟：在「AI Security」(AI 安全性) 部分，設定其他安全性措施：

    1. 如要使用 Model Armor 保護 AI 模型互動，請開啟「啟用 Model Armor」。

    2. 從清單中選取適用於從閘道傳送至伺服器的要求範本。

    3. 如要為回覆使用其他範本，請取消勾選「要求和回覆使用相同的範本」，然後從清單中選取範本。

  9. 按一下「新增閘道」。

gcloud

您可以使用 YAML 宣告式地定義 Agent Gateway。

  1. 定義資源，並將設定儲存至 YAML 檔案。本範例使用的是 my-agent-gateway-ingress.yaml。

    name: AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: CLIENT_TO_AGENT

    將 AGENT_GATEWAY_NAME 替換為 Agent Gateway 資源的名稱。

  2. 執行下列指令，根據 YAML 規格建立 Agent Gateway 資源：

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
 --source="my-agent-gateway-ingress.yaml" \
 --location=LOCATION

    將 LOCATION 替換為要建立 Agent Gateway 資源的位置。例如：us-central1。

建立 Agent Gateway 後，該閘道會成為主要連線點，將流量路由至專案和所選區域中的代理。

接著，瞭解如何部署代理程式，並透過 Agent Gateway 轉送流量。

部署代理程式並透過 Agent Gateway 轉送流量

如要部署 Agent Runtime 代理程式，將流量導向 Agent Gateway，請參閱「將流量導向 Agent Gateway」。

如要部署 Gemini Enterprise 代理，並透過 Agent Gateway 轉送流量，請參閱「透過 Agent Gateway 轉送 Gemini Enterprise 流量」。

Codelab

如需如何設定及使用 Agent Gateway 的完整示範，請參閱下列程式碼研究室：

後續步驟

指南

瞭解如何透過 Agent Gateway 轉送 Agent Runtime 流量，確保連線安全無虞並受到控管。

指南

瞭解如何將 Agent Gateway 的授權委派給 IAP、Model Armor 或您自己的自訂授權服務。

指南

瞭解如何監控 Agent Gateway。

疑難排解

瞭解如何排解 Agent Gateway 連線問題。

指南

瞭解如何透過 Agent Gateway 轉送 Gemini Enterprise 流量。