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

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

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

# 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).

# 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/skills/cloud/agent-platform-troubleshooting/references/agent-registry.md), register all five hostname forms if absent: canonical, short, and variant FQDNs.

# 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/skills/cloud/agent-platform-troubleshooting/references/policies.md), verify the agent service-account holds:

• roles/iap.egressor (required)
• roles/iap.httpsGatewayUser (recommended)

# 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/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 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/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/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/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/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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}