本文由 莫潇羽@无忆研习社（www.wuyi.wiki） 撰写，转载请注明出处。

快速摘要

这篇文章用一句话能讲完的核心结论是：agents-cli 不是又一个新的 AI 编程助手，而是一组"给编程助手喂的工程化知识包" —— 它把 Google Cloud 上构建、评估、部署 Agent 的全套套路打包成 7 个 Skill，塞进 Gemini CLI / Claude Code / Codex / Cursor / Antigravity 等任意一个编程助手的"记忆"里，让原本需要工程师啃几十页文档才能完成的"从 demo 到生产"的链路，缩成一句自然语言指令。

它解决的真问题是：Agent 圈"模型越来越聪明，工程化却越来越碎片化"。开发者和编程助手都在反复消耗 token 去推断 ADK 的 API、评估集格式、Cloud Run 的发布参数、Cloud Trace 的接线姿势。agents-cli 把这些隐性知识显性化成 SKILL.md，让编程助手按部就班地走流程，而不是凭直觉瞎猜。

这篇文章会把它拆透：从 agents-cli 与 Google ADK 的关系、7 个 Skill 各管哪段、uvx google-agents-cli setup 一行命令背后到底发生了什么，到本地 Playground 调试、评估流水线、上 Cloud Run / Agent Runtime / GKE 三种部署路径、Cloud Trace + BigQuery 的可观测性，再到 Gemini Enterprise 注册、Human Mode 兜底，最后是我自己跑下来的一些感受和坑。 想看完整拆解，往下翻。

一、为什么大多数 Agent demo 永远飞不出实验室

1.1 demo 容易，落地难，这事其实有点"反直觉"

过去两年，我自己折腾过的 Agent demo，少说也有十几个：天气问答、文档问答、客服路由、报销审核、PR 自动 review。每一个在本地都能跑得有模有样，演示视频也能剪得很好看。

但等真要把它放到一个对外的环境里，让别人随便提问、让别人调用接口，问题就开始一个接一个冒出来：

• 模型偶尔抽风返回 JSON 格式不对，后端炸了。
• 同样一个问题，今天答得很好，明天答得跟换了个人似的，没法解释。
• 加了第二个工具，整个工具调用链断了，定位半天也不知道为什么。
• 想配置一个监控仪表盘看看每天调用了多少次、平均延迟多少、哪些工具出错，发现根本没有现成的"接线图"。

这一系列问题的根源都是同一个：Agent 从原型走到生产，中间隔的不是模型能力，而是工程化基础设施。

模型这一两年进步飞快，可周边的脚手架、评估、部署、可观测性，每家厂商都自己造一套轮子，几乎每两周就有新工具冒出来。开发者光是"决定该用哪一套"就要耗掉小半天，更别提把它们串成一条稳定的流水线。

1.2 工具链碎片化把人逼疯

我之前给团队写过一份"上线 Agent 需要打通的 12 件事"的 checklist，大概长这样：

每一格背后都对应一份官方文档，少则几千字，多则几万字。让一个工程师把这条路从头啃到尾，平均怎么也得一两周。

更要命的是，这一两周的"啃文档时间"其实并没有为业务增加任何价值 —— 它只是在补齐"上线的最低门槛"。

1.3 编程助手陷入"上下文饥渴"

近一年我们这种重度依赖 AI 编程助手的人，应该都体会到一个现象：让编程助手干工程化的事情，token 烧得特别快。

为什么？因为编程助手并不天然知道你公司在用 GKE 还是 Cloud Run，也不知道你这个 Agent 的评估集应该长什么样，更不知道你上一次部署用的是哪条命令。它每次都要重新读文档、重新猜参数、重新试错。

我自己有一次让 Claude Code 帮我把一个本地跑得好好的 Agent 部署到 Cloud Run，它先去搜了 Dockerfile 的写法，又翻 Cloud Run 的 CLI，再去推断要不要加 IAM 权限，最后还得我手动告诉它 ADK 应该用哪个端口。一通操作下来，token 翻了好几倍，最后还是我自己开着官方文档对着改才搞定。

这种"上下文饥渴"是工程化场景下 AI 编程助手最大的瓶颈。模型再聪明，没看过你这个生态的隐性约定，也只能瞎蒙。

1.4 这才是 agents-cli 真正想解决的问题

知道了上面这些痛点，再回头看 google/agents-cli 这个项目，它的定位一下子就清晰了：

• 它不打算再造一个 Agent 框架（这事 ADK 已经在做）。
• 它也不打算再造一个新的编程助手（Gemini CLI、Claude Code 已经够多了）。
• 它干的是中间那一层：把"在 Google Cloud 上做 Agent 的所有隐性工程化知识"打包成可被编程助手识别的 Skill 文件，让你的编程助手一上手就具备工程化经验，不用再现场推断。

用一句莫潇羽@无忆研习社愿意反复念叨的话来说：agents-cli 让 AI 编程助手不再当"刚入职的实习生"，而是当一个"在 Google Cloud 上做了几年 Agent 的资深工程师"。

1.5 顺便说一下"AI 编程助手 + 工具厂商"这种新模式

这件事还可以从更大的视角去看。

过去厂商发布一个新工具，标准动作是写文档、出 SDK、做 codelab。开发者怎么用是开发者的事。

但今天主流开发者群体已经有相当一部分在重度依赖 Gemini CLI、Claude Code、Codex 这种 AI 编程助手了。文档写得再好，也未必能被这些助手"看懂"和"用对"。

所以现在出现了一种新模式：厂商不只是给人写文档，还得给 AI 编程助手写 Skill。Skill 这种声明式、紧凑、面向 LLM 的知识包，正在成为厂商发布工具的"第二种交付物"。

agents-cli 就是这种新模式的一个非常典型的样本：与其等社区慢慢摸索"怎么在 Google Cloud 上做 Agent"，不如把这套知识自己整理成 Skill，主动喂给所有支持 Skill 标准的编程助手。

这种思路其实非常聪明 —— 它绕开了"做一个新编程助手然后和 Cursor / Claude Code 正面竞争"的红海，转而做"让所有编程助手都变好"的事，朋友变多，敌人变少。

二、agents-cli 究竟是个什么东西

2.1 一句话定位：给编程助手用的工程化技能包 + 独立 CLI

很多人第一眼看到 agents-cli 的名字，下意识会把它当成"又一个 Gemini CLI / Claude Code 的竞争品"。

这是个误会。

agents-cli 自己的定位文档里说得非常直白：它不是编程助手，而是给编程助手用的工具。你的 Gemini CLI 还是那个 Gemini CLI，你的 Claude Code 还是那个 Claude Code，但它们在装上 agents-cli 之后，会突然多出一套"Google Cloud Agent 工程师"的本职技能。

agents-cli 同时具备两层身份：

• 对编程助手而言，它是一组 Skill 文件。装上之后，编程助手"知道了"该怎么搭脚手架、怎么写评估集、怎么发布到 Agent Runtime。
• 对人而言，它本身就是一个独立的命令行工具。你也可以完全抛开编程助手，自己在终端里手敲 agents-cli create my-agent、agents-cli deploy，照样能跑通整条流水线。

这种"双形态"的设计很贴心：它把"让 AI 干活"和"自己干活"的两种路径放在同一个工具下，不强迫你选边。

2.2 agents-cli 与 Google ADK 的关系，一张图讲明白

要真正读懂 agents-cli，绕不开的另一个名字是 Google ADK（Agent Development Kit）。

ADK 是 Google 开源的一个 Agent 框架，目前支持 Python、Java、Go、TypeScript 四种语言。它解决的是"Agent 本身怎么写"的问题：怎么定义工具、怎么组合多 Agent、怎么管理上下文、怎么做工具确认（HITL）。

而 agents-cli 解决的是"围绕 ADK Agent 的一切工程化动作"：怎么生成项目、怎么写评估、怎么部署、怎么观察、怎么注册。

下面这张图，是我自己拿出来给团队同事讲清楚两者边界用的：

flowchart LR
    A[你的业务想法<br/>例：报销审核 Agent] --> B[ADK<br/>负责: Agent 本体<br/>工具/多智能体/上下文]
    B --> C[agents-cli<br/>负责: 工程化外壳<br/>脚手架/评估/部署/观测/发布]
    C --> D[Google Cloud<br/>Agent Runtime / Cloud Run / GKE]
    C -.skills.-> E[编程助手<br/>Gemini CLI / Claude Code / Codex / Cursor]
    E -. 用自然语言驱动 .-> C

一句话总结：ADK 写 Agent 本体，agents-cli 把 ADK Agent 推上生产。两者既独立又互补。

2.3 它在整个 Google Cloud Agent 体系里的位置

把视角再拉高一层，整个 Google Cloud 的 Agent 生态大致是这样的层次：

• 底层模型层：Gemini 系列模型，可以走 AI Studio Key（本地开发）也可以走 Vertex AI（生产）。
• Agent 框架层：ADK，定义 Agent 怎么写。
• 工程化外壳层：agents-cli，负责脚手架、评估、部署、观测、发布。
• 运行时层：Vertex AI Agent Engine（也叫 Agent Runtime）、Cloud Run、GKE 三选一。
• 企业能力层：Gemini Enterprise Agent Platform，提供企业级的目录、IAM、合规、计费、可观测性。

agents-cli 处在这条链路的"工程化外壳"位置，向上承接业务想法，向下衔接运行时和企业能力。

我自己理解这套体系的一个关键转折点是：Google 没有把 agents-cli 做成"一个新框架"，而是做成"一个把现有所有东西串起来的胶水层"。这其实是个挺克制、挺工程化的选择。

2.4 跟其他相似工具的对比

很多朋友会问我：agents-cli 跟我现在用的 LangChain CLI、Vertex AI Agent Starter Pack、AWS Bedrock AgentCore 比，到底差在哪？

我把目前能看到的几个常被拿来对比的工具放在一张表里：

最关键的差异点其实只有一条：agents-cli 是目前少数几个把"Skill 标准"作为一等公民设计进来的工具。这一点决定了它在 AI 编程助手时代的位置 —— 不只是"给人用"，更是"给 AI 用"。

至于"Agent Starter Pack"和 agents-cli 的关系，简单理解就是：Agent Starter Pack 是更早一代的模板集，专注脚手架；agents-cli 是它的"进化版"，把脚手架、评估、部署、可观测性、企业发布全打通成一条流水线，而且原生面向编程助手。

2.5 它适合什么人、不适合什么人

为了避免你看完一头扎进去发现不合适，先把适配人群说清楚：

适合：

• 用 ADK 做 Agent 的人，几乎没有理由不用。
• 用 Gemini CLI / Claude Code / Codex 等编程助手做日常开发的人。
• 想做面向企业内部用户的 Agent，并要用 Google Cloud 跑生产的人。
• 重视工程化、希望评估 / 部署 / 观测都标准化的人。

不太适合：

• 不打算碰 Google Cloud 的人 —— 大部分高级特性会用不上。
• 已经深度绑定 LangGraph / CrewAI / AutoGen 生态的人 —— 短期没有直接收益。
• 只想做"一锤子买卖"的 demo，根本不打算上生产的人 —— agents-cli 在这种场景下是杀鸡用牛刀。

三、Skill 机制：把工程化知识装进编程助手的脑子

3.1 什么是 Agent Skill？为什么这玩意是关键

要理解 agents-cli 的核心创新，得先理解 Agent Skill 这个东西。

Skill 这个标准最早是 Anthropic 提出来的开放格式，本质就是一个文件夹，里面放一份 SKILL.md（写清楚这个技能干什么、在什么情况下触发、要遵守什么规则），可能还有一些辅助脚本和示例。它的妙处在于：

• 任何符合 Skill 标准的工具都能识别它，不绑死任何一家厂商。
• 它是声明式的，不是代码，所以可以塞进任意 LLM 的上下文里被读取。
• 它的触发是基于语义匹配的，编程助手会根据用户当前的任务自动找到合适的 Skill 来"启用"。

目前 Gemini CLI、Claude Code、Codex、Cursor、Antigravity，包括 GitHub Copilot 都支持 Skill 这套机制。这就是为什么 agents-cli 能做到"一份 Skill，到处通用"。

你可以把 Skill 理解成"给 AI 看的内部知识库 + 行为准则"。莫潇羽自己写技能的时候习惯把它类比成新员工入职手册 —— 不是教你怎么写代码，而是告诉你"在我们这家公司，遇到这种问题，标准做法是这样"。

3.1.1 Skill 文件长什么样

为了让你对 Skill 有个具体的感觉，下面是一个典型的 SKILL.md 文件的骨架：

---
name: google-agents-cli-deploy
description: 用于把 ADK Agent 部署到 Agent Runtime / Cloud Run / GKE
  的标准化部署 Skill。触发条件包括："部署 Agent""上 Cloud Run"
  "发布到 Agent Engine"等明确的部署意图……
---

# Deploy Skill

## 一、流程概览
1. 检查项目结构是否符合发布要求
2. 选择部署目标并准备 IaC 配置
3. ……

## 二、Cloud Run 发布
[Cloud Run 特定的步骤、参数、IAM 权限说明]

## 三、Agent Runtime 发布
[Agent Runtime 特定的步骤]

## 四、常见错误与排查
……

可以看到 Skill 文件就是 Markdown，前面一段 YAML frontmatter 说明这个 Skill 的名字、触发条件，下面是结构化的指令。LLM 读到这个文件，就知道在什么场景下要按什么步骤来执行。

这种结构非常适合 LLM 消费 —— 它本身就是被设计来"被读"的，而不是"被执行"的代码。

3.2 七大 Skill 的具体职责，一个个拆给你看

agents-cli 装好之后会往编程助手里塞 7 个 Skill。这 7 个 Skill 不是花架子，每一个都对应 Agent 工程化中的一个真实痛点。我用一张表格先做个总览，然后再挨个聊：

3.2.1 Workflow Skill：流水线的总指挥

它最关键的作用是"让 AI 学会按顺序做事"。在没有这个 Skill 的时候，你跟编程助手说"帮我做一个客服 Agent"，它可能上来就给你写 1000 行 Python。

装上 Workflow Skill 之后，它会先停下来问你：你的目标是原型还是生产？要发布到哪个运行时？有没有特殊的安全约束？然后它会写一份 DESIGN_SPEC.md，把意图固化下来，再开始动手。

这一点对我个人来说是收益最大的，因为它把"设计先行"这件事变成了默认动作。

3.2.2 Scaffold Skill：脚手架专家

主要支持三种动作：create 创建新项目、enhance 给已有项目加上部署/CI-CD/RAG 能力、upgrade 升级到新版本。

值得一提的是，scaffold 提供了多种 Agent 模板，目前能看到的至少有 adk（基础 ADK Agent）、adk_a2a（多 Agent 协作）、agentic_rag（RAG 形态）。模板选对了，后续要改的东西就少一大半。

3.2.3 ADK Code Skill：Agent 写法字典

它是给编程助手准备的"ADK API 速查表"，里面写明白了 Agent、Runner、Session、Memory、Tool 等核心抽象的用法、参数、回调时机、状态怎么传。

实测下来，装了这个 Skill 的编程助手在写 ADK 代码的时候，几乎不再会编造不存在的 API。这种"幻觉率"的下降在工程化场景下非常关键。

3.2.4 Eval Skill：质量守门员

Eval Skill 教编程助手写正确格式的评估集（evalset），讲清楚 LLM-as-Judge 该怎么打分、工具调用轨迹（tool trajectory）该怎么对比、常见失败原因怎么定位。

我自己以前写评估集，每次都要去翻 ADK 文档看 schema，现在直接让 AI 按 Skill 的规范写，省掉一大块脑力。

3.2.5 Deploy Skill：部署目标教练

它把三种部署目标的差异、要传的参数、要配置的 IAM 角色都讲得很清楚。这一段后面专门有一节细聊。

3.2.6 Publish Skill：上架到企业目录

负责把已部署的 Agent 注册到 Gemini Enterprise，让组织内的其他成员能在 https://gemini.google.com/ 这样的统一入口里发现你的 Agent。它支持 ADK 和 A2A 两种注册模式。

3.2.7 Observability Skill：线上诊断医生

这块讲清楚怎么开 Cloud Trace、怎么把请求响应日志落到 BigQuery 做 Agent Analytics，以及怎么接 AgentOps、Phoenix、MLflow 这类第三方观测工具。

3.2.8 Skill 之间的协作姿势

七个 Skill 不是各自孤立的，它们之间其实有一条清晰的"接力顺序"。你可以把它想象成一条工厂流水线：

flowchart LR
    A[Workflow Skill<br/>调度员] --> B[Scaffold Skill<br/>搭骨架]
    B --> C[ADK Code Skill<br/>填业务逻辑]
    C --> D[Eval Skill<br/>质量把关]
    D --> E[Deploy Skill<br/>上云]
    E --> F[Observability Skill<br/>线上看护]
    E --> G[Publish Skill<br/>上架目录]

Workflow Skill 永远是整条流水线的总指挥，编程助手会优先激活它，然后由它决定下一步该叫哪个 Skill 出场。这种"中心调度 + 专项执行"的设计，让整个流程既有条理，又能在任意阶段被打断、被回退。

这里有一个细节很有意思：Workflow Skill 不只是按顺序串，它还会处理回退场景。比如评估没过、部署失败、发布卡住，它都能识别异常并把编程助手引导到正确的恢复路径上。这一点在我自己用下来的体验里特别明显 —— 你不需要担心"AI 一条路走到黑"，它会停下来反问、会主动重试、会主动汇报。

3.3 Skill 机制为什么能省一大笔 token 费

这一点是我自己跑了几轮真实任务后才意识到的。

没有 Skill 的时候，编程助手干一件工程化的事，token 消耗大体是这样的：

[搜索 ADK 官方文档] + [试错若干轮] + [反复确认参数] + [最终生成代码]

每一次"搜索"和"试错"都是高 token 操作。

装上 Skill 之后，路径变成：

[读对应 Skill 文件] + [按规范直接生成代码]

Skill 文件本身不大（几 KB 到几十 KB），但它把"应该怎么做"直接告诉了模型，省掉了大量的搜索、推断、试错环节。

按我之前一次粗略的对比，跑同样一个"部署 Agent 到 Cloud Run"的任务，带 Skill 比不带 Skill，token 消耗差了大概一半多。这个数字没有正式做过 benchmark，仅供你参考，但量级是真实存在的。

四、安装与初始化全流程，一步一图带你走完

4.1 环境前置准备

agents-cli 的环境要求其实不复杂，但有几个细节容易踩坑。这是莫潇羽@无忆研习社亲自走过一遍之后整理出来的清单：

• Python 3.11 或更新版本。注意是 3.11 起步，3.10 不行。
• uv：一个用 Rust 写的现代 Python 包管理器，比 pip 快很多。后面 uvx 这条命令就是 uv 提供的。
• Node.js：装 Skill 的时候会用到，因为 Skill 的安装走的是 npx 的发行通道。
• 平台支持：macOS、Linux、以及 Windows WSL 2。原生 Windows 暂时不行，Windows 用户务必先把 WSL 2 备好。
• 可选项：要做云端部署的话，还需要 Google Cloud SDK 和 Terraform。本地开发阶段这俩可以先不装。

我个人习惯用一个干净的 Python 虚拟环境，避免污染全局：

# 准备一个干净的虚拟环境（可选但推荐）
python3 -m venv ~/.venvs/agents-cli
source ~/.venvs/agents-cli/bin/activate

4.2 一行命令搞定安装

agents-cli 最爽的地方就在这里 —— 整个安装链路只有一条命令需要你亲手敲，其他所有事都可以交给编程助手：

uvx google-agents-cli setup

这一条命令背后发生的事情其实不少：

flowchart TD
    A[uvx google-agents-cli setup] --> B[拉取 google-agents-cli 包]
    B --> C[安装 CLI 二进制]
    C --> D[检测本机已有的编程助手<br/>Gemini CLI / Claude Code / Codex / Cursor]
    D --> E[将 7 个 Skill 写入对应编程助手的 skill 目录]
    E --> F[（可选）启动身份验证流程]
    F --> G[安装完成，可以开始用了]

如果你只想先装 Skill，跳过身份验证，可以加 --skip-auth：

uvx google-agents-cli setup --skip-auth

或者如果你完全不想装 CLI，只想把 Skill 注入到编程助手里，也可以直接走 npx 通道：

npx skills add google/agents-cli

4.3 三种身份验证姿势

身份验证这事在不同场景下选不同方式：

姿势一：交互式浏览器登录。最适合首次配置时使用，会自动打开浏览器走 OAuth。

agents-cli login --interactive

姿势二：检查当前登录状态。怀疑没登好的时候用这个看一眼：

agents-cli login --status

姿势三：本地开发用 AI Studio 的 API Key。这是我个人在做原型阶段最推荐的方式 —— 你不需要任何 Google Cloud 项目，单靠一个 AI Studio Key 就能在本地把 Gemini + ADK 跑起来：

export GEMINI_API_KEY="你的-AI-Studio-Key"

需要注意一点：这种方式只够本地开发用，一旦你要部署到 Cloud Run / Agent Runtime / GKE，就必须切换到完整的 Google Cloud 身份验证。

4.4 验证 Skill 是否成功注入

最后一步，验证 Skill 是不是真的进去了。不同编程助手的验证方式不一样：

• 在 Gemini CLI 里，输入 /skills 看是否能列出 google-agents-cli-workflow 等等。
• 在 Claude Code 里，调出 skill 面板查看。
• 在 Codex / Cursor / Antigravity 里，去对应的 settings 或者命令调色板里搜 skill。

只要能看到 7 个 google-agents-cli-* 开头的 Skill，就说明万事俱备，可以让编程助手开始为你打工了。

4.5 给整个团队铺开 agents-cli 的几点建议

如果你是负责给团队推 agents-cli 的人，下面几条经验来自莫潇羽自己在团队里推这套工具的真实做法：

• 先在一个小项目试跑两周。让一两个核心同事先用一段时间，验证流程是否顺，再向团队铺开。
• 把"如何运行 agents-cli"写进新人入职文档。这个动作很小，但能让团队所有人统一起步。
• 把生成的脚手架代码做一次内部 review。看看它符不符合贵司的命名规范、代码风格、安全合规要求，有需要可以二次定制。
• 把基础设施的 Terraform 配置进 Git。不要把 infra single-project 当作"一次性命令"，把它生成的 IaC 文件作为代码一起进仓库，方便日后审计与复用。
• 关键发布走 Human Mode。前文反复强调过这一点：让 AI 编程助手干 80% 的活，最后 20% 的关键发布，自己手敲。

这一节看着不算"硬核技术"，但实际上是 agents-cli 在团队里能不能真正跑起来的决定性环节。工程化工具的价值，永远是"用起来"才能体现。

五、本地开发：从零搭出第一个 Agent

5.1 创建项目骨架：让编程助手开口干活

这一步开始就可以"动嘴"了。装好 Skill 之后，打开你喜欢的编程助手，给它这样一个自然语言指令：

用 agents-cli 给我搭一个能根据城市查天气、并把回答压缩成穴居人风格的短句的 Agent。先生成原型，不用部署。

你的编程助手会自动激活 workflow 和 scaffold 两个 Skill，然后做这些动作：

• 反问你几个澄清问题：部署目标？安全约束？需不需要 RAG？
• 写一份 DESIGN_SPEC.md，把目标固化下来。
• 调用 agents-cli create caveman-agent --prototype --yes 生成项目脚手架。

当然你也可以不通过编程助手，直接自己敲：

agents-cli create caveman-agent --prototype --yes
cd caveman-agent

5.2 项目结构剖析

生成出来的项目大致长这样（具体结构会随版本演进，以你本机实际生成的为准）：

caveman-agent/
├── DESIGN_SPEC.md          # 设计意图，前期讨论的固化
├── app/
│   ├── __init__.py
│   └── agent.py            # Agent 的核心代码
├── tests/
│   └── eval/
│       └── evalsets/
│           └── basic.evalset.json   # 默认的评估集
├── pyproject.toml          # 依赖与项目元数据
└── README.md

要记住一个核心文件 —— app/agent.py，这里定义了你的 Agent 本体。绝大多数业务逻辑后续都会写在这里。

新生成的项目里默认有个最小可跑的 Agent，能查天气、报时间。打开看一眼，你会看到类似下面这样的代码（这是 ADK 的典型写法）：

from google.adk.agents.llm_agent import Agent
from google.genai import types

def get_weather(city: str) -> str:
    """查询某个城市的天气（这里是个 mock 工具）。"""
    return f"{city} 今天是个晴朗的好天气，气温适中。"

def get_current_time(city: str) -> dict:
    """返回某个城市的当前时间。"""
    return {"status": "success", "city": city, "time": "10:30 AM"}

root_agent = Agent(
    name="root_agent",
    model="gemini-flash-latest",
    instruction="你是一个能查询天气和时间的助手。",
    tools=[get_weather, get_current_time],
)

整套 ADK 的 Agent 定义就这么简洁：起个名、选个模型、写一句指令、挂上几个工具，搞定。

5.3 安装依赖与本地试跑

接下来安装依赖：

agents-cli install

这条命令背后其实就是 uv 在执行 pip install 那一套，把 ADK 以及你 Agent 用到的库都装好。

如果你只想做一次"冒烟测试"，看 Agent 大致能不能跑通，用 agents-cli run 是最快的：

agents-cli run "上海今天天气怎么样？"

终端会直接打印出 Agent 的回答，连 Web 界面都不用开。

5.4 Web Playground：调试体验的天花板

但如果要长时间调试，光看终端输出就太痛苦了。agents-cli 内置了一个本地 Web Playground，开起来就是 ADK 自带的开发调试界面：

agents-cli playground

跑起来之后，终端会打印出一个本地 URL（通常类似 http://localhost:8080，具体端口以你启动时输出的为准）。在浏览器里打开它，从左侧菜单里挑你的 Agent，就可以直接对话。

Playground 提供的几个特性在我自己用下来最实用的是：

• 热重载：你改 app/agent.py 里的代码，保存后 Playground 自动重启，对话不丢。
• 会话级追踪：每条对话都能展开看到 Agent 内部的工具调用、token 用量、模型响应。
• 多 Agent 切换：一个项目里允许放好几个 Agent，菜单里直接切。

这套调试体验对新手非常友好。我有时候带新人上手 Agent，几乎第一节课就是让他们打开 Playground 自己改一改 instruction，看看输出怎么变。

5.5 给 Agent 加工具的常用姿势

ADK 里的工具就是普通的 Python 函数 —— 函数签名 + docstring 就是它"暴露给模型"的接口。所以加工具其实非常简单。

举个例子，给上面的 Agent 加一个"字数统计"工具：

def count_words(text: str) -> str:
    """统计输入文本的单词数量。

    Args:
        text: 需要统计的文本。

    Returns:
        一段描述字数的话。
    """
    word_count = len(text.split())
    return f"这段文本共有 {word_count} 个词。"

root_agent = Agent(
    name="root_agent",
    model="gemini-flash-latest",
    instruction="你是一个能查询天气、报时间、统计字数的助手。",
    tools=[get_weather, get_current_time, count_words],
)

注意两点：

• docstring 极其重要。它是模型决定"什么时候调用这个工具、怎么传参"的唯一依据。docstring 写糊，模型就会乱用。
• 工具应该是确定性的、幂等的。涉及外部 API 时建议加重试与超时，不然 Agent 会被卡死。

到这一步，你已经有了一个能在本地跑、能加工具、能调试的 Agent。下一步就是把它的"质量"用评估固化下来。

5.6 三种常见的 Agent 模板：别只盯着默认的那个

agents-cli scaffold create 支持几种不同形态的模板，挑对了能省你后续大半的改造工作：

• adk：最朴素的单 Agent 模板，适合"输入一个问题、Agent 调几个工具、输出一段回答"这种线性流程。
• adk_a2a：多 Agent 协作模板，内置 Agent-to-Agent 协议，适合需要把任务拆给不同专家 Agent 处理的场景，比如一个研究员 Agent 加一个写作 Agent 加一个审稿 Agent。
• agentic_rag：内置 RAG（Retrieval-Augmented Generation）能力的模板，适合"基于私有知识库做问答"这种典型场景。

切换模板的姿势很简单：

# 创建一个 RAG 形态的 Agent
agents-cli create my-docs-agent --template agentic_rag --yes

# 创建一个多 Agent 协作项目
agents-cli create my-research-team --template adk_a2a --yes

模板的选择对后续开发体验影响巨大。莫潇羽给的建议是：如果一开始就知道自己要做 RAG，千万别在默认 adk 模板上自己手搓 RAG，直接用 agentic_rag 模板省时间。

5.7 给已有项目"加装"能力

agents-cli 还有一个我个人非常喜欢的设计：对存量项目的增强能力。

如果你之前已经用 ADK 自己手搓了一个 Agent，没用 agents-cli 的脚手架，是不是就用不上后续这些工程化能力了？

不是。agents-cli scaffold enhance 可以反向给现有项目"加装"：

# 给已有项目加上 Cloud Run 部署能力
agents-cli scaffold enhance --deployment-target cloud_run

# 加 CI/CD
agents-cli scaffold enhance --cicd-runner github_actions

# 加 RAG 能力
agents-cli scaffold enhance --datastore my_doc_store

这种"渐进式增强"对存量代码非常友好，不需要推翻重来。

六、评估流水线：在上线之前先弄清楚 Agent 到底靠不靠谱

6.1 为什么 Agent 比传统服务更需要评估

传统 Web 服务的质量好坏，基本可以用单元测试和接口测试覆盖：输入 X，输出必须是 Y，错了就报错。

Agent 不一样。

Agent 的输出是自然语言，同一个输入下，每次输出都可能不一样；它的内部还会调用工具，工具调用的顺序、参数、次数本身也是一个评估维度。光靠"输出文本完全匹配"做断言，几乎不可能通过。

所以 Agent 的评估必须换思路：

• 基于评估集（evalset）：写一系列"输入 + 期望行为"的样例。
• 基于轨迹比对（tool trajectory）：Agent 是不是按预期顺序调用了正确的工具。
• 基于 LLM 评判（LLM-as-Judge）：用另一个大模型来打分，比如"这个回答是否准确""是否有礼貌""是否回答了问题"。

agents-cli 内置的 Eval Skill 就是把这套方法论封装进编程助手的脑子里。

6.2 评估集是什么样的

打开你新建项目里的 tests/eval/evalsets/basic.evalset.json，长这样：

{
  "eval_set_id": "basic_eval",
  "name": "基础评估集",
  "eval_cases": [
    {
      "eval_id": "greeting",
      "conversation": [
        {
          "user_content": {
            "parts": [{ "text": "你好，能做什么？" }]
          }
        }
      ],
      "expected_tool_use": [],
      "expected_intermediate_agent_responses": [],
      "final_response": "我可以帮你查询天气和时间。"
    }
  ]
}

一份 evalset 就是一系列 eval_case 的集合，每个 case 描述一个"用户输入 + 期望反应"。可以同时检验：

• 最终输出是不是接近期望。
• 中间是否调用了正确的工具。
• 调用工具时传的参数是否正确。

写评估集这件事，原本是个又繁琐又容易出错的活，但有了 Eval Skill 之后，你直接跟编程助手说"给我加一组评估，覆盖天气查询和时间查询的常见场景"，它就能按规范给你写。

6.3 跑评估：一行命令的事

跑评估也非常简单：

agents-cli eval run                 # 跑默认评估集
agents-cli eval run --evalset basic # 跑指定评估集
agents-cli eval run --all           # 把所有评估集都跑一遍

跑完会输出每个 case 的得分，以及整体的指标，比如响应是否符合预期、工具调用是否完整。

6.4 评估对比：迭代的核心利器

实际项目里最重要的一个评估场景，是对比两次迭代的差异。

举个例子：你刚把 instruction 改了一版，想知道改完之后是变好还是变坏？或者你换了一个新模型，想知道效果是否值得切？这时候就用：

# 先跑一次旧版评估，保存为 baseline
agents-cli eval run --output evals/run_v1.json

# 改完之后跑新版评估
agents-cli eval run --output evals/run_v2.json

# 比较两次结果
agents-cli eval compare evals/run_v1.json evals/run_v2.json

对比的输出会清楚地告诉你：哪些 case 通过率上升了、哪些下降了、平均工具调用次数有没有变化、整体得分是涨还是跌。

这一套"评估 + 对比"的工作流，让 Agent 的迭代变成了和传统服务一样可量化的事情。这也是莫潇羽@无忆研习社个人在 Agent 项目里非常坚持的一条工程纪律：没有评估就别改代码。

6.5 一些我个人的评估实操心得

• evalset 不要追求大而全。先从 20–30 个高频 case 起步，覆盖核心路径，跑得快、改得勤比堆 1000 条更重要。
• 失败 case 一定要单独留一组。比如"用户输入了奇怪字符""模型抽风产生幻觉"，把它们做成 regression set。
• LLM-as-Judge 要谨慎用在主观维度。客观维度（是否调用了某个工具、是否包含某个关键词）用代码断言更准。
• 评估也要做版本管理。建议把 evalset 当成代码一起进 Git，别放在某个人的本地。

6.6 评估指标体系的几个层级

我自己在做 Agent 项目的时候，习惯把评估分成四个层级，从下往上一层比一层贵：

flowchart BT
    A[第 1 层 · 静态检查<br/>代码风格、依赖完整、Schema 校验] --> B[第 2 层 · 单元测试<br/>工具函数级别的对错]