问题：启动一个AI智能体项目感觉像从零开始盖房子
你对要构建的AI智能体有一个清晰的想法。也许它是一个使用RAG（检索增强生成）来回答文档问题的客服机器人，或者是一个协调多个专业智能体的内部工具。你知道它应该做什么，但当你坐下来开始编码时，你会遇到一堵与智能体实际逻辑无关的决策之墙。
应该使用哪种项目结构？如何设置部署管道？CI/CD怎么办？需要Dockerfile吗？如何配置会话存储？每个问题都引出另一个问题，不知不觉中，你已经在基础设施上花了几个小时，而不是构建智能体本身。
对于使用Google智能体开发套件（ADK）的开发者来说，这是一个常见的痛点。ADK提供了构建智能体的强大工具，但初始项目设置——创建正确的目录结构、添加部署配置、设置CI/CD管道——需要许多开发者并不立即具备的Google Cloud基础设施知识。结果往往是缓慢且容易出错的开始，开发者要么从旧项目复制粘贴（有使用过时模式的风险），要么手动构建所有东西（在样板代码上浪费时间）。
核心问题不是技能不足，而是缺乏一个标准化的、有明确指导的起点。你需要一种方法，在几分钟而不是几小时内，从“我想构建一个智能体”过渡到“我有一个包含部署选项的可工作项目结构”。
一个好的解决方案应该提供什么
一个恰当的解决方案应该做到以下几点：
- 减少决策疲劳： 它应该为常见配置（如部署目标和CI/CD运行器）提供合理的默认值和清晰的选择，而不需要你成为每个领域的专家。
- 生成完整、可工作的项目结构： 不仅仅是一个骨架，而是一个包含部署、测试和开发工作流所需配置文件的结构。
- 支持迭代开发： 它应该允许你从一个简单的原型开始，稍后再添加复杂性（如部署或CI/CD），而无需重构项目。
- 不阻碍你的工作： 生成的代码应该是一个起点，而不是一个牢笼。你需要能够轻松修改智能体逻辑、工具和配置。
- 与你现有的工作流集成： 无论你使用GitHub Actions还是Google Cloud Build进行CI/CD，该解决方案都应适应你偏好的工具。
介绍Google Agents CLI脚手架：一个实用的项目设置选项
一个旨在解决这个特定问题的工具是Google Agents CLI中的scaffold命令。它是更广泛的Google ADK技能套件的一部分，专门专注于项目初始化和增强阶段。它不用于编写智能体的核心逻辑或执行部署操作——那些是独立的关注点。
可以把它看作一个理解ADK约定和Google Cloud部署模式的项目生成器。你描述你想要什么（例如，“一个部署在Cloud Run上、使用GitHub Actions CI/CD的RAG智能体”），它就会生成一个包含正确结构、配置文件甚至一个包含常用命令的Makefile的项目目录。
工作原理：原型优先的工作流
推荐的方法是从简单开始，逐步增加复杂性。这与大多数开发者的实际工作方式一致：先让核心想法运行起来，然后再考虑部署和管道。
步骤1：创建一个原型
你可以创建一个只包含智能体代码的项目，最初跳过所有部署和CI/CD脚手架。这让你可以完全专注于定义智能体的指令、工具和逻辑。
agents-cli scaffold create my-support-agent --agent adk --prototype
此命令创建一个目录 my-support-agent，其中包含一个基本的ADK智能体结构。--prototype 标志意味着不会生成部署配置（Terraform、Dockerfile）或CI/CD管道。你得到一个干净的起点，可以在 app/agent.py 和 app/tools.py 上进行迭代。
步骤2：准备好时进行增强
一旦你的智能体在本地工作，你就可以“增强”项目以添加所需的基础设施。例如，要添加部署到Google托管的Agent Runtime：
cd my-support-agent
agents-cli scaffold enhance . --deployment-target agent_runtime
此命令分析你现有的项目，并添加必要的部署配置，而不会覆盖你的智能体代码。你也可以单独添加CI/CD：
agents-cli scaffold enhance . --cicd-runner github_actions
这种迭代模式——先原型，后增强——可以防止你在甚至不知道智能体想法是否可行之前，就陷入基础设施决策的泥潭。
关键功能与选择
scaffold 命令提供了几个模板和配置选项。了解这些有助于你评估它是否适合你的用例。
智能体模板：
adk：大多数智能体的标准模板。adk_a2a：用于需要使用A2A协议与其他智能体协调的智能体。agentic_rag：一个专门的模板，包含用于检索增强生成（RAG）的数据摄取管道。这更复杂，需要预置数据存储。
部署目标：
agent_runtime：Google Cloud上的全托管服务。最简单的选项，自动处理会话。cloud_run：基于容器的部署。控制力更强，需要了解Docker。gke：用于在Google Kubernetes Engine Autopilot上进行基于Kubernetes的部署。控制力和复杂性最大。none：无部署脚手架。仅代码。
CI/CD运行器：
github_actions：生成GitHub Actions工作流文件。google_cloud_build：生成Cloud Build配置文件。
会话存储：
对于有状态的智能体，你可以选择会话数据的存储位置：内存中（用于原型）、Cloud SQL或Agent Platform的托管会话。
评估此技能是否适合你的工作流
在决定使用此工具之前，请考虑以下几点：
适合的情况：
- 你正在从头开始一个新的基于ADK的智能体项目。
- 你想为最初作为原型创建的现有ADK项目添加部署或CI/CD。
- 你偏好遵循Google推荐模式的标准化项目结构。
- 你计划部署到Google Cloud（Agent Runtime、Cloud Run或GKE）。
可能不是合适工具的情况：
- 你没有使用Google智能体开发套件（ADK）。此工具特定于ADK生态系统。
- 你需要从一开始就深度定制项目结构。脚手架生成特定的布局；如果你需要完全不同的结构，手动设置可能更好。
- 你希望编写或调试智能体的核心逻辑。此工具用于项目设置，而不是编码。为此，你需要使用
google-agents-cli-adk-code技能。 - 你正在执行部署操作（如
kubectl apply或gcloud run deploy）。那是google-agents-cli-deploy技能的领域。
使用前需要检查什么
如果你认为此工具可能有帮助，以下是一些需要检查和了解的实际事项：
1. 前提条件和安装：
CLI本身需要 uv（一个Python包安装器）来安装。你需要运行 uv tool install google-agents-cli。请确保你首先拥有一个可用的Python环境并安装了 uv。
2. 项目命名约束：
生成的项目名称有严格规则：26个字符或更少，仅限小写字母、数字和连字符。请相应地规划你的名称。
3. --agent-guidance-filename 标志：
脚手架可以为你的AI编码助手（如Gemini CLI、Claude Code等）生成一个指导文件。它会尝试自动检测你的环境，但你也可以用 --agent-guidance-filename 显式指定。这是一个将工具与你现有的AI辅助开发流集成的小而有用的细节。
4. 现有项目的“增强”工作流：
如果你有一个现有的ADK项目（非此脚手架创建），enhance 命令需要知道你的智能体代码在哪里。默认情况下，它会在 app/ 目录中查找。如果你的代码在其他地方（例如 agent/），你必须指定 --agent-directory agent。弄错这一点会导致 enhance 命令错过你的代码或错误地放置文件。
5. RAG项目需要额外步骤：
如果你选择 agentic_rag 模板，脚手架会创建代码结构，但你必须单独预置底层数据存储并摄取数据。文档提供了具体的命令（agents-cli infra datastore 和 agents-cli data-ingestion）。跳过此步骤意味着你的RAG智能体将没有数据可搜索。
6. 仓库和安全信号：
该工具由Google开发，托管在其官方的 agents-cli 仓库中。它采用Apache-2.0许可。该仓库拥有超过3000颗星，表明了显著的社区兴趣。安全级别标记为“低”，这通常意味着它是一个开发工具，默认情况下不处理敏感的运行时机密，但你应该始终审查生成的配置文件，特别是那些与部署和CI/CD相关的文件，以确保它们符合你的安全策略。
7. 理解生成的文件：
脚手架完成后，花点时间查看关键文件。agents-cli-manifest.yaml 对于CLI理解你的项目很重要。Makefile 包含用于本地开发的有用命令。你的智能体核心逻辑将在 app/agent.py 和 app/tools.py 中。环境变量放在 .env 中。了解这个布局有助于你有效地导航和定制。
结论：为你的智能体之旅提供一个结构化的开始
构建一个AI智能体涉及两个不同的阶段：定义智能体做什么的创造性工作，以及将其打包以进行部署的工程工作。Google Agents CLI脚手架工具旨在高效处理第二阶段，为你提供一个坚实的、有明确指导的基础，让你可以将更多时间花在第一阶段上。
它不是一个为你编写智能体的魔法解决方案，但它是一个实用的工具，可以消除项目设置的摩擦。通过遵循“原型优先”的工作流，你可以快速验证你的智能体想法，然后逐步添加你需要的生产级基础设施。如果你在Google ADK生态系统中工作，并希望避免样板代码的麻烦，这是一个值得检查的工具。
你可以在Google Agents CLI脚手架技能页面上找到更多详细信息、完整的命令参考和示例。