agent-platform-architecture

Gemini 平台架构与工程指南

此技能是设计、构建和验证企业级 Gemini 平台架构的参考体系，适用于多项目层级、混合云／跨云网络、零信任身份边界，以及内联安全／策略执行层。

使用归属

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读并遵循使用归属中的说明。

重要

架构范围与参考资料规范：使用 SKILL.md 选择目标拓扑、出站模式、入站模式和治理层，然后查阅权威的 references/*.md 手册，以获取准确的 CLI 命令、REST/YAML 架构、通用表达式语言（CEL）表达式，以及 Python Agent Development Kit (ADK) 运行时代码（references/*.md 是所有实现语法的唯一事实来源）。如果有远程 Model Context Protocol (MCP) 工具可用（例如 Google Developer Knowledge MCP 服务或 Google 托管的 MCP 端点），请优先调用远程 MCP 工具，而不是使用原始 CLI/REST 命令。用户要求提供架构设计时，不要对客户项目执行未经请求的实时变更。

注意

敏感操作的人为审批关卡：在执行命令或应用配置之前，始终先征求用户的明确确认，只要这些操作会授予宽松的 Identity and Access Management (IAM) 绑定（roles/iap.egressor、roles/compute.networkUser、roles/networkservices.admin）、修改组织政策（constraints/iam.managed.disableAccessPolicyBinding）、更新 Unified Access Policy (UAP) 或 VPC Service Controls (VPC-SC) 政策，或删除资源（REST DELETE ...?force=true 或 CLI --quiet）。

前提条件、身份验证、区域与账单设置

1. Google Cloud SDK、身份验证和项目设置：

   • 安装 Google Cloud SDK (gcloud)， 并对 CLI 和应用默认凭据进行身份验证 （gcloud auth login && gcloud auth application-default login，或设置 GOOGLE_APPLICATION_CREDENTIALS）。

   • 选择或创建目标项目（gcloud projects create {project_id} / gcloud config set project {project_id}），设置 默认区域（gcloud config set compute/region {region}，默认为 us-central1；请参阅 Google Cloud 位置），并 启用所需的 API：

     gcloud services enable aiplatform.googleapis.com agentregistry.googleapis.com \
       agentidentity.googleapis.com agentidentitycredentials.googleapis.com \
       networkservices.googleapis.com networksecurity.googleapis.com iap.googleapis.com \
       modelarmor.googleapis.com compute.googleapis.com dns.googleapis.com \
       certificatemanager.googleapis.com servicenetworking.googleapis.com
     

2. 账单、最小权限 IAM 和产品术语：
   • 确认已关联有效的账单账号（gcloud billing projects describe {project_id} --format="value(billingEnabled)"），并检查 {host_project_id}、{gov_project_id}、{runtime_project_id} 和 {mcp_project_id}（即使评估免费层级额度，也必须完成此步骤； 请参阅 Google Cloud 价格）。
   • 明确授予最小权限 IAM 角色（roles/aiplatform.user、 roles/networkservices.admin、roles/compute.networkAdmin、 roles/compute.networkUser、roles/iap.egressor，或包含 networkservices.agentGateways.get,networkservices.agentGateways.use,networkservices.operations.get 的自定义角色）， 不要使用基本角色 roles/owner 或 roles/editor。
   • 使用经批准的产品名称：Gemini 平台、 Agent Runtime（reasoningEngines）、Agent Gateway （240.0.0.2:443）、Agent Connectivity Template (ACT)、Agent Registry，以及 Unified Access Policy (UAP Policy V2) / Semantic Governance Policy (SGP)。

---

3 阶段架构师工作流与决策树

graph TD
    Start["Enterprise Gemini platform Architecture"] --> Q1{"1. Egress Destinations?"}
    Q1 -->|"RFC 1918 + Google APIs Only"| Priv["ACT: vpcEgress = PRIVATE_RANGES_ONLY<br/>• Direct Private Google Access (PGA)"]
    Q1 -->|"Public Internet, VPC-SC, or Non-RFC 1918 PUPI"| All["ACT: vpcEgress = ALL_TRAFFIC<br/>• 100% Egress via AGW VIP 240.0.0.2:443<br/>• Consolidate Core Google APIs FQDNs"]
    All --> Q2{"2. Layer 7 URL List or Cross-Cloud mTLS?"}
    Q2 -->|"No (Standard NAT)"| Nat["Direct Cloud NAT on PSC-I Subnet<br/>• ENDPOINT_TYPE_VM,ENDPOINT_TYPE_SWG"]
    Q2 -->|"Yes (Next-Hop SWP)"| Swp["Next-Hop SWP (NEXT_HOP_ROUTING_MODE) + PBR<br/>• Internal and Google API DEFAULT_ROUTING bypasses<br/>• Default route via SWP ILB IP<br/>• Exclude PSC-I from manual Cloud NAT"]

1. 阶段 1 — 范围验证与架构发现：
   • 范围边界与单区域发现：对于与 Gemini 平台技术栈无关的通用 Google Cloud IAM/Compute/Storage 调试请求，或要求运行大范围、多区域的实时项目扫描循环的请求，应予以拒绝，并改为指向 gcloud ai reasoning-engines list --region={region}。
   • 架构设计与工程实施：确定项目层级（Host、Governance Hub、Runtime Spoke、Tool/MCP Spoke）、出口模式（ALL_TRAFFIC 与 PRIVATE_RANGES_ONLY）、策略平面（UAP V2、SGP、Model Armor）以及目标输出格式（拓扑规范、gcloud CLI 命令或 REST/YAML 清单）。
2. 阶段 2 — 起草架构计划并映射资源：
   • 使用领域路由器与症状矩阵，综合整理拓扑图、项目/VPC 布局、IAM 引导矩阵和安全控制措施，并将每份手册中的规范 REST/YAML 架构和 CLI 命令映射到目标部署工件中。
3. 阶段 3 — 部署后验证与审核日志核查：
   • 将每项架构设计与部署后验证和 Cloud Audit Log 核查清单 （references/topologies_and_project_layouts.md）配套使用，并验证运行时查询（references/agent_runtime_and_identity.md）。

---

领域路由器与症状矩阵

references/ 中的每份参考手册都是其对应领域 CLI 命令、REST/YAML 架构、配额和 CEL 表达式的唯一事实来源。生成配置或回答领域相关问题前，务必先阅读相应的参考手册：

架构领域	涵盖的主题和架构决策	路由至此的症状和故障模式	权威参考手册
1. 项目层级、共享 VPC、VPC-SC 和自定义路由	多项目隔离（Host、Governance Hub、Runtime Spoke、Tool/MCP Spoke）、PSC-I 子网大小规划、跨项目 Service Agent IAM 引导、VPC-SC 边界、非 RFC 1918 PUPI/对等互连自定义路由交换，以及部署后 Cloud Audit Log 验证。	PSC-I IP 耗尽、跨项目挂接或 addressGroup 权限被拒、VPC-SC 边界阻止、非 RFC 1918 内部路由被丢弃，或部署后验证问题。	references/topologies_and_project_layouts.md
2. Agent Connectivity Template（ACT）和 Agent Gateway	选择 ALL_TRAFFIC 或 PRIVATE_RANGES_ONLY、ACT 和 Agent Gateway REST/YAML 架构、控制平面 URI 格式、注册表挂接限制，以及容器自定义 Root CA 捆绑包信任。	控制平面 URI 验证错误、注册表挂接限制错误，或容器 TLS 验证失败（[SSL: UNEXPECTED_EOF_WHILE_READING]）。	references/agent_gateway_and_act.md
3. 出站路由、下一跳 SWP、PBR 和混合 mTLS	PSC-I 子网的源范围基于策略的路由（PBR）、下一跳 Secure Web Proxy（NEXT_HOP_ROUTING_MODE）、swg-autogen-nat 与手动 Cloud NAT 共存、gRPC/A2A/WebSocket 路由、Spanner SA 模拟，以及跨云 mTLS 出站集线器（Hybrid NEG）。	手动 Cloud NAT 与 swg-autogen-nat 之间的非对称返回路由丢包、PSC-I 接口上的出站 URL 过滤，或通过 Cloud Interconnect/VPN 发起跨云 mTLS。	references/egress_routing_and_swp.md
4. Ingress ALB、URL 重写、Private CA 和第三方 IdP STS	通过 URL Map hostRewrite/pathPrefixRewrite 实现双层和单层 ALB Ingress；Private CA TrustConfig 搭配 Regional Internal ALB 和 Serverless NEG，用于 Cloud Run MCP 服务；通过 LbTrafficExtension（ext_proc + STS）进行第三方 IdP（EntraID/Ping/Okta）令牌交换。	WebPKI 根证书剥离（NO_ADDITIONAL_ROOTS）、Serverless NEG 上空 :authority 被丢弃、*.run.app Google 管理的证书不匹配，或 OAuth/IAP 标头冲突。	references/ingress_patterns_and_rewrites.md
5. UAP Policy V2、IAP V1、SGP 和 Model Armor 治理	组织/文件夹/项目级 UAP Policy V2 和 IAP V1 CEL 授权规则、语义治理策略（SGP CONTENT_AUTHZ）、自定义 AuthzExtension / AuthzPolicy 目标，以及 fail-closed Model Armor Floor Settings、模板和 ADK 回调。	在 MCP initialize 或 tools/list 上出现 Egress request is not authorized（HTTP 403 / status.code=7）、AuthzExtension 上出现 failed to parse the service URL、二进制 gRPC 解析器崩溃，或 fail-open 安全绕过。	references/governance_security_policies.md
6. Agent Registry、整合后的 googleapis 和联合	将核心 Google API FQDN 整合到单个 googleapis 服务（ALL_TRAFFIC）、注册 MCP/A2A/REST 服务、提取服务器生成的 registryResource UUID 以用于 roles/iap.egressor，以及事件驱动的 Spoke 到 Hub 注册表联合。	ALL_TRAFFIC 导致 Agent 启动或遥测流量被黑洞、注册表资源上的 IAM 绑定目标不匹配、OpenAPI/MCP 规范大小超限，或多项目目录漂移。	references/registry_and_federation.md
7. ADK Runtime 打包、Agent 身份和日常运维	使用 AGENT_IDENTITY（SPIFFE）和 Auth Manager 打包 ADK Agent、区域驻留、BigQuery 执行前成本防护、原位更新 ACT、按反向依赖顺序拆除，以及外部 Cloud NAT IP 验证。	原始凭据暴露、HTTP 409 ABORTED 控制平面互斥锁、HTTP 400 FAILED_PRECONDITION（FROM_AGENT_GATEWAY* 或 contains child resources: sessions），或探测 *.run.app 时出现 X-Forwarded-For: 0.0.0.0。	references/agent_runtime_and_identity.md

---

支持性公开文档链接

• Agent Runtime 概览
• Agent Gateway 概览
• Policies 概览
• Agent Identity 概览
• Agent Registry 概览
• 部署 Agent Gateway Runtime
• Private Service Connect 接口