/agent-platform-troubleshooting

name: agent-platform-troubleshooting
description: >-
  Troubleshoots Google Cloud Gemini Enterprise Agent Platform issues across Agent Gateway, Agent Connectivity Templates (ACT), Agent Registry, Agent Identity, Identity-Aware Proxy (IAP), Unified Access Policies (UAP), Model Armor, Semantic Governance Policies (SGP), Cloud DNS peering, Private CA TrustConfig, Next-Hop Secure Web Proxy (SWP), Explicit HTTPS Proxy (L4 AuthzPolicy), and Cloud Trace.
  Use when agent requests fail with 401/403/404/498/500/503 or Code 13, Egress request is not authorized, HTTP CONNECT fails with 404, Agent Runtime crashes on startup, or gateway/ACT/IAP/Model Armor/SGP configs fail validation.
  Don't use for general Google Cloud Identity and Access Management (IAM) debugging or networking issues unrelated to the Agent Platform stack.
metadata:
  version: "1.1.1"
  category: AiAndMachineLearning

Agent Platform Troubleshooting

> **Important:** You MUST ONLY use the reference files located in this skill's > `references/` directory (`references/field-manual.md`, > `references/known-issues.md`, `references/agent-gateway.md`, > `references/policies.md`, `references/agent-registry.md`, > `references/agent-identity.md`). Do NOT search for or read external playbooks > outside this directory.

Diagnose issues across the Google Cloud Gemini Enterprise Agent Platform: Agent Gateway, Agent Connectivity Templates (ACT), Agent Registry (Services, Agents, MCP Servers, Endpoints), Agent Identity, IAP/UAP policies, Model Armor, Semantic Governance Policies (SGP), explicit/transparent proxies, and tracing. This skill produces a **diagnostic report** — findings and fix recommendations. It does not apply fixes; the user owns all mutations.

Usage Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read and follow [Usage Attribution](references/attribution.md). Prefix direct terminal `gcloud` calls (never generated scripts, Terraform, or user code) with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-troubleshooting)"` and append `agent-skills/1.0 (skill:agent-platform-troubleshooting)` to direct HTTP/REST/MCP `User-Agent` headers.

MANDATORY PRE-FLIGHT CHECKLIST (CHECK BEFORE RESPONDING OR CALLING TOOLS)

CRITICAL: Before generating ANY response or calling any tools, evaluate the user's prompt against Rules 1–14. When a Turn-0 rule matches, execute its directive immediately and STOP.

Rule 1: Out-of-Scope GCP IAM / GCS Queries

If the prompt asks about Compute Engine (GCE), Cloud Storage (GCS) buckets, or generic GCP IAM permissions unrelated to the Agent Platform stack:

• **IMMEDIATELY DECLINE ON TURN 0. DO NOT CALL ANY TOOLS OR GIVE IAM GUIDES.**
• Respond: *"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 asked to write, generate, compile, or execute a custom Python or bash script to discover resources (e.g., active Agent Runtime instances):

• **DO NOT CALL ANY TOOLS OR WRITE/RUN ANY SCRIPTS.**
• **RESPOND ON TURN 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, use standard gcloud CLI commands (see [Google Cloud SDK Installation](https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt)) or curl REST API calls with application default credentials: `gcloud agent-registry agents list --location=us-central1` or `curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/reasoningEngines"`"*

Rule 3: Consolidated Registry for Google APIs / Design Queries

If asked about registering multiple Agent Runtime, Cloud Resource Manager, or Google API interfaces, or structuring services in Agent Registry:

• **DO NOT CALL ANY TOOLS. RESPOND ON TURN 0 WITH**:

1. Consolidate ALL Google APIs under a single `googleapis` service entry in Agent Registry via `gcloud agent-registry services create googleapis --endpoint-spec-type=no-spec`. 2. Explicitly state: *"Do NOT register each Google API as a separate registry service entry, as separate entries cause resource clutter, complicate IAM policy management, and risk hitting registry quota limits."* 3. List all 8 required base FQDN interfaces (plus global `https://aiplatform.googleapis.com` when calling global Gemini models):

• `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`

4. Refer to `references/agent-registry.md` §2 for the full command.

Rule 4: Cloud Run / Cloud Functions Egress 401/403 (OIDC vs IAP MCP)

If an agent gets a `401` or `403` egress error calling an MCP server or tool on Cloud Run or Cloud Functions:

• **DO NOT RUN LOG TOOLS. RESPOND ON TURN 0 WITH**:

1. Explain that direct Agent Identity (`principalSet://...` / `principal://...`) to standard Cloud Run OIDC authentication is **not natively supported**. 2. Recommend **Service Account impersonation** in agent code to obtain an OIDC ID token, granting **`roles/iam.serviceAccountTokenCreator`** to the Agent Identity on the target SA (and `roles/run.invoker` to that SA on Cloud Run). 3. Note that for Preview IAP-enabled Cloud Run MCP servers (`--iap --functional-type=mcp-server`, `run.app` short URL), authorize via IAP/UAP instead of `roles/run.invoker` (see `references/known-issues.md` BKI 21 and `re