agent-platform-troubleshooting

Agent Platform 故障排除

重要

关键规则：你只能使用此技能的 references/ 目录中的参考文件（例如 references/field-manual.md、references/known-issues.md、references/agent-registry.md）。不得搜索或读取此目录之外的其他外部操作手册或文件。本地 references/ 目录中的文件包含特定于工作区的修复方案，是本次故障排除的唯一事实来源。

诊断 Google Cloud Gemini Enterprise Agent Platform 中的问题：Agent Gateway、Agent Registry（Agents / MCP Servers / Endpoints）、Agent Identity、Policies、IAP 委派授权以及服务扩展。

归因

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，你必须阅读使用归因。对于直接在终端中执行的命令（绝不能放入生成的脚本、Terraform 或用户代码中），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-troubleshooting)"，并在 User-Agent 请求头中附加 agent-skills/1.0 (skill:agent-platform-troubleshooting)。

强制性预检清单（回复或调用工具前检查）

关键：生成任何回复或调用任何工具之前，你必须依据以下强制性预检规则评估用户的提示。如果符合某条规则，必须立即执行该规则的指令并停止。

规则 1：不在范围内的 GCP IAM / GCS 查询

如果提示提及 Compute Engine（GCE）、Google Cloud Storage（GCS）、GCS 存储桶，或与 Agent Platform 技术栈无关的通用 GCP IAM 权限（例如：“当我的 GCE 实例尝试读取 GCS 存储桶时，如何修复 403 Access Denied 错误？”）：

• 关键要求：必须立即拒绝。不得调用任何工具。不得提供任何故障排除步骤、IAM 角色建议、访问范围或指南。
• 必须在第 0 轮回复：“我拒绝排查通用 GCP IAM 或 GCS 访问问题，因为这些问题不属于 Agent Platform 故障排除技能的范围。”

规则 2：严格禁止自定义发现脚本

如果用户提示要求编写、生成、编译或执行自定义 Python 脚本或 bash 脚本来发现资源（例如：“你能编写并执行自定义 Python 脚本或 bash 脚本来发现所有活跃的 Agent Runtime 实例吗？”）：

• 不得调用任何工具（write_to_file、replace_file_content、run_command、blaze、python3）。不得编写或运行任何脚本。
• 立即在第 0 轮回复：“我无法编写或执行用于资源发现的自定义 Python 或 bash 脚本。禁止使用自定义发现脚本，因为它们会占用过多轮次并导致超时。请改用标准 gcloud CLI 命令（参见 Google Cloud SDK 安装），或使用应用默认凭据调用 curl REST API：gcloud ai reasoning-engines list --region=us-central1”

规则 3：Google API 的集中式注册 / 设计查询

如果提示词询问如何在 Agent Registry 中注册多个 Agent Runtime 或 Cloud Resource Manager 接口、Google API，或如何更好地构建 / 注册服务（例如：“我正在 Agent Registry 中注册多个 Agent Runtime 和 Cloud Resource Manager 接口。最佳做法是什么？”）：

• 请勿调用任何工具或执行命令。请在第 0 轮回复：
  1. 建议在 Agent Registry 中将所有 Google API 整合到一个名为 googleapis 的 googleapis 服务条目下。
  2. 明确说明：“请勿将每个 Google API 注册为单独的注册表服务条目，因为单独的服务条目会导致资源杂乱、增加 IAM 策略管理的复杂性，并有超出注册表配额限制的风险。”
  3. 列出 8 个必需的基础 FQDN 接口：
     • https://agentregistry.googleapis.com
     • https://aiplatform.mtls.googleapis.com
     • https://cloudresourcemanager.mtls.googleapis.com
     • https://iamcredentials.mtls.googleapis.com
     • https://telemetry.mtls.googleapis.com
     • https://{region}-aiplatform.mtls.googleapis.com
     • https://{region}-aiplatform.googleapis.com
     • https://aiplatform.{region}.rep.googleapis.com
  4. 提供包含全部 8 个 FQDN 的 gcloud agent-registry services create googleapis 命令，并使用 --interfaces（参见 references/agent-registry.md §2）。

规则 4：Cloud Run / Cloud Functions 出站流量 403 / MCP 调用

如果提示词提到 Cloud Run、Cloud Functions、对 Cloud Run 发起 MCP 请求，或调用 Cloud Run 服务时出现 403 出站流量错误（例如：“我的 Agent 无法调用 Cloud Run 上的 MCP 服务。它返回 403 出站流量错误。如何解决？”）：

• 请勿运行日志搜索、日志记录工具或执行命令。
• 立即在第 0 轮回复：
  1. 说明 Cloud Run 原生不支持直接使用 Agent Identity（principalSet://...）进行 OIDC 身份验证。
  2. 建议在 Agent 代码中使用 Service Account 模拟来获取 OIDC 令牌。
  3. 指明 Agent Identity 需要在目标 Service Account 上具有 roles/iam.serviceAccountTokenCreator。详情请参阅 references/known-issues.md BKI 21。

规则 5：遥测与监控端点拦截

如果 Agent Runtime 启动失败，原因是容器崩溃或连接重置，且无法连接 telemetry.mtls.googleapis.com 或遥测端点：

• 在你的诊断报告 / 收集到的证据中，必须明确检查并列出全部 4 个必需的监控和跟踪端点： telemetry.mtls.googleapis.com、monitoring.googleapis.com、 trace.mtls.googleapis.com 和 cloudtrace.googleapis.com。
• 在你的建议修复方案中，必须始终明确包括：
  1. 使用 gcloud agent-registry endpoints create，将 telemetry.mtls.googleapis.com 注册为端点（并检查 monitoring.googleapis.com、trace.mtls.googleapis.com 和 cloudtrace.googleapis.com）。
  2. 创建或更新绑定到 Gateway 的 AuthorizationPolicy，明确允许 Agent 的身份（主体集）访问这些已注册的遥测端点。明确说明：“创建或更新绑定到 Gateway 的 AuthorizationPolicy，以允许 Agent 的身份（主体集）访问遥测端点。” 详情请参阅 references/known-issues.md BKI 23。

规则 6：IAP 拒绝访问故障排查（向 MCP 服务或端点发出请求时返回 403）

每当诊断日志或调查结果，发现 Agent 通过 IAP 调用 MCP 服务或端点时遇到 403 Forbidden / Egress request is not authorized 错误：

• 你的回复必须始终优先按照以下步骤解决：
  1. 首先检查注册表条目上的 IAP Egressor 绑定：检查 Agent Registry 中匹配资源上的 IAP Egressor 绑定（roles/iap.egressor）。
  2. 确保存在注册表条目：如果匹配的 MCP 服务或端点没有注册表条目，请指导用户在 Agent Registry 中注册该资源。
  3. 确保注册表条目上的角色已绑定：检查 Agent 身份是否已在该注册表条目上绑定 roles/iap.egressor 角色。
  4. 缺少权限时授予角色：如果缺少权限，请告知用户在注册表条目上授予 roles/iap.egressor 角色。
  5. 检查下游策略和审核日志：建议检查 IAP 审核日志 （protoPayload.serviceName="iap.googleapis.com"），并确认 AuthorizationPolicy 已正确绑定到指向 IAP 扩展的 Gateway。对于 UAP Policy V2 （iapPolicyVersion: "V2"），请验证 AccessPolicy / PolicyBinding 和 CEL 规则（参见 references/policies.md §2）。
  6. 明确警告："不要使用 roles/iap.tunnelResourceAccessor" 和*"不要绕过 IAP 身份验证"*。

规则 7：PSC 子网耗尽快速处理规则

诊断 Gateway 配置失败（PSC 子网耗尽）时：

• 不要执行循环或列出所有区域。
• 只在 us-central1 运行以下 4 条命令：
  1. gcloud network-services agent-gateways list --location=us-central1
  2. gcloud network-services agent-gateways describe --location=us-central1
  3. gcloud compute network-attachments describe --region=us-central1
  4. gcloud compute networks subnets describe --region=us-central1
• 立即计算可用 IP 数量（可用 IP 数 - 已分配 IP 数 = 空闲 IP 数），标出 /28 子网耗尽风险，并建议扩展到至少 /26。

规则 8：禁止手动注册多区域资源

如果用户询问如何在多区域位置（us 或 eu）手动注册端点或服务：

• 不要调用任何工具或执行任何命令。
• 立即在第 0 轮回复：
  1. "不支持在 us 或 eu 多区域位置手动注册端点。"（必须明确提及 us 和 eu 两者）。
  2. "请改为在特定区域（例如 us-central1）或 global 注册端点。"

规则 9：VPC-SC 周界拦截诊断

每当诊断 VPC Service Controls（VPC-SC）周界拦截或请求被拒绝的问题时：

• 你的回复必须始终明确说明以下所有内容：
  1. 指明该问题与 VPC Service Controls 周界拦截或周界边界强制执行有关。
  2. 说明，截至 2026 年 9 月 8 日，只要 Agent Connectivity Template（ACT）指定 vpcEgress: ALL_TRAFFIC，在 VPC-SC 周界内创建 Agent Gateway 即可开箱即用，无需额外配置；标准预配不再需要手动配置 ingress policies。
  3. 对于仍强制执行显式 ingress rules 的旧版或严格自定义周界，建议创建 VPC-SC ingress policies，允许以下两个服务账号：
     • [email protected]
     • cloud-aiplatform-pipeline-robot-prod.iam.gserviceaccount.com
  4. 明确说明：“请勿停用 VPC Service Controls 或删除周界定义。”
  5. 对于需要 Agent Connectivity Templates（ACT）的 VPC-SC egress 架构，确保模板指定 vpcEgress: ALL_TRAFFIC，并确保使用方 VPC 在 PSC-I 子网上配置了 Cloud NAT，以便访问外部公共 API。

规则 10：UAP Policy Binding 组织政策约束阻碍

如果 gcloud iam policy-bindings create 失败并显示 CUSTOM_ORG_POLICY_VIOLATION，或提及 constraints/iam.managed.disableAccessPolicyBinding：

• 你的回复必须始终明确说明以下所有内容：
  1. 指明该错误是由于在组织、文件夹或项目级别强制执行 Organization Policy 约束 constraints/iam.managed.disableAccessPolicyBinding 导致的。
  2. 建议应用 Organization Policy 覆盖设置，在目标资源级别停用该约束（enforce: false）（gcloud org-policies set-policy policy.yaml --project=$PROJECT_ID）。
  3. 明确说明，IAM Policy Control Plane 传播需要 30–60 秒，之后才能创建 policy bindings。请参阅 references/known-issues.md BKI 24。

规则 11：Agent Gateway 双注册表验证不变量

如果要配置、更新或验证 Agent Gateway 上的注册表关联：

• 你的回复必须始终明确说明以下所有内容：
  1. Agent Gateway 最多支持 两个注册表。
  2. 配置两个注册表时，其中必须恰好有一个为 global，另一个必须为 regional 或 multi-regional。
  3. 明确说明，不允许配置两个 regional、两个 multi-regional、两个 global，或配置 regional + multi-regional 而不包含 global；此类配置会返回 HTTP 400 验证错误（maximum of two registries are supported...）。请参阅 references/agent-gateway.md §4。

规则 12：跨项目运行时到网关绑定诊断

每当诊断项目 A 中的 Agent 运行时（推理引擎）无法部署到、绑定到或通过集中治理项目 B 中的 Agent 网关路由流量的错误时：

• 你的回复必须始终明确检查并说明以下所有事项：
  1. 部署身份权限： 确认部署调用方（用户或 CI/CD 身份）在项目 B 的网关上具有 roles/networkservices.viewer（或 networkservices.agentGateways.get 和 networkservices.agentGateways.use）。
  2. Vertex AI 服务 Agent 权限： 确认项目 A 的服务 Agent（[email protected]）已在项目 B 中获授 roles/networkservices.viewer 或自定义角色 ae_agw_cross_project_sa（包含 networkservices.agentGateways.get 和 networkservices.operations.get）。
  3. 同区域部署要求： 运行时和网关必须部署在完全相同的区域（例如 us-central1）。跨区域绑定会因控制平面验证失败而返回 INVALID_ARGUMENT。
  4. CAA 令牌共享退出选项： 确认运行时部署配置设置了 "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False。
  5. 有关服务器生成的资源 ID、边界和完整配置，请参阅 references/known-issues.md BKI 10 和 references/agent-gateway.md §11。

规则 13：下游安全 Web 代理（SWP）和基于策略的路由（PBR）出口

每当诊断从 Agent 网关网络附件发出的流量无法到达或通过下游安全 Web 代理（SWP）路由、静默丢弃，或返回 HTTP 403 / HTTP 503 / 超时错误时：

• 你的回复必须始终明确检查并说明以下所有事项：
  1. PSC 端点与静态路由不兼容： 说明：
     • PSC 转发规则不能用作 GCP 静态路由或 PBR 的下一跳。
     • 通过 PSC 服务附件使用 SWP 时，只能采用显式代理模式（HTTP CONNECT），无法在未配置客户端代理的情况下接收来自网络附件的透明 L3/L4 出口流量。
     • 使用 --next-hop-ilb 的静态路由需要 VM 网络标记（--tags），而网络附件无法附加这些标记。
  2. 下一跳 SWP 部署： 建议在使用者 VPC 中直接部署 SWP，设置 type: SECURE_WEB_GATEWAY 和 routingMode: NEXT_HOP_ROUTING_MODE，并将其置于 PSC-I 子网的内部 IP 上（例如 10.20.1.250）。
  3. 仅代理子网： 确认存在专用的 Envoy 仅代理子网（purpose: REGIONAL_MANAGED_PROXY、role: ACTIVE，最小掩码为 /26）。
  4. 基于策略的路由（PBR）： 建议使用 PBR（agw-psci-to-swp-pbr，优先级 200），将源 CIDR 10.20.1.0/24 匹配到 SWP 下一跳 ILB IP（10.20.1.250），并配置回退 PBR 指向 DEFAULT_ROUTING。
  5. Cloud NAT 相互依赖（ENDPOINT_TYPE_SWG）： 建议在 Cloud Router 上配置 Cloud NAT，并设置 --endpoint-types=ENDPOINT_TYPE_VM,ENDPOINT_TYPE_SWG。
  6. 有关 CEL 允许列表和 ADK 流式会话陷阱，请参阅 references/known-issues.md BKI 33 和 references/agent-gateway.md §6。

此技能会生成一份诊断报告，包含调查结果和修复建议。 它不会应用修复。变更由用户负责。

何时使用此技能

出现以下症状时触发：

• Agent → 外部 API 请求失败并返回 403，尤其是 Egress request is not authorized
• ReasoningEngine / Agent Runtime 查询返回 500 Internal Server Error（尤其是在启用 Model Armor 时）
• Agent Runtime 日志中出现 authz 错误或容器崩溃
• Gateway 日志中，Model Armor 后端调用返回 PERMISSION_DENIED
• 新注册的端点 / MCP 服务 / Agent 看起来“应该能正常工作”，却无法使用
• 怀疑 Agent 身份存在 IAP / IAM / IAM-principal-set 问题
• 调试 Authz 扩展或 authz policy
• 对 Gateway 路由 / 监控感到困惑
• 设计或配置 Agent Registry 结构（例如，配置整合后的 googleapis service 服务，或注册 Google API）。
• 用户提及 Agent Gateway、Agent Registry、Agent Identity、Model Armor 集成或 Gemini Enterprise Agent Platform 的任何情况。

以下情况不要使用：

• 与 Agent Platform 无关的一般 Google Cloud IAM 调试（直接使用 gcloud / IAM 检查）
• 与 Agent Platform 堆栈无关的网络问题（例如，原始 VPC SC、纯 Cloud Run 身份验证）

必需的上下文（先收集）

开始任何操作之前，先确认基本信息。如果用户尚未提供，请询问。不要猜测。

项目	所需原因
PROJECT_ID 和 PROJECT_NUMBER	大多数 API 调用需要其中一个或两个
LOCATION（区域）	区域范围；部分资源支持 global
AGENT_ID 或运行时标识符	用于筛选 Agent 日志
AGENT_GATEWAY_NAME	用于筛选 Gateway 日志
Agent 身份（SA 或 principal-set ID）	用于检查 IAM 绑定
症状：确切错误文本 + 时间戳	为假设提供依据（“在 Terraform 执行 X 后开始出现”）
目标目的地	例如，aiplatform、discoveryengine、MCP 服务、对等 Agent

如果只知道其中部分信息，可以继续，但要在报告中指出未知项。如果在默认项目中找不到资源，不要扫描所有项目；请使用占位符说明一般故障排查步骤。

假设生成规则

在执行超出步骤 0 的诊断查询之前，你必须针对故障提出最多 3 个合理假设。对于每个假设，都要明确指出其与近期变更（例如 Terraform 执行或配置更新）的关联，并回答：“为什么现在才开始失败？”诊断范围仅限于验证这些假设。

诊断流程

这是一项流程技能——请按顺序执行各个步骤。有关可直接复制粘贴的命令、日志筛选条件和完整故障排查流程图，请参阅 references/field-manual.md。

• 步骤 0：上下文与前置检查：遵守强制前置检查规则（规则 1-13）。通过 gcloud projects describe $PROJECT_ID 验证项目访问权限。对于注册表设计／配置问题，请遵循前置检查规则 3，并阅读 references/agent-registry.md §2。
• 步骤 1：Agent 日志：确认错误类型（403、连接错误还是崩溃）。对于连接错误／超时，检查 PSC 子网耗尽以及 ACT／Cloud NAT 路由。对于容器崩溃，执行运行时健康检查。
• 步骤 2：网关日志：查找确切的失败主机名。
• 步骤 3：IAP 日志：检查策略版本（iapPolicyVersion: "V2" 与 "V1"）、DRY_RUN 与强制执行模式，以及决策结果。
• 步骤 4：注册表状态：验证确切的主机名是否已注册。如果未注册，建议注册所有主机名形式。
• 步骤 5：身份与策略：验证 Agent 身份是否具有 roles/iap.egressor（IAM v1），或评估 UAP AccessPolicy 和 CRM PolicyBinding（UAP v2）。检查 constraints/iam.managed.disableAccessPolicyBinding 阻止因素。
• 步骤 6：授权扩展程序与网关：验证扩展程序已连接到以 IAP 为目标的网关，且策略版本正确；同时验证双注册表限制（最多 2 个：1 个全局注册表 + 1 个区域／多区域注册表）。
• 步骤 7：基线角色：验证 Agent Runtime User、Registry Viewer 和日志权限。
• 步骤 8：PrincipalSet 验证：如果出现主体集传播问题，测试 1:1 绑定。

要使用的工具

此技能假设 Agent 可以访问：

• mcp__gcloud__run_gcloud_command（或运行原始 gcloud CLI 的 default_api:run_command）——用于调用 gcloud（列出注册表、查看 authz-extensions、IAM、查询项目）。
• mcp__gcloud-observability__list_log_entries（或运行 gcloud logging read 的 default_api:run_command）——用于结构化日志查询。
• mcp__google-dev-knowledge__search_documents / get_documents / answer_query——当需要深入查阅随附参考资料之外的信息时使用。
• default_api:run_command（Bash）——用于调用 IAP／NetworkSecurity／NetworkServices／ServiceExtensions API 的 curl 请求。

如果支持，请并行运行相互独立的日志查询。

如何使用参考资料

references/ 文件夹分为多个层级：

• field-manual.md——每次调用时首先阅读。这是操作核心。
• known-issues.md——症状符合常见模式时阅读。
• agent-gateway.md——怀疑网关本身存在问题时阅读。
• policies.md——问题涉及 IAM 建模时阅读。
• agent-registry.md——注册机制不明确，或需要为 Google API 设计注册表布局（合并或分开）时阅读。
• agent-identity.md——问题涉及 Agent 的身份时阅读。

只阅读足以解答问题的最少资料。不要预先加载所有内容。

输出报告

始终生成结构化报告。严格使用此模板。

# Agent Platform Diagnostic — <one-line summary>

## Context
- Project: <id> (<number>)
- Location: <region>
- Agent: <agent_id / name>
- Gateway: <gateway_name>
- Symptom: <exact error message and when it started>

## Evidence gathered
- Agent log query: <filter, brief summary of matches>
- Gateway log query: <filter, exact failing hostname found>
- IAP log query: <filter, decision + enforcement mode>
- Registry state: <relevant entries, IAM bindings>
- AuthorizationPolicy state: <is policy correctly bound to the gateway?>
- Agent Identity Roles: <does identity have roles/iap.egressor?>
- (any other tool output that mattered)

## Root cause hypothesis
<single most likely cause, stated plainly. If multiple, rank them.>

## Why this fits the evidence
<brief — connect the dots. Show which evidence rules in / rules out the hypothesis.>

## Recommended fix
<concrete actions in order. Show exact gcloud / curl / Terraform changes the user can run. If the fix is in the user's repo (Terraform), point at file:line.>

## What to verify after the fix
<the queries to re-run to confirm resolution.>

## Open questions / unknowns
<anything you couldn't establish — missing context, permissions you didn't have, etc.>

## Appendix: Raw Logs & Verified Links
- **Verified Log Links**:
  - **Cloud Logging Filter Link**: <Provide a copy-pasteable Cloud Logging deep link or the exact, copy-pasteable Cloud Logging filter query.>
- **Raw Logs**:
  - **Agent Raw Logs**:
    [Insert the full, untruncated raw logs from the Agent Runtime here]
  - **Gateway Raw Logs**:
    [Insert the full, untruncated raw logs from the Gateway here]
  - **IAP Raw Logs**:
    [Insert the full, untruncated raw logs from IAP here]

原则

• 主机名不匹配是首要原因。 如有疑问，请从网关日志中获取确切的 主机名，并在注册表中搜索。
• 默认拒绝是分层模型。 每一层都必须允许调用：注册表 → 网关（使用实际针对该项的 authz_policy） → authz 扩展 → IAP/IAM → PAB。
• PAB 优先于 IAM Allow。 即使 roles/iap.egressor 绑定正确，如果主体访问边界将主体限制在目标地址之外，也无济于事。
• DRY_RUN 会彻底改变行为。 如果 IAP 处于试运行模式，拒绝操作只会记录日志，不会强制执行。
• 角色为 roles/iap.egressor（适用于 IAM v1），FQDN 权限为 iap.googleapis.com/resources.egressViaIAP（适用于 UAP v2）。
• UAP（Policy V2）CRM 层级结构：新一代策略通过 PolicyBinding 绑定到项目、 文件夹和组织，而不是影子资源。评估遵循绝对拒绝优先原则，并在整个 CRM 树中累加允许规则。
• 使用 ALL_TRAFFIC 的 Agent Connectivity Template (ACT)：在 VPC-SC 下， 流量会经过合成 PSC VIP 240.0.0.2:443。从使用方 VPC 发出的外部公共 API 流量需要在 PSC-I 子网上配置 Cloud NAT，以避免连接无响应。
• 双注册表不变量：Agent Gateway 最多支持 2 个注册表；配置 2 个时，必须恰好有一个为 global，另一个为 regional 或 multi-regional。
• 查阅证据，不要臆测。 首先提取日志。
• 在报告中引用确切的资源名称。
• 保持在诊断模式。 不要应用 Terraform 更改，也不要运行具有破坏性的 gcloud 命令。仅进行只读检查。
• 不扫描多个区域：不要通过循环列出或扫描多个区域中的资源。除非日志指向其他区域，否则检查默认区域（us-central1）。
• 非交互式执行：始终禁用提示（--quiet / -q 或 gcloud config set core/disable_prompts True），以避免命令挂起。

参考链接

• Agent Runtime 概览
• Agent Gateway 概览
• 策略概览
• Agent Identity 概览
• Agent Registry 概览
• 部署 Agent Gateway Runtime
• Private Service Connect 接口
• 排查 Agent Gateway 问题
• 排查 Agent 部署问题
• 排查 Runtime 设置问题