renatoschust-dot/gamai-skills/agent-platform-troubleshooting

Claude Code and agent skill by renatoschust-dot/gamai-skills

Trust tier 2
  • community
LLM review pending
Source check pending

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-troubleshooting

SKILL.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 located
in this skill's references/ directory (e.g., references/field-manual.md,
references/known-issues.md, references/agent-registry.md). Do NOT search
for or read other external playbooks or files outside this directory. The
files in the local references/ directory contain workspace-specific fixes
and 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:
  1. Recommend consolidating ALL Google APIs under a single googleapis

service entry named googleapis in the Agent Registry.

  1. 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."*

  1. 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
  1. 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:
  1. Explain that direct Agent Identity (principalSet://...) to Cloud Run

OIDC authentication is not natively supported.

  1. Recommend using Service Account impersonation in the agent code to

obtain an OIDC token.

  1. 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**:

  1. telemetry.mtls.googleapis.com
  2. monitoring.googleapis.com
  3. trace.mtls.googleapis.com
  4. cloudtrace.googleapis.com
  • In your Recommended Fix, you **MUST ALWAYS explicitly include ALL of the

following**:

  1. 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.

  1. 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:
  1. Identify that IAP is denying the request.
  2. Recommend checking IAP audit logs

(protoPayload.serviceName="iap.googleapis.com").

  1. Verify that the agent identity has the `roles/iap.egressor`

(IAP-secured Egressor) role bound to the resource/registry.

  1. Verify that an `AuthorizationPolicy` is correctly bound to the

Gateway targeting the IAP extension.

  1. 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:
  1. `gcloud alpha network-services agent-gateways list

--location=us-central1`

  1. `gcloud alpha network-services agent-gateways describe

--location=us-central1`

  1. gcloud compute network-attachments describe --region=us-central1
  2. 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:
  1. *"Manual endpoint registration is NOT supported in us or eu

multi-region locations."* (You MUST explicitly mention BOTH us AND eu).

  1. *"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:
  1. Identify that the issue is caused by a **VPC Service Controls perimeter

block**.

  1. 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
  1. 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_DENIED for 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.

ItemWhy it's needed
PROJECT_ID and PROJECT_NUMBERMost API calls take one or the other;

: : some take both :

: : regional. global is also valid for : : : some resources :

: runtime identifier : :

AGENT_GATEWAY_NAMETo filter gateway logs
Agent identity (service accountTo 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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/renatoschust-dot/gamai-skills/agent-platform-troubleshooting/badge)](https://verified-skill.com/skills/renatoschust-dot/gamai-skills/agent-platform-troubleshooting)

Something wrong with this skill or its page? Tell us.