Google Cloud Agentic AI 架构与部署参考指南解读 build-deploy-agents Skill 的 related-guidance 官方文档导航【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文围绕 google-cloud-solution-build-deploy-agents 这个 Agent Skill 的核心参考文件 related-guidance.md 展开系统梳理其中收录的 16 份 Google Cloud 官方架构与开发指南并结合本仓库的 SKILL.md、design-principles.md、product-mappings.md 与三份模板资产说明这套文档导航 落地模板如何支撑从需求分析、架构设计、实施部署到验证交付的完整闭环。读完本文你将掌握在 Google Cloud 上设计单/多智能体系统、用 ADK 开发与部署智能体、规划私有网络与治理体系时应当查阅哪类官方指南、每个指南解决什么问题以及它们如何在仓库定义的交付流程中被组合使用。一、related-guidance.md 在 Skill 工作流中的定位related-guidance.md并不是一份孤立的外部链接清单而是整个 Skill 的知识地基。在 SKILL.md 定义的四阶段工作流中该文件在三个关键节点被显式引用Phase 2解决方案设计第 1 步要求先从references/related-guidance.md检索相关 Google Cloud 指南并用检索到的内容支撑后续生成的设计建议见 SKILL.mdPhase 3实施计划第 1 步以该文件中的资源作为生成 Infrastructure as CodeIaC与部署说明的技术基础见 SKILL.mdPhase 4方案验证第 1 步以该文件及其验证模式作为校验检查与验证脚本的起点见 SKILL.md。在 SKILL.md 的 References 小节中related-guidance.md被定义为该 Skill 所使用的 Google Cloud 架构文档、产品手册、开发套件与检查清单的完整列表。也就是说当 Agent 被用于在 Google Cloud 上构建和部署 AI 智能体或多智能体系统时这个文件决定了它能引用哪些官方权威依据。该 Skill 的使用边界在 SKILL.md 的元数据中也有清晰说明它适用于设计或实现 agentic 系统但不适用于通用的 Google Cloud 方案架构应改用google-cloud-solution-architecture也不适用于与智能体上下文无关的单一产品窄任务。二、架构设计篇从设计模式到组件选型related-guidance.md的前三份文档构成了架构设计的决策链先定系统组织模式再看多智能体参考架构最后落实到具体组件选型。2.1 选择 agentic AI 系统的设计模式第一份指南的主题是为 agentic AI 系统选择设计模式。它提供了构建系统组件组织框架的指导核心解决两个问题如何组织系统组件、如何集成模型。在单智能体与多智能体之间做取舍时设计模式的选择直接影响后续的编排复杂度与工作流实现方式。这与仓库中 SKILL.md 的设计模式推荐逻辑完全对应单智能体系统适用于较简单的任务是打磨核心逻辑与工具的良好起点多智能体系统则适用于需要多个专职智能体协作完成工作流的复杂问题。2.2 Google Cloud 上的多智能体 AI 系统第二份指南提供了一份示例参考架构帮助设计健壮的多智能体 AI 系统。它回答的是多个智能体如何在 Google Cloud 上协同的落地问题——包括智能体之间的编排方式、任务分配与结果聚合等参考设计。多智能体场景在仓库的 product-mappings.md 中有配套的产品级落点智能体间通信A2A推荐使用 Agent Gateway 进行受管连接智能体注册目录推荐使用 Agent Registry 统一管理 agent、工具与 MCP 服务器并以此优化多智能体路径中的路由见 product-mappings.md。2.3 选择 agentic AI 架构组件第三份指南聚焦如何评估应用与工作负载特征以选择合适的产品、服务与工具。它是从工作负载特征反推产品选型的评估框架不同的延迟、吞吐、状态管理、工具接入方式会导向不同的组件组合。这份指南与仓库的 product-mappings.md 形成互补——前者讲评估方法后者给出 13 类组件的直接推荐与替代方案包括 Cloud Run 网络、前端、智能体开发框架、智能体运行时、模型运行时、模型选择、智能体记忆、检索数据库与智能体工具等。三、智能体开发篇ADK 与多工具智能体开发层面指南集中推荐 Agent Development KitADK作为智能体开发框架并配套两份开发文档。3.1 开发 ADK 智能体这份指南示范了如何使用 Agent Platform SDK for Python 开发 ADK 智能体涵盖四个核心环节定义智能体、定义模型、添加工具、管理会话sessions与记忆memory。开发框架的默认推荐在 product-mappings.md 中被明确为 ADK。而管理会话与记忆在 product-mappings.md 中有更细的产品映射短期记忆首选 Agent Platform SessionsGemini Enterprise Agent Runtime 的内置托管记忆低运维免除外部数据库的供给与管理升级路径为 Memorystore for Redis Cluster亚毫秒级读写延迟适合实时交互备选 Firestore服务端无服务器扩展适合持久状态存储与 Cloud SQL配合 ADKDatabaseSessionService提供关系型与 ACID 保证长期记忆首选 Memory Bank备选 Firestore需要自行实现语义搜索与向量检索逻辑。3.2 多工具智能体多工具智能体指南覆盖两条路径安装 ADK以及搭建带多个工具的智能体。它解决的核心问题是如何让一个智能体同时掌握多个外部能力。在仓库中工具接入方式被细分为四类见 product-mappings.mdAPI 管理平台企业级规模推荐 Apigee API hub适合大规模 API 工具的管理、安全与监控Model Context ProtocolMCP推荐 Google Cloud 托管的 MCP 服务器或在 Cloud Run/GKE 上以容器方式自托管 MCP 服务器适合需要可互操作、可复用工具的模块化或多智能体系统内置工具Built-in Tools以 ADK 为默认框架适合 Web 搜索、安全环境中的代码执行等常见任务可加速初期开发自定义函数工具Custom Function Tools适合接入没有 MCP 服务器的内部或第三方 API或在多智能体编排中将智能体即工具暴露为函数。这一工具分层在 SKILL.md 的实施要求中也有强制体现实施说明必须演示如何使用 MCP 标准注册数据库读取器等工具。四、部署篇Cloud Run ADK 与 Agents CLI4.1 将 ADK 智能体构建并部署到 Cloud Run这份指南示范了使用 ADK for Python 将 AI 智能体构建并部署到 Cloud Run 的完整流程。Cloud Run 在 product-mappings.md 中是前端与智能体运行时的首选产品作为前端它支持容器化应用并可在空闲时缩容到零作为智能体运行时它非常适合承载自定义语言引擎、本地 API 层或自定义 MCP 服务器但无法托管或服务 Gemini 模型见 product-mappings.md。在 SKILL.md 中部署说明被强制要求满足若干生产级约束提供精确的 ADK 代码定义一个有状态stateful的智能体节点接收 prompt、调用模型、返回工具执行请求演示使用 MCP 标准注册数据库读取器等工具若部署到 Cloud Run必须演示如何配置缩容到零scale to zero以降低空闲期运行成本推荐使用加密环境变量存储模型参数或私有 API 凭据防止敏感凭据以明文形式暴露在容器日志流中在合适场景下使用 Agents CLI 的agents-cli deploy命令执行部署。4.2 Agents CLI概览与开发指南related-guidance.md还收录了两份与 Agents CLI 相关的资料一份是 Agents CLI 概览含 FAQ介绍在 Gemini Enterprise Agent Platform 上构建智能体的 CLI 与技能另一份是完整的开发指南覆盖从定义要构建什么到在生产中监控的全流程开发工作流。Agents CLI 在本仓库的落地用法包括见 SKILL.mdagents-cli scaffold create/agents-cli scaffold enhance搭建或增强项目结构、部署配置与 CI/CD 流水线agents-cli deploy配合--dry-run或-n预览部署步骤与 Terraform 执行后再推向生产见 SKILL.mdagents-cli run本地运行与测试智能体逻辑agents-cli eval run在部署前对智能体质量与性能进行系统化评估见 SKILL.mdagents-cli run --url service-url对已部署的服务端点做部署后验证见 SKILL.md。五、网络、注册与治理篇5.1 多智能体私有网络模式这份指南讲解如何设计支持公开访问的多智能体 Gemini Enterprise 应用的私有网络基础设施核心要求是智能体、子智能体与工具之间建立私有连接。它在仓库中的产品落点是 product-mappings.md 的 Cloud Run 网络部分首选方案区域级外部应用负载均衡器 Cloud Armor负责 HTTP/HTTPS/WebSocket 入站 Direct VPC egressCloud Run 私有网络访问备选 1全局外部应用负载均衡器——单一 Anycast IP、全局 IPv6 终结、低延迟路由但 TLS 在边缘位置全局终结可能不符合严格的区域数据驻留法规备选 2内部应用负载均衡器——在 VPC 内部安全暴露 Cloud Run 服务支持 Cloud Armor 后端安全策略但需要配置 serverless NEG 作为后端备选 3Private Service Connect 接口——通过网络附件为 Gemini Enterprise Agent Runtime 提供安全的私有 VPC 连接但限于 RFC 1918 可路由子网且非可路由/互联网目的地需要代理设置。数据库的 VPC 连接同样有明确推荐首选 Serverless VPC Access connector备选 Direct VPC egress更低延迟、更低资源成本、避免吞吐扩展瓶颈但需要特定路由与子网配置见 product-mappings.md。5.2 自动注册启用智能体发现这份指南介绍如何在受支持的运行时上启用智能体发现。其产品落点是 Agent Registry——提供 agent、工具与 MCP 服务器的统一目录并优化多智能体A2A路径的路由见 product-mappings.md。自动注册的意义在于智能体部署后无需人工登记即可被网络层与其他智能体动态发现。5.3 Agent Gateway 概览Agent Gateway 是 Gemini Enterprise Agent Platform 生态的网络组件负责治理、监控并保护客户端到智能体的入站流量与智能体到任意位置的出站流量。在 design-principles.md 中Agent Gateway 与 Agent Registry动态发现和 Model Armor实时安全检查被组合推荐为 Gemini Enterprise Agent Runtime 部署的治理方案。关于 Agent Gateway 的底层机制本仓库 agent-platform-troubleshooting 的 agent-gateway.md 提供了深入的调试参考它基于 Network Servicesnetworkservices.googleapis.com与 Cloud Control Forwarding Engine 实现支持 Standard企业隔离与 Standalone轻量 Google 托管两种部署模式标准模式需绑定 Agent Connectivity TemplateACT与消费者 VPC 网络附件PSC-I并在vpcEgress: ALL_TRAFFIC模式下强制要求消费者 VPC 子网配置 Cloud NAT否则对外部 SaaS/REST API 的出站调用会挂起超时见 agent-gateway.md。六、Well-Architected Framework六大支柱视角related-guidance.md收录了 Google Cloud 架构框架Well-Architected Framework中 AI 与机器学习视角的六份指南覆盖安全、可靠性、卓越运营、成本优化、性能优化与可持续性。这些指南与仓库 design-principles.md 中的设计建议逐条对应构成原则—操作的完整链条。6.1 安全AI and ML perspective: Security概述确保 AI/ML 部署满足安全与合规要求的原则与建议。仓库层面的落点包括见 design-principles.md限制应用访问禁用前端 Cloud Run 服务的默认 run.app URL改用配置了 Cloud Armor 安全策略的区域级外部应用负载均衡器以处理请求过滤、速率限制与 DDoS 防护对架构中的资源执行 IAM 最小权限原则使用经过身份验证的扩展 agent 卡片保护 Agent2AgentA2A通信并附加 OpenID ConnectOIDC身份令牌让 IAM 校验只有授权智能体才能访问数据引入**人在环路human-in-the-loop**流程让主管能够监控、暂停并覆盖业务关键型智能体动作始终推荐Model Armor作为安全层检查模型输入输出的安全性、PII 检测与提示注入威胁。6.2 可靠性AI and ML perspective: Reliability概述在 Google Cloud 上设计与运维可靠 AI/ML 系统的原则强调将高级可靠性实践与可观测性集成进架构蓝图。仓库落点包括见 design-principles.md采用去中心化设计构建容错智能体让智能体可独立运行以在故障中存活上线前在副本预发布环境中模拟智能体间协调问题与意外行为使用 Cloud Run 的区域多可用区部署实现自动负载均衡并抵御可用区故障通过监控标准配额速率规划模型容量业务关键型生产工作负载使用 Provisioned Throughput。6.3 卓越运营AI and ML perspective: Operational excellence概述构建与运维健壮 AI/ML 系统的原则帮助建立可观测性、自动化与可扩展性等基础要素。仓库落点包括见 design-principles.md将智能体日志以结构化格式路由到 Cloud Logging并集成标准 stdout/stderr 流使用Cloud Trace与追踪可视化器跟踪完整的智能体工作流、推理循环与执行路径使用 Gemini Enterprise Agent Platform 上的 agent evaluation 或 ADK 评估方法论进行持续评估使用MCP Database Toolbox集中化数据库工具与连接扩展策略。6.4 成本优化AI and ML perspective: Cost optimization概述在整个 ML 生命周期内优化 AI 系统成本的原则与建议。仓库落点包括见 design-principles.md使用静态查找数据库或**上下文缓存context caching**降低含长系统提示请求的 token 输入成本结构化提示词以获得简洁响应最小化生成 token 输出从最小、最具成本效益的模型起步再根据性能需求升级到更强大的推理模型。6.5 性能优化AI and ML perspective: Performance optimization概述优化 Google Cloud 上 AI/ML 工作负载性能的原则帮助在模型架构、参数与训练策略等因素上做出决策。仓库落点包括见 design-principles.md实时语音交互场景可为智能体短期记忆/会话状态部署内存中的Memorystore for Redis Cluster实现亚毫秒级读取速度并防止实时语音交互中的静音基于实时工作负载为 Cloud Run 实例配置内存与 CPU 上限以优化服务性能缓解工具膨胀tool bloat会降低准确率、增加延迟与成本限制工具复杂度、提供细粒度工具集并实现渐进式披露progressive disclosure如搜索工具模式、Agent Skills、多智能体委派。6.6 可持续性Sustainability pillar提供在 Google Cloud 上设计、构建与管理节能且碳感知工作负载的建议。仓库落点包括见 design-principles.md将简单任务路由到**小语言模型SLM**并优化模型路由最小化总模型推理足迹使用 Cloud Run 原生自动扩缩在空闲期将计算运行时缩容到零避免浪费资源基线能耗。6.7 平台语言支持related-guidance.md还收录了 Gemini Enterprise Agent Platform 的语言支持文档用于明确受支持的语言范围。这一点在 product-mappings.md 中被作为 Agent Runtime 的选型约束引用Gemini Enterprise Agent Runtime 是功能完备的托管运行时内置记忆/会话、安全代码执行沙箱、原生连接远程 MCP 服务器但仅限于受支持的语言且不直接托管自定义 MCP 服务器必须外部托管在 Cloud Run 或 GKE 上。七、与仓库配套文件的协同工作方式related-guidance.md的价值只有在与 Skill 的其他资产组合使用时才完全释放形成导航 → 映射 → 原则 → 模板的四层支撑体系导航层related-guidance.md确定查什么——官方设计模式、多智能体架构、开发与部署教程、网络模式、治理组件与 WAF 支柱指南映射层product-mappings.md 确定用什么——将已确认技术分解中的每个组件映射到具体的 Google Cloud 产品与功能并给出备选方案、权衡与替代项原则层design-principles.md 确定怎么选——围绕安全、可靠性、卓越运营、成本、性能与可持续性给出设计建议其中安全与可靠性建议在生成设计建议时被要求重点参考模板层三份模板确定怎么交——solution-template.md架构设计文档含产品映射表与 Mermaid 架构图、implementation-template.md部署前提与分步部署说明、validation-template.md含terraform plan干跑、curl连通性与gcloud projects get-iam-policy安全校验等可执行验证命令。八、实战落地把参考指南接入四阶段交付流程在实际使用该 Skill 时related-guidance.md的内容会贯穿整个交付过程对照 SKILL.md 的检查清单Phase 1需求发现与分析收集功能与非功能需求安全、隐私、合规、可靠性、灾备、成本、运营、性能、可持续性确认既有系统、知识库与依赖识别歧义与矛盾后推荐设计模式单智能体 vs 多智能体产出并确认技术分解Phase 2解决方案设计检索related-guidance.md作为设计依据按product-mappings.md映射产品产出 Mermaid 架构图与设计建议按solution-template.md编译为solution-architecture.md并请求评审Phase 3实施计划以related-guidance.md为技术基础生成 IaC如 Terraform与部署脚本必要时用agents-cli scaffold create/enhance搭建项目与 CI/CD写出含 ADK 状态节点代码、MCP 工具注册、Cloud Run 缩容到零、加密环境变量的部署说明编译为implementation-instructions.md并请求评审Phase 4方案验证以related-guidance.md的验证模式为起点定义terraform plan干跑、agents-cli deploy --dry-run预览、agents-cli run/agents-cli eval run本地质量验证、连通性路由与安全策略检查编译为validation-plan.md执行验证并最终确认。总结related-guidance.md以 16 份官方指南浓缩了 Google Cloud agentic AI 从设计到交付的完整知识面设计模式与多智能体参考架构解决怎么设计ADK 开发与多工具智能体教程解决怎么开发Cloud Run 部署与 Agents CLI 解决怎么交付私有网络模式、自动注册与 Agent Gateway 解决怎么治理六大 WAF 支柱视角解决怎么做好。在本仓库中它通过与product-mappings.md、design-principles.md及三份模板的联动被封装进一个可重复的四阶段交付工作流使 Agent 在每次生成架构与部署方案时都有官方依据可循、有模板可落、有验证手段可查。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考