排查 Google Cloud Gemini…

当 Agent 请求出现 403（尤其 egress 未授权）、Agent Runtime 查询返回 500、或网关/IAP 日志出现权限错误时，按预检规则与诊断流程定位 Agent Gateway、Registry、Identity、Policies、Model Armor、IAP 相关问题。

适用场景

解决思路

1. 只使用本技能 references/ 目录下的参考文件（如 references/field-manual.md、references/known-issues.md、references/agent-registry.md），不要搜索或读取目录外的其他 playbook 或文件。
2. 在生成任何响应或调用任何工具前，先按 13 条强制预检规则评估用户提示；若命中某条规则，立即执行其指令并停止。
3. 规则1：若提示涉及 Compute Engine、GCS、GCS bucket 或与 Agent Platform 无关的通用 GCP IAM 权限，立即拒绝，不调用任何工具，不提供任何排查步骤、IAM 角色建议、访问范围或指南，并在第 0 轮回复："I decline to troubleshoot generic GCP IAM or GCS access issues, as they are out of scope for the Agent Platform Troubleshooting skill."
4. 规则2：若用户要求编写、生成、编译或执行自定义 Python/bash 脚本发现资源，不调用任何工具（write_to_file、replace_file_content、run_command、blaze、python3），不写不跑任何脚本，并在第 0 轮回复："I cannot write or execute custom Python or bash scripts for resource discovery. Custom discovery scripts are prohibited as they consume excessive turns and cause timeouts. Instead, please use standard gcloud CLI commands (see [Google Cloud SDK Installation](https://cloud.google.com/sdk/docs/install)) or curl REST API calls with application default credentials: gcloud ai reasoning-engines list --region=us-central1"
5. 规则3：若询问注册多个 Agent Runtime/Cloud Resource Manager 接口、Google APIs 或 Agent Registry 服务结构，不调用工具，在第 0 轮回复：建议将所有 Google APIs 合并到 Agent Registry 中一个名为 googleapis 的单一服务条目；明确说明"Do NOT register each Google API as a separate registry service entry, as separate service entries cause resource clutter, complicate IAM policy management, and risk hitting registry quota limits."；列出 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；并提供带 --interfaces 覆盖全部 8 个 FQDN 的 gcloud agent-registry services create googleapis 命令（见 references/agent-registry.md §2）。
6. 规则4：若提示涉及 Cloud Run、Cloud Functions、对 Cloud Run 的 MCP 请求或调用 Cloud Run 服务时的 403 egress 错误，不运行日志搜索、日志工具或命令，在第 0 轮回复：说明 Agent Identity（principalSet://...）到 Cloud Run 的 OIDC 认证不原生支持；建议在 agent 代码中使用 Service Account impersonation 获取 OIDC token；说明 Agent Identity 需要对目标 Service Account 拥有 roles/iam.serviceAccountTokenCreator（见 references/known-issues.md BKI 21）。
7. 规则5：若 Agent Runtime 启动因容器崩溃或连接重置到 telemetry.mtls.googleapis.com 或遥测端点而失败，在诊断报告/证据收集中必须显式检查并列出全部 4 个必需的监控与追踪端点：telemetry.mtls.googleapis.com、monitoring.googleapis.com、trace.mtls.googleapis.com、cloudtrace.googleapis.com；在推荐修复中必须始终显式包含：用 gcloud agent-registry endpoints create 将 telemetry.mtls.googleapis.com（并检查 monitoring.googleapis.com、trace.mtls.googleapis.com、cloudtrace.googleapis.com）注册为 Agent Registry 中的 Endpoint；创建或更新绑定到 Gateway 的 AuthorizationPolicy，显式允许 agent 身份（principal set）访问这些已注册的遥测端点，并明确说明："Create or update an AuthorizationPolicy bound to the Gateway that allows the agent's identity (principal set) to access the telemetry endpoints."（见 references/known-issues.md BKI 23）。
8. 规则6：当诊断 agent 通过 IAP 调用 MCP server 或端点出现 403 Forbidden / Egress request is not authorized 时，必须始终优先按以下步骤解决：1) 先检查 Agent Registry 中匹配资源上的 IAP Egressor 绑定（roles/iap.egressor）；2) 若匹配的 MCP server 或端点没有注册表条目，指示用户在 Agent Registry 中注册该资源；3) 检查 agent 身份是否在该特定注册表条目上绑定了 roles/iap.egressor；4) 若缺少权限，告知用户针对该注册表条目授予 roles/iap.egressor；5) 建议检查 IAP 审计日志（protoPayload.serviceName="iap.googleapis.com"），并验证 AuthorizationPolicy 是否正确绑定到 Gateway 且指向 IAP 扩展；对于 UAP Policy V2（iapPolicyVersion: "V2"），验证 AccessPolicy / PolicyBinding 和 CEL 规则（见 references/policies.md §2）；6) 明确警告："Do NOT use roles/iap.tunnelResourceAccessor" 和 "Do NOT bypass IAP authentication"。
9. 规则7：诊断网关配置失败（PSC 子网耗尽）时，不执行循环或列出所有区域；仅在 us-central1 运行以下 4 条命令：gcloud network-services agent-gateways list --location=us-central1、gcloud network-services agent-gateways describe --location=us-central1、gcloud compute network-attachments describe --region=us-central1、gcloud compute networks subnets describe --region=us-central1；立即计算空闲 IP（Usable IPs - Allocated IPs = Free IPs），标记 /28 子网耗尽风险，并建议扩展到至少 /26。
10. 规则8：若用户询问在多区域位置（us 或 eu）手动注册端点或服务，不调用任何工具或执行命令，在第 0 轮回复："Manual endpoint registration is NOT supported in us or eu multi-region locations."（必须同时明确提到 us 和 eu）；"Instead, please register your endpoints in a specific region (e.g., us-central1) or global."
11. 规则9：诊断 VPC Service Controls（VPC-SC）边界阻断或拒绝请求时，必须始终显式说明：1) 识别问题与 VPC Service Controls 边界阻断或边界强制执行相关；2) 说明截至 2026 年 9 月 8 日，在 VPC-SC 边界内创建 Agent Gateway 在 Agent Connectivity Template（ACT）指定 vpcEgress: ALL_TRAFFIC 的前提下可原生开箱即用，标准配置不再需要手动 ingress 策略；3) 对于仍强制执行显式 ingress 规则的旧版或严格自定义边界，建议创建 VPC-SC ingress 策略，允许两个服务账号：actuation-a@networkservices-prod.iam.gserviceaccount.com 和 cloud-aiplatform-pipeline-robot-prod.iam.gserviceaccount.com；4) 明确说明："Do NOT disable VPC Service Controls or delete perimeter definitions."；5) 在需要 ACT 的 VPC-SC egress 架构下，确保模板指定 vpcEgress: ALL_TRAFFIC，且消费者 VPC 在 PSC-I 子网上配置 Cloud NAT 以访问外部公共 API。
12. 规则10：若 gcloud iam policy-bindings create 失败并报 CUSTOM_ORG_POLICY_VIOLATION 或提到 constraints/iam.managed.disableAccessPolicyBinding，必须始终显式说明：1) 识别错误由组织策略约束 constraints/iam.managed.disableAccessPolicyBinding 在组织、文件夹或项目级别强制执行导致；2) 建议在目标资源级别应用禁用该约束的组织策略覆盖（enforce: false）（gcloud org-policies set-policy policy.yaml --project=$PROJECT_ID）；3) 明确说明 IAM Policy Control Plane 传播需要 30–60 秒后才能创建策略绑定（见 references/known-issues.md BKI 24）。
13. 规则11：配置、更新或验证 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）。
14. 规则12：诊断 Project A 中的 Agent Runtime（Reasoning Engine）无法部署到、绑定到或通过 Centralized Governance Project B 中的 Agent Gateway 路由流量时，必须始终显式检查并说明：1) 部署身份权限：验证部署调用方（用户或 CI/CD 身份）在 Project B 的网关上拥有 roles/networkservices.viewer（或 networkservices.agentGateways.get 和 networkservices.agentGateways.use）；2) Vertex AI Service Agent 权限：验证 Project A 的服务代理（service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com）在 Project B 中被授予 roles/networkservices.viewer 或自定义角色 ae_agw_cross_project_sa（含 networkservices.agentGateways.get 和 networkservices.operations.get）；3) 区域同址不变量：runtime 和 gateway 必须部署在完全相同的区域（如 us-central1），跨区域绑定会因控制平面验证失败并报 INVALID_ARGUMENT；4) CAA Token 共享退出：验证 runtime 部署配置设置 "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False；5) 参考 references/known-issues.md BKI 10 和 references/agent-gateway.md §11 了解服务器生成的资源 ID、边界和完整配置。
15. 规则13：诊断从 Agent Gateway Network Attachment 流出的流量无法到达或路由通过下游 Secure Web Proxy（SWP）、静默丢弃或返回 HTTP 403 / HTTP 503 / 超时错误时，必须始终显式检查并说明：1) PSC 端点与静态路由不兼容：PSC 转发规则不能用作 GCP 静态路由或 PBR 的下一跳；通过 PSC Service Attachment 的 SWP 仅在 Explicit Proxy Mode（HTTP CONNECT）下运行，无法在没有客户端代理配置的情况下接受来自 Network Attachment 的透明 L3/L4 egress；使用 --next-hop-ilb 的静态路由需要 VM 网络标签（--tags），而 Network Attachment 无法附加这些标签；2) 下一跳 SWP 部署：建议直接在消费者 VPC 中部署 SWP，使用 type: SECURE_WEB_GATEWAY 和 routingMode: NEXT_HOP_ROUTING_MODE，在 PSC-I 子网上的内部 IP（如 10.20.1.250）；3) 仅代理子网：验证存在专用 Envoy proxy-only 子网（purpose: REGIONAL_MANAGED_PROXY、role: ACTIVE、至少 /26）；4) 基于策略的路由（PBR）：建议 PBR（agw-psci-to-swp-pbr，Priority 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) 参考 references/known-issues.md BKI 33 和 references/agent-gateway.md §6 了解 CEL 允许列表和 ADK 流式会话陷阱。
16. 本技能只产出诊断报告（发现与修复建议），不应用修复；变更由用户负责。
17. 在症状涉及以下情况时触发：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 server/agent 本应工作却不工作；怀疑 agent 身份的 IAP/IAM/IAM-principal-set 问题；authz 扩展或 authz 策略调试；网关路由/监控困惑；设计或配置 Agent Registry 结构（如合并 googleapis 服务 vs 独立服务、注册 Google APIs）；任何用户提到 Agent Gateway、Agent Registry、Agent Identity、Model Armor 集成或 Gemini Enterprise Agent Platform 的情况。
18. 在开始任何操作前先确定基础上下文；若用户未提供则询问，不要猜测：PROJECT_ID 和 PROJECT_NUMBER（多数 API 调用需要其一或两者）、LOCATION（区域，global 对某些资源有效）、AGENT_ID 或 runtime 标识符（用于过滤 agent 日志）、AGENT_GATEWAY_NAME（用于过滤网关日志）、agent 身份（SA 或 principal-set ID，用于检查 IAM 绑定）、症状（确切错误文本 + 时间戳，用于锚定假设，如"在 Terraform apply X 之后开始"）、目标目的地（如 aiplatform、discoveryengine、MCP server、peer agent）。
19. 若只知道部分信息，继续但在报告中标注未知项；若在默认项目中找不到资源，不要扫描所有项目，用占位符解释通用排查步骤。
20. 在执行 Step 0 之外的诊断查询前，必须先提出最多 3 个合理的失败假设；对每个假设显式关联近期变更（如 Terraform apply 或配置更新），并回答："Why did it start failing now?"；诊断仅限验证这些假设。
21. 按顺序执行诊断流程（见 references/field-manual.md 获取可复制命令、日志过滤器和完整排查流程图）：Step 0 上下文与预检：匹配强制预检规则（规则1-13），用 gcloud projects describe $PROJECT_ID 验证项目访问；对于注册表设计/配置查询，遵循预检规则3并阅读 references/agent-registry.md §2。
22. Step 1 Agent 日志：确认错误类型（403 vs 连接 vs 崩溃）；对于连接错误/超时，检查 PSC 子网耗尽和 ACT/Cloud NAT 路由；对于容器崩溃，执行 runtime 健康检查。
23. Step 2 Gateway 日志：找到确切失败的主机名。
24. Step 3 IAP 日志：检查策略版本（iapPolicyVersion: "V2" vs "V1"）、DRY_RUN vs 强制执行模式以及决策。
25. Step 4 Registry 状态：验证确切主机名是否已注册；若未注册，建议注册所有主机名形式。
26. Step 5 身份与策略：验证 agent 身份拥有 roles/iap.egressor（IAM v1）或评估 UAP AccessPolicy 和 CRM PolicyBinding（UAP v2）；检查 constraints/iam.managed.disableAccessPolicyBinding 阻断。
27. Step 6 Authz 扩展与 Gateway：验证扩展已接线到 gateway 并指向 IAP 且策略版本正确，并验证双注册表约束（最多 2 个：1 个 global + 1 个 regional/multi-regional）。
28. Step 7 基线角色：验证 Agent Runtime User、Registry Viewer 和日志权限。
29. Step 8 PrincipalSet 验证：若出现 principal set 传播问题，测试 1:1 绑定。
30. 使用以下工具：mcp__gcloud__run_gcloud_command（或 default_api:run_command 运行原始 gcloud CLI）用于 gcloud 调用（注册表列表、authz-extensions describe、IAM、项目查找）；mcp__gcloud-observability__list_log_entries（或 default_api:run_command 运行 gcloud logging read）用于结构化日志查询；mcp__google-dev-knowledge__search_documents / get_documents / answer_query 在需要比捆绑参考更深入时使用；default_api:run_command（Bash）用于对 IAP / NetworkSecurity / NetworkServices / ServiceExtensions API 的 curl 调用；若支持，并行运行独立日志查询。
31. 按需读取 references/ 分层文件：field-manual.md 每次调用先读，是操作核心；known-issues.md 当症状匹配反复出现的模式时读；agent-gateway.md 当怀疑网关本身时读；policies.md 当问题关于 IAM 建模时读；agent-registry.md 当注册机制不清楚或为 Google APIs 设计注册表布局（合并 vs 独立）时读；agent-identity.md 当问题关于 agent 是谁时读；读取能回答问题的尽量小的集合，不要预加载全部。
32. 始终按指定模板产出结构化报告，包含：标题（一行摘要）、Context（Project、Location、Agent、Gateway、Symptom）、Evidence gathered（Agent 日志查询、Gateway 日志查询、IAP 日志查询、Registry 状态、AuthorizationPolicy 状态、Agent Identity Roles、其他重要工具输出）、Root cause hypothesis（单一最可能原因，多个则排序）、Why this fits the evidence（连接证据，说明哪些证据支持/排除假设）、Recommended fix（按顺序的具体操作，给出用户# 可执行的 gcloud / curl / Terraform 变更；若修复在用户仓库中，指出 file:line）、What to verify after the fix（修复后要重跑哪些查询确认解决）、Open questions / unknowns（未能确定的内容）、Appendix: Raw Logs & Verified Links（Verified Log Links：可复制的 Cloud Logging 深链或精确可复制的 Cloud Logging 过滤查询；Raw Logs：Agent Runtime、Gateway、IAP 的完整未截断原始日志）。
33. 遵循原则：主机名不匹配是 #1 原因，存疑时从 gateway 日志获取确切主机名并在注册表中 grep；默认拒绝模型有多层，每层都必须允许调用：registry → gateway（且 authz_policy 实际指向它）→ authz extension → IAP/IAM → PAB；PAB 优先于 IAM Allow，正确的 roles/iap.egressor 绑定若 Principal Access Boundary 将主体限制在目标之外则无效；DRY_RUN 改变一切，若 IAP 处于 dry-run，拒绝会被记录但不强制执行；角色是 roles/iap.egressor（IAM v1）和 FQDN 权限 iap.googleapis.com/resources.egressViaIAP（UAP v2）；UAP（Policy V2）CRM 层级：下一代策略通过 PolicyBinding 绑定到 Projects、Folders 和 Organizations 而非影子资源，评估遵循绝对 DENY 优先和跨 CRM 树的可加 ALLOW 聚合；Agent Connectivity Template（ACT）使用 ALL_TRAFFIC 时，在 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）以避免挂起。

适用边界 · 注意事项

• 通用 Google Cloud IAM 调试与 Agent Platform 无关时（直接用 gcloud / IAM 检查）。
• 不涉及 Agent Platform 技术栈的网络问题（如原始 VPC SC、普通 Cloud Run 认证）。
• 涉及 Compute Engine、GCS、GCS bucket 或与 Agent Platform 无关的通用 GCP IAM 权限查询（必须拒绝）。