企业官网建设流程全解析

agents-cli vs ADK vs Claude Code：三者关系一次讲透，新手避坑指南

【免费下载链接】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

agents-cli是 Google 官方的 CLI + 技能包（skills）工具，它能把Claude Code等任意编码助手变成「构建 AI 智能体专家」：一键生成智能体项目骨架、自动跑评测、一键部署到 Google Cloud。而ADK（Agent Development Kit）是真正用来写智能体代码的框架。一句话记住分工：Claude Code 是开车的人，agents-cli 是导航加规则手册，ADK 是那辆车。本文用 4 张官方架构图 + 5 个高频坑位，带你一次讲透三者关系。

🗺️ 一图看懂：三者的分工边界

先建立全局视角。下图是 Google Cloud 智能体平台的高层架构，注意中间「LLM Orchestration」区域——平台允许你选择任意智能体框架，ADK 是其中默认且最完整的一档（支持 ADK、A2A、LangGraph 等）：

三者定位对比：

🧰 agents-cli 到底帮你做了什么

agents-cli不是编码助手，也不是 ADK 的替代品——它是架在两者之上的「全生命周期工具层」，覆盖脚手架 → 构建 → 评测 → 部署 → 发布 → 可观测性 8 个阶段（完整生命周期见docs/src/guide/lifecycle.md）。

安装只需一条命令，它会把 CLI 和 7 个技能包一并装入你的编码助手：

uvx google-agents-cli setup

7 个技能包各司其职，本质是「写给编码助手的专家手册」，每个技能入口都在 skills 目录下，例如开发流程总入口skills/google-agents-cli-workflow/SKILL.md、ADK 代码模式速查skills/google-agents-cli-adk-code/SKILL.md、部署决策矩阵skills/google-agents-cli-deploy/SKILL.md。

日常你高频接触的只有 4 个动词：

🔧 ADK：真正写代码的框架

智能体的本体代码由 ADK 编写：一个模型（model）+ 一段指令（instruction）+ 一组工具函数（tools）+ 一个App包装，核心逻辑通常不到 30 行。下图展示了 ADK 在整个平台中的位置——ADK 与 A2A 协议处于「Agent Orchestration」核心层，上方接评测（Evaluation）与模型服务（Model Garden），下方接三种部署目标：

关键点：ADK 可以脱离 agents-cli 单独使用，但那样你得自己手写评测配置、CI/CD、Terraform 部署脚本——而这正是 agents-cli 技能包存在的意义。

🤖 Claude Code：它只是「开车的」

新手最常见的误解是以为 agents-cli 要和 Claude Code「二选一」。完全相反：agents-cli 是装进 Claude Code 里的技能。

安装后，在 Claude Code 中输入/skills，你会看到google-agents-cli-workflow等技能已就绪。之后直接说人话即可，例如：

「用 agents-cli 帮我构建一个回答文档问题的客服智能体」

Claude Code 会自动按技能包指导：先澄清需求 → 调scaffold create生成骨架 → 写 ADK 代码 → 跑eval run→ 你确认后再deploy。脚手架源码实现可参考src/google/agents/cli/scaffold/commands/create.py，生成后的目录结构详解见docs/src/guide/project-structure.md。

⚠️ 新手必踩的 5 个坑，逐一排雷

1. 把 agents-cli 当成 Claude Code 的竞品— 错。它不能对话、不能写代码，它让 Claude Code 更懂「怎么在 Google Cloud 上造智能体」。
2. 跳过脚手架直接手写— 手动搭建会漏掉评测样板、CI/CD 配置和项目清单（manifest）约定。哪怕只是快速实验，也请先scaffold create。
3. 以为起步必须开通 Google Cloud 账号— 本地开发（create/run/eval）只需一个免费的 AI Studio API Key；只有部署阶段才需要 GCP 项目。
4. 用 pytest 断言 LLM 输出内容— 大模型输出是非确定性的，行为验证应交给eval run的 LLM-as-judge 指标，pytest 只测代码正确性。
5. 评测没迭代几轮就急着上线— 技能包明确要求「部署必须经人工确认」，且评测阶段通常要迭代 5–10 轮，别嫌烦。

🚀 从原型到生产：一条完整链路

当你用scaffold带部署目标创建项目时，CI/CD 流水线会自动生成，节奏非常清晰——提 PR 触发 CI（单测 + 集成测试），合并主干触发 CD（构建镜像 → 部署 Staging → 压测），生产部署前还需人工审批：

📡 上线之后不慌：可观测性兜底

部署只是开始。agents-cli 的google-agents-cli-observability技能包会把智能体的每次调用接入 Cloud Trace 追踪、Cloud Logging 提示词日志，并汇入 BigQuery 做行为分析——出了问题可以精确回放整条推理链路，生产数据还能反哺下一轮评测集（详见docs/src/guide/observability/index.md）：

写在最后

记住这张「分工三角」就不会再迷路：

• 想写智能体代码？→ 那是 ADK 的活
• 想让编码助手别踩坑？→ 那是 agents-cli 技能包的活
• 想下达指令、动手执行？→ 那是 Claude Code 的活

三条命令上手：

uvx google-agents-cli setup # 安装 CLI + 技能 agents-cli scaffold my-agent # 生成项目 agents-cli eval run # 跑评测

新手教程（含逐步骤演示）见docs/src/guide/getting-started.md，进阶用法可浏览docs/src/guide/下的 deployment、evaluation 等章节。装好技能后，剩下的交给你的编码助手即可 🚀

【免费下载链接】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