透過 Agent Gateway 轉送 Gemini Enterprise 流量

本頁說明如何透過 Agent Gateway 導向 Gemini Enterprise 流量。Agent Gateway 是 Gemini Enterprise Agent Platform 生態系統的中央網路和安全元件。無論是使用者與代理、代理與工具，還是代理之間的互動，都能透過這項服務安全且受控地連線。

事前準備

  • 請務必熟悉 Gemini Enterprise 概念
  • 瞭解 Agent Gateway。請注意，代理閘道僅支援「代理至任何位置」(輸出) 模式的 Gemini Enterprise。系統不支援 Ingress 流量。
  • 部署 Gemini Enterprise 應用程式 (也稱為引擎)。本頁的程序假設您已部署應用程式。詳情請參閱「建立應用程式」。

必要權限

授予 Discovery Engine 服務代理 (即專案 Gemini Enterprise 執行個體的 Google 代管服務帳戶) 下列權限，讓 Discovery Engine 服務代理可以探索資源並轉送流量。

  • Agent Registry：

    • agentregistry.agents.list
    • agentregistry.agents.search
    • agentregistry.agents.get
    • agentregistry.mcpServers.list
    • agentregistry.mcpServers.search
    • agentregistry.mcpServers.get

  • Agent Gateway：

    • networkservices.agentGateways.list
    • networkservices.agentGateways.get
    • networkservices.agentGateways.use

請按照下列步驟，授予 Discovery Engine 服務代理程式權限。

  1. 建立具有這些權限的自訂角色。

    gcloud iam roles create AGENT_GATEWAY_ROLE_NAME \
--project=PROJECT_ID \
--title="Custom Agent Gateway and Agent Registry access role" \
--description="Custom role for Agent Gateway and Agent Registry access" \
--permissions="agentregistry.agents.list,agentregistry.agents.search,agentregistry.agents.get,agentregistry.mcpServers.list,agentregistry.mcpServers.search,agentregistry.mcpServers.get,networkservices.agentGateways.list,networkservices.agentGateways.get,networkservices.agentGateways.use"

    更改下列內容：

    • AGENT_GATEWAY_ROLE_NAME：自訂角色的名稱。
    • PROJECT_ID：部署代理程式的專案 ID。

  2. 將角色指派給 Gemini Enterprise 服務帳戶。

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
  --role="projects/PROJECT_ID/roles/AGENT_GATEWAY_ROLE_NAME"

    更改下列內容：

    • PROJECT_ID：專案 ID。
    • PROJECT_NUMBER：您的專案編號。
    • AGENT_GATEWAY_ROLE_NAME：您建立的自訂角色名稱。

規劃位置和 Agent Registry 對應

部署 Agent Gateway 前，請先選擇要部署閘道的區域，以及註冊資源的 Agent Registry。請注意下列要求：

  • 位置對應：在與 Gemini Enterprise 應用程式多區域設定對應的特定區域中，部署 Agent Gateway，確保路徑正確。

  • 登錄對應：為部署作業選擇全域、多區域或區域登錄。如需部署模式和登錄選項的更多指引，請參閱「規劃 Agent Gateway 部署作業」。

表格：Gemini Enterprise 應用程式位置和代理程式登錄對應
Gemini Enterprise 應用程式位置 必要的 Agent Gateway 區域 Agent Gateway 支援的 Agent Registry 執行個體
global us-central1

選擇下列其中一個選項：

  • global (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/global)
  • us (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us)
  • us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
us us-central1

選擇下列其中一個選項：

  • global (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/global)
  • us (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us)
  • us-central1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/us-central1)
eu europe-west1

選擇下列其中一個選項：

  • global (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/global)
  • eu (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/eu)
  • europe-west1 (//agentregistry.googleapis.com/projects/PROJECT_ID/locations/europe-west1)

透過 Agent Gateway 轉送 Gemini Enterprise 流量

如要透過 Agent Gateway 轉送 Gemini Enterprise 流量，請按照下列步驟操作：

  1. 建立 Agent Gateway 資源，並確保遵守上一節選取的區域和登錄檔。如需操作說明，請參閱「設定 Agent Gateway」。

    驗證閘道設定。使用 Network Services API 擷取 Agent Gateway 設定，並檢查設定。

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://networkservices.googleapis.com/v1alpha1/projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"

    以下是設定正確的閘道輸出範例：

    {
  "name": "projects/my-ge-project/locations/us-central1/agentGateways/my-egress-gateway",
  "description": "A full configuration for Agent Gateway for Gemini Enterprise egress",
  "googleManaged": {
    "governedAccessPath": "AGENT_TO_ANYWHERE"
  },
  "protocols": [
    "MCP"
  ],
  "registries": [
    "//agentregistry.googleapis.com/projects/my-ge-project/locations/global"
  ]
}

  2. 使用 UpdateEngine API 將閘道繫結至 Gemini Enterprise 應用程式。請注意，完成這個步驟後，所有現有的代理程式流量都會立即透過指定的代理程式閘道轉送。

    控制台

    1. 前往 Google Cloud 控制台的「Gemini Enterprise」頁面。

      Gemini Enterprise

    2. 按一下要與 Agent Gateway 建立關聯的應用程式名稱。

    3. 點按「安全性」。

    4. 在「Configuration」(設定) 分頁的「Agent Gateway configuration」(代理程式閘道設定) 下方，輸入閘道的完整資源名稱。請使用下列格式：projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME。

    5. 按一下 [儲存]。

    REST

    1. 請使用下列要求更新應用程式。

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
-d '{
  "agentGatewaySetting": {
    "defaultEgressAgentGateway": {
      "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
    }
  }
}' \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_APP_LOCATION/collections/default_collection/engines/GE_APP_ID?updateMask=agentGatewaySetting.defaultEgressAgentGateway.name"

      更改下列內容：

      • PROJECT_ID：專案 ID。
      • AGENT_GATEWAY_REGION：Agent Gateway 的區域。
      • AGENT_GATEWAY_NAME：Agent Gateway 的名稱。
      • PROJECT_NUMBER：專案編號。
      • GE_APP_LOCATION：Gemini Enterprise 應用程式的位置 (例如 us 或 global)。
      • GE_APP_ID：Gemini Enterprise 應用程式的 ID。

    2. 如要驗證應用程式設定，請使用下列指令擷取設定並檢查：

      curl -s -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/GE_LOCATION/collections/default_collection/engines/GE_APP_ID" \
| jq '{name: .name, displayName: .displayName, agentGatewaySetting: .agentGatewaySetting}'

      以下是設定正確的應用程式輸出內容範例：

      {
"name": "projects/PROJECT_NUMBER/locations/GE_LOCATION/collections/default_collection/engines/GE_APP_ID",
"displayName": "GE_APP_ID",
"agentGatewaySetting": {
  "defaultEgressAgentGateway": {
    "name": "projects/PROJECT_ID/locations/AGENT_GATEWAY_REGION/agentGateways/AGENT_GATEWAY_NAME"
  }
}
}

  3. 雖然 Gemini Enterprise 應用程式已啟用輸出內容控管功能，但應用程式不會自動得知可與 Agent Registry 上的哪些外部資源互動。

    您必須明確將所選代理程式、端點和 MCP 伺服器匯入 Gemini Enterprise 應用程式。匯入的資源必須使用其確切的登錄式資源名稱參照。如需操作說明，請參閱下列指南：

  4. 如要確認輸出功能是否正常運作，請執行下列步驟：

    1. 開啟 Gemini Enterprise 網頁應用程式。
    2. 提交查詢，觸發外部工具 (例如「Give me a list of recent issues from GitHub」)。
    3. 監控執行作業，確保成功擷取回應。 在幕後，Gemini Enterprise 代理會封裝要求、透過 Agent Gateway 傳送要求 (Agent Gateway 會強制執行所有已設定的授權政策)，並從目的地擷取回應。

將 Gemini Enterprise 繫結限制為已核准的代理閘道

您可以建立自訂組織政策限制，限制 Gemini Enterprise 應用程式是否可繫結至任何或所有代理程式閘道。

建立自訂組織政策限制

這個範例會建立自訂限制，禁止 Gemini Enterprise 應用程式與代理閘道之間的所有繫結。

代理至任意目的地

  1. 如要為「代理程式到任何位置」模式 (輸出) 定義自訂限制，請建立名為 constraint-agent-gateway-egress.yaml 的檔案。

    以下範例說明如何禁止任何繫結，強制執行嚴格的網路隔離。condition 欄位指定如果指定 Agent Gateway 資源 (欄位存在且不為空)，則作業遭拒。

    name: organizations/ORGANIZATION_ID/customConstraints/custom.disallowGeminiEnterpriseAgentGatewayBinding
resource_types:
– discoveryengine.googleapis.com/Engine
condition: >-
has(resource.agentGatewaySetting.defaultEgressAgentGateway.name) &&
resource.agentGatewaySetting.defaultEgressAgentGateway.name != ''
actionType: DENY
displayName: "Disallow all Agent Gateway Bindings for Discovery Engines"
description: "To enforce strict network isolation, Discovery Engines are not permitted to bind to any Agent Gateway."

    更改下列內容：

    • ORGANIZATION_ID：您的機構 ID。
    • PROJECT_ID：您的專案 ID。
    • REGION：建立閘道的區域。
    • AGENT_GATEWAY_NAME：閘道名稱。

  2. 套用自訂限制條件。

    gcloud org-policies set-custom-constraint EGRESS_CONSTRAINT_PATH

    將 EGRESS_CONSTRAINT_PATH 替換為上一步建立的自訂限制檔案完整路徑。

  3. 建立組織政策，強制執行限制條件。如要定義組織政策，請建立名為 policy-agent-gateway-egress.yaml 的政策 YAML 檔案。在本範例中，我們是在專案層級強制執行這項限制，但您也可以在機構或資料夾層級設定這項限制。

    name: projects/PROJECT_ID/policies/custom.disallowGeminiEnterpriseAgentGatewayBinding
spec:
rules:
– enforce: true

    將 PROJECT_ID 替換為專案 ID。

  4. 強制執行機構政策。

    gcloud org-policies set-policy EGRESS_POLICY_PATH

    請將 EGRESS_POLICY_PATH 替換為上一步建立的機構政策 YAML 檔案完整路徑。政策最多需要 15 分鐘才會生效。

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

後續步驟

程式碼研究室

瞭解如何透過 Gemini Enterprise Agent Platform 上的 Agent Gateway，控管代理式工作負載。

指南

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

指南

瞭解如何監控 Agent Gateway。

疑難排解

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