agents-cli – 谷歌云智能体开源的官方命令行工具

1. Agents CLI 是什么

Agents CLI 是谷歌云智能体平台推出的官方命令行工具，专为简化 AI Agent 全生命周期管理而设计。该工具将谷歌云十余年的工程化经验打包为 7 个独立的结构化技能模块，覆盖从项目脚手架搭建、ADK 开发、本地评估到 Cloud Run 或 GKE 部署及 Gemini Enterprise 企业级发布的完整流程。开发者可让 AI 编程助手自动完成全流程操作，也可通过人工模式直接接管 CLI 命令。本地开发仅需 AI Studio API Key，无需配置 Google Cloud 项目即可快速进行原型验证，大幅降低企业级 Agent 开发的门槛。

技术定位与领域： 属于 AI Agent 工程化与 DevOps 交叉领域，专注于解决企业级 AI Agent 从开发到部署的标准化流程管理问题。其独特定位在于将云原生基础设施管理与 Agent 开发框架深度融合，提供端到端的工程化解决方案，而非单纯的模型调用工具或开发框架。

研发背景： 由谷歌云智能体平台团队开发，基于谷歌在 Gemini 大模型、ADK（Agent Development Kit）和 A2A（Agent-to-Agent）协议方面的深厚技术积累。研发动机源于企业内部和外部客户在 Agent 生产化过程中遇到的工程化痛点——从原型到生产环境的转化往往需要大量手动配置和文档查阅，缺乏标准化的工具链支持。

核心价值： 解决了 AI Agent 开发中“原型易得、生产难成”的核心矛盾。传统上，开发一个可用的 Agent 原型只需几小时，但将其部署到生产环境、配置监控、建立评估流水线、实现 CI/CD 则需要数天甚至数周。Agents CLI 通过技能包注入机制将工程化知识直接嵌入编程助手，使开发者无需深入了解云服务细节即可完成生产级部署，将整个流程从数天压缩到数小时。

技术特点： 基于 ADK + A2A 的编排架构实现了 Agent 间的标准化互操作，分层云原生设计（编排层、模型层、数据层、可观测性层）确保了企业级可靠性。其核心创新在于上下文压缩机制——通过将云服务的连接逻辑和部署规范预先编码为结构化命令，避免编程助手在每次交互中重复推断基础设施配置，显著降低 Token 消耗并提升输出确定性。

2. 主要功能

• 技能包注入机制： 将谷歌云的工程化知识打包为 Workflow、ADK Code、Scaffold、Eval、Deploy、Publish、Observability 七个结构化技能模块，通过 npx skills add 注入 Gemini CLI、Claude Code、Codex 等编程助手的上下文，使其无需自行推断云服务连接逻辑即可生成准确的 Agent 代码和配置，这是该工具区别于传统 CLI 的核心差异化能力。

• 项目脚手架生成： 提供 scaffold 命令，支持一键创建标准化 Agent 项目，自动生成包含标准目录结构、ADK 基础代码、依赖文件和默认配置的全新项目。同时支持为现有项目追加部署、CI/CD、RAG 能力，以及将项目升级至新版规范，确保项目结构的一致性和可维护性。

• 本地开发与调试环境： 内置 run 命令支持单条指令快速冒烟测试，playground 可启动本地 Web 可视化界面（默认地址 http://127.0.0.1:8000）进行交互式调试，支持在浏览器中选择 Agent 并直接输入指令进行实时测试。同时提供 install 和 lint 命令管理依赖与代码质量，形成完整的本地开发闭环。

• 评估与验证流水线： 通过 eval run 运行基于数据集的评估流水线，按预设指标和评估集测试 Agent 表现，并通过 eval compare 对比不同版本结果。支持 LLM-as-Judge 和轨迹评分（Trajectory Scoring）两种评估模式，前者利用大模型对输出质量进行评判，后者通过分析 Agent 执行轨迹评估行为一致性，确保部署前的质量保障。

• 多目标自动化部署： deploy 命令支持一键部署至三类目标环境：Agent Runtime（自动处理记忆与编排）、Cloud Run（无服务器容器化，适合快速上线）或 GKE（Kubernetes 集群，适合大规模生产环境）。每种环境都预配置了最佳实践参数，开发者无需深入了解容器编排细节。

• 企业级发布与发现： publish gemini-enterprise 可将部署后的 Agent 注册到 Gemini Enterprise 平台，使其在组织内可被搜索和调用，实现企业内部 Agent 资产的统一管理和复用，这是面向大型企业组织的关键功能。

• 基础设施即代码： 提供 infra 系列命令生成 Terraform 配置、搭建 staging/prod 的 CI/CD 流水线，配置向量存储等 RAG 数据基础设施及数据接入管道，将基础设施管理纳入 Agent 开发的标准流程，满足 DevOps 团队对基础设施可重复性和版本控制的要求。

3. 应用场景

• 企业级多 Agent 系统开发： 需要从零搭建可投产的多 Agent 系统，涉及编排、记忆、评估和监控的复杂场景。Agents CLI 的 scaffold 命令可快速生成标准项目结构，eval 流水线确保 Agent 行为一致性，deploy 命令一键部署至生产环境，适合客服系统、自动化流程引擎等企业级应用。

• 快速原型验证： 开发者想在本地快速测试 Agent 逻辑，无需配置云服务即可运行和评估。使用 AI Studio API Key 进行本地认证，通过 playground 进行交互式调试，可在数小时内完成从构思到可运行原型的验证，适合产品经理、技术主管进行概念验证。

• AI 编程助手增强： 让团队现有的编程助手（Cursor / Claude Code）获得 Google Cloud 部署专家能力。通过技能包注入，编程助手可以自动生成正确的 Terraform 配置、CI/CD 流水线和部署脚本，避免开发者手动查阅文档和配置参数，适合 DevOps 团队提升效率。

• DevOps 自动化流水线： 需要自动生成 Terraform 配置、CI/CD 流水线，实现 Agent 应用的基础设施即代码管理。infra 系列命令可一键生成 staging/prod 环境的完整基础设施配置，包括向量存储、数据接入管道等 RAG 基础设施，适合追求标准化和可重复性的工程团队。

• 组织级 Agent 发布与管理： 将内部开发的 Agent 注册到 Gemini Enterprise，实现企业内统一发现和使用。通过 publish gemini-enterprise 命令，企业可以将不同团队开发的 Agent 资产集中管理，支持组织内搜索和调用，避免重复开发，适合大型企业的 AI 卓越中心（CoE）团队。

4. 如何使用

1. 环境准备： 确保本地已安装 Python 3.11 或更高版本、uv（Python 包管理器）和 Node.js（用于技能包安装）。建议使用 Linux 或 macOS 系统以获得最佳兼容性，Windows 用户可通过 WSL2 运行。验证命令：python --version && uv --version && node --version。

2. 安装 CLI 与技能包： 执行 uvx google-agents-cli setup 一键安装命令行工具，该命令会自动检测本地环境并安装所需依赖。安装完成后，Workflow、ADK Code、Scaffold、Eval、Deploy、Publish、Observability 七个结构化技能包会同步部署到你的编程助手（如 Gemini CLI、Claude Code 或 Cursor）。

3. 仅安装技能包（可选）： 若已有其他工具管理 CLI，可运行 npx skills add google/agents-cli 单独向编程助手注入技能知识。这种方式适用于团队中已有标准化 CLI 管理工具的场景，只需让编程助手获得 Google Cloud 部署专家能力即可。

4. 身份认证： 运行 agents-cli login --interactive 通过浏览器完成 Google Cloud 交互式登录。对于本地开发场景，可执行 export GEMINI_API_KEY="your-key" 使用 AI Studio API Key 进行认证，无需配置 GCP 项目即可快速原型验证，这是降低试用门槛的关键设计。

5. 创建项目： 执行 agents-cli scaffold my-first-agent 自动生成包含标准目录结构、ADK 基础代码、依赖文件和默认配置的全新 Agent 项目。生成的目录结构包括 agent/（Agent 代码）、tests/（测试文件）、config/（配置文件）等标准模块。

6. 安装依赖： 在项目根目录运行 agents-cli install，工具会自动解析并安装 requirements.txt 或 pyproject.toml 中声明的 Python 依赖包。建议在运行前确认网络连接稳定，因为部分依赖包体积较大。

7. 本地调试： 执行 agents-cli playground 启动本地 Web 可视化界面（默认地址 http://127.0.0.1:8000），在浏览器中选择 Agent 并直接输入指令进行交互式调试。此模式无需编写测试脚本，适合快速验证 Agent 逻辑的正确性和响应质量。

最佳实践： 建议在首次使用时先通过 agents-cli info 查看系统状态和安装配置；在团队协作中，将 agents-cli scaffold 生成的项目结构纳入版本控制，确保团队成员使用统一的项目模板。

5. 优缺点分析

6. 同类工具对比

选型建议： 对于已经或计划使用 Google Cloud 的企业团队，Agents CLI 是首选工具。其与 Google Cloud 生态的深度集成（Cloud Run、GKE、Gemini Enterprise）提供了其他工具无法比拟的部署便利性和企业级特性。特别是需要多 Agent 编排、企业级发布和全链路可观测性的场景，Agents CLI 的技能包机制和评估流水线能显著提升开发效率。

对于以本地开发为主、不需要云部署的团队，Cursor CLI 或 LangChain CLI 可能更合适。Cursor CLI 在代码编辑和重构方面有独特优势，而 LangChain CLI 在 Agent 框架灵活性和社区资源方面更具优势。如果团队主要使用非 Google 云平台（如 AWS 或 Azure），则需要考虑其他方案，因为 Agents CLI 的部署目标仅限于 Google Cloud 环境。

7. 编辑点评

从技术创新角度评估，Agents CLI 最值得关注的不是其 CLI 功能本身，而是技能包注入机制这一设计范式。传统上，CLI 工具只是提供一组命令供开发者手动执行，而 Agents CLI 将工程化知识编码为结构化技能模块，直接注入 AI 编程助手的上下文空间。这种“知识即代码”的思路本质上是对 AI 编程助手能力的增强——不是简单地提供命令列表，而是让编程助手理解何时、为何以及如何使用这些命令。这种设计理念在开源项目中尚属首次，具有重要的示范意义。

从实用价值来看，Agents CLI 精准地解决了 AI Agent 开发中的“最后一公里”问题。当前 AI Agent 框架（如 LangChain、AutoGen、CrewAI）在原型开发阶段表现出色，但在生产化部署方面普遍存在短板——缺乏标准化的评估流水线、部署配置复杂、可观测性不足。Agents CLI 通过端到端的工具链填补了这一空白，特别是其内置的评估流水线和轨迹评分机制，为 Agent 的质量保障提供了可量化的手段，这在生产环境中至关重要。

适用人群定位明确：主要面向使用 Google Cloud 的企业开发团队，特别是那些需要将 AI Agent 从原型快速转化为生产服务的 DevOps 和 AI 工程师。对于个人开发者或小团队，其本地零成本起步的特性也降低了试用门槛，但需要接受后续部署必须依赖 Google Cloud 的限制。

未来发展潜力方面，Agents CLI 有望成为 Google Cloud AI Agent 生态的入口工具。随着 A2A 协议和 ADK 的普及，Agents CLI 可能扩展为跨平台的多 Agent 管理工具，甚至支持非 Google Cloud 的部署目标。此外，技能包机制的开放性也为社区贡献自定义技能包提供了可能，这将进一步丰富其生态。

8. 常见问题 FAQ

Q：Agents CLI 是否支持非 Google Cloud 平台的部署？
A：目前不支持。Agents CLI 的 deploy 命令仅支持 Agent Runtime、Cloud Run 和 GKE 三类 Google Cloud 环境。如果需要在 AWS 或 Azure 上部署，建议考虑 LangChain CLI 或其他云平台的原生工具。

Q：本地开发必须要有 Google Cloud 项目吗？
A：不需要。本地开发仅需 AI Studio API Key，通过 export GEMINI_API_KEY="your-key" 即可完成认证，无需创建或配置 GCP 项目。只有在需要部署到生产环境时才需要 Google Cloud 项目。

Q：技能包注入会影响编程助手的其他功能吗？
A：不会。技能包注入只是为编程助手添加了额外的上下文知识，不会覆盖或修改其原有功能。编程助手在处理非 Agent 相关任务时，仍然会使用其默认的知识和能力。

Q：Agents CLI 与 LangChain 的关系是什么？
A：两者是互补关系。Agents CLI 基于 Google 的 ADK 框架，而非 LangChain。但 Agents CLI 生成的 Agent 项目可以集成 LangChain 的工具和链，只要通过 ADK 的 Python API 进行封装即可。对于已经使用 LangChain 的团队，可以通过 ADK 的兼容层实现迁移。

Q：如何自定义评估指标？
A：目前评估指标主要通过内置的 LLM-as-Judge 和轨迹评分实现。如果需要自定义指标，需要修改评估配置文件中的指标定义，或编写自定义评估回调函数。官方文档对此部分说明不够详细，建议参考 GitHub 仓库中的示例代码。

Q：Agents CLI 是否支持 Windows 系统？
A：支持，但建议通过 WSL2（Windows Subsystem for Linux）运行以获得最佳体验。原生 Windows 环境可能存在路径兼容性和依赖安装问题，特别是在使用 Node.js 技能包安装时。

Q：技能包可以自定义开发吗？
A：目前技能包由官方维护，暂不支持社区自定义技能包。但官方表示未来可能开放技能包开发接口，允许开发者贡献自定义技能模块。当前可以通过修改 .cursorrules 或编程助手的配置文件实现类似效果。

9. 项目地址

• 项目官网： https://google.github.io/agents-cli/
• GitHub 仓库： https://github.com/google/agents-cli
• Google Cloud 文档： https://cloud.google.com/agent-platform/docs/agents-cli-overview