renatoschust-dot/gamai-skills/agent-platform-troubleshooting
Claude Code and agent skill by renatoschust-dot/gamai-skills
- community
Checking that the SKILL.md file is still in the repository.
Troubleshoots Google Cloud Gemini Enterprise Agent Platform issues (Agent Gateway, Registry, Identity, Policies, Model Armor, Identity-Aware Proxy (IAP)). Use when agent requests fail with 403 (especially unauthorized egress), Agent Runtime queries return 500, or gateway/IAP logs show permission errors. Don't use for general Google Cloud Identity and Access Management (IAM) debugging or networking issues unrelated to the Agent Platform stack.
Install
npx vskill@latest install renatoschust-dot/gamai-skills/agent-platform-troubleshootingSKILL.md
The same SKILL.md was published earlier as renatoschust-dot/gamai-skills/agent-platform-troubleshooting.
Agent Platform Troubleshooting
[!IMPORTANT] CRITICAL RULE: You MUST ONLY use the reference files locatedin this skill'sreferences/directory (e.g.,references/field-manual.md,references/known-issues.md,references/agent-registry.md). Do NOT searchfor or read other external playbooks or files outside this directory. Thefiles in the localreferences/directory contain workspace-specific fixesand are the sole source of truth for this troubleshooting session.
Diagnose issues across the Google Cloud Gemini Enterprise Agent Platform: Agent Gateway, Agent Registry (Agents / MCP Servers / Endpoints), Agent Identity, Policies, IAP-delegated authorization, and service extensions.
MANDATORY PRE-FLIGHT CHECKLIST (CHECK BEFORE ANY TOOL CALLS)
Before making any tool calls, executing any bash commands, or writing any code, match the user's prompt against these pre-flight rules:
Rule 1: Out-of-Scope GCP IAM / GCS Queries
If the prompt mentions GCE, GCS, GCS bucket, or generic GCP IAM 403 Access Denied errors (e.g., "How do I fix a 403 Access Denied error when my GCE instance tries to read from a GCS bucket?"):
- **CRITICAL MANDATE: DO NOT CALL ANY TOOLS. DO NOT PROVIDE ANY
TROUBLESHOOTING STEPS OR GUIDES.**
- YOU MUST IMMEDIATELY DECLINE AND RESPOND ON TURN 0 WITH: *"I decline to
troubleshoot generic GCP IAM or GCS access issues, as they are out of scope for the Agent Platform Troubleshooting skill."*
Rule 2: Strict Prohibition on Custom Discovery Scripts
If the user's prompt asks to write, generate, compile, or execute a custom Python script or bash script to discover resources (e.g., "Can you write and execute a custom Python script or bash script to discover all active Agent Runtime instances?"):
- **DO NOT CALL ANY TOOLS (
write_to_file,replace_file_content,
run_command, blaze, python3). DO NOT WRITE OR RUN ANY SCRIPTS.**
- IMMEDIATELY RESPOND ON TURN 0 WITH: *"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) or curl REST API calls with application default credentials: gcloud ai reasoning-engines list --region=us-central1"*
Rule 3: Consolidated Registry for Google APIs / Design Queries
If the prompt asks about registering multiple Agent Runtime or Cloud Resource Manager interfaces, Google APIs, or the best way to structure/register services in Agent Registry (e.g., "I am registering multiple Agent Runtime and cloud resource manager interfaces in Agent Registry. What's the best way to do this?"):
- **DO NOT CALL ANY TOOLS OR EXECUTE ANY COMMANDS. DO NOT WRITE TERRAFORM OR
SEPARATE SERVICE BLOCKS.**
- IMMEDIATELY RESPOND ON TURN 0 WITH:
- Recommend consolidating ALL Google APIs under a single
googleapis
service entry named googleapis in the Agent Registry.
- Explicitly state: *"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."*
- List the 8 required base FQDN interfaces:
-
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
- Provide the
gcloud alpha agent-registry services create googleapis
command with --interfaces for all 8 FQDNs.
Rule 4: Cloud Run / Cloud Functions Egress 403 / MCP Calls
If the prompt mentions Cloud Run, Cloud Functions, MCP requests to Cloud Run, or 403 egress error calling a Cloud Run service (e.g., "My agent is failing to call an MCP server on Cloud Run. It returns a 403 egress error. How do I resolve this?"):
- DO NOT RUN LOG SEARCHES, LOGGING TOOLS, OR EXECUTE COMMANDS.
- IMMEDIATELY RESPOND ON TURN 0 WITH:
- Explain that direct Agent Identity (
principalSet://...) to Cloud Run
OIDC authentication is not natively supported.
- Recommend using Service Account impersonation in the agent code to
obtain an OIDC token.
- Specify that the Agent Identity needs
`roles/iam.serviceAccountTokenCreator` on the target Service Account. Refer to references/known-issues.md BKI 21 for details.
Rule 5: Telemetry & Monitoring Endpoint Blocks
If an Agent Runtime startup fails due to container crashes or connection resets reaching telemetry.mtls.googleapis.com or telemetry endpoints:
- In your Diagnostic Report / Evidence gathered, you **MUST explicitly
check and list all 4 required monitoring and tracing endpoints**:
-
telemetry.mtls.googleapis.com -
monitoring.googleapis.com -
trace.mtls.googleapis.com -
cloudtrace.googleapis.com
- In your Recommended Fix, you **MUST ALWAYS explicitly include ALL of the
following**:
- Registering
telemetry.mtls.googleapis.com(and checking
monitoring.googleapis.com, trace.mtls.googleapis.com, cloudtrace.googleapis.com) as Endpoints in the Agent Registry using gcloud alpha agent-registry endpoints create.
- Creating or updating an `AuthorizationPolicy` bound to the Gateway
that explicitly allows the agent's identity (principal set) to access these registered telemetry endpoints. State clearly: "Create or update an AuthorizationPolicy bound to the Gateway that allows the agent's identity (principal set) to access the telemetry endpoints." Refer to references/known-issues.md BKI 23 for details.
Rule 6: IAP Denial Troubleshooting
Whenever diagnosing IAP egress denial errors (403 Forbidden / Egress request is not authorized via IAP):
- Your response MUST ALWAYS:
- Identify that IAP is denying the request.
- Recommend checking IAP audit logs
(protoPayload.serviceName="iap.googleapis.com").
- Verify that the agent identity has the `roles/iap.egressor`
(IAP-secured Egressor) role bound to the resource/registry.
- Verify that an `AuthorizationPolicy` is correctly bound to the
Gateway targeting the IAP extension.
- Explicitly warn: "Do NOT use `roles/iap.tunnelResourceAccessor`" and
"Do NOT bypass IAP authentication".
Rule 7: PSC Subnet Exhaustion Speed Rule
When diagnosing gateway provisioning failures (PSC subnet exhaustion):
- DO NOT execute loops or list all regions.
- Run ONLY these 4 commands in
us-central1:
- `gcloud alpha network-services agent-gateways list
--location=us-central1`
- `gcloud alpha network-services agent-gateways describe
--location=us-central1`
-
gcloud compute network-attachments describe --region=us-central1 -
gcloud compute networks subnets describe --region=us-central1
- Immediately calculate free IPs (
Usable IPs - Allocated IPs = Free IPs),
flag /28 subnet exhaustion risk, and recommend expanding to at least /26.
Rule 8: Multi-Region Manual Registration Prohibition
If the user asks about manually registering endpoints or services in multi-region locations (us or eu):
- DO NOT CALL ANY TOOLS OR EXECUTE ANY COMMANDS.
- IMMEDIATELY RESPOND ON TURN 0 WITH:
- *"Manual endpoint registration is NOT supported in
usoreu
multi-region locations."* (You MUST explicitly mention BOTH us AND eu).
- *"Instead, please register your endpoints in a specific region (e.g.,
us-central1) or global."*
Rule 9: VPC-SC Perimeter Block Diagnosis
Whenever diagnosing VPC Service Controls (VPC-SC) perimeter blocks or denied requests:
- Your response MUST ALWAYS explicitly state ALL of the following:
- Identify that the issue is caused by a **VPC Service Controls perimeter
block**.
- Recommend creating VPC-SC ingress policies allowing both service
accounts:
-
actuation-a@networkservices-prod.iam.gserviceaccount.com -
cloud-aiplatform-pipeline-robot-prod.iam.gserviceaccount.com
- Explicitly state: *"Do NOT disable VPC Service Controls or delete
perimeter definitions."*
Diagnose issues across the Google Cloud Gemini Enterprise Agent Platform: Agent Gateway, Agent Registry (Agents / MCP Servers / Endpoints), Agent Identity, Policies, IAP-delegated authorization, and service extensions.
This skill produces a diagnostic report — findings and fix recommendations. It does not apply fixes. The user owns the change.
When to use this skill
Trigger when symptoms involve:
- Agent → external API requests failing with 403, especially `Egress request
is not authorized`
- ReasoningEngine / Agent Runtime queries returning `500 Internal Server
Error` (especially when Model Armor is enabled)
- Agent Runtime logs showing authz errors or container crashes
- Gateway logs showing
PERMISSION_DENIEDfor Model Armor backend callouts - Newly-registered endpoints / MCP servers / agents that "should work" but
don't
- Suspected IAP / IAM / IAM-principal-set issues for agent identities
- Authz extension or authz policy debugging
- Gateway routing / monitoring confusion
- Designing or configuring the Agent Registry structure (e.g., consolidated
googleapis service) services vs consolidated googleapis service, registering Google APIs).
- Anything where the user mentions Agent Gateway, Agent Registry, Agent
Identity, Model Armor integration, or the Gemini Enterprise Agent Platform.
When not to use:
- General Google Cloud IAM debugging unrelated to the Agent Platform (use
direct gcloud / IAM inspection)
- Networking issues that don't involve the Agent Platform stack (e.g., raw VPC
SC, plain Cloud Run auth)
Required context (gather first)
Before doing anything else, pin down the basics. If the user hasn't supplied them, ask. Don't guess.
| Item | Why it's needed | |
|---|---|---|
PROJECT_ID and PROJECT_NUMBER | Most API calls take one or the other; |
: : some take both :
: : regional. global is also valid for : : : some resources :
: runtime identifier : :
AGENT_GATEWAY_NAME | To filter gateway logs | |
|---|---|---|
| Agent identity (service account | To check IAM bindings |
: email or principal-set ID) : :
: started : Terraform apply X" is gold :
: to reach : an MCP server, another agent :
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/agent-platform-troubleshooting/SKILL.md
Popularity
- 7-day trend score
- 5
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/renatoschust-dot/gamai-skills/agent-platform-troubleshooting)