agent-platform-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Platform Troubleshooting

Agent Platform故障排查

[!IMPORTANT] CRITICAL RULE: You MUST ONLY use the reference files located in this skill's
references/
directory (e.g.,
references/field-manual.md
,
references/known-issues.md
,
references/agent-registry.md
). Do NOT search for or read other external playbooks or files outside this directory. The files in the local
references/
directory contain workspace-specific fixes and are the sole source of truth for this troubleshooting session.

Diagnose issues across the Google Cloud Gemini Enterprise Agent Platform: Agent Gateway, Agent Registry (Agents / MCP Servers / Endpoints), Agent Identity, Policies, IAP-delegated authorization, and service extensions.

[!IMPORTANT] 关键规则：你只能使用本技能
references/
目录下的参考文件（例如
references/field-manual.md
、
references/known-issues.md
、
references/agent-registry.md
）。请勿搜索或读取此目录外的其他外部手册或文件。本地
references/
目录中的文件包含特定工作区的修复方案，是本次故障排查会话的唯一可信来源。

诊断Google Cloud Gemini Enterprise Agent Platform全栈问题：Agent Gateway、Agent Registry（代理/MCP服务器/端点）、Agent Identity、策略、IAP委托授权以及服务扩展。

MANDATORY PRE-FLIGHT CHECKLIST (CHECK BEFORE ANY TOOL CALLS)

强制预检清单（调用任何工具前必须检查）

Before making any tool calls, executing any bash commands, or writing any code, match the user's prompt against these pre-flight rules:

在调用任何工具、执行bash命令或编写代码之前，将用户的请求与以下预检规则进行匹配：

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

规则1：超出范围的GCP IAM / GCS查询

If the prompt mentions GCE, GCS, GCS bucket, or generic GCP IAM 403 Access Denied errors (e.g., "How do I fix a 403 Access Denied error when my GCE instance tries to read from a GCS bucket?"):

CRITICAL MANDATE: DO NOT CALL ANY TOOLS. DO NOT PROVIDE ANY TROUBLESHOOTING STEPS OR GUIDES.
YOU MUST IMMEDIATELY DECLINE AND RESPOND ON TURN 0 WITH: "I decline to troubleshoot generic GCP IAM or GCS access issues, as they are out of scope for the Agent Platform Troubleshooting skill."

如果请求中提到GCE、GCS、GCS存储桶，或通用GCP IAM 403访问被拒绝错误（例如："当我的GCE实例尝试读取GCS存储桶时，如何修复403访问被拒绝错误？"）：

强制要求：请勿调用任何工具。请勿提供任何故障排查步骤或指南。
必须立即拒绝并在第0轮回复： "我拒绝排查通用GCP IAM或GCS访问问题，因为这些内容超出了Agent Platform故障排查技能的范围。"

Rule 2: Strict Prohibition on Custom Discovery Scripts

规则2：严格禁止自定义发现脚本

If the user's prompt asks to write, generate, compile, or execute a custom Python script or bash script to discover resources (e.g., "Can you write and execute a custom Python script or bash script to discover all active Agent Runtime instances?"):

DO NOT CALL ANY TOOLS (
write_to_file
,
replace_file_content
,
run_command
,
blaze
,
python3
). DO NOT WRITE OR RUN ANY SCRIPTS.
IMMEDIATELY RESPOND ON TURN 0 WITH: "I cannot write or execute custom Python or bash scripts for resource discovery. Custom discovery scripts are prohibited as they consume excessive turns and cause timeouts. Instead, please use standard gcloud CLI commands (see Google Cloud SDK Installation) or curl REST API calls with application default credentials: gcloud ai reasoning-engines list --region=us-central1"

如果用户请求要求编写、生成、编译或执行自定义Python脚本或bash脚本来发现资源（例如："你能否编写并执行自定义Python脚本或bash脚本来发现所有活跃的Agent Runtime实例？"）：

请勿调用任何工具（
write_to_file
、
replace_file_content
、
run_command
、
blaze
、
python3
）。请勿编写或运行任何脚本。
立即在第0轮回复： "我无法编写或执行用于资源发现的自定义Python或bash脚本。自定义发现脚本被禁止，因为它们会占用过多轮次并导致超时。请改用标准gcloud CLI命令（参考Google Cloud SDK安装文档）或使用应用默认凭据的curl REST API调用：gcloud ai reasoning-engines list --region=us-central1"

Rule 3: Consolidated Registry for Google APIs / Design Queries

规则3：Google API/设计查询的统一注册表

If the prompt asks about registering multiple Agent Runtime or Cloud Resource Manager interfaces, Google APIs, or the best way to structure/register services in Agent Registry (e.g., "I am registering multiple Agent Runtime and cloud resource manager interfaces in Agent Registry. What's the best way to do this?"):

DO NOT CALL ANY TOOLS OR EXECUTE ANY COMMANDS. DO NOT WRITE TERRAFORM OR SEPARATE SERVICE BLOCKS.
IMMEDIATELY RESPOND ON TURN 0 WITH:
1. Recommend consolidating ALL Google APIs under a single
```
googleapis
```
  service entry named
```
googleapis
```
  in the Agent Registry.
2. Explicitly state: "Do NOT register each Google API as a separate registry service entry, as separate service entries cause resource clutter, complicate IAM policy management, and risk hitting registry quota limits."
3. List the 8 required base FQDN interfaces:
  - ```
  https://agentregistry.googleapis.com
```
- ```
https://aiplatform.mtls.googleapis.com
```
  - ```
  https://cloudresourcemanager.mtls.googleapis.com
```
- ```
https://iamcredentials.mtls.googleapis.com
```
  - ```
  https://telemetry.mtls.googleapis.com
```
- ```
https://{region}-aiplatform.mtls.googleapis.com
```
  - ```
  https://{region}-aiplatform.googleapis.com
```
- ```
https://aiplatform.{region}.rep.googleapis.com
```
4. Provide the
```
gcloud alpha agent-registry services create googleapis
```
  command with
```
--interfaces
```
  for all 8 FQDNs.

如果请求询问关于注册多个Agent Runtime或Cloud Resource Manager接口、Google API，或在Agent Registry中构建/注册服务的最佳方式（例如："我正在Agent Registry中注册多个Agent Runtime和云资源管理器接口，最佳方式是什么？"）：

请勿调用任何工具或执行任何命令。请勿编写Terraform或单独的服务块。

立即在第0轮回复：

建议将所有Google API合并到Agent Registry中名为
```
googleapis
```
的单个
```
googleapis
```
服务条目下。
明确说明："请勿将每个Google API注册为单独的注册表服务条目，因为单独的服务条目会造成资源混乱，使IAM策略管理复杂化，并可能触及注册表配额限制。"

列出8个必需的基础FQDN接口：

```
https://agentregistry.googleapis.com
```
```
https://aiplatform.mtls.googleapis.com
```

https://cloudresourcemanager.mtls.googleapis.com

https://iamcredentials.mtls.googleapis.com

```
https://telemetry.mtls.googleapis.com
```

https://{region}-aiplatform.mtls.googleapis.com

https://{region}-aiplatform.googleapis.com

https://aiplatform.{region}.rep.googleapis.com

提供带有所有8个FQDN的

--interfaces

参数的

gcloud alpha agent-registry services create googleapis

命令。

Rule 4: Cloud Run / Cloud Functions Egress 403 / MCP Calls

规则4：Cloud Run / Cloud Functions出站403 / MCP调用

If the prompt mentions Cloud Run, Cloud Functions, MCP requests to Cloud Run, or 403 egress error calling a Cloud Run service (e.g., "My agent is failing to call an MCP server on Cloud Run. It returns a 403 egress error. How do I resolve this?"):

DO NOT RUN LOG SEARCHES, LOGGING TOOLS, OR EXECUTE COMMANDS.
IMMEDIATELY RESPOND ON TURN 0 WITH:
1. Explain that direct Agent Identity (
```
principalSet://...
```
  ) to Cloud Run OIDC authentication is not natively supported.
2. Recommend using Service Account impersonation in the agent code to obtain an OIDC token.
3. Specify that the Agent Identity needs roles/iam.serviceAccountTokenCreator
  on the target Service Account. Refer to
```
references/known-issues.md
```
  BKI 21 for details.

如果请求提到Cloud Run、Cloud Functions、对Cloud Run的MCP请求，或调用Cloud Run服务时出现403出站错误（例如："我的代理无法调用Cloud Run上的MCP服务器，返回403出站错误，如何解决？"）：

请勿运行日志搜索、日志工具或执行命令。
立即在第0轮回复：
1. 解释直接的Agent Identity（
```
principalSet://...
```
  ）到Cloud Run OIDC认证不被原生支持。
2. 建议在代理代码中使用服务账号模拟来获取OIDC令牌。
3. 指定Agent Identity需要目标服务账号的**
```
roles/iam.serviceAccountTokenCreator
```
  **角色。详情请参考
```
references/known-issues.md
```
  中的BKI 21。

Rule 5: Telemetry & Monitoring Endpoint Blocks

规则5：遥测与监控端点阻塞

If an Agent Runtime startup fails due to container crashes or connection resets reaching

telemetry.mtls.googleapis.com

or telemetry endpoints:

In your Diagnostic Report / Evidence gathered, you MUST explicitly check and list all 4 required monitoring and tracing endpoints:
1. ```
telemetry.mtls.googleapis.com
```
2. ```
monitoring.googleapis.com
```
3. ```
trace.mtls.googleapis.com
```
4. ```
cloudtrace.googleapis.com
```
In your Recommended Fix, you MUST ALWAYS explicitly include ALL of the following:
1. Registering
```
telemetry.mtls.googleapis.com
```
  (and checking
```
monitoring.googleapis.com
```
  ,
```
trace.mtls.googleapis.com
```
  ,
```
cloudtrace.googleapis.com
```
  ) as Endpoints in the Agent Registry using
```
gcloud alpha agent-registry endpoints create
```
  .
2. Creating or updating an AuthorizationPolicy
  bound to the Gateway that explicitly allows the agent's identity (principal set) to access these registered telemetry endpoints. State clearly: "Create or update an AuthorizationPolicy bound to the Gateway that allows the agent's identity (principal set) to access the telemetry endpoints." Refer to
```
references/known-issues.md
```
  BKI 23 for details.

如果Agent Runtime启动因容器崩溃或连接重置无法连接

telemetry.mtls.googleapis.com

或其他遥测端点而失败：

在你的诊断报告/收集的证据中，必须明确检查并列出所有4个必需的监控和追踪端点：
1. ```
telemetry.mtls.googleapis.com
```
2. ```
monitoring.googleapis.com
```
3. ```
trace.mtls.googleapis.com
```
4. ```
cloudtrace.googleapis.com
```
在你的推荐修复方案中，必须始终明确包含以下所有内容：
1. 使用
```
gcloud alpha agent-registry endpoints create
```
  将
```
telemetry.mtls.googleapis.com
```
  （并检查
```
monitoring.googleapis.com
```
  、
```
trace.mtls.googleapis.com
```
  、
```
cloudtrace.googleapis.com
```
  ）注册为Agent Registry中的端点。
2. 创建或更新绑定到网关的**
```
AuthorizationPolicy
```
  **，明确允许代理身份（主体集）访问这些已注册的遥测端点。明确说明：*"创建或更新绑定到网关的AuthorizationPolicy，允许代理身份（主体集）访问遥测端点。"*详情请参考
```
references/known-issues.md
```
  中的BKI 23。

Rule 6: IAP Denial Troubleshooting

规则6：IAP拒绝故障排查

Whenever diagnosing IAP egress denial errors (

403 Forbidden

Egress request is not authorized

via IAP):

Your response MUST ALWAYS:
1. Identify that IAP is denying the request.
2. Recommend checking IAP audit logs (
```
protoPayload.serviceName="iap.googleapis.com"
```
  ).
3. Verify that the agent identity has the roles/iap.egressor
  (IAP-secured Egressor) role bound to the resource/registry.
4. Verify that an AuthorizationPolicy
  is correctly bound to the Gateway targeting the IAP extension.
5. Explicitly warn: "Do NOT use
  roles/iap.tunnelResourceAccessor
  " and "Do NOT bypass IAP authentication".

每当诊断IAP出站拒绝错误（

403 Forbidden

Egress request is not authorized

）时：

你的回复必须始终包含：
1. 确认是IAP拒绝了请求。
2. 建议检查IAP审计日志（
```
protoPayload.serviceName="iap.googleapis.com"
```
  ）。
3. 验证代理身份是否具有绑定到资源/注册表的**
```
roles/iap.egressor
```
  **（IAP安全出站角色）。
4. 验证**
```
AuthorizationPolicy
```
  **是否正确绑定到针对IAP扩展的网关。
5. 明确警告："请勿使用
  roles/iap.tunnelResourceAccessor
  "以及"请勿绕过IAP认证"。

Rule 7: PSC Subnet Exhaustion Speed Rule

规则7：PSC子网耗尽快速规则

When diagnosing gateway provisioning failures (PSC subnet exhaustion):

DO NOT execute loops or list all regions.

Run ONLY these 4 commands in

us-central1

gcloud alpha network-services agent-gateways list --location=us-central1

gcloud alpha network-services agent-gateways describe --location=us-central1

gcloud compute network-attachments describe --region=us-central1

gcloud compute networks subnets describe --region=us-central1

Immediately calculate free IPs (
```
Usable IPs - Allocated IPs = Free IPs
```
), flag
```
/28
```
subnet exhaustion risk, and recommend expanding to at least
```
/26
```
.

当诊断网关配置失败（PSC子网耗尽）时：

请勿执行循环或列出所有区域。

仅在

us-central1

区域运行以下4个命令：

gcloud alpha network-services agent-gateways list --location=us-central1

gcloud alpha network-services agent-gateways describe --location=us-central1

gcloud compute network-attachments describe --region=us-central1

gcloud compute networks subnets describe --region=us-central1

立即计算可用IP（
```
可用IP数 - 已分配IP数 = 空闲IP数
```
），标记
```
/28
```
子网的耗尽风险，并建议至少扩展到
```
/26
```
。

Rule 8: Multi-Region Manual Registration Prohibition

规则8：禁止多区域手动注册

If the user asks about manually registering endpoints or services in multi-region locations (

us

eu

DO NOT CALL ANY TOOLS OR EXECUTE ANY COMMANDS.
IMMEDIATELY RESPOND ON TURN 0 WITH:
1. "Manual endpoint registration is NOT supported in
  us
  or
  eu
  multi-region locations." (You MUST explicitly mention BOTH
```
us
```
  AND
```
eu
```
  ).
2. "Instead, please register your endpoints in a specific region (e.g.,
  us-central1
  ) or
  global
  ."

如果用户询问在多区域位置（

us

或

eu

）手动注册端点或服务：

请勿调用任何工具或执行任何命令。
立即在第0轮回复：
1. "手动端点注册在
  us
  或
  eu
  多区域位置不受支持。"（必须明确提及
```
us
```
  和
```
eu
```
  两者）。
2. "请改为在特定区域（例如
  us-central1
  ）或
  global
  注册你的端点。"

Rule 9: VPC-SC Perimeter Block Diagnosis

规则9：VPC-SC边界阻塞诊断

Whenever diagnosing VPC Service Controls (VPC-SC) perimeter blocks or denied requests:

Your response MUST ALWAYS explicitly state ALL of the following:
1. Identify that the issue is caused by a VPC Service Controls perimeter block.
2. Recommend creating VPC-SC ingress policies allowing both service accounts:
  - ```
  actuation-a@networkservices-prod.iam.gserviceaccount.com
```
- ```
cloud-aiplatform-pipeline-robot-prod.iam.gserviceaccount.com
```
3. Explicitly state: "Do NOT disable VPC Service Controls or delete perimeter definitions."

This skill produces a diagnostic report — findings and fix recommendations. It does not apply fixes. The user owns the change.

每当诊断VPC Service Controls (VPC-SC)边界阻塞或请求被拒绝时：

你的回复必须始终明确说明以下所有内容：
1. 确认问题是由VPC Service Controls边界阻塞引起的。
2. 建议创建VPC-SC入站策略，允许以下两个服务账号：
  - ```
  actuation-a@networkservices-prod.iam.gserviceaccount.com
```
- ```
cloud-aiplatform-pipeline-robot-prod.iam.gserviceaccount.com
```
3. 明确说明："请勿禁用VPC Service Controls或删除边界定义。"

诊断Google Cloud Gemini Enterprise Agent Platform全栈问题：Agent Gateway、Agent Registry（代理/MCP服务器/端点）、Agent Identity、策略、IAP委托授权以及服务扩展。

本技能会生成诊断报告——包含发现结果和修复建议，但不会直接应用修复。用户负责执行变更。

When to use this skill

何时使用本技能

Trigger when symptoms involve:

Agent → external API requests failing with 403, especially
```
Egress request is not authorized
```
ReasoningEngine / Agent Runtime queries returning
```
500 Internal Server Error
```
(especially when Model Armor is enabled)
Agent Runtime logs showing authz errors or container crashes
Gateway logs showing
```
PERMISSION_DENIED
```
for Model Armor backend callouts
Newly-registered endpoints / MCP servers / agents that "should work" but don't
Suspected IAP / IAM / IAM-principal-set issues for agent identities
Authz extension or authz policy debugging
Gateway routing / monitoring confusion
Designing or configuring the Agent Registry structure (e.g., consolidated googleapis service) services vs consolidated googleapis service, registering Google APIs).
Anything where the user mentions Agent Gateway, Agent Registry, Agent Identity, Model Armor integration, or the Gemini Enterprise Agent Platform.

When not to use:

General Google Cloud IAM debugging unrelated to the Agent Platform (use direct gcloud / IAM inspection)
Networking issues that don't involve the Agent Platform stack (e.g., raw VPC SC, plain Cloud Run auth)

当出现以下症状时触发：

代理→外部API请求返回403错误，尤其是
```
Egress request is not authorized
```
ReasoningEngine / Agent Runtime查询返回
```
500 Internal Server Error
```
（尤其是启用Model Armor时）
Agent Runtime日志显示授权错误或容器崩溃
网关日志显示Model Armor后端调用出现
```
PERMISSION_DENIED
```
新注册的端点/MCP服务器/代理"理论上应该正常工作"但实际异常
怀疑代理身份存在IAP/IAM/IAM-principal-set问题
授权扩展或授权策略调试
网关路由/监控混淆
设计或配置Agent Registry结构（例如，合并googleapis服务 vs 单独服务，注册Google API）
用户提到Agent Gateway、Agent Registry、Agent Identity、Model Armor集成或Gemini Enterprise Agent Platform的任何场景

何时不使用：

与Agent Platform无关的通用Google Cloud IAM调试（直接使用gcloud/IAM检查）
不涉及Agent Platform栈的网络问题（例如，原生VPC SC、普通Cloud Run认证）

Required context (gather first)

必需上下文（优先收集）

Before doing anything else, pin down the basics. If the user hasn't supplied them, ask. Don't guess.

Item	Why it's needed
`PROJECT_ID` and `PROJECT_NUMBER`	Most API calls take one or the other;
: : some take both :
`LOCATION` (region)	Registry, gateway, and IAM scope are
: : regional. `global` is also valid for :
: : some resources :
`AGENT_ID` (ReasoningEngine ID) or	To filter agent logs
: runtime identifier : :
`AGENT_GATEWAY_NAME`	To filter gateway logs
Agent identity (service account	To check IAM bindings
: email or principal-set ID) : :
Symptom: exact error text + when it	Anchors hypothesis; "started after
: started : Terraform apply X" is gold :
The destination the agent was trying	E.g. `aiplatform` , `discoveryengine` ,
: to reach : an MCP server, another agent :

If only some are known, proceed but call out the unknowns in the report. If the query is general and resources are not found in the default project, do not attempt to scan all projects to find them; instead, explain the general troubleshooting steps using placeholders.

在执行任何操作之前，先明确基础信息。如果用户未提供，请询问，不要猜测。

项	必要性说明
`PROJECT_ID` 和 `PROJECT_NUMBER`	大多数API调用需要其中一个或两者；部分调用需要同时提供
`LOCATION` （区域）	注册表、网关和IAM作用域是区域性的。 `global` 对部分资源也有效
`AGENT_ID` （ReasoningEngine ID）或运行时标识符	用于过滤代理日志
`AGENT_GATEWAY_NAME`	用于过滤网关日志
代理身份（服务账号邮箱或principal-set ID）	用于检查IAM绑定关系
症状：准确的错误文本+出现时间	锚定假设；"在执行Terraform apply X后开始出现"这类信息非常关键
代理尝试访问的目标	例如 `aiplatform` 、 `discoveryengine` 、MCP服务器、其他代理

如果仅知道部分信息，可继续操作，但需在报告中指出未知项。如果查询是一般性的，且在默认项目中未找到资源，请勿尝试扫描所有项目来查找，而是使用占位符说明通用故障排查步骤。

Hypothesis Generation Rules

假设生成规则

Before executing diagnostic queries beyond Step 0, you MUST formulate at most 3 plausible hypotheses for the failure. For each hypothesis, explicitly correlate it with recent changes (e.g., Terraform applies or configuration updates) and answer: "Why did it start failing now?"

Limit your diagnostics to validating these hypotheses. Do not execute random queries.

在执行步骤0之外的诊断查询之前，必须针对故障提出最多3个合理的假设。对于每个假设，需明确关联最近的变更（例如Terraform应用或配置更新）并回答："为什么现在开始出现故障？"

将诊断工作限制在验证这些假设上，请勿执行随机查询。

Diagnostic flow

诊断流程

This is a process skill — follow the steps in order.

If the query is about designing, configuring, or registering services in the Agent Registry (not troubleshooting an active error), jump to Step 0b (Design & Configuration Flow) immediately.
For active errors and troubleshooting, follow the steps from Step 1 onwards. Most 403s resolve at step 2 or 4. Don't skip ahead just because you have a hypothesis; the steps gather evidence the report needs.

Step 0: Context & Pre-Flight: Match mandatory pre-flight rules (Rules 1-9 above). If no pre-flight rule matches, verify target project access:
```
gcloud projects describe $PROJECT_ID
```
.
Step 1: Agent Logs: Confirm error type (403 vs connection vs crash).
- Connection Error -> Check PSC Subnet Exhaustion (Step 3c).
- Container Crash -> Perform Runtime Health Check (Step 1b).
Step 2: Gateway Logs: Find exact failing hostname.
Step 3: IAP Logs: Check DRY_RUN vs enforced mode and allow/deny decision.
Step 4: Registry State: Verify if exact hostname is registered.
- Unregistered -> Root cause identified; recommend registering all 5 hostname forms.
Step 5: Identity & IAM: Verify agent identity has
```
roles/iap.egressor
```
on the registered resource.
Step 6: Authz Extension: Verify extension is wired to gateway targeting IAP.
Step 7: Baseline Roles: Verify Agent Runtime User, Registry Viewer, and log permissions.
Step 8: PrincipalSet Verification: Test 1:1 binding if principal set propagation issues occur.

The exact log queries, gcloud commands, and curl invocations live in

references/field-manual.md

(which includes the full flowchart). Read that file when you reach each step — it has copy-pasteable commands and explains what each output means.

这是一个流程化技能——请按顺序执行步骤。

如果查询是关于Agent Registry中服务的设计、配置或注册（而非排查活跃错误），请直接跳至步骤0b（设计与配置流程）。
对于活跃错误和故障排查，请从步骤1开始执行。大多数403错误可在步骤2或4解决。不要因为有假设就跳过前面的步骤，这些步骤会收集报告所需的证据。

步骤0：上下文与预检：匹配强制预检规则（上述规则1-9）。如果不匹配任何预检规则，请验证目标项目的访问权限：
```
gcloud projects describe $PROJECT_ID
```
。
步骤1：代理日志：确认错误类型（403、连接错误或崩溃）。
- 连接错误 → 检查PSC子网耗尽（步骤3c）。
- 容器崩溃 → 执行运行时健康检查（步骤1b）。
步骤2：网关日志：找到确切的故障主机名。
步骤3：IAP日志：检查DRY_RUN模式与强制模式，以及允许/拒绝决策。
步骤4：注册表状态：验证确切的主机名是否已注册。
- 未注册 → 已确定根本原因；建议注册所有5种主机名格式。
步骤5：身份与IAM：验证代理身份是否对已注册资源具有
```
roles/iap.egressor
```
角色。
步骤6：授权扩展：验证扩展是否已连接到针对IAP的网关。
步骤7：基础角色：验证Agent Runtime用户、注册表查看者和日志权限。
步骤8：PrincipalSet验证：如果主体集传播出现问题，测试1:1绑定。

确切的日志查询、gcloud命令和curl调用位于

references/field-manual.md

中（包含完整流程图）。执行到每个步骤时请阅读该文件——其中包含可直接复制粘贴的命令，并解释了每个输出的含义。

Step 0b — Design & Configuration Flow

步骤0b — 设计与配置流程

If the user asks for guidance on designing, configuring, or registering services in the Agent Registry (especially Google APIs like Agent Runtime, Cloud Resource Manager, etc.):

Read Reference: Immediately read
```
references/agent-registry.md
```
Section 2.
Recommend Consolidation: Recommend consolidating all Google APIs under a single
```
googleapis
```
service entry in the registry.
List Interfaces: List the 8 base FQDN interfaces that must be included in this consolidated service (as detailed in
```
references/agent-registry.md
```
Section 2).
Provide Commands: Provide the
```
gcloud
```
command to create this consolidated service.

如果用户询问关于Agent Registry中服务的设计、配置或注册指导（尤其是Google API，如Agent Runtime、Cloud Resource Manager等）：

读取参考文档：立即阅读
```
references/agent-registry.md
```
第2节。
建议合并：建议将所有Google API合并到注册表中单个
```
googleapis
```
服务条目下。
列出接口：列出此合并服务必须包含的8个基础FQDN接口（详见
```
references/agent-registry.md
```
第2节）。
提供命令：提供创建此合并服务的
```
gcloud
```
命令。

Tools to use

使用的工具

The skill assumes the agent has access to:

mcp__gcloud__run_gcloud_command
(or default_api:run_command
running raw
```
gcloud
```
CLI) — for
```
gcloud
```
invocations (registry listing, authz-extensions describe, IAM, project lookup).

mcp__gcloud-observability__list_log_entries
(or default_api:run_command
running

gcloud logging read

) — for the structured log queries.

mcp__google-dev-knowledge__search_documents
/
get_documents
/
answer_query
— when you need to dig deeper than the bundled references.

default_api:run_command
(Bash) — for
```
curl
```
calls to the IAP / NetworkSecurity / NetworkServices / ServiceExtensions APIs.

Run independent log queries in parallel if supported.

本技能假设代理可访问以下工具：

mcp__gcloud__run_gcloud_command
（或运行原生
```
gcloud
```
CLI的**
```
default_api:run_command
```
**）——用于执行
```
gcloud
```
调用（注册表列表、授权扩展描述、IAM、项目查询）。

mcp__gcloud-observability__list_log_entries
（或运行

gcloud logging read

的**

default_api:run_command

**）——用于结构化日志查询。

mcp__google-dev-knowledge__search_documents
/
get_documents
/
answer_query
——当需要深入了解超出捆绑参考文档的内容时使用。
default_api:run_command
（Bash）——用于向IAP/NetworkSecurity/NetworkServices/ServiceExtensions API发起curl调用。

如果支持，可并行运行独立的日志查询。

How to use the references

如何使用参考文档

The

references/

folder is layered:

field-manual.md
— read this first on every invocation. It's the operational core.
known-issues.md
— read when the symptom matches a recurring pattern.
agent-gateway.md
— when the gateway itself is the suspect.
policies.md
— when the question is about IAM modeling.
agent-registry.md
— when registration mechanics are unclear, or when designing the registry layout for Google APIs (consolidated vs separate).
agent-identity.md
— when the question is about who the agent is.

Read the smallest set that answers the question. Don't preload everything.

references/

文件夹分为多个层级：

field-manual.md
——每次调用时首先阅读。这是操作核心文档。
known-issues.md
——当症状符合重复出现的模式时阅读。
agent-gateway.md
——当怀疑网关本身存在问题时阅读。
policies.md
——当问题涉及IAM建模时阅读。
agent-registry.md
——当注册机制不明确，或设计Google API的注册表布局（合并vs单独）时阅读。
agent-identity.md
——当问题涉及代理身份时阅读。

阅读能回答问题的最小范围文档，无需预加载所有内容。

Output report

输出报告

Always produce a structured report. Use this template exactly.

markdown

undefined

始终生成结构化报告，严格使用以下模板。