使用Google Agents CLI与ADK快速构建AI智能体：从零部署文本压缩应用

30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度在 AI 应用开发领域构建一个功能完善、可评估、可部署的智能体Agent往往涉及复杂的框架选择、环境配置和部署流程。Google Cloud 推出的 Agents CLI 工具结合其开源的 Agent Development Kit (ADK)为开发者提供了一条从零到一构建 AI 智能体的“高速公路”。本文将手把手带你体验如何利用agents-cli通过自然语言指令快速搭建、测试并部署一个“原始人风格”的文本压缩智能体让你直观感受现代 AI 开发工具链的效率提升。1. 背景与核心概念什么是 Agents CLI 与 ADK在深入实战之前我们有必要厘清几个核心概念理解它们在整个 Google Cloud AI 生态中的定位。Agent Development Kit (ADK)是一个开源的、代码优先的框架专为构建复杂的 AI 智能体而设计。你可以把它想象成构建智能体的“脚手架”或“工具箱”。它提供了一套标准化的组件和模式用于定义智能体的行为、工具调用、记忆管理和多智能体协作。使用 ADK开发者可以专注于智能体的业务逻辑而无需从零开始处理底层的通信、状态管理和编排问题。Agents CLI则是一个命令行工具它充当了 AI 开发工具如 Gemini CLI, Claude Code, Codex 等与 ADK 框架之间的“翻译官”和“自动化引擎”。它的核心价值在于统一接口为不同的 AI 开发工具提供了一个标准化的、机器可读的接口来与 ADK 交互。封装专家知识它将 ADK 的最佳实践、智能体评估方法和 Google Cloud 部署配置等复杂知识封装成一系列可执行的“技能”Skills。端到端生命周期管理通过自然语言指令驱动 AI 开发工具自动完成从项目创建、代码编写、本地测试、评估到云端部署的全流程。简单来说ADK 是“砖瓦和蓝图”构建框架而 Agents CLI 是“智能施工队”自动化工具。你开发者只需要用自然语言告诉这个“施工队”你想要什么样的房子智能体它就能自动调用 ADK 的“砖瓦”按照最佳“蓝图”把房子盖起来甚至帮你完成水电验收评估和交付部署。Gemini Enterprise Agent Platform是运行这些智能体的云平台。它提供了运行时环境、模型服务、向量检索、可观测性、安全治理等一系列企业级能力。我们最终构建的智能体将部署到这个平台上运行。本次实战的目标是创建一个“原始人压缩器”Caveman Compressor智能体。它的功能非常有趣将冗长、客套的文本压缩成简短、直接、带有原始人幽默风格的摘要。例如将“我希望将应用程序部署到生产环境”压缩为“我部署。生产环境。现在。” 这个例子虽然简单但能完整演示 Agents CLI 的核心工作流。2. 环境准备与前置条件开始构建之前请确保你的开发环境满足以下要求。这是后续所有步骤能够顺利进行的基础。2.1 基础环境要求操作系统支持 macOS, Linux 或 Windows (WSL2 推荐)。本文示例基于 Linux/macOS 命令行。Python 环境需要 Python 3.9 或更高版本。建议使用pyenv或conda管理 Python 版本避免系统 Python 环境冲突。包管理工具 uvAgents CLI 推荐使用uv进行安装和管理。uv是一个用 Rust 编写的极速 Python 包安装器和解析器。AI 开发工具你需要安装一个支持与 Agents CLI 交互的 AI 开发工具。根据网络热词常见的选择包括Gemini CLI: Google 官方的命令行工具。Claude Code: Anthropic 推出的编码助手。Codex: 一个流行的 AI 编程工具。Antigravity: 另一个被提及的 AI 开发工具。 你可以根据个人喜好选择其一。本文的指令将基于“你的 AI 开发工具”这一通用表述你需要将其替换为你实际使用的工具。2.2 Google Cloud 项目配置由于最终要将智能体部署到 Google Cloud你需要一个可用的 Google Cloud 项目。创建或选择项目访问 Google Cloud Console 创建一个新项目或选择一个现有项目。启用 API在你的项目中启用Agent Platform API。这是使用 Agents CLI 和部署智能体的前提。身份验证确保你已在本地通过gcloud auth application-default login或设置服务账号密钥的方式完成了 Google Cloud 的身份验证。这样 CLI 工具才能有权限操作你的云资源。2.3 安装 Agents CLI这是整个流程中唯一需要你手动执行的 CLI 命令。打开你的终端执行以下命令# 使用 uvx 安装并运行 Agents CLI 的 setup 命令 uvx google-agents-cli setupuvx是uv工具的一部分用于直接运行远程的 Python 包。这条命令会完成 Agents CLI 的初始化和环境配置。安装完成后你可以通过agents-cli --help来验证安装是否成功并查看所有可用的命令。3. 项目脚手架从想法到代码结构一切就绪后我们就可以开始“动口不动手”的创造了。打开你选择的 AI 开发工具例如 Gemini CLI 的聊天界面或 Claude Code 的集成环境。第一步发出创建指令向你的 AI 开发工具输入以下自然语言提示Prompt使用 agents-cli 构建一个能将冗长文本压缩成简洁、原始人风格摘要的智能体。第二步观察自动化流程你的 AI 开发工具在接收到这个指令后会激活其内置的google-agents-cli-workflow和google-agents-cli-scaffold技能。接下来你会看到一系列自动化的交互和操作澄清问题工具可能会问你一些 clarifying questions例如智能体的部署目标是什么例如Cloud Run, GKE是否有特定的安全或合规性约束 根据提示词材料它可能会询问部署目标和安全约束。你可以根据实际情况回答或使用默认选项。生成设计文档工具会自动创建一个DESIGN_SPEC.md文件用于记录智能体的设计目标、输入输出规范等。执行脚手架命令工具会在后台自动执行以下关键命令# 创建名为 “caveman-agent” 的项目原型 agents-cli create caveman-agent --prototype --yes # 进入项目目录并安装依赖 cd caveman-agent agents-cli install这个过程完成后你将获得一个完整的项目目录结构类似于caveman-agent/ ├── app/ │ ├── agent.py # 智能体的核心定义文件 │ └── ... # 其他应用文件 ├── tests/ │ └── eval/ # 评估测试集目录 ├── pyproject.toml # 项目依赖和配置 ├── DESIGN_SPEC.md # 自动生成的设计规格文档 └── ... # 其他配置文件这个项目已经包含了 ADK 智能体的基础模板、测试框架和评估集配置为你省去了大量初始化工作。4. 构建智能体核心逻辑项目脚手架搭好后我们需要定义智能体的核心行为。继续在你的 AI 开发工具中输入指令让它修改智能体代码。指令你可以直接要求工具“编辑app/agent.py文件实现原始人压缩器的逻辑”。或者更简单地根据之前的对话上下文工具会自动进行这一步。工具会利用google-agents-cli-adk-code技能遵循 ADK 的最佳实践来编写代码。最终app/agent.py文件的核心内容会被更新为类似以下代码# 文件路径caveman-agent/app/agent.py from adk.agents import Agent from adk.agents.models import Gemini # 定义根智能体 root_agent Agent( namecaveman_agent, modelGemini(modelgemini-flash-latest), # 使用 Gemini Flash 模型 instruction你是一个文本压缩器。将冗长的输入文本转换为简短、简单的摘要并带有原始人般的语气。规则 - 省略冠词、填充词和客套话。 - 使用短句和简单的词语。 - 保留技术术语。 - 语气应该是突兀和有趣的但必须保留核心含义。 示例输入 “I would like to deploy the application to production environment.” 示例输出 “Me deploy. Production. Now.” , # 后续可以在这里添加 tools工具参数让智能体能调用外部API或函数 )这段代码清晰地定义了一个名为caveman_agent的智能体model: 指定了使用的 AI 模型这里是gemini-flash-latest一个兼顾速度与性能的模型。instruction: 这是智能体的“人格”和“任务说明书”。我们通过详细的规则和示例引导模型生成符合“原始人”风格的压缩文本。本地测试代码修改后AI 开发工具通常会主动执行一个基本功能测试来验证智能体是否工作。它可能会在后台运行类似以下的命令agents-cli run “请帮我理解一下我的项目有哪些部署选项”你期望看到的输出应该是类似“部署选项Agent Runtime, Cloud Run, GKE。选一个。上线。”这样的压缩风格回复。这证明你的智能体已经能在本地运行并理解其任务。5. 评估智能体确保输出质量构建完成并不意味着结束我们需要评估智能体的表现是否符合预期。Agents CLI 提供了强大的评估框架。指令在 AI 开发工具中输入为原始人智能体编写评估并运行它们。AI 开发工具会激活google-agents-cli-eval技能并自动完成以下工作创建评估集在tests/eval/evalsets/目录下生成一个评估文件例如caveman.evalset.json。这个文件包含了一系列测试用例用于评估智能体在不同方面的表现// 示例结构 (tests/eval/evalsets/caveman.evalset.json) { “evalset”: [ { “input”: “Could you kindly assist me in exploring the various deployment methodologies available for our software project?” “expected_output_criteria”: [“contains ‘deploy’” “contains ‘method’ or ‘option’” “tone is abrupt”] }, { “input”: “The synergistic paradigm shift necessitates a holistic reevaluation of our core competencies.” “expected_output_criteria”: [“preserves ‘paradigm shift’” “preserves ‘core competencies’” “output is much shorter”] } // ... 更多测试用例 ] }这些用例会覆盖压缩质量、技术术语保留、语气风格等多个维度。配置评估标准在tests/eval/eval_config.json中配置 LLM-as-Judge使用大语言模型作为裁判的评判标准告诉系统如何给智能体的回复打分。运行评估自动执行评估命令。agents-cli eval run迭代优化评估运行后你会得到一份报告显示哪些测试用例通过了哪些失败了。如果失败你可以给 AI 开发工具反馈。例如对问候语的测试响应太礼貌了。让它更粗鲁一些。工具会根据你的反馈调整app/agent.py中的instruction然后重新运行agents-cli eval run。这个过程可以反复进行直到智能体的输出质量达到你的要求。这种基于评估的迭代是生产级 AI 应用开发的关键环节。6. 部署到 Google Cloud智能体通过评估后就可以部署到生产环境了。我们将把它部署到 Google Cloud Run这是一个全托管的无服务器计算平台。指令在 AI 开发工具中输入将此智能体部署到 Cloud Run。AI 开发工具会激活google-agents-cli-deploy技能执行部署流程增强脚手架首先为特定的部署目标Cloud Run添加必要的基础设施配置。agents-cli scaffold enhance --deployment-target cloud_run这个命令会生成或修改Dockerfile、service.yaml等部署描述文件。执行部署然后执行部署命令。agents-cli deploy这个命令会完成一系列操作构建容器镜像、将镜像推送到 Google Container Registry (GCR) 或 Artifact Registry、在 Cloud Run 上创建或更新服务、配置网络访问等。部署成功后命令行会输出一个Service URL。你可以通过这个 URL 访问你刚刚部署的智能体 API。例如使用curl命令进行测试curl -X POST \ -H “Content-Type: application/json” \ -d ‘{“input”: “I am writing to respectfully request an update on the current status of the quarterly financial report compilation process.”}’ \ https://your-caveman-agent-service.a.run.app预期的响应应该是一个原始人风格的压缩摘要。7. 可观测性与监控部署上线后监控智能体的运行状况至关重要。默认追踪Cloud Trace 在部署时默认是启用的。你可以在 Google Cloud Console 中打开 Cloud Trace 浏览器向你的服务发送一些请求就能看到详细的追踪信息包括每次 LLM 调用的耗时、工具执行情况等。增强可观测性如果你需要更详细的数据如日志持久化、自定义指标可以指示 AI 开发工具为我的智能体设置可观测性基础设施。工具会为你自动配置一个服务账号、一个 Cloud Storage 存储桶和一个 BigQuery 数据集并更新部署的服务以使用这些资源将日志、指标和追踪数据导出进行深度分析。8. 常见问题与排查思路在实际操作中你可能会遇到一些问题。以下是一些常见问题的排查指南问题现象可能原因解决思路uvx google-agents-cli setup失败1. 网络问题。2. Python 或 uv 未正确安装。3. 系统权限问题。1. 检查网络连接尝试使用稳定网络。2. 确认python --version和uv --version命令可用。重新安装uv(curl -LsSf https://astral.sh/uv/install.sh | sh)。3. 在 macOS/Linux 上尝试使用sudo或在用户目录下安装。agents-cli create命令执行慢或失败1. 依赖下载慢特别是首次使用。2. Google Cloud 身份认证失败。1. 耐心等待或配置 pip/uv 使用国内镜像源注意 uv 的源配置方式不同。2. 运行gcloud auth application-default login重新登录并确认当前项目gcloud config set project YOUR_PROJECT_ID是正确的。AI 开发工具无法识别agents-cli指令1. 工具未集成 Agents CLI 技能。2. 提示词不够明确。1. 确认你使用的 AI 开发工具如 Claude Code, Codex支持并已加载google-agents-cli-*技能包。查阅对应工具的插件或技能商店。2. 在提示词中明确提及“使用 agents-cli”例如“请使用 agents-cli 工具来...”。部署到 Cloud Run 时权限错误1. 当前账号缺少 Cloud Run、Cloud Build 或 IAM 相关权限。1. 在 Google Cloud Console 的 IAM 页面确保你的用户或服务账号拥有以下角色Cloud Run Admin、Cloud Build Editor、Service Account User、Storage Admin用于容器镜像。智能体 API 访问返回 5xx 错误1. 容器启动失败。2. 代码运行时错误。3. 模型 API 调用失败。1. 在 Cloud Console 的 Cloud Run 服务详情页查看“日志”标签页排查容器启动和运行时错误。2. 检查app/agent.py中模型名称等配置是否正确以及 Google Cloud 项目是否已启用必要的 API如 Gemini API。3. 确认是否有配额限制或账单问题。评估 (agents-cli eval run) 失败1. 评估集 JSON 格式错误。2. LLM-as-Judge 的 API 密钥或模型不可用。1. 检查tests/eval/evalsets/下的 JSON 文件格式是否正确。2. 评估通常也依赖大模型确保你的环境能访问到评估配置中指定的模型默认识别项目中的模型设置。9. 最佳实践与进阶探索掌握了基础流程后遵循一些最佳实践能让你的智能体更健壮、更强大。9.1 智能体设计最佳实践清晰的指令instruction是智能体的灵魂。务必清晰、具体使用规则和示例来约束输出。迭代优化指令是提升智能体质量最有效的方法。逐步复杂化先从简单的、无状态的智能体开始如本文的压缩器。验证流程跑通后再逐步增加工具调用、记忆、多智能体协作等复杂功能。善用评估不要只做一次评估。建立覆盖核心用例、边界用例和对抗性用例的评估集。将agents-cli eval run集成到你的 CI/CD 流程中确保每次代码变更都不会导致质量回退。9.2 工程与运维建议版本控制将agents-cli create生成的项目完整地纳入 Git 等版本控制系统。这包括代码、评估集和配置。配置分离将模型名称、API 密钥等敏感或易变配置通过环境变量或 Google Cloud Secret Manager 管理不要硬编码在agent.py中。监控告警除了利用平台提供的 Trace 和 Logging为智能体的响应延迟、错误率和 token 消耗设置监控和告警。安全与治理在 Google Cloud Agent Platform 中利用 IAM 策略、语义治理策略Semantic Governance和 Agent Gateway 来控制谁可以访问、调用你的智能体并过滤不安全的输入输出。9.3 下一步可以做什么Agents CLI 和 ADK 的能力远不止于此。你可以尝试用自然语言指令探索更复杂的场景添加工具对 AI 开发工具说“集成一个 Google 搜索工具让智能体能获取实时信息。” 工具会自动为你配置网络搜索技能。构建多智能体系统尝试“创建一个能与其他智能体交互的智能体使用 adk_a2a 模板。” 这将引导你进入多智能体编排的领域。实现 RAG指令“基于我们的文档使用 agentic_rag 模板构建一个问答智能体。” 这会将向量数据库和检索能力集成到你的智能体中。通过本文的实践你已经体验了如何利用 Agents CLI 这一“杠杆”用自然语言驱动 AI 开发工具高效完成智能体从创建、编码、评估到部署的全过程。这种开发模式极大地降低了 AI 应用开发的门槛让开发者能更专注于业务逻辑和创新。建议你以这个“原始人压缩器”为起点复制项目修改指令和评估集尝试构建属于你自己的第一个生产级 AI 智能体。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度