google-cloud-solution-build-deploy-agents

在 Google Cloud 上构建和部署 AI Agent

此技能将引导 Agent 完成工作流：针对给定的工作负载、用例或需求，在云端设计并实施量身定制的多产品解决方案。

归属说明

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

工作流

解决方案设计和实施工作流分为以下阶段：

• 阶段 1：需求发现与分析：分析工作负载的需求、限制、依赖项和当前状态。
• 阶段 2：解决方案设计：根据 Google Cloud 设计最佳实践和建议，为工作负载构建技术栈、架构和部署配置。
• 阶段 3：实施计划：生成用于部署解决方案的自动化内容和说明。
• 阶段 4：解决方案验证：验证部署是否满足工作负载的需求。

将此清单复制到当前任务／计划文档中，以跟踪四个阶段的进度：

• 阶段 1：已完成并确认需求发现与分析。
• 阶段 2：已生成并批准解决方案架构。
• 阶段 3：已生成并批准实施计划。
• 阶段 4：已生成并批准解决方案验证。

阶段 1：需求发现与分析

1. 发现需求：收集并了解工作负载的功能性和非功能性需求、业务目标和当前状态（如有），包括其架构、依赖项和限制。

   重要：首先，检查用户的初始提示是否已回答以下问题，或是否明确要求根据给定参数提出解决方案架构／图示。

   • 如果用户的提示提供了充分的需求，并明确要求提出架构方案或图示，则跳过以下问题，直接进入推荐 Agent 设计模式步骤。

   • 如果用户的提示未提供充分的需求，则完成以下步骤以收集缺失信息：

     1. 请用户描述其工作负载的功能需求：业务流程、活动和用例。

     2. 请用户描述其工作负载的非功能性需求（安全、隐私、合规性、可靠性、灾难恢复、成本、运维、性能和可持续性）。

     3. 询问用户，AI Agent 需要访问哪些现有系统、知识库、产品文档或其他文档，才能提供有依据的指导。

     4. 请用户描述对其他工作负载、产品或工具的依赖关系（如有）。

     5. 查看用户目前提供的信息，并检查其中是否存在歧义或矛盾。

        如果发现用户提供的需求中存在任何歧义或矛盾，则针对发现的每个歧义或矛盾执行以下操作：

        • 描述该歧义或矛盾。
        • 询问用户希望如何解决该歧义或矛盾。
          • 如果用户将选择权交给你（例如，用户回复“按你认为最好的方式处理”或“由你决定”），则明确提出解决该歧义或矛盾的建议，解释理由，并请用户批准该建议。 关键：在你根据前述指导解决所有已识别的歧义和矛盾之前， 绝不能推荐或生成任何架构设计、技术分解或 Google Cloud 产品 建议。

2. 推荐 Agent 设计模式：评估工作负载的复杂性、工作流、延迟和成本 要求，以推荐 Agent 设计模式：

   • 单 Agent 系统：适用于较简单的任务，可作为优化核心逻辑和工具的 有效起点。
   • 多 Agent 系统：适用于需要多个专用 Agent 协作完成工作流的 复杂问题。

3. 识别组件：根据需求分析，生成工作负载的技术分解。技术分解必须 识别工作负载的逻辑组件及其关系。还需识别解决方案需要集成的任何跨云 组件、混合组件或本地部署组件。

4. 请求确认：询问用户推荐的设计模式和技术分解是否符合其工作负载 要求。

5. 迭代：如果用户要求修改，则生成更新后的技术分解，并请用户确认 修改。持续迭代，直到用户确认技术分解。只有在用户确认技术分解后， 才能进入下一阶段。

阶段 2：解决方案设计

1. 从 references/related-guidance.md 中检索相关 Google Cloud 指导。

   重要：使用从 references/related-guidance.md 中检索到的内容， 为本阶段后续步骤生成的指导提供依据。

2. 将组件映射到 Google Cloud 产品：对于已确认技术分解中的每个组件， 查阅 product-mappings.md，了解网络、 前端、Agent/模型运行时、内存存储和工具方面的详细建议、权衡及替代方案， 并确定适用的 Google Cloud 产品和功能。

3. 创建架构图：使用 Mermaid 格式创建架构图：https://github.com/mermaid-js/mermaid。 图中应展示组件、组件之间的关系，以及数据流和控制流。

4. 生成设计建议：根据以下 Google Cloud 最佳实践和建议生成设计指导。 使用 references/related-guidance.md 中的信息，并重点参考 references/design-principles.md 中的指导。

5. 起草解决方案架构：将需求、技术分解、产品映射、架构图和设计建议 汇总到一个 Markdown 文件中，并遵循 solution-template.md 中的格式。在工作区中将 该文档保存为 solution-architecture.md。

6. 请求评审：在回复中直接向用户展示生成的解决方案架构（包括图表的 完整 fenced mermaid 代码块），并明确请求用户提供反馈或批准。展示架构时， 请用户批准你继续制定实施计划。

7. 迭代：如果用户要求修改，则生成更新后的解决方案架构，并重复执行从 “将组件映射到 Google Cloud 产品”到“请求评审”的步骤，直到用户批准 解决方案架构。

第 3 阶段：实施计划

1. 检索相关实施资源：

   重要提示：使用 references/related-guidance.md 中的资源，作为本阶段后续步骤中生成的基础设施即代码（IaC）和部署说明的技术依据。

2. 确定部署前提条件：记录部署所需的前提条件，包括以下内容：

   • 项目及其结算关联
   • 所需的 Google Cloud API
   • 所需的 IAM 权限
   • 任何其他前提条件

3. 生成基础设施即代码（IaC）：生成代码（例如 Terraform）和部署脚本，以自动配置拟议的 Google Cloud 资源。

   • 在适当情况下，除原始基础设施脚本之外或替代原始基础设施脚本，指导用户使用 Agents CLI 命令（agents-cli scaffold create 或 agents-cli scaffold enhance）来搭建或增强项目结构、部署配置和 CI/CD 流水线。

4. 编写部署说明：起草按顺序排列的分步部署说明，用于执行 IaC 并初始化工作负载组件。将部署前提条件、IaC 和部署说明整合到一个 Markdown 文件中，并遵循 implementation-template.md 中的格式。将此文档保存到工作区，命名为 implementation-instructions.md。

   • 说明 MUST 提供确切的 ADK 代码，用于定义一个有状态 Agent 节点，该节点接收提示词、调用模型并返回工具执行请求。
   • 说明 MUST 演示如何使用 Model Context Protocol（MCP）标准注册数据库读取器等工具。
   • 如果将 Agent 部署到 Cloud Run，说明 MUST 展示如何将 Cloud Run 配置为在 Agent 空闲时缩至零实例，以降低运行成本。
   • 说明 MUST 建议使用加密环境变量来存储模型参数或私有 API 凭据。加密有助于防止敏感凭据以明文形式暴露在容器日志流中。
   • 在适当情况下，说明 MUST 指定使用 Agents CLI 的 agents-cli deploy 命令（配合或替代原始基础设施／部署脚本）运行部署。

5. 请求审核：向用户展示生成的部署说明，并明确征求其反馈和确认。

6. 迭代：如果用户要求修改，则生成更新后的实施计划，并重复从“生成基础设施即代码（IaC）”到“请求审核”的步骤，直到用户批准实施计划。

阶段 4：解决方案验证

1. 检索相关验证资源：

   重要提示：使用 references/related-guidance.md 中的资源及其验证模式，作为本阶段后续步骤中生成验证检查和验证脚本的起点。

2. 定义验证检查：概述验证步骤，以确认已部署的基础设施满足工作负载的要求：

   • 部署试运行：使用 terraform plan 等命令预览变更。说明如何以试运行模式运行 Agent 部署（例如使用 agents-cli deploy --dry-run 或 -n），以便在推送到生产环境之前预览步骤和 Terraform 执行情况。
   • 本地测试和质量验证：建议使用 Agents CLI 在本地运行并测试 Agent 逻辑（agents-cli run），并进行系统化评估（agents-cli eval run），以便在部署前验证 Agent 的质量和性能。
   • 连通性和路由：验证网络路径、负载均衡器路由和服务端点。
   • 安全策略：验证访问限制、防火墙规则和 IAM 强制执行情况。

3. 生成验证脚本：起草轻量级脚本或命令行说明（例如使用 curl、gcloud 或 agents-cli），供用户运行以执行这些验证检查。

   • 验证计划必须包含使用 Agents CLI 进行本地运行、评估和部署后验证检查的说明（例如，使用 agents-cli run --url <service-url> 测试已部署的服务端点）。

4. 编写验证计划：按照 validation-template.md 中的格式，将验证步骤、验证脚本和预期结果整理到一个 Markdown 文件中。将该文档保存到工作区，命名为 validation-plan.md。

5. 请求审核：向用户展示验证计划，并明确征求用户对该计划的反馈或批准。

6. 执行验证并定稿：协助用户执行验证检查并排查部署问题。成功验证解决方案后，向用户请求最终批准。

7. 迭代：如果用户要求修改，则生成更新后的验证计划，并从“定义验证检查”到“请求审核”重复这些步骤，直到用户批准验证计划。

---

参考资料和辅助链接

• 如需查看此技能使用的 Google Cloud 架构文档、产品手册、开发套件和检查清单的完整列表，请参阅 related-guidance.md。