企业官网建设流程全解析

agents-cli 完全指南：让任意 Coding Agent 掌握 Google Cloud AI Agent 的构建、评估与部署

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli

本指南以本仓库根目录的 README 为主体，系统讲解agents-cli的定位、安装方式、7 大 Agent Skills、完整 CLI 命令体系、底层架构与常见问题，并结合仓库源码（入口、setup、scaffold、eval、deploy、publish、extension 等模块）进行源码级补充。读完本文，你将掌握：用一行命令为你的 Coding Agent（Antigravity CLI、Claude Code、Codex 或任意其他 Agent）装上 Google Cloud AI Agent 全生命周期能力，并独立完成从脚手架创建、本地运行、评估、部署到发布的全流程。

一、agents-cli 是什么：为 Coding Agent 打造的"专业工具包"

agents-cli（Agents CLI in Agent Platform）不是一个新的 Coding Agent，而是服务于 Coding Agent 的 CLI 与 Skills 工具集。它的目标非常明确：把你的常用编程助手变成构建、扩展、治理和优化企业级 Agent 的专家，让你不必亲自掌握每一个 CLI 和服务。

定位差异：Antigravity CLI、Claude Code、Codex 是"编程 Agent 本体"；agents-cli是"给编程 Agent 用的工具"，提供让它更擅长在 Google Cloud 上构建、评估、部署 ADK Agent 的 CLI 命令和技能。

在仓库源码中，这一设计有直接体现：src/google/agents/cli/main.py 是整个 CLI 的 Click 根组，它通过自定义的_MainGroup（继承自LazyGroup）惰性注册所有命令——命令模块只有在用户真正调用（或请求其--help）时才被导入，保证冷启动性能。而在 src/google/agents/cli/setup/cmd_setup.py 的 docstring 中，setup 命令会检测已安装的 Coding Agent（Claude Code、Antigravity CLI、Cursor、Windsurf 等）并为之安装 ADK 开发技能，这正是"为 Agent 赋能"理念的实现。

agents-cli构建在 Google ADK（Agent Development Kit）之上，可无缝配合以下工具使用：

• Antigravity CLI
• Claude Code
• Codex
• 以及其他任意 Coding Agent

二、快速开始：3 步构建你的第一个 Agent

2.1 前置条件

开始之前，请确保环境满足以下要求：

• Python 3.11+
• uv（Python 包与项目管理工具）
• Node.js（用于npx skills安装技能）

2.2 第 1 步：安装

推荐方式——一键完成 CLI 安装与 Skills 安装：

uvx google-agents-cli setup

setup命令内部按固定流程执行，源码见 src/google/agents/cli/setup/cmd_setup.py：

1. 打印 Logo：输出 ASCII 艺术字与随机箴言；
2. 认证检查：检测 Google Cloud / AI Studio 认证状态；
3. CLI 安装：通过uv tool install google-agents-cli安装工具本体，若已安装会检查版本更新；
4. Skills 安装：通过npx skills add将技能安装到检测到的 Coding Agent；
5. Antigravity 技能链接：将全局技能镜像到 Antigravity 的技能目录（~/.gemini/config/skills、~/.gemini/antigravity-cli/skills等）；
6. 汇总输出。

setup支持多个实用参数：

只安装 Skills 的方式——如果你的 Coding Agent 已具备，只需技能：

npx skills add google/agents-cli

值得强调的是，setup的技能安装具备三级回退机制（见_install_skills函数）：优先从远程源通过npx skills add安装；失败后回退到使用随 CLI 捆绑的本地技能包；若连npx都不可用，则直接将捆绑技能复制到~/.agents/skills技能存储目录。这意味着即使离线环境也能完成技能安装。

2.3 第 2 步：打开你的 Coding Agent

启动 Antigravity CLI、Claude Code、Codex，或任意你偏好的 Coding Agent。

2.4 第 3 步：构建第一个 Agent

直接对你的 Coding Agent 下达自然语言指令即可，例如：

"Use agents-cli to build a caveman-style agent that compresses verbose text into terse, technical grunts"

（用 agents-cli 构建一个"穴居人风格"的 Agent：把冗长文本压缩成简洁、技术化的咕哝。）

Coding Agent 会自动加载已安装的 skills，按照 workflow skill 中定义的开发阶段（理解需求 → 学习配方 → 脚手架 → 构建 → 评估 → 部署 → 发布 → 观测）逐步执行。

三、Agent Skills：你的 Coding Agent 将学会的 7 项技能

agents-cli通过 Skills 将领域知识注入 Coding Agent。这些技能的元数据（SKILL.md）全部打包在仓库中，安装后即成为 Agent 的行为指南：

3.1 workflow skill：贯穿全程的"指挥中心"

skills/google-agents-cli-workflow/SKILL.md 是所有技能的入口，定义了 8 个开发阶段：

该 skill 还特别强调：在编写任何 Agent 代码之前，必须先确保存在脚手架项目，否则会丢失评估样板代码、CI/CD 配置和项目约定。

3.2 eval skill：质量飞轮方法论

skills/google-agents-cli-eval/SKILL.md 定义了"质量飞轮"（Quality Flywheel）四阶段循环：准备数据 → 运行评估 → 分析失败 → 优化与代码修复，每阶段既有默认路径（Coding Agent 直接执行），也有可选的云端评估服务命令（eval dataset synthesize、eval analyze、eval optimize、eval submit）。

3.3 deploy skill：部署目标决策矩阵

skills/google-agents-cli-deploy/SKILL.md 给出了三大部署目标的对比矩阵：

三个目标均为容器化部署，任何语言（Python、Go、Java、TypeScript）都适用。

3.4 Skills 在仓库中的组织

所有技能的内容均可在仓库中直接查阅：skills/ 目录包含 7 个技能包，每个技能包含SKILL.md主文件与references/参考资料目录（如 eval 技能含 dataset schema、metrics、LLM-as-judge 等 6 份参考文档）。这些技能同时被打包进 CLI（src/google/agents/cli/skills/data/），使setup可以离线回退安装。

四、CLI 命令全景：从脚手架到发布的一站式命令

4.1 核心命令速览

4.2 全部命令（按功能分组）

认证

脚手架（Scaffold）

开发（Develop）

评估（Evaluate）

部署与发布（Deploy & Publish）

其他

4.3 命令体系背后的惰性加载机制

命令之所以能如此"轻快"，源于 src/google/agents/cli/_click.py 中的LazyGroup：子命令模块只有在真正被调用（或请求其--help）时才导入，父组的--help只渲染注册时提供的short_help字符串，不触发任何导入。例如 scaffold/cmd_scaffold_group.py 中，create、enhance、upgrade三个子命令都以add_lazy_command("create", "google.agents.cli.scaffold.commands.create:create", ...)的形式注册。

4.4create命令：模板化创建 Agent 项目

agents-cli create <name>基于 src/google/agents/cli/scaffold/agents/ 下的模板创建项目，支持 ADK 的 Python/Go/Java/TypeScript 多语言模板以及空模板。核心参数（源码见 src/google/agents/cli/scaffold/commands/create.py 的shared_template_options装饰器）：

部署目标与会话类型等常量定义于 src/google/agents/cli/scaffold/utils/template.py：DEPLOYMENT_TARGETS定义了agent_runtime（Vertex AI 托管平台）、cloud_run（Serverless 容器平台）、gke（托管 Kubernetes/Autopilot）、none（不部署云端）四种目标；SESSION_TYPES定义了in_memory（无状态、数据在内存）、cloud_sql（PostgreSQL 持久化）、agent_platform_sessions（托管会话服务）三种会话类型；SUPPORTED_LANGUAGES支持 Python、Go、Java、TypeScript 四种语言。该文件还维护了AGENT_ALIASES兼容映射（adk_base、adk_a2a_base、adk_a2a→adk），保证旧参数名可用。

4.5eval命令组：评估全流程

src/google/agents/cli/eval/cmd_eval_group.py 注册了完整的评估命令组。核心命令eval run的参数（src/google/agents/cli/eval/cmd_run.py）：

• --dataset：指向 JSON 评估数据集（默认使用agents-cli create脚手架生成的文件）；
• --output：结果与产物保存目录（默认artifacts/grade_results/）；
• --metrics：逗号分隔的指标列表（如final_response_quality,grounding）；
• --config：包含指标与自定义指标配置的 JSON/YAML 文件；
• --project：评分用 GCP 项目 ID（覆盖GOOGLE_CLOUD_PROJECT与 ADC）；
• --region：评分区域。

4.6deploy与publish

• agents-cli deploy（src/google/agents/cli/deploy/cmd_deploy.py）将 Agent 部署到所选目标，内部封装了 Docker 构建、Terraform 基础设施供给与部署状态轮询；
• agents-cli publish gemini-enterprise（src/google/agents/cli/publish/cmd_publish_group.py）将已部署的 Agent Runtime 注册到 Gemini Enterprise。

4.7info与update

• agents-cli info（src/google/agents/cli/info/cmd_info.py）一次性输出 CLI 版本、安装路径、项目根目录、已安装技能（按作用域分组）、已加载扩展与版本冲突警告，支持--json输出；
• agents-cli update强制重装技能到所有 IDE。

五、架构：agents-cli 所构建的 Google Cloud Agent 技术栈

这张架构图展示了agents-cli所构建的 Google Cloud Agent 技术栈的完整分层：

• 用户与客户端层：用户通过 Client 发起交互；
• Agent 编排层：使用 Google 的 ADK 与 A2A 构建，可选使用现成示例；
• 模型层：LLM，依托 Model Garden（模型花园）提供能力；
• 评估层：Agent Platform Evaluation，验证 Agent 性能；
• 部署层：Agent Runtime，提供 Cloud Run（容器化部署）与 GKE 两种运行选项；
• 辅助支撑层：IaC & CI/CD（Terraform 与 CI/CD 流水线）、可观测性（OpenTelemetry 与日志）、数据层（向量存储、监控、数据存储与分析）。

从原型到生产的自动化流水线如图：

图中展示了完整的 CI/CD 流程：CI 阶段在 Pull Request 时触发，执行单元测试与集成测试（配置见deployment/ci/pr_checks.yaml）；CD 阶段在合并到 main 分支时触发，流水线 #1 完成容器构建 → 部署到 staging → 负载测试（deployment/cd/staging.yaml），流水线 #2 经人工审批后部署生产（deployment/cd/deploy-to-prod.yaml）。

六、常见问题（FAQ）解析

6.1 这是 Antigravity CLI、Claude Code 或 Codex 的替代品吗？

不是。agents-cli是为 Coding Agent 服务的工具，它本身不是 Coding Agent。它提供让 Coding Agent 更擅长在 Google Cloud 上构建、评估和部署 ADK Agent 的 CLI 命令与技能。

6.2 与直接使用adk有何不同？

ADK 是 Agent 框架，agents-cli则为 Coding Agent 提供端到端构建、评估、部署 ADK Agent 的技能与工具。

6.3 需要 Google Cloud 吗？

本地开发（create、run、eval）不需要——可以使用 AI Studio API Key 在本地通过 ADK 运行 Gemini。部署与云端功能则需要 Google Cloud。

6.4 可以用于已有 Agent 项目吗？

可以。agents-cli scaffold enhance能为已有项目添加部署与 CI/CD 能力。

6.5 不使用 Coding Agent 也能用吗？

可以。CLI 可独立运行——你可以直接在终端执行agents-cli scaffold、eval、deploy及其他所有命令；技能只是让 Coding Agent 更容易替你完成这些操作。

6.6 如何扩展更多技能？

agents-cli的技能覆盖 Agent 构建生命周期（scaffold、ADK 代码模式、评估、部署、发布、可观测性）。对于相邻需求，可以并行安装其他技能套件，例如通用软件工程工作流（构思、规格门禁、规划、代码评审）与 Google Cloud 基础技能（BigQuery、Cloud Run、Firebase、GKE）。

七、扩展机制：为其他框架提供生命周期支持

除了内置技能，agents-cli还提供了扩展机制（见 schemas/agents-cli-extension-v1alpha1.schema.json 定义的扩展清单 Schema），允许第三方为其他 Agent 框架接入同一套生命周期命令。仓库内置的 LangChain 扩展（extensions/langchain/template/agents-cli-extension.yaml）就是一个完整示例：它通过commands.override把playground、run、publish.gemini-enterprise、eval.generate等命令重写为 LangChain/LangGraph 的实现，并将依赖 ADK 内省能力的eval.dataset、eval.optimize标记为不支持。

扩展加载逻辑在 src/google/agents/cli/main.py 的_apply_extensions中实现：CLI 启动时会从项目根目录与用户配置目录发现扩展，检查其声明的requires.agents-cli版本区间，将扩展命令安装（或按"阻塞"策略替换）为内置命令，并以 WARNING 日志显式提示每个命令覆盖的来源（扩展名 + 作用域），避免静默接管。

结语

agents-cli将"构建、评估、部署 Google Cloud Agent"这一复杂的端到端工程，压缩为 Coding Agent 可以直接调用的命令与技能。无论你偏好 Antigravity CLI、Claude Code、Codex 还是其他编程助手，只需一条uvx google-agents-cli setup，即可让它在几分钟内掌握 ADK 项目脚手架、质量飞轮评估方法论、多目标部署、Gemini Enterprise 发布与全栈可观测能力，把精力重新聚焦到 Agent 本身的业务逻辑上。安装与使用过程中如有问题，仓库中的 CONTRIBUTING.md、RELEASE_NOTES.md 以及各技能的references/目录都是深入了解的起点。

【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli