[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M698YP6ECW2J1HM05NHN206V":3,"skill-same:01M698YP6ECW2J1HM05NHN206V":106},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":45,"linkOnly":46,"markdownContent":47,"markdownBody":48,"frontMatter":49,"refName":53,"commitSha":54,"skillDirectory":55,"forksCount":56,"repositoryHtmlUrl":57,"repositoryHomepageUrl":6,"ownerHtmlUrl":58,"ownerBlogUrl":59,"ownerDescription":60,"updatedAt":61,"install":62,"resources":75},"01M698YP6ECW2J1HM05NHN206V","agent-platform-troubleshooting",null,"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\u002F403\u002F404\u002F498\u002F500\u002F503 or Code 13, Egress request is not authorized, HTTP CONNECT fails with 404, Agent Runtime crashes on startup, or gateway\u002FACT\u002FIAP\u002FModel Armor\u002FSGP 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.","google\u002Fskills","google","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F1342004?v=4","01M698VYEFDM0VJBZDYYJ2T83S","Google","01M698WR0H76ENHE587T9EJT89",24044,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,9,36,37,38,39,40,41,42,43,44],"agent platform","agent platform troubleshooting","platform","troubleshooting","iam","for","act","agent registry","general","use","stack","iap","Enterprise","agent identity","registry","connect","secure","identity","google cloud","gemini enterprise agent platform","gemini","2026-11-10 10:12:30",false,"---\nname: agent-platform-troubleshooting\ndescription: >-\n  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.\n  Use when agent requests fail with 401\u002F403\u002F404\u002F498\u002F500\u002F503 or Code 13, Egress request is not authorized, HTTP CONNECT fails with 404, Agent Runtime crashes on startup, or gateway\u002FACT\u002FIAP\u002FModel Armor\u002FSGP configs fail validation.\n  Don't use for general Google Cloud Identity and Access Management (IAM) debugging or networking issues unrelated to the Agent Platform stack.\nmetadata:\n  version: \"1.1.1\"\n  category: AiAndMachineLearning\n---\n\n# Agent Platform Troubleshooting\n\n> **Important:** You MUST ONLY use the reference files located in this skill's\n> `references\u002F` directory (`references\u002Ffield-manual.md`,\n> `references\u002Fknown-issues.md`, `references\u002Fagent-gateway.md`,\n> `references\u002Fpolicies.md`, `references\u002Fagent-registry.md`,\n> `references\u002Fagent-identity.md`). Do NOT search for or read external playbooks\n> outside this directory.\n\nDiagnose issues across the Google Cloud Gemini Enterprise Agent Platform: Agent\nGateway, Agent Connectivity Templates (ACT), Agent Registry (Services, Agents,\nMCP Servers, Endpoints), Agent Identity, IAP\u002FUAP policies, Model Armor,\nSemantic Governance Policies (SGP), explicit\u002Ftransparent proxies, and tracing.\nThis skill produces a **diagnostic report** — findings and fix recommendations.\nIt does not apply fixes; the user owns all mutations.\n\n## Usage Attribution\n\n**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you\nMUST read and follow [Usage Attribution](references\u002Fattribution.md). Prefix\ndirect terminal `gcloud` calls (never generated scripts, Terraform, or user\ncode) with\n`CLOUDSDK_METRICS_REQUEST_ATTRIBUTION=\"agent-skills\u002F1.0 (skill:agent-platform-troubleshooting)\"`\nand append `agent-skills\u002F1.0 (skill:agent-platform-troubleshooting)` to direct\nHTTP\u002FREST\u002FMCP `User-Agent` headers.\n\n## MANDATORY PRE-FLIGHT CHECKLIST (CHECK BEFORE RESPONDING OR CALLING TOOLS)\n\nCRITICAL: Before generating ANY response or calling any tools, evaluate the\nuser's prompt against Rules 1–14. When a Turn-0 rule matches, execute its\ndirective immediately and STOP.\n\n### Rule 1: Out-of-Scope GCP IAM \u002F GCS Queries\nIf the prompt asks about Compute Engine (GCE), Cloud Storage (GCS) buckets, or\ngeneric GCP IAM permissions unrelated to the Agent Platform stack:\n- **IMMEDIATELY DECLINE ON TURN 0. DO NOT CALL ANY TOOLS OR GIVE IAM GUIDES.**\n- Respond: *\"I decline to troubleshoot generic GCP IAM or GCS access issues, as\n  they are out of scope for the Agent Platform Troubleshooting skill.\"*\n\n### Rule 2: Strict Prohibition on Custom Discovery Scripts\nIf asked to write, generate, compile, or execute a custom Python or bash script\nto discover resources (e.g., active Agent Runtime instances):\n- **DO NOT CALL ANY TOOLS OR WRITE\u002FRUN ANY SCRIPTS.**\n- **RESPOND ON TURN 0**: *\"I cannot write or execute custom Python or bash\n  scripts for resource discovery. Custom discovery scripts are prohibited as\n  they consume excessive turns and cause timeouts. Instead, use standard gcloud\n  CLI commands (see [Google Cloud SDK Installation](https:\u002F\u002Fdocs.cloud.google.com\u002Fsdk\u002Fdocs\u002Finstall-sdk.md.txt))\n  or curl REST API calls with application default credentials:\n  `gcloud agent-registry agents list --location=us-central1` or `curl -H \"Authorization: Bearer $(gcloud auth application-default print-access-token)\" \"https:\u002F\u002Fus-central1-aiplatform.googleapis.com\u002Fv1\u002Fprojects\u002FPROJECT_ID\u002Flocations\u002Fus-central1\u002FreasoningEngines\"`\"*\n\n### Rule 3: Consolidated Registry for Google APIs \u002F Design Queries\nIf asked about registering multiple Agent Runtime, Cloud Resource Manager, or\nGoogle API interfaces, or structuring services in Agent Registry:\n- **DO NOT CALL ANY TOOLS. RESPOND ON TURN 0 WITH**:\n  1. Consolidate ALL Google APIs under a single `googleapis` service entry in\n     Agent Registry via `gcloud agent-registry services create googleapis --endpoint-spec-type=no-spec`.\n  2. Explicitly state: *\"Do NOT register each Google API as a separate registry\n     service entry, as separate entries cause resource clutter, complicate IAM\n     policy management, and risk hitting registry quota limits.\"*\n  3. List all 8 required base FQDN interfaces (plus global\n     `https:\u002F\u002Faiplatform.googleapis.com` when calling global Gemini models):\n     - `https:\u002F\u002Fagentregistry.googleapis.com`\n     - `https:\u002F\u002Faiplatform.mtls.googleapis.com`\n     - `https:\u002F\u002Fcloudresourcemanager.mtls.googleapis.com`\n     - `https:\u002F\u002Fiamcredentials.mtls.googleapis.com`\n     - `https:\u002F\u002Ftelemetry.mtls.googleapis.com`\n     - `https:\u002F\u002F{region}-aiplatform.mtls.googleapis.com`\n     - `https:\u002F\u002F{region}-aiplatform.googleapis.com`\n     - `https:\u002F\u002Faiplatform.{region}.rep.googleapis.com`\n  4. Refer to `references\u002Fagent-registry.md` §2 for the full command.\n\n### Rule 4: Cloud Run \u002F Cloud Functions Egress 401\u002F403 (OIDC vs IAP MCP)\nIf an agent gets a `401` or `403` egress error calling an MCP server or tool on\nCloud Run or Cloud Functions:\n- **DO NOT RUN LOG TOOLS. RESPOND ON TURN 0 WITH**:\n  1. Explain that direct Agent Identity (`principalSet:\u002F\u002F...` \u002F `principal:\u002F\u002F...`)\n     to standard Cloud Run OIDC authentication is **not natively supported**.\n  2. Recommend **Service Account impersonation** in agent code to obtain an OIDC\n     ID token, granting **`roles\u002Fiam.serviceAccountTokenCreator`** to the Agent\n     Identity on the target SA (and `roles\u002Frun.invoker` to that SA on Cloud Run).\n  3. Note that for Preview IAP-enabled Cloud Run MCP servers (`--iap\n     --functional-type=mcp-server`, `run.app` short URL), authorize via IAP\u002FUAP\n     instead of `roles\u002Frun.invoker` (see `references\u002Fknown-issues.md` BKI 21 and\n     `references\u002Fagent-identity.md`).\n\n### Rule 5: Telemetry & Monitoring Endpoint Blocks on Startup\nIf Agent Runtime startup crashes (`set_up()`) with connection resets or\nhandshake errors reaching `telemetry.mtls.googleapis.com`:\n- **Evidence**: Explicitly check whether all 4 monitoring\u002Ftracing endpoints are\n  registered as Endpoints in Agent Registry (`gcloud agent-registry endpoints list`):\n  `telemetry.mtls.googleapis.com`, `monitoring.googleapis.com`,\n  `trace.mtls.googleapis.com`, and `cloudtrace.googleapis.com`.\n- **Recommended Fix**:\n  1. Register missing telemetry\u002Ftracing interfaces via `gcloud agent-registry\n     services create --endpoint-spec-type=no-spec` (which projects read-only\n     Endpoints in Agent Registry for `telemetry.mtls.googleapis.com`,\n     `monitoring.googleapis.com`, `trace.mtls.googleapis.com`, and\n     `cloudtrace.googleapis.com`).\n  2. Create or update an **`AuthorizationPolicy`** (`AuthzPolicy` \u002F IAP \u002F UAP)\n     bound to the Gateway that allows the agent's principal set (identity) to\n     access the telemetry endpoints (see `references\u002Fknown-issues.md` BKI 23).\n\n### Rule 6: IAP Denial Troubleshooting (`403` \u002F `Egress request is not authorized`)\nWhen logs or symptoms show `403` \u002F `Egress request is not authorized` via IAP:\n1. **Check IAP Egressor bindings on the registry entry FIRST** (`roles\u002Fiap.egressor`\n   via `gcloud iap web get-iam-policy --resource-type=agent-registry` bound to\n   the server-generated child UUID from `registryResource`, not `SERVICE_NAME`).\n2. **Create a registry entry** (`gcloud agent-registry services create`) if none\n   exists for the exact target hostname.\n3. **Grant `roles\u002Fiap.egressor`** on the registry entry (IAM v1 — `set-iam-policy` requires top-level `{\"bindings\": [...]}` JSON without a `\"policy\"` wrapper) or verify UAP\n   `AccessPolicy` + CRM `PolicyBinding` (`iapPolicyVersion: \"V2\"`,\n   `iap.googleapis.com\u002Fresources.egressViaIAP`; see `references\u002Fpolicies.md` §2).\n4. **Check IAP audit logs** (`protoPayload.serviceName=\"iap.googleapis.com\"`)\n   and verify an `AuthorizationPolicy` (`AuthzPolicy`) is bound to the Gateway.\n5. **Explicitly warn**: *\"Do NOT use `roles\u002Fiap.tunnelResourceAccessor` (which\n   is for classic IAP TCP tunneling to GCE VMs, not Agent Gateway egress) and do\n   NOT bypass IAP authentication.\"*\n\n### Rule 7: PSC Subnet Exhaustion Speed Rule (`PROVISIONING` Hang)\nWhen diagnosing gateway provisioning stuck or failing on subnet IP exhaustion:\n- **DO NOT loop across regions.** Run ONLY in the target region (default `us-central1`):\n  1. `gcloud network-services agent-gateways list --location=us-central1`\n  2. `gcloud network-services agent-gateways describe \u003CGW> --location=us-central1`\n  3. `gcloud compute network-attachments describe \u003CNA> --region=us-central1`\n  4. `gcloud compute networks subnets describe \u003CSUBNET> --region=us-central1`\n- Check free IP count (`Usable - Allocated = Free`) **before** recommending any\n  Network Attachment deletion; flag that a `\u002F28` subnet is easily exhausted and\n  recommend expanding the CIDR range to at least `\u002F26` (`known-issues.md` BKI 19).\n\n### Rule 8: Multi-Region Manual Registration Prohibition (`us` \u002F `eu`)\nIf asked about manually registering endpoints or services in `us` or `eu`:\n- **DO NOT CALL ANY TOOLS. RESPOND ON TURN 0**:\n  1. *\"Manual endpoint\u002Fservice registration is NOT supported in `us` or `eu`\n     multi-region locations (`us` and `eu` are read-only roll-up locations for\n     auto-discovered resources).\"* (Explicitly name BOTH `us` and `eu`.)\n  2. *\"Register manually in a specific region (e.g., `us-central1`) or `global`.\"*\n\n### Rule 9: VPC Service Controls (VPC-SC) Perimeter & ACT `ALL_TRAFFIC`\nWhen diagnosing VPC-SC perimeter blocks or external API hangs under VPC-SC:\n1. Identify a **VPC Service Controls perimeter block** \u002F boundary enforcement.\n2. Check that the Agent Connectivity Template (ACT) sets **`vpcEgress:\n   ALL_TRAFFIC`** (native VPC-SC creation works out of the box since Sept 8,\n   2026 when `vpcEgress: ALL_TRAFFIC` is set) and that **Cloud NAT** is\n   configured on the consumer VPC's PSC-I network attachment subnet.\n3. For legacy or strict custom perimeters blocking Google actuation identities,\n   recommend creating **ingress policies** allowing:\n   - `actuation-a@networkservices-prod.iam.gserviceaccount.com`\n   - `cloud-aiplatform-pipeline-robot-prod@system.gserviceaccount.com`\n4. Explicitly state: *\"Do NOT disable VPC Service Controls or delete perimeters.\"*\n   Refer to `references\u002Fknown-issues.md` BKI 18 & 28.\n\n### Rule 10: UAP Policy Binding Org Policy Blocker & Blanket `DENY` Crash\n- **`CUSTOM_ORG_POLICY_VIOLATION` on `gcloud iam policy-bindings create`**:\n  Caused by **`constraints\u002Fiam.managed.disableAccessPolicyBinding`** (note: some\n  docs misspell this plural). Apply an Org Policy override (`enforce: false`) at\n  the target resource and wait **30 to 60 seconds** for IAM propagation (BKI 24).\n- **Startup crash after UAP `destination.is_registered == false` `DENY`**:\n  Explain that the blanket `DENY` blocked internal\u002Funauthenticated SDK bootstrap\n  and metadata calls (such as Cloud Resource Manager project lookups) during\n  Reasoning Engine init; remove or scope the blanket `DENY` rule (BKI 5).\n\n### Rule 11: Agent Gateway Dual-Registry & Jurisdiction Invariants\nWhen configuring or validating `registries` on an Agent Gateway:\n1. An Agent Gateway supports a **maximum of two registries**.\n2. When two registries are configured, **exactly one must be `global`** and the\n   other must be **`regional` or `multi-regional`**.\n3. Binding two regional registries (e.g., `us-central1` + `europe-west1`), two\n   multi-regionals, two globals, or a mismatched jurisdiction (e.g., `us-central1`\n   gateway + `eu` registry) is invalid and rejected with an **HTTP 400**\n   validation error (`references\u002Fagent-gateway.md` §4, BKI 26).\n\n### Rule 12: Cross-Project Runtime-to-Gateway Binding Diagnosis\nWhen Reasoning Engine in Project 1 fails to bind to a Gateway in Project 2:\n1. **Deploying Identity**: Needs `networkservices.agentGateways.use` and\n   `networkservices.agentGateways.get` (or `roles\u002Fnetworkservices.viewer`) in Project 2.\n2. **Vertex AI Service Agent**: Grant `roles\u002Fnetworkservices.viewer` or custom\n   role `ae_agw_cross_project_sa` (alias `ar_agw_cross_project_sa`) to\n   `service-PROJECT_1_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com` in Project 2.\n3. **Regional Colocation**: Verify both runtime and gateway are in the **same region**.\n4. **CAA Opt-Out**: Set `GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES`\n   to `False` (`references\u002Fknown-issues.md` BKI 10, `references\u002Fagent-gateway.md` §11).\n\n### Rule 13: Downstream SWP + PBR vs. Explicit Forward HTTPS Proxy\nDistinguish the two supported consumer-VPC proxy architectures:\n- **Pattern A — Transparent Next-Hop SWP + PBR** (no client `HTTPS_PROXY` needed):\n  1. Explain that **PSC endpoints cannot be route next-hops**, **SWP behind PSC\n     Service Attachments only supports explicit proxy mode (not transparent\n     next-hop mode)**, and **static routes cannot be used because Network\n     Attachments cannot have VM network tags**.\n  2. Deploy SWP directly in the consumer VPC with `type: SECURE_WEB_GATEWAY` and\n     `routingMode: NEXT_HOP_ROUTING_MODE` on an internal IP on the PSC-I subnet\n     (e.g., `10.20.1.250`), with a `\u002F26` `REGIONAL_MANAGED_PROXY` `ACTIVE` subnet.\n  3. Configure **Policy-Based Routing (PBR)** matching source CIDR `10.20.1.0\u002F24`\n     to `--next-hop-ilb-ip=10.20.1.250` (priority 200) + fallback PBR (1000).\n  4. Create **Cloud NAT with `ENDPOINT_TYPE_SWG`** (`nats create ... --endpoint-types=ENDPOINT_TYPE_VM,ENDPOINT_TYPE_SWG`),\n     and allowlist `\u003Cregion>-aiplatform.mtls.googleapis.com` in SWP CEL (BKI 33).\n- **Pattern B — Explicit Forward HTTPS Proxy (`HTTPS_PROXY` + L4 `AuthzPolicy`)**:\n  1. Without L4 bypass, `HTTPS_PROXY=https:\u002F\u002Fproxy.corp.internal:443` fails on\n     `HTTP CONNECT` with **HTTP `404`** because Agent Gateway's L7 HTTP manager\n     terminates TLS and rejects nested `CONNECT`.\n  2. Import a **`v1beta1`** L4 `AuthzPolicy` via **`gcloud beta network-security\n     authz-policies import`** with `action: ALLOW` and `networkRules` matching\n     `to.operations[].snis` (omit `target.loadBalancingScheme` and `ports`; max 5 rules;\n     omit `from` or include `7.0.0.0\u002F8` + PSC-I CIDR in `from.sources[].ipBlocks`).\n  3. Listen with TLS on `:443`, allow the consumer PSC-I subnet CIDR on VPC firewall\u002Fproxy ACLs (never `7.0.0.0\u002F8`),\n     set `NO_PROXY`\u002F`no_proxy` to `.googleapis.com,googleapis.com,metadata.google.internal,169.254.169.254,localhost,127.0.0.1`,\n     bundle `agentGatewayCard.rootCertificates` + Private CA in container env\n     vars (`SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`), and warn L4 `ALLOW` bypasses\n     L7 IAP\u002FUAP, Model Armor, SGP, and `httpRules` for matched SNIs (BKI 34).\n\n### Rule 14: DNS Peering, `TrustConfig`, Model Armor, SGP, MCP, Identity, & Lifecycle\n- **DNS Peering & Service Agent**: Public FQDNs resolve via public recursive DNS.\n  Private DNS requires `dnsPeeringConfig` (`domains` array with trailing `.`; ACT\n  uses string `targetNetwork` only, whereas inline `AgentGateway.networkConfig.dnsPeeringConfig`\n  also requires `targetProject`). Cloud DNS caps total peering hops at **2**\n  (Gateway consumes Hop 1 → max 1 consumer peering hop; a 2nd hop fails preflight\n  or returns `SERVFAIL` → `503`, BKI 35). Grant `roles\u002Fdns.peer`, `roles\u002Fdns.reader`,\n  `roles\u002Fcompute.networkViewer`, and `roles\u002Fcompute.networkUser` to\n  `service-GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com`\n  (and `compute.networkAttachments.use` to caller, BKI 9). Never use authoritative `\".\"` private root zones (`\".\"` requires a Cloud DNS Private Forwarding Zone).\n- **Private CA `TrustConfig` & Immutable ACT**: Set `egressNetworkConfig.tlsConfig.trustConfig`\n  **with `additionalRoots: PUBLICLY_TRUSTED_ROOTS`** (omitting breaks `*.googleapis.com`).\n  ACT fields are immutable — create a new ACT and rebind via `PATCH` with\n  `updateMask=agentConnectivityTemplate` (BKI 6).\n- **Model Armor (`CONTENT_AUTHZ`)**: Ingress (`CLIENT_TO_AGENT`, max 1, ADK\n  `streamQuery` only) uses `service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com`;\n  Egress (`AGENT_TO_ANYWHERE`, max 4) uses `service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com`.\n  Scope `httpRules` `when` to exclude gRPC and streams **>60 seconds** (`Stream removed`, BKI 13).\n- **Semantic Governance Policies (SGP)**: Uses `gcp-sa-aiplatform`, non-streaming\n  LLM calls only, `.contains()` + `!request.headers['content-type'].startsWith('application\u002Fgrpc')`\n  in `when`, and full-map updates on `PATCH ?updateMask=metadata` so\n  `sgpEnforcementMode: \"DRY_RUN\"` and `sgpUserIntentMatching` are preserved (BKI 38).\n- **Native MCP, Identity, Trace, & Teardown**: Set `baseProtocolMethodsOption:\n  MATCH_BASE_PROTOCOL_METHODS` on MCP `ALLOW` rules (BKI 39). Orgless trust\n  domains use `agents.global.proj-PROJECT_NUMBER.system.id.goog` (`proj-`, never\n  `project-`); never grant `roles\u002Faiplatform.expressUser` or project-wide\n  `roles\u002Faiplatform.user` to Agent Identities. For Cloud Trace (`TelemetryPolicy`),\n  always recommend enabling `cloudtrace.googleapis.com` (`gcloud services enable cloudtrace.googleapis.com`)\n  and granting `roles\u002Fcloudtrace.agent` to `compute-system`, `gcp-sa-networksecurity`,\n  and `gcp-sa-agentgateway` (see `references\u002Fagent-gateway.md` §8.3 and `references\u002Ffield-manual.md` Step 14.4). Tear down in strict 7-step order\n  (workloads → UAP bindings → `AuthzPolicy` → extensions → `AgentGateway` → ACT →\n  VPC) and use unique gateway IDs if deletion tombstones collide (BKIs 25, 30).\n\n## Quick Symptom Triage Matrix\n\n| Symptom \u002F Error | Primary Suspect | Reference |\n| :--- | :--- | :--- |\n| `403` \u002F `Egress request is not authorized` | Unregistered FQDN, missing `roles\u002Fiap.egressor` \u002F UAP binding, or PAB | Rules 4, 6; `references\u002Fpolicies.md` §2; BKIs 4, 7, 8, 15 |\n| `HTTP 404` on `HTTP CONNECT` (`HTTPS_PROXY`) | Missing `gcloud beta` L4 `AuthzPolicy` (`networkRules` `snis`) | Rule 13B; `references\u002Fagent-gateway.md` §6.3; BKI 34 |\n| `HTTP 498` immediately after binding runtime | Enforcing gateway bound before allowlisting essential platform APIs | `references\u002Fagent-gateway.md` §2; BKI 37 |\n| `500` \u002F `PERMISSION_DENIED` \u002F `Stream removed` | Model Armor SA roles (`gcp-sa-dep` vs `gcp-sa-aiplatform-re`) or 60s stream cap | Rule 14; `references\u002Fpolicies.md` §12; BKI 13 |\n| `503` \u002F `NXDOMAIN` \u002F `SERVFAIL` on private host | >2-hop DNS peering, authoritative `\".\"` zone, Packet Intercept, or SWP | Rules 13A, 14; `references\u002Fagent-gateway.md` §3, §6; BKIs 33, 35, 36 |\n| `Config validation failed` \u002F `PERMISSION_DENIED` on import | Disabled `agentregistry.googleapis.com`, missing caller\u002F`gcp-sa-agentgateway` IAM, or bad NA URI | Rule 14; BKIs 9, 20, 26 |\n| `HTTP 409 ABORTED` \u002F `400 already being used` | Active control-plane LRO mutex (~2 min), tombstone collision, or reverse teardown | `references\u002Fagent-gateway.md` §9, §10; BKIs 25, 29, 30 |\n| Startup crash (`reasoning_engine_stderr`) | Blocked telemetry\u002FCRM bootstrap, UAP blanket `DENY`, or SGP gRPC interception | Rules 5, 10, 14; BKIs 1, 5, 17, 23, 38 |\n\n## When to use this skill\n\nTrigger on Agent Gateway, Agent Connectivity Templates (ACT), Agent Registry,\nAgent Identity, IAP\u002FUAP policies, Model Armor, Semantic Governance Policies\n(SGP), SWP\u002FExplicit Proxy egress, Private CA `TrustConfig`, Cloud DNS peering,\nCloud Trace `TelemetryPolicy`, or Gemini Enterprise \u002F Agent Runtime \u002F GKE \u002F\nCloud Run gateway bindings. Do **not** use for generic Google Cloud IAM, GCS,\nGCE, or networking issues unrelated to the Agent Platform stack.\n\n## Required context & Hypothesis Rules\n\nGather `PROJECT_ID`, `PROJECT_NUMBER`, `LOCATION` (default `us-central1`),\n`AGENT_ID`, `AGENT_GATEWAY_NAME`, Agent Identity (`principal:\u002F\u002F` or\n`principalSet:\u002F\u002F`), exact error + timestamp, and target destination. If missing,\nask or state unknowns using placeholders — never scan across projects or loop\nover regions. Before Step 1 queries, formulate **at most 3 hypotheses** anchored\nto *\"Why did it start failing now?\"* (e.g., recent Terraform\u002Fconfig changes).\n\n## Diagnostic flow\n\nFollow in order (copy-paste commands in `references\u002Ffield-manual.md`):\n- **Step 0 — Pre-Flight & Access**: Evaluate Rules 1–14. Verify project access\n  (`gcloud projects describe $PROJECT_ID`).\n- **Step 1 — Agent & Startup Logs**: Classify error (`403`, `404 CONNECT`, `498`,\n  `500`, `503`, crash, timeout). Check PSC subnet IPs, ACT `ALL_TRAFFIC` + Cloud\n  NAT, and `agentGatewayCard.rootCertificates` CA trust.\n- **Step 2 — Gateway Logs**: Query `networkservices.googleapis.com\u002FGateway`\n  (filtering `-httpRequest.requestMethod=\"CONNECT\"` when inspecting L7 requests)\n  to find the exact failing SNI\u002Fhostname and `serviceExtensionsInfo`.\n- **Step 3 — IAP \u002F Model Armor \u002F SGP Logs**: Check `iapPolicyVersion` (`V1` vs\n  `V2`), `DRY_RUN` vs enforced, Model Armor callout status, or\n  `logs\u002Fsemantic-governance-policy` verdicts and rationales.\n- **Step 4 — Registry State**: Verify exact hostname permutations in\n  `gcloud agent-registry {services,endpoints,mcp-servers,agents} list` and\n  confirm dual-registry + jurisdiction rules.\n- **Step 5 — Identity & Policies**: Check `roles\u002Fiap.egressor` via\n  `--resource-type=agent-registry` on the child UUID (V1), UAP\n  `AccessPolicy`\u002F`PolicyBinding` + `constraints\u002Fiam.managed.disableAccessPolicyBinding`\n  (V2), PAB overrides, and least-privilege Agent Identity roles (`proj-` for orgless).\n- **Step 6 — AuthzPolicy & Extensions**: Verify L4 `networkRules` vs L7\n  `httpRules`, MCP `MATCH_BASE_PROTOCOL_METHODS`, Model Armor \u002F SGP `when`\n  exclusions, `ExtensionBinding` scope, and policy caps (max 4 egress, max 1 ingress `CONTENT_AUTHZ`).\n- **Step 7 — Connectivity, DNS, & TLS**: Verify ACT `TrustConfig`\n  (`PUBLICLY_TRUSTED_ROOTS`), `gcp-sa-agentgateway` IAM, \u003C=2 DNS peering hops,\n  no Packet Intercept on the consumer VPC, and SWP\u002FExplicit Proxy settings.\n- **Step 8 — PrincipalSet & Trace Verification**: Test 1:1 `principal:\u002F\u002F`\n  binding if `principalSet:\u002F\u002F` lags; for Cloud Trace, enable `cloudtrace.googleapis.com`, verify `v1beta1` `TelemetryPolicy` (`telemetryTarget` referencing `agentGateways\u002F*` and object `parentBasedSampling: {enabled: true, samplingRate: 1.0}`, never string `ENABLED`), and grant `roles\u002Fcloudtrace.agent` to `service-\u003CPROJECT_NUMBER>@compute-system.iam.gserviceaccount.com`, `service-\u003CPROJECT_NUMBER>@gcp-sa-networksecurity.iam.gserviceaccount.com`, and `service-\u003CPROJECT_NUMBER>@gcp-sa-agentgateway.iam.gserviceaccount.com`.\n\n## Tools & Layered References\n\nUse `mcp__gcloud__run_gcloud_command` (or `gcloud --quiet`),\n`mcp__gcloud-observability__list_log_entries` (or `gcloud logging read`),\n`mcp__google-dev-knowledge__search_documents` \u002F `get_documents` \u002F `answer_query`,\nand `curl` REST GETs, plus bundled references (load only the smallest set needed):\n- [references\u002Ffield-manual.md](references\u002Ffield-manual.md) — read first for operational commands & log queries\n- [references\u002Fknown-issues.md](references\u002Fknown-issues.md) — BKIs #1–#13, #15–#39 for fast pattern matches\n- [references\u002Fagent-gateway.md](references\u002Fagent-gateway.md) — topologies, ACT, DNS, TLS, SWP\u002FExplicit Proxy, Trace, teardown\n- [references\u002Fpolicies.md](references\u002Fpolicies.md) — L4\u002FL7 `AuthzPolicy`, MCP, UAP v3beta, Model Armor, SGP\n- [references\u002Fagent-registry.md](references\u002Fagent-registry.md) — `services` vs projected `endpoints`, 9 API families, jurisdictions\n- [references\u002Fagent-identity.md](references\u002Fagent-identity.md) — 3-identity delegation, Cloud Run OIDC vs IAP MCP, WIF\n\n## Output report\n\nAlways produce a read-only diagnostic report using this exact structure:\n\n```markdown\n# Agent Platform Diagnostic — \u003Cone-line summary>\n\n## Context\n- Project: \u003Cid> (\u003Cnumber>) | Location: \u003Cregion>\n- Agent: \u003Cagent_id> | Gateway: \u003Cgateway_name>\n- Symptom: \u003Cexact error message and when it started>\n\n## Evidence gathered\n- Agent log query: \u003Cfilter, summary>\n- Gateway log query: \u003Cfilter, exact failing hostname \u002F extension status>\n- IAP \u002F Policy log query: \u003Cfilter, decision + enforcement mode>\n- Registry & Policy state: \u003Centries, AuthzPolicy bindings, roles\u002Fiap.egressor or UAP>\n\n## Root cause hypothesis\n\u003Cranked root cause(s)>\n\n## Why this fits the evidence\n\u003Cconnect log\u002Fconfig evidence to root cause>\n\n## Recommended fix\n\u003Cordered gcloud \u002F curl \u002F YAML \u002F Terraform changes for the user to apply>\n\n## What to verify after the fix\n\u003Cverification queries>\n\n## Open questions \u002F unknowns\n\u003Cmissing context or unverified items>\n\n## Appendix: Raw Logs & Verified Links\n- **Cloud Logging Filter**: \u003Cexact copy-pasteable filter or deep link>\n- **Raw Logs**: \u003Cuntruncated Agent, Gateway, and IAP\u002FPolicy log entries>\n```\n\n## Principles\n\n- **Exact hostname match first**: Compare gateway log hostnames directly against Agent Registry.\n- **Layered default-deny**: Registry → Gateway `AuthzPolicy` → Extension → IAP\u002FUAP\u002FModel Armor\u002FSGP → PAB (PAB overrides IAM Allow).\n- **L4 bypass vs L7 governance**: L4 `networkRules` enables `HTTP CONNECT` explicit proxies (`:443`) but bypasses L7 IAP, Model Armor, and SGP for matched SNIs.\n- **Read-only, single-region, non-interactive**: Pull evidence first, never mutate resources, check `us-central1` unless logs indicate otherwise, and pass `--quiet`.\n\n## Supporting Links\n\n- [Agent Gateway Overview](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fagent-gateway-overview.md.txt)\n- [Configure VPC Connectivity & DNS](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fset-up-vpc-connectivity.md.txt)\n- [Delegate Authorization & MCP](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fdelegate-authorization.md.txt)\n- [Configure Model Armor](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fconfigure-model-armor.md.txt)\n- [Configure Semantic Governance](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fpolicies\u002Fconfigure-semantic-governance.md.txt)\n- [Monitor & Trace Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fmonitor-agent-gateway.md.txt)\n- [Deploy Agent Gateway Runtime](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Fagent-gateway-runtime-deploy.md.txt)\n- [Troubleshoot Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Ftroubleshooting\u002Ftroubleshoot-agent-gateway.md.txt)\n- [Troubleshoot IAM Policies (UAP)](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Ftroubleshooting\u002Ftroubleshoot-iam-policies-uap.md.txt)\n","# Agent Platform Troubleshooting\n\n> **Important:** You MUST ONLY use the reference files located in this skill's\n> `references\u002F` directory (`references\u002Ffield-manual.md`,\n> `references\u002Fknown-issues.md`, `references\u002Fagent-gateway.md`,\n> `references\u002Fpolicies.md`, `references\u002Fagent-registry.md`,\n> `references\u002Fagent-identity.md`). Do NOT search for or read external playbooks\n> outside this directory.\n\nDiagnose issues across the Google Cloud Gemini Enterprise Agent Platform: Agent\nGateway, Agent Connectivity Templates (ACT), Agent Registry (Services, Agents,\nMCP Servers, Endpoints), Agent Identity, IAP\u002FUAP policies, Model Armor,\nSemantic Governance Policies (SGP), explicit\u002Ftransparent proxies, and tracing.\nThis skill produces a **diagnostic report** — findings and fix recommendations.\nIt does not apply fixes; the user owns all mutations.\n\n## Usage Attribution\n\n**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you\nMUST read and follow [Usage Attribution](references\u002Fattribution.md). Prefix\ndirect terminal `gcloud` calls (never generated scripts, Terraform, or user\ncode) with\n`CLOUDSDK_METRICS_REQUEST_ATTRIBUTION=\"agent-skills\u002F1.0 (skill:agent-platform-troubleshooting)\"`\nand append `agent-skills\u002F1.0 (skill:agent-platform-troubleshooting)` to direct\nHTTP\u002FREST\u002FMCP `User-Agent` headers.\n\n## MANDATORY PRE-FLIGHT CHECKLIST (CHECK BEFORE RESPONDING OR CALLING TOOLS)\n\nCRITICAL: Before generating ANY response or calling any tools, evaluate the\nuser's prompt against Rules 1–14. When a Turn-0 rule matches, execute its\ndirective immediately and STOP.\n\n### Rule 1: Out-of-Scope GCP IAM \u002F GCS Queries\nIf the prompt asks about Compute Engine (GCE), Cloud Storage (GCS) buckets, or\ngeneric GCP IAM permissions unrelated to the Agent Platform stack:\n- **IMMEDIATELY DECLINE ON TURN 0. DO NOT CALL ANY TOOLS OR GIVE IAM GUIDES.**\n- Respond: *\"I decline to troubleshoot generic GCP IAM or GCS access issues, as\n  they are out of scope for the Agent Platform Troubleshooting skill.\"*\n\n### Rule 2: Strict Prohibition on Custom Discovery Scripts\nIf asked to write, generate, compile, or execute a custom Python or bash script\nto discover resources (e.g., active Agent Runtime instances):\n- **DO NOT CALL ANY TOOLS OR WRITE\u002FRUN ANY SCRIPTS.**\n- **RESPOND ON TURN 0**: *\"I cannot write or execute custom Python or bash\n  scripts for resource discovery. Custom discovery scripts are prohibited as\n  they consume excessive turns and cause timeouts. Instead, use standard gcloud\n  CLI commands (see [Google Cloud SDK Installation](https:\u002F\u002Fdocs.cloud.google.com\u002Fsdk\u002Fdocs\u002Finstall-sdk.md.txt))\n  or curl REST API calls with application default credentials:\n  `gcloud agent-registry agents list --location=us-central1` or `curl -H \"Authorization: Bearer $(gcloud auth application-default print-access-token)\" \"https:\u002F\u002Fus-central1-aiplatform.googleapis.com\u002Fv1\u002Fprojects\u002FPROJECT_ID\u002Flocations\u002Fus-central1\u002FreasoningEngines\"`\"*\n\n### Rule 3: Consolidated Registry for Google APIs \u002F Design Queries\nIf asked about registering multiple Agent Runtime, Cloud Resource Manager, or\nGoogle API interfaces, or structuring services in Agent Registry:\n- **DO NOT CALL ANY TOOLS. RESPOND ON TURN 0 WITH**:\n  1. Consolidate ALL Google APIs under a single `googleapis` service entry in\n     Agent Registry via `gcloud agent-registry services create googleapis --endpoint-spec-type=no-spec`.\n  2. Explicitly state: *\"Do NOT register each Google API as a separate registry\n     service entry, as separate entries cause resource clutter, complicate IAM\n     policy management, and risk hitting registry quota limits.\"*\n  3. List all 8 required base FQDN interfaces (plus global\n     `https:\u002F\u002Faiplatform.googleapis.com` when calling global Gemini models):\n     - `https:\u002F\u002Fagentregistry.googleapis.com`\n     - `https:\u002F\u002Faiplatform.mtls.googleapis.com`\n     - `https:\u002F\u002Fcloudresourcemanager.mtls.googleapis.com`\n     - `https:\u002F\u002Fiamcredentials.mtls.googleapis.com`\n     - `https:\u002F\u002Ftelemetry.mtls.googleapis.com`\n     - `https:\u002F\u002F{region}-aiplatform.mtls.googleapis.com`\n     - `https:\u002F\u002F{region}-aiplatform.googleapis.com`\n     - `https:\u002F\u002Faiplatform.{region}.rep.googleapis.com`\n  4. Refer to `references\u002Fagent-registry.md` §2 for the full command.\n\n### Rule 4: Cloud Run \u002F Cloud Functions Egress 401\u002F403 (OIDC vs IAP MCP)\nIf an agent gets a `401` or `403` egress error calling an MCP server or tool on\nCloud Run or Cloud Functions:\n- **DO NOT RUN LOG TOOLS. RESPOND ON TURN 0 WITH**:\n  1. Explain that direct Agent Identity (`principalSet:\u002F\u002F...` \u002F `principal:\u002F\u002F...`)\n     to standard Cloud Run OIDC authentication is **not natively supported**.\n  2. Recommend **Service Account impersonation** in agent code to obtain an OIDC\n     ID token, granting **`roles\u002Fiam.serviceAccountTokenCreator`** to the Agent\n     Identity on the target SA (and `roles\u002Frun.invoker` to that SA on Cloud Run).\n  3. Note that for Preview IAP-enabled Cloud Run MCP servers (`--iap\n     --functional-type=mcp-server`, `run.app` short URL), authorize via IAP\u002FUAP\n     instead of `roles\u002Frun.invoker` (see `references\u002Fknown-issues.md` BKI 21 and\n     `references\u002Fagent-identity.md`).\n\n### Rule 5: Telemetry & Monitoring Endpoint Blocks on Startup\nIf Agent Runtime startup crashes (`set_up()`) with connection resets or\nhandshake errors reaching `telemetry.mtls.googleapis.com`:\n- **Evidence**: Explicitly check whether all 4 monitoring\u002Ftracing endpoints are\n  registered as Endpoints in Agent Registry (`gcloud agent-registry endpoints list`):\n  `telemetry.mtls.googleapis.com`, `monitoring.googleapis.com`,\n  `trace.mtls.googleapis.com`, and `cloudtrace.googleapis.com`.\n- **Recommended Fix**:\n  1. Register missing telemetry\u002Ftracing interfaces via `gcloud agent-registry\n     services create --endpoint-spec-type=no-spec` (which projects read-only\n     Endpoints in Agent Registry for `telemetry.mtls.googleapis.com`,\n     `monitoring.googleapis.com`, `trace.mtls.googleapis.com`, and\n     `cloudtrace.googleapis.com`).\n  2. Create or update an **`AuthorizationPolicy`** (`AuthzPolicy` \u002F IAP \u002F UAP)\n     bound to the Gateway that allows the agent's principal set (identity) to\n     access the telemetry endpoints (see `references\u002Fknown-issues.md` BKI 23).\n\n### Rule 6: IAP Denial Troubleshooting (`403` \u002F `Egress request is not authorized`)\nWhen logs or symptoms show `403` \u002F `Egress request is not authorized` via IAP:\n1. **Check IAP Egressor bindings on the registry entry FIRST** (`roles\u002Fiap.egressor`\n   via `gcloud iap web get-iam-policy --resource-type=agent-registry` bound to\n   the server-generated child UUID from `registryResource`, not `SERVICE_NAME`).\n2. **Create a registry entry** (`gcloud agent-registry services create`) if none\n   exists for the exact target hostname.\n3. **Grant `roles\u002Fiap.egressor`** on the registry entry (IAM v1 — `set-iam-policy` requires top-level `{\"bindings\": [...]}` JSON without a `\"policy\"` wrapper) or verify UAP\n   `AccessPolicy` + CRM `PolicyBinding` (`iapPolicyVersion: \"V2\"`,\n   `iap.googleapis.com\u002Fresources.egressViaIAP`; see `references\u002Fpolicies.md` §2).\n4. **Check IAP audit logs** (`protoPayload.serviceName=\"iap.googleapis.com\"`)\n   and verify an `AuthorizationPolicy` (`AuthzPolicy`) is bound to the Gateway.\n5. **Explicitly warn**: *\"Do NOT use `roles\u002Fiap.tunnelResourceAccessor` (which\n   is for classic IAP TCP tunneling to GCE VMs, not Agent Gateway egress) and do\n   NOT bypass IAP authentication.\"*\n\n### Rule 7: PSC Subnet Exhaustion Speed Rule (`PROVISIONING` Hang)\nWhen diagnosing gateway provisioning stuck or failing on subnet IP exhaustion:\n- **DO NOT loop across regions.** Run ONLY in the target region (default `us-central1`):\n  1. `gcloud network-services agent-gateways list --location=us-central1`\n  2. `gcloud network-services agent-gateways describe \u003CGW> --location=us-central1`\n  3. `gcloud compute network-attachments describe \u003CNA> --region=us-central1`\n  4. `gcloud compute networks subnets describe \u003CSUBNET> --region=us-central1`\n- Check free IP count (`Usable - Allocated = Free`) **before** recommending any\n  Network Attachment deletion; flag that a `\u002F28` subnet is easily exhausted and\n  recommend expanding the CIDR range to at least `\u002F26` (`known-issues.md` BKI 19).\n\n### Rule 8: Multi-Region Manual Registration Prohibition (`us` \u002F `eu`)\nIf asked about manually registering endpoints or services in `us` or `eu`:\n- **DO NOT CALL ANY TOOLS. RESPOND ON TURN 0**:\n  1. *\"Manual endpoint\u002Fservice registration is NOT supported in `us` or `eu`\n     multi-region locations (`us` and `eu` are read-only roll-up locations for\n     auto-discovered resources).\"* (Explicitly name BOTH `us` and `eu`.)\n  2. *\"Register manually in a specific region (e.g., `us-central1`) or `global`.\"*\n\n### Rule 9: VPC Service Controls (VPC-SC) Perimeter & ACT `ALL_TRAFFIC`\nWhen diagnosing VPC-SC perimeter blocks or external API hangs under VPC-SC:\n1. Identify a **VPC Service Controls perimeter block** \u002F boundary enforcement.\n2. Check that the Agent Connectivity Template (ACT) sets **`vpcEgress:\n   ALL_TRAFFIC`** (native VPC-SC creation works out of the box since Sept 8,\n   2026 when `vpcEgress: ALL_TRAFFIC` is set) and that **Cloud NAT** is\n   configured on the consumer VPC's PSC-I network attachment subnet.\n3. For legacy or strict custom perimeters blocking Google actuation identities,\n   recommend creating **ingress policies** allowing:\n   - `actuation-a@networkservices-prod.iam.gserviceaccount.com`\n   - `cloud-aiplatform-pipeline-robot-prod@system.gserviceaccount.com`\n4. Explicitly state: *\"Do NOT disable VPC Service Controls or delete perimeters.\"*\n   Refer to `references\u002Fknown-issues.md` BKI 18 & 28.\n\n### Rule 10: UAP Policy Binding Org Policy Blocker & Blanket `DENY` Crash\n- **`CUSTOM_ORG_POLICY_VIOLATION` on `gcloud iam policy-bindings create`**:\n  Caused by **`constraints\u002Fiam.managed.disableAccessPolicyBinding`** (note: some\n  docs misspell this plural). Apply an Org Policy override (`enforce: false`) at\n  the target resource and wait **30 to 60 seconds** for IAM propagation (BKI 24).\n- **Startup crash after UAP `destination.is_registered == false` `DENY`**:\n  Explain that the blanket `DENY` blocked internal\u002Funauthenticated SDK bootstrap\n  and metadata calls (such as Cloud Resource Manager project lookups) during\n  Reasoning Engine init; remove or scope the blanket `DENY` rule (BKI 5).\n\n### Rule 11: Agent Gateway Dual-Registry & Jurisdiction Invariants\nWhen configuring or validating `registries` on an Agent Gateway:\n1. An Agent Gateway supports a **maximum of two registries**.\n2. When two registries are configured, **exactly one must be `global`** and the\n   other must be **`regional` or `multi-regional`**.\n3. Binding two regional registries (e.g., `us-central1` + `europe-west1`), two\n   multi-regionals, two globals, or a mismatched jurisdiction (e.g., `us-central1`\n   gateway + `eu` registry) is invalid and rejected with an **HTTP 400**\n   validation error (`references\u002Fagent-gateway.md` §4, BKI 26).\n\n### Rule 12: Cross-Project Runtime-to-Gateway Binding Diagnosis\nWhen Reasoning Engine in Project 1 fails to bind to a Gateway in Project 2:\n1. **Deploying Identity**: Needs `networkservices.agentGateways.use` and\n   `networkservices.agentGateways.get` (or `roles\u002Fnetworkservices.viewer`) in Project 2.\n2. **Vertex AI Service Agent**: Grant `roles\u002Fnetworkservices.viewer` or custom\n   role `ae_agw_cross_project_sa` (alias `ar_agw_cross_project_sa`) to\n   `service-PROJECT_1_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com` in Project 2.\n3. **Regional Colocation**: Verify both runtime and gateway are in the **same region**.\n4. **CAA Opt-Out**: Set `GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES`\n   to `False` (`references\u002Fknown-issues.md` BKI 10, `references\u002Fagent-gateway.md` §11).\n\n### Rule 13: Downstream SWP + PBR vs. Explicit Forward HTTPS Proxy\nDistinguish the two supported consumer-VPC proxy architectures:\n- **Pattern A — Transparent Next-Hop SWP + PBR** (no client `HTTPS_PROXY` needed):\n  1. Explain that **PSC endpoints cannot be route next-hops**, **SWP behind PSC\n     Service Attachments only supports explicit proxy mode (not transparent\n     next-hop mode)**, and **static routes cannot be used because Network\n     Attachments cannot have VM network tags**.\n  2. Deploy SWP directly in the consumer VPC with `type: SECURE_WEB_GATEWAY` and\n     `routingMode: NEXT_HOP_ROUTING_MODE` on an internal IP on the PSC-I subnet\n     (e.g., `10.20.1.250`), with a `\u002F26` `REGIONAL_MANAGED_PROXY` `ACTIVE` subnet.\n  3. Configure **Policy-Based Routing (PBR)** matching source CIDR `10.20.1.0\u002F24`\n     to `--next-hop-ilb-ip=10.20.1.250` (priority 200) + fallback PBR (1000).\n  4. Create **Cloud NAT with `ENDPOINT_TYPE_SWG`** (`nats create ... --endpoint-types=ENDPOINT_TYPE_VM,ENDPOINT_TYPE_SWG`),\n     and allowlist `\u003Cregion>-aiplatform.mtls.googleapis.com` in SWP CEL (BKI 33).\n- **Pattern B — Explicit Forward HTTPS Proxy (`HTTPS_PROXY` + L4 `AuthzPolicy`)**:\n  1. Without L4 bypass, `HTTPS_PROXY=https:\u002F\u002Fproxy.corp.internal:443` fails on\n     `HTTP CONNECT` with **HTTP `404`** because Agent Gateway's L7 HTTP manager\n     terminates TLS and rejects nested `CONNECT`.\n  2. Import a **`v1beta1`** L4 `AuthzPolicy` via **`gcloud beta network-security\n     authz-policies import`** with `action: ALLOW` and `networkRules` matching\n     `to.operations[].snis` (omit `target.loadBalancingScheme` and `ports`; max 5 rules;\n     omit `from` or include `7.0.0.0\u002F8` + PSC-I CIDR in `from.sources[].ipBlocks`).\n  3. Listen with TLS on `:443`, allow the consumer PSC-I subnet CIDR on VPC firewall\u002Fproxy ACLs (never `7.0.0.0\u002F8`),\n     set `NO_PROXY`\u002F`no_proxy` to `.googleapis.com,googleapis.com,metadata.google.internal,169.254.169.254,localhost,127.0.0.1`,\n     bundle `agentGatewayCard.rootCertificates` + Private CA in container env\n     vars (`SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`), and warn L4 `ALLOW` bypasses\n     L7 IAP\u002FUAP, Model Armor, SGP, and `httpRules` for matched SNIs (BKI 34).\n\n### Rule 14: DNS Peering, `TrustConfig`, Model Armor, SGP, MCP, Identity, & Lifecycle\n- **DNS Peering & Service Agent**: Public FQDNs resolve via public recursive DNS.\n  Private DNS requires `dnsPeeringConfig` (`domains` array with trailing `.`; ACT\n  uses string `targetNetwork` only, whereas inline `AgentGateway.networkConfig.dnsPeeringConfig`\n  also requires `targetProject`). Cloud DNS caps total peering hops at **2**\n  (Gateway consumes Hop 1 → max 1 consumer peering hop; a 2nd hop fails preflight\n  or returns `SERVFAIL` → `503`, BKI 35). Grant `roles\u002Fdns.peer`, `roles\u002Fdns.reader`,\n  `roles\u002Fcompute.networkViewer`, and `roles\u002Fcompute.networkUser` to\n  `service-GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com`\n  (and `compute.networkAttachments.use` to caller, BKI 9). Never use authoritative `\".\"` private root zones (`\".\"` requires a Cloud DNS Private Forwarding Zone).\n- **Private CA `TrustConfig` & Immutable ACT**: Set `egressNetworkConfig.tlsConfig.trustConfig`\n  **with `additionalRoots: PUBLICLY_TRUSTED_ROOTS`** (omitting breaks `*.googleapis.com`).\n  ACT fields are immutable — create a new ACT and rebind via `PATCH` with\n  `updateMask=agentConnectivityTemplate` (BKI 6).\n- **Model Armor (`CONTENT_AUTHZ`)**: Ingress (`CLIENT_TO_AGENT`, max 1, ADK\n  `streamQuery` only) uses `service-AGENT_PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com`;\n  Egress (`AGENT_TO_ANYWHERE`, max 4) uses `service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com`.\n  Scope `httpRules` `when` to exclude gRPC and streams **>60 seconds** (`Stream removed`, BKI 13).\n- **Semantic Governance Policies (SGP)**: Uses `gcp-sa-aiplatform`, non-streaming\n  LLM calls only, `.contains()` + `!request.headers['content-type'].startsWith('application\u002Fgrpc')`\n  in `when`, and full-map updates on `PATCH ?updateMask=metadata` so\n  `sgpEnforcementMode: \"DRY_RUN\"` and `sgpUserIntentMatching` are preserved (BKI 38).\n- **Native MCP, Identity, Trace, & Teardown**: Set `baseProtocolMethodsOption:\n  MATCH_BASE_PROTOCOL_METHODS` on MCP `ALLOW` rules (BKI 39). Orgless trust\n  domains use `agents.global.proj-PROJECT_NUMBER.system.id.goog` (`proj-`, never\n  `project-`); never grant `roles\u002Faiplatform.expressUser` or project-wide\n  `roles\u002Faiplatform.user` to Agent Identities. For Cloud Trace (`TelemetryPolicy`),\n  always recommend enabling `cloudtrace.googleapis.com` (`gcloud services enable cloudtrace.googleapis.com`)\n  and granting `roles\u002Fcloudtrace.agent` to `compute-system`, `gcp-sa-networksecurity`,\n  and `gcp-sa-agentgateway` (see `references\u002Fagent-gateway.md` §8.3 and `references\u002Ffield-manual.md` Step 14.4). Tear down in strict 7-step order\n  (workloads → UAP bindings → `AuthzPolicy` → extensions → `AgentGateway` → ACT →\n  VPC) and use unique gateway IDs if deletion tombstones collide (BKIs 25, 30).\n\n## Quick Symptom Triage Matrix\n\n| Symptom \u002F Error | Primary Suspect | Reference |\n| :--- | :--- | :--- |\n| `403` \u002F `Egress request is not authorized` | Unregistered FQDN, missing `roles\u002Fiap.egressor` \u002F UAP binding, or PAB | Rules 4, 6; `references\u002Fpolicies.md` §2; BKIs 4, 7, 8, 15 |\n| `HTTP 404` on `HTTP CONNECT` (`HTTPS_PROXY`) | Missing `gcloud beta` L4 `AuthzPolicy` (`networkRules` `snis`) | Rule 13B; `references\u002Fagent-gateway.md` §6.3; BKI 34 |\n| `HTTP 498` immediately after binding runtime | Enforcing gateway bound before allowlisting essential platform APIs | `references\u002Fagent-gateway.md` §2; BKI 37 |\n| `500` \u002F `PERMISSION_DENIED` \u002F `Stream removed` | Model Armor SA roles (`gcp-sa-dep` vs `gcp-sa-aiplatform-re`) or 60s stream cap | Rule 14; `references\u002Fpolicies.md` §12; BKI 13 |\n| `503` \u002F `NXDOMAIN` \u002F `SERVFAIL` on private host | >2-hop DNS peering, authoritative `\".\"` zone, Packet Intercept, or SWP | Rules 13A, 14; `references\u002Fagent-gateway.md` §3, §6; BKIs 33, 35, 36 |\n| `Config validation failed` \u002F `PERMISSION_DENIED` on import | Disabled `agentregistry.googleapis.com`, missing caller\u002F`gcp-sa-agentgateway` IAM, or bad NA URI | Rule 14; BKIs 9, 20, 26 |\n| `HTTP 409 ABORTED` \u002F `400 already being used` | Active control-plane LRO mutex (~2 min), tombstone collision, or reverse teardown | `references\u002Fagent-gateway.md` §9, §10; BKIs 25, 29, 30 |\n| Startup crash (`reasoning_engine_stderr`) | Blocked telemetry\u002FCRM bootstrap, UAP blanket `DENY`, or SGP gRPC interception | Rules 5, 10, 14; BKIs 1, 5, 17, 23, 38 |\n\n## When to use this skill\n\nTrigger on Agent Gateway, Agent Connectivity Templates (ACT), Agent Registry,\nAgent Identity, IAP\u002FUAP policies, Model Armor, Semantic Governance Policies\n(SGP), SWP\u002FExplicit Proxy egress, Private CA `TrustConfig`, Cloud DNS peering,\nCloud Trace `TelemetryPolicy`, or Gemini Enterprise \u002F Agent Runtime \u002F GKE \u002F\nCloud Run gateway bindings. Do **not** use for generic Google Cloud IAM, GCS,\nGCE, or networking issues unrelated to the Agent Platform stack.\n\n## Required context & Hypothesis Rules\n\nGather `PROJECT_ID`, `PROJECT_NUMBER`, `LOCATION` (default `us-central1`),\n`AGENT_ID`, `AGENT_GATEWAY_NAME`, Agent Identity (`principal:\u002F\u002F` or\n`principalSet:\u002F\u002F`), exact error + timestamp, and target destination. If missing,\nask or state unknowns using placeholders — never scan across projects or loop\nover regions. Before Step 1 queries, formulate **at most 3 hypotheses** anchored\nto *\"Why did it start failing now?\"* (e.g., recent Terraform\u002Fconfig changes).\n\n## Diagnostic flow\n\nFollow in order (copy-paste commands in `references\u002Ffield-manual.md`):\n- **Step 0 — Pre-Flight & Access**: Evaluate Rules 1–14. Verify project access\n  (`gcloud projects describe $PROJECT_ID`).\n- **Step 1 — Agent & Startup Logs**: Classify error (`403`, `404 CONNECT`, `498`,\n  `500`, `503`, crash, timeout). Check PSC subnet IPs, ACT `ALL_TRAFFIC` + Cloud\n  NAT, and `agentGatewayCard.rootCertificates` CA trust.\n- **Step 2 — Gateway Logs**: Query `networkservices.googleapis.com\u002FGateway`\n  (filtering `-httpRequest.requestMethod=\"CONNECT\"` when inspecting L7 requests)\n  to find the exact failing SNI\u002Fhostname and `serviceExtensionsInfo`.\n- **Step 3 — IAP \u002F Model Armor \u002F SGP Logs**: Check `iapPolicyVersion` (`V1` vs\n  `V2`), `DRY_RUN` vs enforced, Model Armor callout status, or\n  `logs\u002Fsemantic-governance-policy` verdicts and rationales.\n- **Step 4 — Registry State**: Verify exact hostname permutations in\n  `gcloud agent-registry {services,endpoints,mcp-servers,agents} list` and\n  confirm dual-registry + jurisdiction rules.\n- **Step 5 — Identity & Policies**: Check `roles\u002Fiap.egressor` via\n  `--resource-type=agent-registry` on the child UUID (V1), UAP\n  `AccessPolicy`\u002F`PolicyBinding` + `constraints\u002Fiam.managed.disableAccessPolicyBinding`\n  (V2), PAB overrides, and least-privilege Agent Identity roles (`proj-` for orgless).\n- **Step 6 — AuthzPolicy & Extensions**: Verify L4 `networkRules` vs L7\n  `httpRules`, MCP `MATCH_BASE_PROTOCOL_METHODS`, Model Armor \u002F SGP `when`\n  exclusions, `ExtensionBinding` scope, and policy caps (max 4 egress, max 1 ingress `CONTENT_AUTHZ`).\n- **Step 7 — Connectivity, DNS, & TLS**: Verify ACT `TrustConfig`\n  (`PUBLICLY_TRUSTED_ROOTS`), `gcp-sa-agentgateway` IAM, \u003C=2 DNS peering hops,\n  no Packet Intercept on the consumer VPC, and SWP\u002FExplicit Proxy settings.\n- **Step 8 — PrincipalSet & Trace Verification**: Test 1:1 `principal:\u002F\u002F`\n  binding if `principalSet:\u002F\u002F` lags; for Cloud Trace, enable `cloudtrace.googleapis.com`, verify `v1beta1` `TelemetryPolicy` (`telemetryTarget` referencing `agentGateways\u002F*` and object `parentBasedSampling: {enabled: true, samplingRate: 1.0}`, never string `ENABLED`), and grant `roles\u002Fcloudtrace.agent` to `service-\u003CPROJECT_NUMBER>@compute-system.iam.gserviceaccount.com`, `service-\u003CPROJECT_NUMBER>@gcp-sa-networksecurity.iam.gserviceaccount.com`, and `service-\u003CPROJECT_NUMBER>@gcp-sa-agentgateway.iam.gserviceaccount.com`.\n\n## Tools & Layered References\n\nUse `mcp__gcloud__run_gcloud_command` (or `gcloud --quiet`),\n`mcp__gcloud-observability__list_log_entries` (or `gcloud logging read`),\n`mcp__google-dev-knowledge__search_documents` \u002F `get_documents` \u002F `answer_query`,\nand `curl` REST GETs, plus bundled references (load only the smallest set needed):\n- [references\u002Ffield-manual.md](references\u002Ffield-manual.md) — read first for operational commands & log queries\n- [references\u002Fknown-issues.md](references\u002Fknown-issues.md) — BKIs #1–#13, #15–#39 for fast pattern matches\n- [references\u002Fagent-gateway.md](references\u002Fagent-gateway.md) — topologies, ACT, DNS, TLS, SWP\u002FExplicit Proxy, Trace, teardown\n- [references\u002Fpolicies.md](references\u002Fpolicies.md) — L4\u002FL7 `AuthzPolicy`, MCP, UAP v3beta, Model Armor, SGP\n- [references\u002Fagent-registry.md](references\u002Fagent-registry.md) — `services` vs projected `endpoints`, 9 API families, jurisdictions\n- [references\u002Fagent-identity.md](references\u002Fagent-identity.md) — 3-identity delegation, Cloud Run OIDC vs IAP MCP, WIF\n\n## Output report\n\nAlways produce a read-only diagnostic report using this exact structure:\n\n```markdown\n# Agent Platform Diagnostic — \u003Cone-line summary>\n\n## Context\n- Project: \u003Cid> (\u003Cnumber>) | Location: \u003Cregion>\n- Agent: \u003Cagent_id> | Gateway: \u003Cgateway_name>\n- Symptom: \u003Cexact error message and when it started>\n\n## Evidence gathered\n- Agent log query: \u003Cfilter, summary>\n- Gateway log query: \u003Cfilter, exact failing hostname \u002F extension status>\n- IAP \u002F Policy log query: \u003Cfilter, decision + enforcement mode>\n- Registry & Policy state: \u003Centries, AuthzPolicy bindings, roles\u002Fiap.egressor or UAP>\n\n## Root cause hypothesis\n\u003Cranked root cause(s)>\n\n## Why this fits the evidence\n\u003Cconnect log\u002Fconfig evidence to root cause>\n\n## Recommended fix\n\u003Cordered gcloud \u002F curl \u002F YAML \u002F Terraform changes for the user to apply>\n\n## What to verify after the fix\n\u003Cverification queries>\n\n## Open questions \u002F unknowns\n\u003Cmissing context or unverified items>\n\n## Appendix: Raw Logs & Verified Links\n- **Cloud Logging Filter**: \u003Cexact copy-pasteable filter or deep link>\n- **Raw Logs**: \u003Cuntruncated Agent, Gateway, and IAP\u002FPolicy log entries>\n```\n\n## Principles\n\n- **Exact hostname match first**: Compare gateway log hostnames directly against Agent Registry.\n- **Layered default-deny**: Registry → Gateway `AuthzPolicy` → Extension → IAP\u002FUAP\u002FModel Armor\u002FSGP → PAB (PAB overrides IAM Allow).\n- **L4 bypass vs L7 governance**: L4 `networkRules` enables `HTTP CONNECT` explicit proxies (`:443`) but bypasses L7 IAP, Model Armor, and SGP for matched SNIs.\n- **Read-only, single-region, non-interactive**: Pull evidence first, never mutate resources, check `us-central1` unless logs indicate otherwise, and pass `--quiet`.\n\n## Supporting Links\n\n- [Agent Gateway Overview](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fagent-gateway-overview.md.txt)\n- [Configure VPC Connectivity & DNS](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fset-up-vpc-connectivity.md.txt)\n- [Delegate Authorization & MCP](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fdelegate-authorization.md.txt)\n- [Configure Model Armor](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fconfigure-model-armor.md.txt)\n- [Configure Semantic Governance](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fpolicies\u002Fconfigure-semantic-governance.md.txt)\n- [Monitor & Trace Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fgovern\u002Fgateways\u002Fmonitor-agent-gateway.md.txt)\n- [Deploy Agent Gateway Runtime](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Fscale\u002Fruntime\u002Fagent-gateway-runtime-deploy.md.txt)\n- [Troubleshoot Agent Gateway](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Ftroubleshooting\u002Ftroubleshoot-agent-gateway.md.txt)\n- [Troubleshoot IAM Policies (UAP)](https:\u002F\u002Fdocs.cloud.google.com\u002Fgemini-enterprise-agent-platform\u002Ftroubleshooting\u002Ftroubleshoot-iam-policies-uap.md.txt)\n",{"name":5,"metadata":50,"description":7},{"version":51,"category":52},"1.1.1","AiAndMachineLearning","main","cb11c49ce1076788d69115a9f001b07b4ba0b616","skills\u002Fcloud\u002Fagent-platform-troubleshooting",2002,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills","https:\u002F\u002Fgithub.com\u002Fgoogle","https:\u002F\u002Fopensource.google\u002F","Google ❤️ Open Source","2026-11-13 02:42:47",{"source":8,"skillName":5,"commands":63,"prompt":73,"zipAvailable":74},[64,67,70],{"tool":65,"command":66},"npx","npx skills add google\u002Fskills --skill agent-platform-troubleshooting",{"tool":68,"command":69},"bunx","bunx skills add google\u002Fskills --skill agent-platform-troubleshooting",{"tool":71,"command":72},"pnpm","pnpm dlx skills add google\u002Fskills --skill agent-platform-troubleshooting","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002FSKILL.md",true,[76,82,86,90,94,98,102],{"path":77,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":80,"sourceHtmlUrl":81},"references\u002Fagent-gateway.md","REFERENCE","参考文档",56554,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002Freferences\u002Fagent-gateway.md",{"path":83,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":84,"sourceHtmlUrl":85},"references\u002Fagent-identity.md",34397,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002Freferences\u002Fagent-identity.md",{"path":87,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Fagent-registry.md",50926,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002Freferences\u002Fagent-registry.md",{"path":91,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Fattribution.md",1938,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002Freferences\u002Fattribution.md",{"path":95,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Ffield-manual.md",69938,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002Freferences\u002Ffield-manual.md",{"path":99,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":100,"sourceHtmlUrl":101},"references\u002Fknown-issues.md",89712,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002Freferences\u002Fknown-issues.md",{"path":103,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":104,"sourceHtmlUrl":105},"references\u002Fpolicies.md",77022,"https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fagent-platform-troubleshooting\u002Freferences\u002Fpolicies.md",[107,139,168,197,224,248],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":119,"publishedAt":45},"01M6998S2EZKD3GEJ7F943RZTE","sign-in-with-google-web","Implement, configure, and secure Sign In With Google (SiwG) using Google Identity Services (GIS \u002F `https:\u002F\u002Faccounts.google.com\u002Fgsi\u002Fclient`) across web architectures. Use when creating Google sign-in buttons, implementing Google One Tap with FedCM, integrating GIS in React\u002FNext.js\u002FAngular\u002FHTML, verifying ID tokens on backend runtimes (Python\u002FNode.js\u002FGo\u002FJava), enforcing Google Workspace domain restrictions (`hd`), securing client-side ID tokens via WebCrypto nonces or encrypted IndexedDB, embedding in cross-origin iframes via the Intermediate Iframe API (`https:\u002F\u002Faccounts.google.com\u002Fgsi\u002Fintermediate`), configuring Content Security Policy (CSP), COOP, and Permissions Policy (`identity-credentials-get`) headers, or handling sign-out and revocation. Don't use for legacy Google Sign-In (`gapi.auth2`), Google Cloud IAM service accounts, or Android\u002FiOS native Credential Manager.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fidentity\u002Fsign-in-with-google-web\u002FSKILL.md",[113,116],{"categoryNo":114,"categoryName":115,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000009","前端开发",{"categoryNo":117,"categoryName":118,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",[9,120,121,122,123,124,125,126,127,42,128,129,130,131,132,28,133,134,40,135,41,136,137,138],"sign in with google web","sign","with","web","android","go","security","google workspace","implement","policy","python","implementing","react","permissions","buttons","manager","architectures","domain","runtimes",{"skillNo":140,"name":141,"nameZh":6,"description":142,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":143,"categories":144,"keywords":152,"publishedAt":45},"01M6998PHPDCAD684VW5WRG83D","dpop-adoption","Implement and debug OAuth 2.0 DPoP (RFC 9449) refresh token sender-constraining for WebCrypto, Node.js ES6, and browser runtimes integrating with Google's OAuth platform. Use when configuring non-extractable asymmetric key pairs (P-256), generating DPoP Proof JWTs for authorization code exchange and token refresh, or handling 400 use_dpop_nonce challenge retry loops at oauth2.googleapis.com\u002Ftoken. Don't use for unconstrained OAuth 2.0 flows (where refresh tokens are not bound to a client key pair), or for Google Cloud IAM \u002F service account authentication.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fidentity\u002Fdpop-adoption\u002FSKILL.md",[145,146,147],{"categoryNo":117,"categoryName":118,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":148,"categoryName":149,"taxonomyType":150,"taxonomyTypeDesc":151},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[153,154,9,42,155,156,157,158,159,160,28,161,162,163,164,165,166,41,138,26,167],"dpop adoption","adoption","es6","retry","authentication","flows","challenge","code","browser","loops","at","node","token","pair","when",{"skillNo":169,"name":170,"nameZh":6,"description":171,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":172,"categories":173,"keywords":180,"publishedAt":45},"01M6998M72TC73EEAQH4XC7EXW","retrieving-developer-knowledge","Searches, retrieves, and synthesizes official Google developer documentation across Google Cloud, AI\u002FGemini, Android, Chrome, Web, Flutter, Go, Firebase, and other Google developer platforms. Integrates with the Developer Knowledge MCP server (search_documents, get_documents, answer_query) or the Developer Knowledge REST API fallback. Use when searching for gcloud CLI commands, API syntax, IAM permissions, official documentation, architectural comparisons, or product choice overviews. Don't use for local filesystem lookups or non-Google documentation.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fdevelopers\u002Fretrieving-developer-knowledge\u002FSKILL.md",[174,175,178,179],{"categoryNo":117,"categoryName":118,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":176,"categoryName":177,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":148,"categoryName":149,"taxonomyType":150,"taxonomyTypeDesc":151},[181,182,183,184,42,185,186,187,188,189,190,191,192,167,193,194,195,28,196,133],"retrieving developer knowledge","knowledge","developer","MCP","mcp server","official","developer documentation","get","search","local","choice","documents","query","api","across","documentation",{"skillNo":198,"name":199,"nameZh":6,"description":200,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":201,"categories":202,"keywords":203,"publishedAt":45},"01M6998J2CZEXS9BES9S3WWFKC","migrate-to-rust","Clones, analyzes, plans, and migrates legacy codebases (C++, Fortran, Java, Python, C, Shell) from a GitHub URL or local directory to a modern, high-performance, deterministic, 100% Safe Rust architecture, tracking live telemetry across every task bucket, test failure\u002Ffix cycle, and Profile-Guided Optimization (PGO) stage, and producing a first-person AI storytelling report and interactive HTML infographic. Use when migrating a GitHub repository or local codebase to Rust, porting legacy C++, Fortran, Python, or Java workloads to memory-safe Rust, designing Struct-of-Arrays (SoA) or SIMD Rust architectures, or optimizing Rust ports with LLVM PGO. Don't use for unrelated non-Rust refactoring or single-line syntax questions.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fdevelopers\u002Fmigrate-to-rust\u002FSKILL.md",[],[204,205,206,207,208,209,210,211,130,212,213,214,215,216,217,190,218,219,220,167,221,222,195,223],"migrate to rust","rust","migrate","github","memory","performance","directory","safe","ports","llvm","soa","cycle","porting","fix","arrays","infographic","high-performance","URL","architecture","unrelated",{"skillNo":225,"name":226,"nameZh":6,"description":227,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":228,"categories":229,"keywords":233,"publishedAt":45},"01M6998GCC3K29WZ82KXMB9E02","finding-google-skills","Google platform decision and setup guidance, loaded on demand from Google's skill catalog. Use when a developer is choosing or setting up part of their stack, such as where to run a service, a database, storage, messaging, authentication, analytics, ads, or AI model serving, and a Google product is a reasonable candidate - whether or not a vendor is named - or when a request names a Google product or API. Brings in the matching Google skill so the answer can weigh Google options, their trade-offs, and when they are not the right fit. Skip when the stack is already settled on another provider and no Google product is named, or the task involves no platform choice.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fdevelopers\u002Ffinding-google-skills\u002FSKILL.md",[230,231,232],{"categoryNo":117,"categoryName":118,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":148,"categoryName":149,"taxonomyType":150,"taxonomyTypeDesc":151},[9,234,235,236,237,26,238,239,240,241,242,157,243,244,245,191,33,246,167,247,194],"finding google skills","storage","as","messaging","model","trade-offs","provider","answer","fit","catalog","up","decision","database","candidate",{"skillNo":249,"name":250,"nameZh":6,"description":251,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":252,"categories":253,"keywords":256,"publishedAt":45},"01M6998DWNHTH0BS6W1CY8ZXMP","workload-manager-basics","Use this skill to manage Google Cloud Workload Manager evaluations, rules, scanned resources, and validation results by using public client libraries and the REST API. Use when you need to inspect workload best-practice rules, create and run evaluations for Google Cloud general best practices, SAP, SQL Server, or custom organizational rules, review violations, export results to BigQuery, or automate Workload Manager through client libraries because no service-specific public CLI or MCP server is available. Don't use for general Google Compute Engine instance management, VPC configuration, or standard IAM auditing.","https:\u002F\u002Fgithub.com\u002Fgoogle\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcloud\u002Fworkload-manager-basics\u002FSKILL.md",[254,255],{"categoryNo":117,"categoryName":118,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[257,258,135,259,9,184,260,42,185,261,262,263,264,167,265,194,28,266,267,268,269],"workload manager basics","workload","basics","cli","review","vpc","resources","inspect","you","create","libraries","server","run"]