Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

排解 Agent Gateway 連線問題

本指南可協助您排解 Gemini Enterprise Agent Platform 的連線問題，特別是使用 Agent Gateway、代理身分、Identity and Access Management (IAM) 政策，以及透過 Service Extensions 委派授權時。

輸出要求流程

Agent Platform 會對所有輸出流量採用「預設拒絕」政策。如要讓代理程式連線至外部資源，您必須在每個網路和身分層明確允許存取權。啟用 Agent Gateway 後，閘道會攔截代理程式的所有要求，並套用已設定的政策。

如要成功提出要求，必須符合下列所有條件：

Agent Registry：目的地必須註冊為端點、Model Context Protocol (MCP) 伺服器或代理。
Agent Gateway：閘道必須與明確以其為目標的授權政策相關聯。根據預設，閘道會使用 IAP 和 Model Armor 保護要求。
透過 Service Extensions 委派授權：您可以使用 Service Extensions，將授權決策委派給自訂授權引擎。視設定的授權政策而定，一或多個授權引擎會允許或拒絕要求。
IAM 允許政策：指派給代理程式的代理程式身分必須直接或透過主體集，在已註冊的目的地資源上擁有 roles/iap.egressor 角色。詳情請參閱「建立 IAM 代理程式政策」。

常見問題

排解 Agent Gateway 問題時，請參閱下列常見問題和解決方法。

Agent Runtime 啟動期間發生錯誤

如果 Agent Runtime 執行個體無法啟動或部署，可能是因為 IAP 封鎖內部流量，或是代理程式缺少初始化所需的基本角色。

確認 IAP 未封鎖對內部服務的呼叫

症狀：啟動時發生 403 Forbidden 錯誤。

原因：Agent Gateway 對所有流量都採用預設拒絕政策。因此，當 IAP 處於強制執行模式時，即使是內部服務 (例如 aiplatform 或 logging)，除非已註冊且代理程式具備必要的 IAM 權限，否則都會遭到封鎖。

修正：暫時將 IAP 切換至模擬測試模式，查看哪些連線失敗，但不會封鎖啟動程序。找出目標服務主機名稱後，請在代理程式登錄中註冊這些名稱，並將 roles/iap.egressor 角色授予代理程式。

啟動期間可能需要註冊的常見內部服務包括：
- Resource Manager：https://cloudresourcemanager.mtls.googleapis.com 和 https://cloudresourcemanager.mtls.googleapis.com/
- Cloud Trace (如已啟用)：https://telemetry.mtls.googleapis.com/
- Cloud Logging (如已啟用)：https://logging.googleapis.com/
確認代理程式身分具備必要的基本角色

症狀：在 aiplatform.googleapis.com/reasoning_engine_stderr 記錄中，您會看到 google.api_core.exceptions.Unknown: None 或 Failed to convert project number to project ID 等錯誤。錯誤發生在 Reasoning Engine 啟動期間。

原因。代理程式身分缺少 resourcemanager.projects.get 權限，因此無法在初始化期間解析專案名稱。

修正。請確認代理程式身分 (或其主體集) 具備讀取自身執行階段設定所需的權限。您必須具備下列角色：
- roles/aiplatform.agentDefaultAccess：預設的代理程式角色。
- roles/aiplatform.user：執行代理程式時必須提供。
- roles/agentregistry.viewer：查看已註冊資源時必須提供。
- roles/logging.logWriter 和 roles/monitoring.metricWriter：可觀測性必備。
- roles/browser：在 SDK 初始化期間執行 resourcemanager.projects.get 時，必須提供這項資訊。
如要驗證指派給代理程式身分的角色，請執行下列指令：
```
gcloud projects get-iam-policy PROJECT_ID \
--flatten="bindings[].members" \
--filter="bindings.members:AGENT_IDENTITY_PRINCIPAL"
```
更改下列內容：
- PROJECT_ID： Google Cloud 專案 ID。
- AGENT_IDENTITY_PRINCIPAL：代理程式身分主體。使用下列格式： principal://TRUST_DOMAIN/resources/SERVICE/RESOURCE_PATH
如要瞭解如何授予角色，請參閱「搭配 Agent Runtime 使用 Agent Identity」。

`403 Forbidden` 個錯誤

如果遇到 403 Forbidden 錯誤，請確認是否與 Agent Gateway 輸出相關。以下是輸出錯誤訊息範例：

{"code": 403, "message": "403 Forbidden. {'message': 'Egress request is not authorized.', 'status': 'Forbidden'}"}

在 Logging 中查詢代理程式記錄，找出特定失敗的呼叫：

resource.type="aiplatform.googleapis.com/ReasoningEngine"
resource.labels.location="LOCATION"
resource.labels.reasoning_engine_id="AGENT_ID"
textPayload:"403"

更改下列內容：

LOCATION：部署代理程式的區域，例如 us-central1。
AGENT_ID：代理程式 (推理引擎) 的 ID。

在記錄項目的 textPayload 中尋找 Egress request is not authorized 訊息。如果 403 錯誤包含不同文字，則目的地服務可能直接拒絕呼叫，而非 Agent Gateway。

您也可以使用內建的可觀測性資訊主頁，查看輸出流量記錄，包括 403 拒絕。

無法連線至自簽或私人 CA 目的地

症狀：代理程式無法連線至提供自簽或私有 CA 核發憑證的目的地。
原因：Agent Gateway 不會驗證自行簽署的憑證鏈結。
解決方法：使用公開信任的 CA 憑證，或使用沒有 CA 憑證的目的地。

使用自訂容器 (BYOC) 部署的代理程式無法連線至 Agent Gateway

症狀：透過 Agent Gateway 轉送時，BYOC 代理程式無法建立連線。記錄可能會顯示 TLS 交握或憑證驗證錯誤。
原因：代理程式的自訂容器不信任 Agent Gateway 的憑證授權單位。
修正方式：請確認您已將 Agent Gateway 的根憑證新增至容器的 CA 存放區。請參閱「為 Agent Gateway 設定自訂容器 (BYOC) 代理程式」。

偵錯工作流程

如果缺少出口要求流程一節所述的任何條件，您的要求可能會遭到封鎖。

查看 IAP 裁決

如要將記錄搜尋範圍縮小至 IAP 輸出決策，請在 Logging 中執行下列查詢：

protoPayload.serviceName="iap.googleapis.com"
protoPayload.authorizationInfo.permission="iap.webServiceVersions.egressViaIAP"
protoPayload.metadata.mcp_attributes.base_protocol_method="true"

如果完全沒有看到相符的 IAP 記錄項目，則可能是閘道在 IAP 評估要求前就已拒絕要求。請繼續執行下一個步驟。

如果看到相符的記錄項目，請檢查下列欄位：

protoPayload.authorizationInfo[].granted：指出要求是獲得允許 (true) 還是遭到拒絕 (false)。
protoPayload.authenticationInfo.principalSubject：呼叫端的 SPIFFE ID 或principal://...身分。確認這與代理商身分相符。
protoPayload.authorizationInfo[].resource：通話解析到的已註冊目的地資源。
labels."iap.googleapis.com/audited_resource_name"：如果這個值是 unregisteredResource，則不會註冊目的地主機名稱。向代理程式登錄檔註冊目的地主機名稱，並確認代理程式具有這個目的地的 roles/iap.egressor 角色。
強制執行模式：查看要求的強制執行模式。如要篩選模擬執行要求，可以在查詢中加入 protoPayload.metadata.iamEnforcementMode="DRY_RUN"。在 DRY_RUN 模式下，IAP 會記錄拒絕要求，但不會強制執行。因此，如果代理程式在試執行模式下失敗並出現 403 錯誤，拒絕要求的原因可能是閘道的輸出 Proxy 或目的地資源。

查看 Agent Gateway 決策

如要查看 Agent Gateway 如何評估要求，請在 Logging 中查詢閘道記錄。在本例中，我們只會篩選出 403 錯誤的記錄：

resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
resource.labels.location="REGION"
resource.labels.gateway_name="AGENT_GATEWAY_NAME"
httpRequest.status=403
-httpRequest.requestMethod="CONNECT"

查看相符記錄項目中的下列欄位：

jsonPayload.authzPolicyInfo.policies.result：整體授權結果，可為 ALLOWED 或 DENIED。
httpRequest.requestUrl：請記下代理程式嘗試連線的確切目標網址。在下一個步驟中，我們會檢查目的地資源使用的主機名稱是否已在 Agent Registry 中註冊。

確認目的地已在 Agent Registry 註冊

代理程式嘗試連線的每個目的地主機名稱，以及主機名稱的任何變體，都必須在代理程式登錄中註冊。這是因為 Google API (例如 aiplatform.googleapis.com) 可透過多個主機名稱解析，具體取決於 SDK 版本、區域用戶端設定或 mTLS 用法。例如 us-central1-aiplatform.googleapis.com、us-central1-aiplatform.mtls.googleapis.com 或 aiplatform.googleapis.com。

不過，閘道只會完全比對主機名稱。因此，如果您註冊 aiplatform.googleapis.com，但代理程式呼叫 us-central1-aiplatform.googleapis.com，閘道會拒絕要求。閘道會將其視為未註冊的資源。

執行下列範例指令碼，根據資源類型列出登錄項目，並檢查代理程式呼叫所用特定主機名稱的項目：

HOSTNAME="HOSTNAME"
PROJECT_ID="PROJECT_ID"
LOCATION="REGION"

echo "Checking Endpoints..."
gcloud agent-registry endpoints list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking MCP Servers..."
gcloud agent-registry mcp-servers list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

echo "Checking Agents..."
gcloud agent-registry agents list \
  --project="$PROJECT_ID" \
  --location="$LOCATION" | grep "$HOSTNAME"

更改下列內容：

HOSTNAME：代理程式嘗試連線的目的地主機名稱，例如 us-central1-aiplatform.mtls.googleapis.com。
PROJECT_ID： Google Cloud 專案 ID。
REGION：Agent Registry 和 Agent Gateway 資源的位置，例如 us-central1。

輸出 1：主機名稱已註冊

如果主機名稱存在於代理程式登錄項目中，您會看到類似下列範例的輸出內容：

Checking Endpoints...
  url: https://us-central1-aiplatform.mtls.googleapis.com
Checking MCP Servers...
Checking Agents...

請繼續執行下一個步驟。

輸出 2：登錄中沒有主機名稱

如果登錄檔中沒有主機名稱，您會看到類似下列範例的輸出內容：

Checking Endpoints...
Checking MCP Servers...
Checking Agents...

如要修正問題，請註冊缺少的 MCP 伺服器或端點，然後將新登錄項目的 roles/iap.egressor 角色授予代理。

驗證目標資源的 IAM 繫結

確認代理程式身分或其主體集在目的地具有 roles/iap.egressor 角色。Agent Gateway 會特別尋找 iap.webServiceVersions.egressViaIAP 權限，而這項權限只會由 roles/iap.egressor 角色授予。

您可以在兩個範圍繫結角色：

全儲存庫：存取儲存庫中的所有代理、MCP 伺服器和端點。
依資源：縮小存取範圍。資源專屬繫結會取代該特定資源的登錄檔繫結，而不是與其合併。

請使用下列其中一個範例檢查繫結：

如要檢查登錄層級 IAM 政策繫結，請執行下列指令：

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry:getIamPolicy" \
-H "Content-Type: application/json"

如要檢查端點專屬 IAM 政策繫結，請執行下列指令：

export HOSTNAME=HOSTNAME

ENDPOINT_ID=$(gcloud agent-registry endpoints list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$HOSTNAME" \
--format="value(name.basename())")

echo "ENDPOINT_ID=$ENDPOINT_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/endpoints/${ENDPOINT_ID}:getIamPolicy"

將 HOSTNAME 替換為代理程式嘗試連線的目標主機名稱，例如 us-central1-aiplatform.mtls.googleapis.com。

如要檢查每個 MCP 伺服器的 IAM 政策繫結，請執行下列指令：

export MCP_SERVER=MCP_SERVER

MCP_SERVER_ID=$(gcloud agent-registry mcp-servers list \
--project="PROJECT_ID" \
--location="REGION" \
--filter="interfaces.url:$MCP_SERVER" \
--format="value(name.basename())")

echo "MCP_SERVER_ID=$MCP_SERVER_ID"

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-d '{}' \
-X POST "https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/iap_web/agentRegistry/mcpServers/${MCP_SERVER_ID}:getIamPolicy"

將 MCP_SERVER 替換為 MCP 伺服器的網址 (例如 https://example-abc12345-uc.a.run.app/mcp)。

在傳回的政策資訊中，尋找與代理程式身分或主體集相符的 roles/iap.egressor 角色繫結。如果傳回的輸出內容包含 "etag" 欄位，但沒有繫結，表示沒有身分與存取權管理政策。

如果繫結存在但包含 condition，請確認一般運算語言 (CEL) 運算式未排除代理程式。如果篩選條件是依據代理缺少屬性，系統可能會默默排除代理。

如果端點或 MCP 伺服器沒有與代理 ID 或主體相符的繫結，請在資源上授予代理角色：

檢查授權政策和擴充功能

在本節中，我們要確保授權政策明確指定與代理程式相關聯的 Agent Gateway。

取得與閘道相關聯的授權擴充功能詳細資料，並確認您使用的擴充功能已依預期設定。
```
gcloud service-extensions authz-extensions describe AUTHORIZATION_EXTENSION_NAME \
  --location=LOCATION \
  --project=PROJECT_ID
```
將 AUTHORIZATION_EXTENSION_NAME 替換為與閘道相關聯的擴充功能名稱。如果不知道擴充功能的名稱，可以前往 Google Cloud Google Cloud 控制台的閘道詳細資料頁面，並記下「服務擴充功能」下「擴充功能名稱」欄位的值。
確認授權政策明確指定閘道資源，並連結至相同的授權擴充功能。您可以在 Google Cloud Google Cloud 控制台中前往閘道的詳細資料頁面，並記下「服務擴充功能」下「政策名稱」欄位的值。

如果沒有政策以閘道為目標，或閘道與政策的對應不正確，授權擴充功能就不會執行。

檢查主體存取邊界政策

主體存取邊界政策的優先順序高於 IAM 允許政策。也就是說，即使您已正確設定所有 IAM 繫結，如果有效的主體存取權界線政策將目的地資源排除在代理程式範圍之外，要求仍會失敗。

如要列出全機構適用的政策，請執行下列指令：

gcloud iam principal-access-boundary-policies list \
  --organization="ORGANIZATION_ID" \
  --location=global

如要找出繫結至代理程式主體組合的政策，請執行：

gcloud iam policy-bindings search-target-policy-bindings \
  --project="PROJECT_ID" \
  --target="PRINCIPAL_SET"

更改下列內容：

ORGANIZATION_ID：您的 Google Cloud 機構 ID。
PROJECT_ID： Google Cloud 專案 ID。
PRINCIPAL_SET：代理程式身分的主體組合。

如果存在繫結，請檢查 details.rules[].resources[] 欄位，確認目的地是否在代理程式的範圍內。

測試主體與主體組合繫結

如果權限運作不穩定或意外失敗，問題可能與代理程式群組身分 (主體集) 的設定有關。基於主體集權限可能無法運作的原因如下：

同步延遲：將身分新增至集合後，IAM 可能需要幾分鐘才能更新並辨識新成員。
缺少屬性：如果主體集成員資格需要特定屬性，代理商的身分必須包含這些屬性 (例如部門或團隊標籤)。如果身分缺少這些屬性，代理人可能會從群組中排除。

如要測試群組成員資格是否為問題所在，請在受影響的資源上新增直接繫結 principal://，直接授予特定代理程式權限。如果代理程式成功與直接繫結建立連線，則根本原因可能是主體集屬性不符或同步延遲。如要解決這個問題，請驗證並修正代理程式的身分屬性，或使用直接 principal:// 繫結。

後續步驟

程式碼研究室

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

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

指南

Agent Gateway

瞭解如何監控 Agent Gateway。

排解 Agent Gateway 連線問題 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

輸出要求流程

常見問題

Agent Runtime 啟動期間發生錯誤

403 Forbidden 個錯誤

無法連線至自簽或私人 CA 目的地

使用自訂容器 (BYOC) 部署的代理程式無法連線至 Agent Gateway

偵錯工作流程

查看 IAP 裁決

查看 Agent Gateway 決策

確認目的地已在 Agent Registry 註冊

輸出 1：主機名稱已註冊

輸出 2：登錄中沒有主機名稱

驗證目標資源的 IAM 繫結

檢查授權政策和擴充功能

檢查主體存取邊界政策

測試主體與主體組合繫結

後續步驟

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

Agent Gateway

排解 Agent Gateway 連線問題

`403 Forbidden` 個錯誤