智能体开发中的“白纸困境”
你有一个关于AI智能体的绝妙想法。也许它是一个查询内部知识库的客服机器人，或者是一个与本地文件系统交互的编程助手。你坐下来开始构建，结果不到一小时，你就淹没在了配置文件的海洋里。
你需要一个合理的项目结构。你需要决定如何处理状态管理。你需要建立评估框架来测试你的智能体在发布前是否真的有效。你需要弄清楚如何将其部署到云端，同时避免破产或暴露安全漏洞。
大多数开发者会从文档或旧项目中复制粘贴代码片段开始。这导致了一个“弗兰肯斯坦”式的代码库，其中脚手架逻辑与业务逻辑混杂在一起。当需要部署时，你才意识到你没有正确设置CI/CD管道，或者你的本地测试环境与云环境不匹配。
结果呢？你把80%的时间花在与基础设施和样板代码作斗争上，只有20%的时间真正用于构建智能体的智能。
为什么会发生这种情况？
智能体开发本质上很复杂，因为它处于软件工程和概率性AI的交叉点。与标准Web应用不同，智能体涉及：
- 动态状态： 智能体需要在多轮对话中记住上下文。
- 工具集成： 智能体调用外部API和函数。
- 评估： 你需要衡量“正确性”，而这通常是主观的。
- 安全性： 你必须防范提示注入和幻觉。
如果没有标准化的工作流程，每个开发者都会重新发明轮子。你可能构建了一个很棒的智能体，但如果你无法可靠地测试或部署它，它就只能停留在本地实验阶段。
引入结构化生命周期：Google Agents CLI 工作流
如果你正在使用Google的Agent Development Kit (ADK)构建智能体，有一个专门设计的技能可以消除这种摩擦。它被称为 Google Agents CLI 工作流。
这不仅仅是一个库；它是一套指南和一个命令行界面（CLI），强制执行结构化的开发生命周期。它迫使你立即停止编写代码，转而遵循一条经过验证的路径：脚手架 → 构建 → 评估 → 部署 → 观察。
它如何解决样板代码问题
n
这个技能的核心理念是“脚手架优先”。它不会让你随意编写Python文件，而是使用 agents-cli 工具生成一个项目结构，该结构已经包含：
- 评估样板代码： 预配置的数据集和用于测试智能体的指标。
- CI/CD 配置： 为GitHub Actions或Google Cloud Build准备好的管道。
- 项目约定： 处理工具、回调和状态的标准化方式。
通过使用此工作流，你可以确保你的智能体从第一行代码开始就“为生产环境做好准备”。
深入探讨：工作流的7个阶段
该技能定义了一个清晰的路线图。以下是它如何分解开发过程：
阶段 0：理解（最重要的一步）
在你接触终端之前，该技能迫使你回答关键问题。它会查找名为 .agents-cli-spec.md 的文件。如果不存在，你必须创建一个。
你必须定义：
- 问题： 智能体到底要解决什么？
- 外部API： 它需要哪些工具？
- 安全约束： 智能体绝不能做什么？
- 部署偏好： 这是原型还是完整的生产部署？
这一步防止了范围蔓延。它确保你在开始之前确切知道要构建什么。
阶段 1：研究参考示例
不要重新发明轮子。该技能鼓励你查看Google提供的现有示例。例如，如果你正在构建一个对事件做出反应的智能体（如定时任务），你应该研究 ambient-expense-agent 示例。
阶段 2：搭建脚手架
这是CLI大放异彩的地方。你运行一个命令来创建项目结构。
agents-cli scaffold create my-new-agent
此命令设置目录结构、pyproject.toml 和必要的配置文件。它确保你不会遗漏评估设置。
阶段 3：构建
现在你编写代码。该技能提供了关于API模式、工具和回调的指南。它强调正确使用ADK（Agent Development Kit）。
阶段 4：评估
这通常是DIY项目中被跳过的步骤。该工作流强制要求评估。你针对数据集运行智能体以衡量性能。CLI提供命令来运行这些评估并迭代修复问题。
阶段 5：部署
部署是大多数智能体失败的地方。该技能为常见错误（如 403 Forbidden 或超时）提供了具体的故障排除步骤。它将用户友好的术语（如“Vertex AI”）映射到正确的CLI标志（如 --deployment-target agent_runtime）。
阶段 6：发布
如果你希望你的智能体通过Gemini Enterprise Agent Platform对其他智能体或用户可用，此阶段将处理注册事宜。
阶段 7：观察
一旦部署，你需要了解正在发生什么。该工作流包括跟踪、日志记录和监控的设置。
实践示例：构建一个简单的问答智能体
假设你想构建一个回答公司人力资源政策PDF问题的智能体。
- 规格说明： 你编写
.agents-cli-spec.md，说明目标是“HR政策问答”，工具是“PDF阅读器”。 - 搭建脚手架： 你运行
agents-cli scaffold create hr-agent。 - 构建： 你编写代码来加载PDF并使用向量搜索工具。
- 评估： 你创建一个包含10个问题和答案的测试集。你运行评估循环以确保智能体在90%的情况下能正确回答。
- 部署： 你部署到Cloud Run。
如果没有这个工作流，你可能会跳过评估步骤，部署一个会产生幻觉答案的智能体。有了这个工作流，你被迫先证明它有效。
这个技能适合你吗？
这个技能具有很强的导向性。它专为以下开发者设计：
- 正在使用 Google Agent Development Kit (ADK) 构建智能体。
- 希望部署到 Google Cloud（Agent Runtime, Cloud Run, GKE）。
- 重视 结构化开发 胜过临时脚本。
- 需要确保他们的智能体在部署前是 安全且经过评估的。
何时不使用它
- 如果你正在构建一个不需要部署或评估的简单脚本。
- 如果你专门使用其他云提供商（AWS, Azure），尽管脚手架逻辑在本地可能仍然有用。
- 如果你更喜欢完全非结构化的、类似笔记本的开发方式。
评估代码库
该技能由GitHub上的 google/agents-cli 代码库支持。
- Stars: 3,000+（表明社区兴趣浓厚且维护良好）。
- 所有者： Google（官方支持）。
- 许可证： Apache-2.0（宽松许可，商业使用安全）。
- 安全级别： 低（标准CLI工具，但始终要审查依赖项）。
该代码库正在积极维护，是与ADK生态系统交互的官方方式。
设置和先决条件
要使用此技能，你需要：
- Python： 3.10或更高版本。
- uv： 一个快速的Python包安装器。你可以通过
pip install uv安装，或遵循官方指南。 - CLI本身： 安装工具：
uv tool install google-agents-cli
安装后，运行 agents-cli info 以验证安装。
结论
构建AI智能体令人兴奋，但本地脚本与生产就绪的智能体之间的差距是巨大的。Google Agents CLI 工作流通过提供一个严谨、结构化的生命周期来弥合这一差距。它迫使你在编写代码之前就考虑评估和部署，从而为你节省后期通常会发生的痛苦重构。
如果你认真考虑在Google Cloud上构建健壮的智能体，那么审视这个技能是值得迈出的第一步。