Agents CLI接入编码助手流程教程

先给结论

Agents CLI 不是一个聊天机器人，而是把 Google Cloud 上的 Agent 构建、评测、部署和观测流程包装成一套 CLI 与 skills 的工具。官方 README 说得直白：它能让 Antigra vity CLI、Claude Code、Codex 或其他编码助手更懂 Google Cloud Agent 开发生命周期。

• 最小试用不必马上上云，文档提供了本地路径：安装 CLI 与 skills，准备模型认证，创建 prototype agent，再启动 ADK web playground。
• 真正的验收点不是“生成了项目”，而是依赖能否安装、playground 是否启动、登录状态是否清楚、后续 eval/deploy 命令能否被纳入流程。

之所以值得写成教程，是因为它解决了一个具体麻烦：编码助手在写 Agent 项目时，常常要同时理解 ADK、模型认证、Google Cloud 项目、部署目标、评测数据、日志和 IAM 权限。资料分散后，助手容易在文档中来回搜索，开发者也很难判断它给出的部署命令是否缺了前置条件。Agents CLI 的思路不是让你换掉 Codex 或 Claude Code，而是给这些编码助手装一套“会做 Agent 工程”的上下文和命令。

它的边界也得先说清楚。这个工具更适合已经准备尝试 ADK 或 Google Cloud Agent Platform 的团队；如果你只是想本地写一个玩具 prompt，或者完全不打算碰 Google Cloud，收益会小一些。它还处于预览阶段，官方明确提到 Pre-GA 条款，所以不该一上来就接入生产发布链路。更稳妥的方式是：先跑通本地 create/install/playground，再决定是否进入 eval、infra、deploy 和 publish。

适合谁先试

• 适合：已经在用 Codex、Claude Code、Antigra vity CLI 或其他编码助手写 Agent 项目，但经常被云端部署、评测、CI/CD 和权限配置卡住的人。
• 适合：想用 ADK 做一个支持 Agent，并且希望从项目脚手架、依赖安装、本地 playground、评测到部署都有固定命令的人。
• 不适合：只想找一个通用聊天前端、没有 Google Cloud 项目、暂时不做评测和部署的人。

建议把第一次试用目标压得很小：不要让编码助手一上来就“帮我做一个生产级客服 Agent”。更合理的目标是“用 agents-cli 创建一个 prototype agent，本地能启动 playground，能说明下一步如何加入 eval”。这样你能分清三件事：CLI 本身是否可用，编码助手是否能看到 skills，生成项目是否有可运行结构。只有这三件事稳定了，再谈 RAG、部署、Gemini Enterprise 注册和观测。

最小使用路径

1. 先检查本机前置条件。官方 Getting Started 写明必需项是 Python 3.11、uv 和 Node.js；如果后面要部署，还需要 Google Cloud SDK 和 Terraform。
2. 安装 CLI 与 skills。完整安装可以用 uvx google-agents-cli setup；如果只想给编码助手装 skills，也可以用 npx skills add google/agents-cli。
3. 准备模型认证。本地开发可以使用 AI Studio API key；认证文档给出的方式是设置 GOOGLE_GENAI_USE_VERTEXAI=FALSE 和 GOOGLE_API_KEY。若走 Vertex AI 或部署，则需要 agents-cli login 或 gcloud application-default login。
4. 让编码助手确认 skills 可见。Claude Code 可以看 skills 列表；Codex 或其他支持 skills 的助手，需要确认 google-agents-cli-workflow、scaffold、eval、deploy 等能力能被读取。
5. 先手动跑一条最小命令链。不要把全部控制权交给助手，先自己创建 prototype agent、安装依赖并启动 playground，确认 localhost:8080 能访问。
6. 再把需求交给编码助手。输入一个窄任务，例如“Build a support agent that answers questions from our docs”，观察它是否按 scaffold、install、run、eval 的顺序推进，而不是直接编造云端资源。

python3 --version
uvx google-agents-cli setup
npx skills add google/agents-cli
export GOOGLE_GENAI_USE_VERTEXAI=FALSE
export GOOGLE_API_KEY="replace_me"
agents-cli login --status
agents-cli create my-agent --prototype --yes
cd my-agent
agents-cli install
agents-cli playground
curl -I http://localhost:8080

这组命令的目的不是把生产部署一次性完成，而是验证最小闭环。python3 版本先挡掉基础环境问题；setup 和 skills add 分别验证 CLI 与编码助手上下文；login --status 让你看清当前认证；create/install/playground 证明项目能生成并启动；curl 检查本地服务是否真的起来。只要其中一步失败，就先停在本地排查，不要继续让助手写部署脚本。

配置与认证

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=replace_me
# 如果走 Vertex AI 或部署，再使用 agents-cli login -i 或 gcloud auth application-default login
GOOGLE_CLOUD_LOCATION=us-east1

认证这里最容易混乱，因为它分三层。第一层是编码助手自己的认证，例如 Codex 的 OpenAI 账号、Claude Code 的 Anthropic 账号；Agents CLI 不负责这一层。第二层是你正在构建的 Agent 调模型需要的认证，本地快速试验可以用 AI Studio API key。第三层才是部署认证，涉及 Google Cloud 项目、ADC、账单和 IAM 权限。把三层混在一起，是很多 Agent 项目一开始就跑偏的原因。

所以，环境应该分成两个文件或两段 shell profile：本地开发只放 GOOGLE_GENAI_USE_VERTEXAI 和 GOOGLE_API_KEY；部署前再处理 gcloud auth application-default login、项目 ID、区域和权限。这样即使编码助手读到了本地项目，也不会顺手拿到不该拿的部署权限。

工作流拆解

Agents CLI 的价值在生命周期，而不是单条命令。README 里列出的命令覆盖 scaffold、run、install、lint、eval generate、eval grade、eval compare、deploy、publish gemini-enterprise、infra single-project、infra cicd、data-ingestion 等阶段。对开发者来说，这意味着你可以把 Agent 项目的工作拆成四道门：能创建、能运行、能评测、能部署。每过一道门都留下可检查的产物。

• 第一道门是创建。create 或 scaffold 生成项目结构，检查点是目录、依赖文件、agent 入口和 README 是否完整。
• 第二道门是运行。install 和 playground 的检查点是依赖安装成功、本地 8080 页面可访问、热重载不报错。
• 第三道门是评测。eval generate 和 eval grade 的检查点是 traces、指标和失败样例，而不是“模型说它通过了”。
• 第四道门是部署。deploy、infra 和 publish 的检查点是 Cloud Run、Agent Runtime、Gemini Enterprise 注册、日志和权限边界。

agents-cli info
agents-cli lint
agents-cli eval generate
agents-cli eval grade
agents-cli eval compare evals/run_v1.json evals/run_v2.json
agents-cli deploy
agents-cli publish gemini-enterprise

这组命令不建议第一次全部执行。它更像一张路线图：info 看当前项目配置，lint 先挡基础质量问题，eval generate/grade 用来产出可复核的评测结果，compare 用来比较两轮变化，deploy 和 publish 才进入云端发布。把它们写出来，是为了让读者知道 Agents CLI 的重点不是“生成一个项目”，而是给 Agent 项目补上工程化检查点。

失败时怎么收敛

如果 setup 阶段失败，先查 Python、uv、Node.js，而不是让编码助手改项目代码。如果 login --status 显示没有可用认证，先决定走 AI Studio 还是 Vertex AI，不要同时混用 API key 和 ADC。若 create 成功但 playground 起不来，先看 agents-cli install 的依赖日志和本地端口占用。若 eval 阶段没有数据，不要让助手编造指标，应该先补评测样例和预期答案。

部署失败时更要收敛权限。Agent Runtime、Cloud Run、GKE、Terraform、CI/CD 和 Gemini Enterprise 注册都牵涉项目权限与账单。第一次试用只应该在测试项目里做，而且最好让编码助手先给出计划和将要执行的命令，再由人确认。Agents CLI 能减少文档搜索成本，但不能替代你对云资源、预算和 IAM 边界的审核。

风险边界

• 验收指标：本地先看 agents-cli login --status、localhost:8080、依赖安装日志、eval 输出和 traces；不要只看项目目录是否生成。
• 权限边界：本地开发只给模型 key；部署前再单独开启 Google Cloud ADC、项目、区域和 IAM 权限，避免编码助手过早拿到发布权限。
• 成本边界：eval、deploy、Cloud Run、Agent Runtime 和日志都可能产生费用；第一次只在测试项目里跑，且限制样例数量。
• 适用边界：它适合 ADK 与 Google Cloud Agent 生命周期，不适合完全不碰 Google Cloud 的纯本地聊天工具。
• 预览边界：官方标注为 Pre-GA，生产使用前要检查服务条款、支持级别、回滚路径和人工审批流程。

这个工具真正有用的地方，是把“编码助手会写代码”推进到“编码助手能按生命周期做 Agent 工程”。但这一步需要你把关。好的使用方式不是让助手直接部署，而是让它先根据 agents-cli skills 写计划、创建项目、补测试、生成 eval，再把云端变更交给人确认。这样工具才是在降低上下文和操作成本，而不是制造另一个黑盒。

是否值得放进日常

今天可以试的人：已经准备使用 ADK 或 Google Cloud Agent Platform，并且希望 Codex、Claude Code 或其他编码助手按固定生命周期做 scaffold、run、eval、deploy 的开发者。应该先观望的人：没有 Google Cloud 项目、没有评测样例、也不打算部署的纯本地用户。试用时看三个指标：最小项目能否在 30 分钟内跑到 playground，编码助手是否能解释每条 agents-cli 命令的作用，eval 输出是否能暴露具体失败样例。

下一步建议很简单：先在一个空目录里跑 setup，再让你的编码助手创建一个 support-agent prototype。不要马上接入生产文档，不要马上部署。把第一次试验限制在公开样例、测试项目和少量评测数据上；当 create、install、playground、eval 这几步都有可复核的产物，再考虑 infra、deploy 和 publish。这样 Agents CLI 才是工具，而不是又一层难排查的自动化。