agent-platform-troubleshooting

📌 agent-platform-troubleshooting 是什么？

一句话概括：agent-platform-troubleshooting 是一款专注「Gemini 企业级 Agent 平台故障排查」的 AI 技能。

它是 Google 官方仓库（google/skills）出品的 AI Agent 技术排障类 Skill，专门诊断 Gemini Enterprise Agent Platform 上的各类问题，覆盖 Agent Gateway、Agent Registry（Agents / MCP Servers / Endpoints）、Agent Identity、策略、IAP 委托授权和服务扩展。

它与普通代码调试工具的区别在于：它不修代码，而是从日志、网关、IAP、注册表、身份与 IAM 一路定位根因，最终输出一份结构化的诊断报告（上下文、证据、根因、建议修复、验证、原始日志）。官方说明明确它只诊断、不自动执行修复。

📋 核心要点速览

项目说明
名称agent-platform-troubleshooting
来源google/skills（Google 官方技能库）
定位Gemini 企业级 Agent 平台故障诊断
输出结构化诊断报告，不自动修复
典型场景403 Egress 未授权、500 错误、网关 PERMISSION_DENIED
兼容性Google Cloud 认证 + 相关项目/Agent 上下文

🧩 主要功能

  • Agent 运行错误分析：定位 Agent → 外部 API 请求 403（尤其「Egress request is not authorized」）等问题。
  • 配置问题排查：检查 Agent Gateway、Registry、Identity 与策略配置。
  • 工具调用故障诊断：ReasoningEngine / Agent Runtime 查询返回 500、授权错误等。
  • 日志分析：依次检查 Agent 日志、Gateway 日志、IAP 日志。
  • 环境依赖排查：IAP/IAM principal-set、服务账号模拟、PSC 子网耗尽等。
  • 错误原因定位与修复建议：输出根因与建议，不直接改配置。

✨ 核心特色

  • 专门针对 Agent 平台：不是泛化的 GCP IAM 或 VPC-SC 调试。
  • 9 条强制预检规则：开始任何工具调用前先做范围与安全预检。
  • 假设生成规则：最多 3 个合理假设，且每个都要与「为什么现在才失败」关联。
  • 0-8 步诊断流程：从上下文/预检到日志、网关、IAP、注册表、身份、授权、基线角色、PrincipalSet 逐层验证。
  • 只诊断不修复：降低对生产系统的误操作风险。

🎯 可以用来做什么？

  • Agent 无法启动。
  • 工具调用失败。
  • API 返回 403/500 错误。
  • 模型连接异常。
  • 环境变量与策略配置错误。
  • Agent 工作流运行中断。

🙋 适合哪些人？

  • AI Agent 开发者。
  • 自动化工作流搭建者。
  • 软件工程师。
  • 技术支持人员。
  • 负责维护 AI 系统的团队。

🛠️ 如何安装？

官方安装命令为：

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

使用时需要提供 PROJECT_ID/NUMBER、LOCATION、AGENT_ID、GATEWAY_NAME、agent identity、精确症状文本与目标等上下文，并具备相应的 Google Cloud 访问权限。

✍️ 怎么使用？

按排障流程推进：

  1. 描述问题并收集必要上下文（项目、位置、Agent、网关）。
  2. 执行 9 条强制预检规则。
  3. 检查 Agent 日志。
  4. 检查 Gateway 日志。
  5. 检查 IAP 日志。
  6. 检查 Registry 状态。
  7. 检查 Identity 与 IAM。
  8. 检查授权扩展与基线角色。
  9. 验证 PrincipalSet。
  10. 输出结构化诊断报告。

💡 使用技巧

  • 提供完整错误信息，而不是只说「运行失败」。
  • 说明问题首次出现的时间。
  • 区分代码错误、配置错误和服务端错误。
  • 修复前保留原始配置。
  • 涉及生产环境时先做风险评估。

💰 收费吗？

Skill 本身开源免费，但运行排障可能依赖付费的 Agent 服务、Google Cloud 资源或第三方 API，需按实际环境判断。排障过程本身不收费，涉及的云资源按用量计费。

👍👎 优点与缺点

内容
优点针对技术问题；标准化排障流程；可减少人工排查时间；输出结构化报告。
缺点诊断准确性依赖错误信息；复杂故障仍需人工判断；涉及生产系统时不能盲目执行建议。

⚖️ 与同类工具对比

对比维度agent-platform-troubleshooting通用代码助手
主要方向Agent 平台故障广泛的软件开发
故障分析重点能力方向取决于使用方式
适用人群Agent 开发和维护人员各类开发者
使用场景运行、配置、集成故障编码、重构、调试

❓ 常见问题 FAQ

  • 支持哪些 AI Agent 平台？专注 Google Cloud Gemini Enterprise Agent Platform。
  • 能否解决 API 报错？能定位 403/500 等错误的根因，但不自动修复。
  • 是否需要提供完整日志？建议提供，日志是诊断的核心证据。
  • 能否自动修改配置？不能，它只输出诊断报告与建议。
  • 是否适合生产环境排障？可以用于诊断，但执行修复前需人工评估。

⚠️ 使用限制

  • 不用于泛化 GCP IAM 调试、原始 VPC-SC 问题或与 Agent 平台无关的 Cloud Run 授权。
  • 只诊断不修复。
  • 需 Google Cloud 认证与相应项目/Agent 访问权限。

🤖 适合哪些 AI 工具

该 Skill 面向支持 skills 命令行的 AI 编码助手与 Agent 环境，通过标准 SKILL.md 结构被调用；诊断过程需要能访问 Google Cloud 项目、日志与配置的权限。

📝 编辑评价

agent-platform-troubleshooting 是 Google 官方为自家 Agent 平台写的「排障手册」：9 条预检规则把范围管得很死，0-8 步流程把「先看哪里、再看哪里」理得清清楚楚，而且明确只诊断不修复，这对生产环境尤其重要。如果你在跑 Gemini 企业级 Agent 平台、经常被 403/500 卡住，它能把排查时间显著缩短；但你要接受它给的是「证据 + 根因 + 建议」，而不是一键修好。