# How to Troubleshoot Agent Platform Issues Using the `agent-platform-troubleshooting` Skill

> Troubleshoot Agent Platform issues with the agent-platform-troubleshooting skill. Get step-by-step gcloud and curl commands for root-cause analysis without executing any commands.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-09-05

---

**The `agent-platform-troubleshooting` skill is a read-only diagnostic process that guides you through root-cause analysis of Gemini Enterprise Agent Platform failures by telling you exactly which `gcloud` and `curl` commands to run, without executing any commands itself.**

When issues arise in the **Gemini Enterprise Agent Platform**—spanning Agent Gateway, Agent Registry, Agent Identity, IAP-delegated authorization, or Model Armor—the `agent-platform-troubleshooting` skill provides a structured, evidence-based approach to identify root causes. This skill, maintained in the [`google/skills`](https://github.com/google/skills) repository, contains no executable code; it delivers precise diagnostic instructions that you run manually in your environment.

## What the `agent-platform-troubleshooting` Skill Covers

The skill addresses failures such as `403 Egress request is not authorized` or `500 Internal Server Error` from Agent Runtimes. Its knowledge base resides in seven core files within `skills/cloud/agent-platform-troubleshooting/`:

| Component | Purpose | Source File |
|-----------|---------|-------------|
| **Skill definition** | Master flow, pre-flight rules, and diagnostic template | [[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/SKILL.md) |
| **Field manual** | Concrete `gcloud`/`curl` commands for each step | [[`references/field-manual.md`](https://github.com/google/skills/blob/main/references/field-manual.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/field-manual.md) |
| **Known issues** | Symptom-to-resolution mappings (e.g., BKI 21) | [[`references/known-issues.md`](https://github.com/google/skills/blob/main/references/known-issues.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/known-issues.md) |
| **Agent registry** | FQDN interface requirements and consolidated `googleapis` service | [[`references/agent-registry.md`](https://github.com/google/skills/blob/main/references/agent-registry.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/agent-registry.md) |
| **Policies** | Required IAM roles and AuthorizationPolicy specs | [[`references/policies.md`](https://github.com/google/skills/blob/main/references/policies.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/policies.md) |
| **Agent identity** | Principal-set IDs and token-creator roles | [[`references/agent-identity.md`](https://github.com/google/skills/blob/main/references/agent-identity.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/agent-identity.md) |
| **Agent gateway** | Gateway-specific log filters and troubleshooting hints | [[`references/agent-gateway.md`](https://github.com/google/skills/blob/main/references/agent-gateway.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/agent-gateway.md) |

## Pre-Flight Validation Before Troubleshooting Agent Platform Issues

Every diagnostic session begins with mandatory checks defined in [[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/SKILL.md). The skill **refuses** requests that match disallowed scenarios:

- Generic GCP IAM troubleshooting outside Agent Platform scope
- Custom discovery scripts not using official `gcloud` commands
- Multi-region manual registration workflows
- Requests requiring command execution on your behalf

If your issue falls outside Agent Platform boundaries, the skill directs you to appropriate Google Cloud documentation rather than proceeding with an invalid diagnostic path.

## Required Context for Agent Platform Troubleshooting

According to [[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/SKILL.md), you must provide these fields before analysis begins:

- `PROJECT_ID` and `PROJECT_NUMBER`
- `LOCATION` (region)
- `AGENT_ID`
- `AGENT_GATEWAY_NAME`
- Agent service-account principal
- Exact error message
- Target hostname

Missing fields are flagged in the final diagnostic report, ensuring complete evidence gathering.

## The 8-Step Diagnostic Flow for Agent Platform Issues

The `agent-platform-troubleshooting` skill follows this deterministic sequence, stopping when a plausible root cause emerges:

### Step 1: Form Hypotheses (Maximum 3)

Based on recent changes—such as a Terraform apply—identify likely causes: missing IAM binding, hostname mismatch, or PSC subnet exhaustion.

### Step 2: Query Agent Runtime Logs

Use [[`field-manual.md`](https://github.com/google/skills/blob/main/field-manual.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/field-manual.md) commands to examine Agent Runtime logs. Connection errors trigger Step 3c (PSC subnet investigation); container crashes route to runtime health checks.

```bash

# Query Agent runtime logs for 403 errors

gcloud logging read 'resource.type="k8s_container" \
  AND resource.labels.project_id=$PROJECT_ID \
  AND labels."agent.googleapis.com/agent_id"="$AGENT_ID" \
  AND textPayload:"403"' \
  --project=$PROJECT_ID --limit=20 --format=json

```

### Step 3: Inspect Gateway Logs

Pull gateway entries containing the **exact failing hostname**—the `#1 cause` of authorization failures per the skill's internal prioritization.

```bash

# Gateway logs for PERMISSION_DENIED entries

gcloud logging read 'resource.type="gateway" \
  AND resource.labels.location=$LOCATION \
  AND textPayload:"PERMISSION_DENIED"' \
  --project=$PROJECT_ID --limit=10 --format=json

```

### Step 4: Verify IAP Audit Logs

Confirm whether IAP operates in **DRY_RUN** or **ENFORCED** mode, validating the decision outcome (`ALLOW` or `DENY`).

```bash

# IAP audit logs for egress authorization failures

gcloud logging read 'protoPayload.serviceName="iap.googleapis.com" \
  AND protoPayload.status.message:"Egress request is not authorized"' \
  --project=$PROJECT_ID --limit=5 --format=json

```

### Step 5: Validate Registry State

Confirm the hostname exists in Agent Registry. Per [[`agent-registry.md`](https://github.com/google/skills/blob/main/agent-registry.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/agent-registry.md), register all five hostname forms if absent: canonical, short, and variant FQDNs.

```bash

# Check registry entry for target hostname

gcloud alpha agent-registry endpoints describe $HOSTNAME \
  --location=$LOCATION --project=$PROJECT_ID

```

### Step 6: Audit IAM Roles

Per [[`policies.md`](https://github.com/google/skills/blob/main/policies.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/policies.md), verify the agent service-account holds:

- `roles/iap.egressor` (required)
- `roles/iap.httpsGatewayUser` (recommended)

```bash

# Verify IAM role bindings for the service account

gcloud projects get-iam-policy $PROJECT_ID \
  --flatten="bindings[].members" \
  --format="table(bindings.role, bindings.members)" \
  | grep "roles/iap.egressor" | grep "$SERVICE_ACCOUNT"

```

### Step 7: Check AuthorizationPolicy Binding

Confirm an `AuthorizationPolicy` is bound to the gateway and permits the agent identity to reach the target endpoint.

### Step 8: Verify Baseline Roles and PrincipalSet

Ensure Agent Runtime User, Registry Viewer, and logging permissions exist. If needed, test the 1:1 binding of principal set to service account to rule out propagation delays.

## Producing the Agent Platform Diagnostic Report

The `agent-platform-troubleshooting` skill outputs a structured markdown report following the exact template in [[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/SKILL.md) (lines 49-84):

| Section | Content |
|---------|---------|
| **Context** | Collected `PROJECT_ID`, `AGENT_ID`, error message, etc. |
| **Evidence gathered** | Log snippets, IAM policy excerpts, registry query results |
| **Root-cause hypothesis** | Highest-confidence explanation with supporting data |
| **Recommended fix** | Specific configuration or permission changes |
| **Verification steps** | Commands to confirm resolution |

## Why the `agent-platform-troubleshooting` Skill Architecture Works

- **Safety-first design**: Zero command execution; all diagnostics are read-only inspections of logs, IAM, and registry state
- **Deterministic flow**: Evidence gates prevent infinite troubleshooting loops—analysis stops when root cause probability exceeds threshold
- **Single source of truth**: All commands and explanations live in `references/`, ensuring consistency across sessions
- **Extensible knowledge base**: New known-issues (e.g., BKI 21 for Cloud Run egress) add to [`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md) without skill logic changes

## Summary

- The **`agent-platform-troubleshooting` skill** is a **read-only diagnostic guide** in the `google/skills` repository for Gemini Enterprise Agent Platform issues
- **Seven reference files** in `skills/cloud/agent-platform-troubleshooting/references/` contain all commands and policies
- **Pre-flight validation** in [[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/SKILL.md) filters out-of-scope requests immediately
- **Eight-step diagnostic flow** progresses from logs → registry → IAM → AuthorizationPolicy, stopping at first plausible root cause
- **Structured markdown report** follows a standardized template with context, evidence, hypothesis, fix, and verification

## Frequently Asked Questions

### What makes the `agent-platform-troubleshooting` skill different from automated troubleshooting tools?

Unlike automated runners, this skill **never executes commands on your infrastructure**. It provides precise `gcloud` and `curl` instructions that you copy and run manually, eliminating execution risks while maintaining full auditability of every diagnostic step.

### Which IAM roles does the skill check for Agent Platform authorization?

Per [[`policies.md`](https://github.com/google/skills/blob/main/policies.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/policies.md), the skill verifies `roles/iap.egressor` on the agent service account and recommends `roles/iap.httpsGatewayUser` for enhanced gateway access.

### How does the skill handle known recurring issues?

[[`known-issues.md`](https://github.com/google/skills/blob/main/known-issues.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/references/known-issues.md) maps symptoms to **BKI numbers** (Broad Known Issues)—such as BKI 21 for Cloud Run egress failures—providing pre-validated resolution paths without redundant investigation.

### What information must I gather before starting Agent Platform troubleshooting?

Required context per [[`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md)](https://github.com/google/skills/blob/main/skills/cloud/agent-platform-troubleshooting/SKILL.md): `PROJECT_ID`, `PROJECT_NUMBER`, `LOCATION`, `AGENT_ID`, `AGENT_GATEWAY_NAME`, agent service-account principal, exact error message, and target hostname. Missing fields are explicitly flagged in your diagnostic report.