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

排解 Agent Gateway 連線問題

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

使用 Agent Platform 疑難排解技能排解問題

如要與 AI 程式開發輔助互動，診斷連線能力、授權和啟動問題，可以從 Google Cloud Agent Skills 存放區安裝 agent-platform-troubleshooting 技能。

這項技能可為 AI 代理提供特定領域的診斷教戰手冊、記錄檔篩選器，以及 Agent Platform 堆疊中的解決步驟，包括：

Agent Gateway 輸出拒絕：診斷閘道攔截的 403 Forbidden 錯誤，並驗證 IAP 授權決策。
Agent Runtime 啟動失敗：找出缺少的角色 (例如 roles/browser 或 resourcemanager.projects.get) 和啟動程序例外狀況。
Agent Registry 目的地問題：驗證服務項目、端點介面和整合式 Google API 設定。
IAM 存取權政策：驗證統一存取政策 (UAP) 繫結、條件運算式和主體存取邊界 (PAB) 範圍。
容器信任：診斷自備容器 (BYOC) 或私人憑證授權單位 (CA) 的 TLS 憑證和握手錯誤。

如要在代理環境中安裝技能，請執行下列指令：

npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting

輸出要求流程

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

要求必須符合下列所有條件，才能成功：

IAM 存取權政策：指派給代理的代理身分必須直接或透過主體集，取得目的地資源的 iap.resources.egressViaIAP 權限。詳情請參閱「建立 IAM 代理政策」。瞭解如何排解 IAP 政策問題。
代理註冊資料庫：建議在代理註冊資料庫中註冊目的地，以便強制執行精細的個別資源存取政策和工具層級控管。如果代理嘗試連線至未註冊的目的地，您必須為未註冊的端點設定政策，將 iap.resources.egressViaIAP 權限授予代理身分。
Agent Gateway：閘道必須與明確指定該閘道的授權政策建立關聯。根據預設，閘道會使用 IAP 和 Model Armor 保護要求。
使用 Service Extensions 委派授權：您可以使用 Service Extensions，將授權決策委派給自訂授權引擎。視設定的授權政策而定，一或多個授權引擎會允許或拒絕要求。

常見問題

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

Agent Runtime 啟動期間發生錯誤

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

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

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

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

修正方式：暫時將 IAP 切換至模擬測試模式，查看哪些連線失敗，但不會阻擋啟動，或查詢 Cloud Logging，找出確切的封鎖主機名稱。找出目標服務主機名稱後，請在 Agent Registry 中註冊，並將 iap.resources.egressViaIAP 權限授予代理。

如要使用 Cloud Logging 找出特定遭封鎖的主機名稱，請在 Logs Explorer 中執行下列查詢：
```
resource.type="networkservices.googleapis.com/Gateway"
resource.labels.gateway_type="SECURE_WEB_GATEWAY"
httpRequest.status=403
```
檢查結果中的 httpRequest.requestUrl 或 jsonPayload.authzPolicyInfo 欄位，找出目的地主機名稱。

啟動時可能需要註冊的常見內部服務包括：
- Agent Platform (推論引擎和工作階段)： https://REGION-aiplatform.mtls.googleapis.com
- Resource Manager：https://cloudresourcemanager.mtls.googleapis.com和https://cloudresourcemanager.mtls.googleapis.com/
- Google Cloud Observability (如已啟用)：https://telemetry.mtls.googleapis.com/
- Cloud Logging (如已啟用)：https://logging.googleapis.com/
- Cloud Monitoring：https://monitoring.googleapis.com/ 和 https://monitoring.mtls.googleapis.com/
- Cloud Trace：https://cloudtrace.googleapis.com/和https://cloudtrace.mtls.googleapis.com/
- Secret Manager：https://secretmanager.googleapis.com/和https://secretmanager.mtls.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 與代理身分」。

`403 Forbidden` 個錯誤

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

{"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 或自行簽署憑證的目的地，則須進行額外設定。
緩解措施：如要使用私人 CA 或自行簽署的憑證連線至目的地，您必須使用代理連線範本中的 tlsConfig 設定，設定自訂 TLS 信任錨點。如果代理程式也會連線至 Google Cloud API (*.googleapis.com) 或其他公開 HTTPS 端點，請務必在 tlsConfig 中將 additionalRoots 設為 PUBLICLY_TRUSTED_ROOTS。如果更新 tlsConfig 設定，則必須繫結新的連線能力範本 (或解除繫結並重新繫結範本)，因為 Agent Gateway 不會自動擷取附加範本上的就地 tlsConfig 變更。

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

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

政策繫結失敗或模擬管理拒絕

症狀：政策繫結設定失敗、繫結政策時系統以互動方式提示您輸入 etag，或要求失敗並顯示錯誤的控管拒絕錯誤 (例如「未註冊的目的地已正確拒絕」)。
原因：專案中已停用 Identity-Aware Proxy API (iap.googleapis.com)。
修正方式：啟用 IAP API。

透過員工身分聯盟管理 Agent Gateway 時發生錯誤

如果您在Google Cloud 控制台管理 Agent Gateway，或使用 gcloud CLI 透過員工身分聯盟 (WIF) 驗證，就可能遇到這個問題。

控制台顯示一般載入或建立錯誤，例如：

「載入時發生錯誤…」
「伺服器無法執行您的要求」
「無法建立 Agent Gateway」
「無法載入」

此外，gcloud 指令 (例如 gcloud network-services agent-gateways import) 可能會傳回內部錯誤，例如 error 13: an internal error has occurred。

如要解決這個問題，請使用透過 Cloud Identity 或 Google Workspace 管理、具備必要權限 (例如 roles/networkservices.admin) 的標準 Google 帳戶進行驗證。

在預先發布版中，Agent Platform Governance 和 Gateway 服務對聯合身分的支援有限。即使將更廣泛的 IAM 角色授予聯合主體，也無法解決問題。

偵錯工作流程

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

查看 IAP 裁決

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

protoPayload.serviceName="iap.googleapis.com"
protoPayload.authorizationInfo.permission="iap.resources.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，表示目的地主機名稱未註冊。請向 Agent Registry 註冊目的地主機名稱，並確認代理具備這個目的地的 iap.resources.egressViaIAP 權限。
強制執行模式：查看要求的強制執行模式。如要篩選模擬測試要求，您可以在查詢中新增 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 中註冊。

確認目的地註冊和 IAM 存取權政策涵蓋範圍

如要存取目的地，一律須透過 IAM 允許政策，將 iap.resources.egressViaIAP 權限授予代理身分。建議您在 Agent Registry 中註冊目的地，以便強制執行精細的個別資源存取政策，並確保主機名稱比對準確。如果目的地未註冊，請確認未註冊端點的政策是否授予代理身分必要權限。

如果您採用個別資源政策，則代理嘗試連線的每個目的地主機名稱和任何主機名稱變化版本，都必須在代理登錄檔中註冊。這是因為 Google API (例如 aiplatform.googleapis.com) 可透過多個主機名稱解析，具體取決於 SDK 版本、區域用戶端設定或 mTLS 使用情形 (例如 us-central1-aiplatform.googleapis.com 或 us-central1-aiplatform.mtls.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...

請前往「驗證目的地資源的 IAM 繫結」，檢查個別資源或整個登錄檔的政策是否授予代理身分存取權。

輸出 2：主機名稱不存在於登錄檔中

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

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

如要使用個別資源或整個登錄檔的政策，請先在 Agent Registry 中註冊目的地。如果您對未註冊的端點使用政策，請前往「驗證目的地資源的 IAM 繫結」。

驗證目的地資源的 IAM 繫結

請確認代理身分或其主體集具備目的地的 iap.resources.egressViaIAP 權限。

您可以在三個範圍內設定政策繫結：

整個儲存庫：可存取儲存庫中註冊的所有代理、MCP 伺服器和端點。
個別資源：縮小存取權範圍。每項資源的繫結會取代該特定資源的登錄檔層級繫結，而非與其合併。
未註冊端點的政策：存取未在 Agent Registry 中註冊的目的地。

請參考下列其中一個範例，檢查繫結：

如要檢查登錄檔層級 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)。

在傳回的政策資訊中，尋找與代理身分或主體集相符、具有 iap.resources.egressViaIAP 權限的繫結。如果傳回的輸出內容包含 "etag" 欄位，但沒有繫結，表示沒有 IAM 政策。

如果繫結存在，但包含 condition，請確認一般運算語言 (CEL) 運算式未排除代理。如果篩選條件是依據代理缺少的屬性，可能會在不顯示任何訊息的情況下排除代理。

如果目標目的地沒有相符的政策繫結，可將 iap.resources.egressViaIAP 權限授予代理身分或主體集，請使用下列其中一種政策選項授予權限：

Registry 層級政策 (建議)：設定代理至 Registry 政策，授予 Agent Registry 中所有已註冊資源的存取權。
個別資源政策 (MCP 伺服器或端點)：在 Agent Registry 註冊 MCP 伺服器或註冊端點，然後建立代理至 MCP 伺服器政策或代理至端點政策。
未註冊端點的政策：設定未註冊端點的政策，即可授予存取權，不必註冊資源。

檢查授權政策和擴充功能

在本節中，我們會確認是否有授權政策明確指定與代理相關聯的 Agent Gateway。

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

如果沒有政策指定閘道，或閘道與政策的對應關係不正確，系統就不會執行授權擴充功能。

檢查主體存取邊界政策

主體存取邊界政策的優先順序高於 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 Platform 疑難排解技能排解問題

輸出要求流程

常見問題

Agent Runtime 啟動期間發生錯誤

403 Forbidden 個錯誤

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

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

政策繫結失敗或模擬管理拒絕

透過員工身分聯盟管理 Agent Gateway 時發生錯誤

偵錯工作流程

查看 IAP 裁決

查看 Agent Gateway 決策

確認目的地註冊和 IAM 存取權政策涵蓋範圍

輸出 1：主機名稱已註冊

輸出 2：主機名稱不存在於登錄檔中

驗證目的地資源的 IAM 繫結

檢查授權政策和擴充功能

檢查主體存取邊界政策

測試主體與主體組合繫結

後續步驟

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

監控 Agent Gateway

排解 Agent Gateway 連線問題

`403 Forbidden` 個錯誤