15分钟用agents-cli搭建部署AI Agent

15分钟用agents-cli搭建部署AI Agent

想做一个 AI Agent，却发现要学 ADK 框架、搞评估测试、还要研究怎么部署到 Cloud Run 或 GKE……光是搭环境就花了一下午？

Agent 开发本该聚焦在业务逻辑上，而不是陷在工具链的泥潭里。今天带你用 Google 官方出品的 agents-cli，从零完成一个 AI Agent 的创建、本地测试、效果评估和云端部署。跟着步骤走即可，无需事先掌握 ADK 或 Google Cloud 的全部细节。

前置条件

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

• Python 3.11+（推荐用 pyenv 或 conda 管理版本）
• uv（现代 Python 包管理器，依赖解析比 pip 快 10~100 倍）
• Node.js（用于 skills 加载）
• Google AI Studio API Key（本地开发用，免费申请）

安装 uv（如果还没装）：

curl -LsSf https://astral.sh/uv/install.sh | sh

第一步：安装 agents-cli 并初始化项目

agents-cli 不需要全局安装，用 uvx 直接运行：

uvx google-agents-cli setup

这条命令会安装 agents-cli，并把 Agent 开发所需的 skills 注入到 coding agent（如 Claude Code 或 Codex）中。skills 相当于让 coding agent 学会 ADK 写法、评估方法和部署流程的插件包。CLI 本身完全可独立工作。

安装完成后，创建你的第一个 Agent 项目：

uvx google-agents-cli scaffold text-summarizer
cd text-summarizer

此时会得到标准项目结构，包含 Agent 定义、测试用例和配置文件。

第二步：让 Agent 跑起来

先确认项目能正常运行，不要急着写复杂逻辑：

## 配置 API Key
export GOOGLE_API_KEY="你的AI_Studio_API_Key"

## 运行测试
uvx google-agents-cli run "请总结一下下面这段技术文档的核心要点"

该命令读取项目中的 Agent 配置，调用 Gemini 模型并返回结果。用单次 prompt 快速验证 Agent 行为是否可达，迭代效率极高。

第三步：编写你自己的 Agent 逻辑

打开项目中的 Agent 定义文件（通常是 agent.py），将其改造成实用工具。这是一个技术文档摘要 Agent 的最小可运行示例：

from google.adk.agents import Agent

agent = Agent(
    name="tech-doc-summarizer",
    model="gemini-2.5-pro",
    instruction="""你是一个技术文档摘要专家。
请阅读输入的技术文档，输出包含以下结构：
1. 核心概念（一句话概括）
2. 关键特性（3-5个要点）
3. 使用场景（何时用 / 何时不用）
保持输出简洁专业，避免废话。""",
    description="专门用于摘要技术文档的 AI Agent",
)

gemini-2.5-pro 是目前推荐的平衡选择。本地频繁测试可改用 gemini-1.5-flash 降低成本，只需改 model 参数即可。

写完后再用 run 命令测试几组输入，确认输出符合预期再继续。

第四步：用 Eval 量化评估你的 Agent

Agent 表现需要客观数据支撑。agents-cli 内置完整评估流水线：

## 自动生成评估数据集
uvx google-agents-cli eval dataset synthesize

## 运行 Agent 处理所有评估用例，生成 traces
uvx google-agents-cli eval generate

## 对输出结果打分
uvx google-agents-cli eval grade

eval 流程会自动生成多轮对话测试场景、用 LLM-as-judge 对输出打分、聚类分析失败模式（eval analyze）、甚至自动调优 prompt（eval optimize）。

运行完 eval grade 后查看评估报告，根据结果调整 system prompt 或添加工具，再跑一次评估直到达标。

第五步：部署到 Google Cloud

本地测试和评估通过后，即可部署：

## 认证登录
uvx google-agents-cli login

## 一键部署
uvx google-agents-cli deploy

该命令自动完成：打包代码、构建镜像、推送至 Artifact Registry、部署到 Agent Runtime 或 Cloud Run、配置端点和认证。无需手写 Dockerfile 或 infra YAML。

部署成功后会返回可调用的 API 端点。可在应用里通过 HTTP 调用，或用 agents-cli publish gemini-enterprise 注册到 Gemini Enterprise 平台。

常见问题

Q: 一定要配合 Claude Code / Codex 使用吗？
不需要。agents-cli 可完全独立运行，所有命令直接在终端执行。skills 只是让 coding agent 更懂这个工具。

Q: 本地开发一定要 Google Cloud 账号吗？
不需要。用 AI Studio API Key 就能完成 scaffold、run、eval 全流程。只有 deploy 和 publish 才需要 Cloud 账号。

Q: eval 生成的自动数据集质量不高怎么办？
eval dataset synthesize 适合快速启动。有真实业务数据时，建议手动准备 eval cases（JSON 数组格式，包含 input 和 expected output）。真实数据越多，评估结果越可信。

Q: 已有现成的 ADK 项目，能用 agents-cli 管理吗？
可以。进入已有项目目录运行 agents-cli scaffold enhance，自动添加部署和 CI/CD 配置，不会覆盖现有代码。

Q: 部署后调用报 401 怎么办？
检查认证配置。部署到 Cloud Run 的 Agent 默认需要 IAM 认证，可在 Cloud Console 改为允许未认证调用（仅测试环境），或给服务账号绑定正确的调用者角色。

总结

完整流程回顾：

1. uvx google-agents-cli scaffold <name> —— 创建项目骨架
2. export GOOGLE_API_KEY=... —— 配置 API
3. uvx google-agents-cli run "prompt" —— 本地快速测试
4. eval generate && eval grade —— 量化评估效果
5. login && deploy —— 一键部署上云

整个过程不需要手写 Dockerfile、不用研究 ADK 的每个 API、无需手动配置 Cloud 资源。agents-cli 把 Agent 开发的全生命周期标准化了，你只需要聚焦在业务逻辑上。

下一步建议：

• 试试 eval optimize 让 CLI 自动调优 prompt
• 用 scaffold enhance 给已有项目加上 CI/CD 管道
• 探索 data-ingestion 命令搭建 RAG 管道