skills.rest
google
googleOFFICIAL
Explore all skills by this author →
Website𝕏@GoogleOSSGitHub

agent-platform-troubleshooting

Diagnose Google Cloud Gemini Enterprise Agent Platform failures across gateways, registries, identity, and IAP.

19.1k|1.5k|Updated Mar 31, 2026
Search Tags:#Google Cloud#Troubleshooting#Diagnostics#iap#agent registry#agent gateway#Gemini Enterprise
One-click install
npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agent-platform-troubleshooting
Source: https://github.com/google/skills/tree/main/skills/cloud/agent-platform-troubleshooting
Command: npx skills add https://github.com/google/skills --skill agent-platform-troubleshooting

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Agents on the Google Cloud Gemini Enterprise Agent Platform fail with opaque 403 egress denials, 500 runtime errors, and gateway permission errors that span multiple layers (Agent Registry, Agent Gateway, IAP, authorization policies). This Skill provides a structured diagnostic workflow that pinpoints the root cause and produces a fix recommendation report.

Core Features & Use Cases

  • Layered Diagnostic Flow: Walks through agent logs, gateway logs, IAP logs, registry state, IAM bindings, and authorization extensions in a defined order to isolate failures.
  • Pre-Flight Rules: Instantly handles known patterns such as PSC subnet exhaustion, IAP dry-run misconfiguration, hostname mismatches, and VPC-SC perimeter blocks.
  • Structured Diagnostic Report: Produces a consistent report with evidence, root cause hypothesis, recommended gcloud/curl fixes, and verification steps.
  • Use Case: When an agent's call to an MCP server on Cloud Run returns a 403 egress error, the Skill identifies that direct Agent Identity OIDC authentication is unsupported and recommends service account impersonation with the correct IAM role.

Quick Start

Ask the assistant to troubleshoot why your agent's requests through the Agent Gateway are failing with a 403 egress error in your Google Cloud project.

Frequently Asked Questions about agent-platform-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I troubleshoot a 403 egress error from Google Cloud Agent Gateway?▼

A 403 egress error usually means the destination hostname is not registered in Agent Registry or the agent identity lacks the roles/iap.egressor binding. Check gateway logs for the exact failing hostname, verify registry registration, then confirm the IAM binding and AuthorizationPolicy targeting the gateway.

Why does my agent get a 500 error from Agent Runtime when Model Armor is enabled?▼

A 500 Internal Server Error with Model Armor enabled typically indicates the gateway service account is missing cross-project IAM roles such as roles/modelarmor.calloutUser or roles/modelarmor.user. Verify all three required bindings and check gateway logs for PERMISSION_DENIED on Model Armor backend callouts.

Should I register each Google API separately in Agent Registry?▼

No, consolidate all Google APIs under a single googleapis service entry with multiple interfaces. Separate service entries cause resource clutter, complicate IAM policy management, and risk hitting registry quota limits. Include the 8 base FQDN interfaces such as aiplatform.mtls.googleapis.com and telemetry.mtls.googleapis.com.

Can I manually register endpoints in the us or eu multi-region locations?▼

No, manual endpoint registration is not supported in us or eu multi-region locations. Register endpoints in a specific region such as us-central1 or in the global location instead.

What IAM role does an agent identity need for IAP-protected egress?▼

The agent identity needs roles/iap.egressor bound on the target registry resource, endpoint, or MCP server. Do not use roles/iap.tunnelResourceAccessor, which only governs classic IAP TCP tunnels and does not apply to Agent Gateway egress.

When should I not use the Agent Platform troubleshooting skill?▼

Do not use it for general Google Cloud IAM debugging unrelated to the Agent Platform, such as GCE-to-GCS access denied errors, or for networking issues that do not involve the Agent Platform stack. Use direct gcloud and IAM inspection for those cases.

Related Skills

Explore More Software Engineering Skills→
TeamDay-AITeamDay-AI
2

aws-agentic-ai

Deploy and configure AWS Bedrock AgentCore across Gateway, Runtime, Memory, and Identity services.

Official
Advanced
rbah31rbah31
5

remote-fix

Guide an AI through diagnosing, fixing, and reporting remote issues via PRs.

Community
Advanced
tomztomz

gcp-monitoring

Establish observability for Google Cloud Platform workloads with monitoring, logging, tracing, and profiling.

Community
Advanced
googlegoogle
17.1k

iam-recommendations-fetcher

Fetch IAM recommendations and insights from Google Cloud targets.

Official
Intermediate