本指南可協助您排解 Gemini Enterprise Agent Platform 的連線問題，特別是使用 Agent Gateway、代理身分、Identity and Access Management (IAM) 政策，以及透過 Service Extensions 委派授權時。
使用 Agent Platform 疑難排解技能排解問題
如要與 AI 程式設計助理互動，診斷連線、授權和啟動問題，可以從 Cloud de Confiance by S3NS Agent Skills 存放區安裝 agent-platform-troubleshooting 技能。
這項技能可為 AI 代理提供特定領域的診斷劇本、記錄篩選器，以及 Agent Platform 堆疊的解決步驟，包括：
- Agent Gateway 輸出遭拒：診斷閘道攔截的錯誤，並驗證 IAP 授權決策。
403 Forbidden - 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/
- Agent Platform (推論引擎和工作階段)：
確認代理程式身分具備必要的基本角色
症狀：
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： Cloud de Confiance 專案 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 或自行簽署憑證的目的地，必須進行額外設定。
- 緩解：如要使用私人 CA 或自行簽署的憑證連線至目的地，請在代理程式連線能力範本中，使用
tlsConfig設定檔設定自訂傳輸層安全標準：TLS 信任錨點。
使用自訂容器 (BYOC) 部署的代理程式無法連線至 Agent Gateway
- 症狀：透過 Agent Gateway 轉送時，BYOC 代理無法建立連線。記錄可能會顯示 TLS 交握或憑證驗證錯誤。
- 原因：代理的自訂容器不信任代理閘道的憑證授權單位。
- 修正方式：請確認您已將 Agent Gateway 的根憑證新增至容器的 CA 存放區。請參閱「為 Agent Gateway 設定自訂容器 (BYOC) 代理程式」。
政策繫結失敗或模擬治理拒絕
- 症狀：政策繫結設定失敗、繫結政策時系統以互動方式提示您輸入
etag，或要求失敗並顯示錯誤的控管拒絕錯誤 (例如「未註冊的目的地已正確拒絕」)。 - 原因：專案中的 Identity-Aware Proxy API (
iap.googleapis.com) 已停用。 - 修正方式：啟用 Identity-Aware Proxy API。
透過員工身分聯盟管理 Agent Gateway 時發生失敗
如果您在Cloud de Confiance 控制台中管理 Agent Gateway，或使用透過 Workforce Identity Federation (WIF) 驗證的 gcloud CLI，可能會遇到這個問題。
控制台會顯示一般載入或建立錯誤，例如：
- 「載入時發生錯誤…」
- 「伺服器無法執行要求」
- 「無法建立 Agent Gateway」
- 「無法載入」
此外，gcloud 指令 (例如 gcloud network-services agent-gateways import) 可能會傳回內部錯誤，例如 error 13: an internal error has occurred。
如要解決這個問題，請使用透過 Cloud Identity 或 Google Workspace 管理的標準 Google 帳戶進行驗證，該帳戶必須具備必要權限，例如 roles/networkservices.admin。
在預先發布版中，Agent Platform Governance 和 Gateway 服務僅支援部分聯合身分功能。授予聯合主體範圍較廣的 IAM 角色無法解決問題。
偵錯工作流程
如果缺少輸出要求流程一節所述的任何條件，要求可能會遭到封鎖。
查看 IAP 裁決
如要將記錄搜尋範圍縮小至 IAP 輸出決策，請在 Cloud 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，表示目的地主機名稱未註冊。向代理程式登錄服務註冊目的地主機名稱，並確認代理程式具有這個目的地的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： Cloud de Confiance 專案 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 替換為與閘道相關聯的擴充功能名稱。如果不知道擴充功能名稱，可以前往 Cloud de Confiance Cloud de Confiance 控制台的閘道詳細資料頁面，並記下「服務擴充功能」下「擴充功能名稱」欄位的值。
確認授權政策明確指定閘道資源，並連結至相同的授權擴充功能。您可以前往 Cloud de Confiance Cloud de Confiance 控制台的閘道詳細資料頁面，記下「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：您的 Cloud de Confiance 組織 ID。PROJECT_ID： Cloud de Confiance 專案 ID。PRINCIPAL_SET：代理程式身分的主體組合。
如果繫結存在，請檢查 details.rules[].resources[] 欄位，確認目的地在代理程式的範圍內。
測試主體與主體組合繫結
如果權限運作不穩定或意外失敗，問題可能與代理程式群組身分 (主體集) 的設定方式有關。主體集權限可能因下列原因而失敗：
- 同步延遲：將身分新增至集合後，IAM 可能需要幾分鐘才能更新並辨識新成員。
- 缺少屬性：如果主體集成員資格需要特定屬性，代理程式的身分必須包含這些屬性 (例如部門或團隊標籤)。如果身分缺少這些屬性，代理程式可能會在不通知的情況下從群組中排除。
如要測試群組成員資格是否為問題所在，請在受影響的資源上新增直接繫結 principal://，直接將權限授予特定代理程式。如果代理程式成功與直接繫結建立連線，則根本原因可能是主體集屬性不符或同步延遲。如要解決這個問題，請驗證並更正代理的身分屬性，或使用直接 principal:// 繫結。
後續步驟
Codelabs：使用 Agent Platform 管理代理功能工作負載
瞭解如何透過 Gemini Enterprise Agent Platform 上的 Agent Gateway，控管代理工作負載。