本指南可帮助您调试并排查 Gemini Enterprise Agent Platform 的连接问题，尤其是在您将 Agent Gateway、代理身份、Identity and Access Management (IAM) 政策和委托授权与服务扩展程序搭配使用时。
使用 Agent Platform 问题排查技能进行问题排查
如需与 AI 编码助理互动，诊断连接、授权和启动问题，您可以从 Cloud de Confiance by S3NS 代理技能库中安装 agent-platform-troubleshooting 技能。
此技能可为 AI 智能体提供整个智能体平台堆栈中的特定领域诊断剧本、日志过滤器和问题解决步骤，包括：
- 代理网关出站拒绝：诊断网关拦截的
403 Forbidden错误并验证 IAP 授权决策。 - Agent Runtime 启动失败：识别缺失的角色（例如
roles/browser或resourcemanager.projects.get）和引导异常。 - Agent Registry 目标问题：验证服务条目、端点接口和整合的 Google API 配置。
- IAM 访问权限政策：验证 Unified Access Policies (UAP) 绑定、条件表达式和 Principal Access Boundary (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，以确定确切的被屏蔽主机名。确定目标服务主机名后，在代理注册表中注册这些主机名，并向代理授予
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 Identity 与 Agent Runtime 搭配使用。
403 Forbidden 个错误
如果您遇到 403 Forbidden 错误，请确认该错误是否与代理网关出站流量相关。以下是出站流量错误消息示例：
{"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) 部署的代理无法连接到代理网关
- 症状：BYOC代理在通过 Agent Gateway 路由时无法建立连接。日志可能会显示 TLS 握手或证书验证错误。
- 原因：智能体的自定义容器不信任 Agent Gateway 的证书授权机构。
- 修复：确保您已将代理网关的根证书添加到容器的 CA 存储区。请参阅为代理网关配置自定义容器 (BYOC) 代理。
政策绑定失败或模拟治理拒绝
- 症状：政策绑定配置失败；在绑定政策时，系统会以交互方式提示您输入
etag；或者请求失败，并显示错误的治理拒绝错误（例如“未注册的目标正确拒绝”）。 - 原因：您的项目中停用了 Identity-Aware Proxy API (
iap.googleapis.com)。 - 修复：启用 Identity-Aware Proxy API。
使用员工身份联合管理代理网关时出现故障
如果您在Cloud de Confiance 控制台中管理代理网关，或者在使用员工身份联合 (WIF) 进行身份验证时使用 gcloud CLI，则可能会遇到此问题。
控制台会显示常规加载或创建错误，例如：
- “加载时出错…”
- “服务器无法完成您的请求”
- “未能创建代理网关”
- “加载失败”
此外，gcloud 命令（例如 gcloud network-services agent-gateways import）可能会返回内部错误，例如 error 13: an internal error has occurred。
如需解决此问题，请使用通过 Cloud Identity 或 Google Workspace 管理且具有所需权限（例如 roles/networkservices.admin）的标准 Google 账号进行身份验证。
在预览版中，联合身份在代理平台治理和网关服务方面仅提供有限支持。向联合身份验证主账号授予更广泛的 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，则表示目标主机名未注册。向代理注册表注册目标主机名，并确保代理对该目标具有iap.resources.egressViaIAP权限。- 实施模式：查看请求的实施模式。如需过滤干运行请求，您可以向查询添加
protoPayload.metadata.iamEnforcementMode="DRY_RUN"。在DRY_RUN模式下，IAP 会记录拒绝事件，但不会强制执行这些拒绝事件。因此，如果代理在试运行模式下失败并出现403错误，则拒绝可能来自网关的出站代理或目标资源。
查看 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：记下代理尝试访问的确切目标网址。在下一步中，我们会检查目标资源使用的主机名是否已在代理注册表中注册。
验证目标注册和 IAM 访问权限政策覆盖范围
如需访问目标平台，始终需要 IAM 允许政策向代理身份授予 iap.resources.egressViaIAP 权限。建议在代理注册表中注册目的地，以强制执行精细的资源级访问政策，并确保准确的主机名匹配。对于未注册的目标，请验证未注册端点的政策是否向代理身份授予了所需的权限。
如果您依赖于按资源设置的政策，则代理尝试访问的每个目标主机名以及主机名的任何变体都必须在代理注册表中注册。这是因为 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。如需检查是否存在 per-MCP server 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 控制台中的网关详情页面，然后记下“Service Extensions”下的扩展程序名称字段的值。
验证授权政策是否明确以网关资源为目标，并链接到同一授权扩展程序。您可以前往 Cloud de Confiance Cloud de Confiance 控制台中的网关详情页面，并记下 Service Extensions 下的政策名称字段的值。
如果没有政策以网关为目标，或者网关到政策的映射不正确，则不会执行授权扩展程序。
检查主账号访问边界政策
主账号访问权限边界政策优先于 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:// 绑定。
后续步骤
Codelab：使用 Agent Platform 管理代理工作负载
了解如何在 Gemini Enterprise Agent Platform 上使用 Agent Gateway 治理智能体工作负载。