30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度在实际 AI 代理开发中一个常见的痛点是如何将自然语言描述的创意快速转化为一个可运行、可评估、可部署的 AI 代理。开发者往往需要手动搭建项目结构、编写复杂的代理逻辑、设计评估集、配置部署环境这个过程不仅耗时而且容易出错。Google 推出的 Agents CLI 正是为了解决这一系列工程化问题而设计的工具。它不是一个独立的命令行工具而是一个专为 AI 开发工具如 Gemini CLI、Claude Code、Codex 等设计的“技能包”将这些工具与 Google Cloud 的 Agent Development Kit (ADK) 和 Agent Platform 深度集成让开发者能够通过自然语言指令完成从构思到上线的完整代理生命周期管理。本文将带你深入理解 Agents CLI 的核心机制并完成一个从零开始的实战演练构建一个能将冗长文本压缩成“原始人”风格摘要的“Caveman Compressor”代理。你将学会如何利用 Agents CLI 背后的技能通过 AI 开发工具自动化完成项目脚手架搭建、代理逻辑编写、本地测试、评估集创建与运行以及最终部署到 Google Cloud 的 Cloud Run 服务。整个过程将清晰地展示如何将自然语言指令转化为具体的工程操作实现高效的 AI 代理开发工作流。1. 理解 Agents CLI 的核心定位与工作流在深入代码之前必须厘清 Agents CLI 在整个 Google Cloud AI 代理生态中的角色。它不是让你在终端里直接输入agents-cli命令来创建代理而是为 AI 开发工具提供了一套可调用的“技能”。1.1 Agents CLI 是什么AI 开发工具的“副驾驶”Agents CLI 本质上是一个封装了专家知识的工具集。它将 Agent Development Kit (ADK) 的复杂设计模式、代理评估的最佳实践以及 Google Cloud 部署的配置细节打包成一系列机器可读的“技能”。当你在 Gemini CLI、Claude Code 或 Codex 等工具中输入如“构建一个文本压缩代理”这样的自然语言指令时这些工具能够识别并调用 Agents CLI 对应的技能如google-agents-cli-scaffold自动执行一系列标准化的工程任务。这种设计带来了几个关键优势降低认知负荷开发者无需记忆 ADK 的 API 细节、评估框架的配置语法或 Cloud Run 的部署参数。标准化流程确保每个代理项目都遵循一致的最佳实践结构便于团队协作和后期维护。加速迭代通过自然语言快速触发构建、评估、部署循环极大提升了原型开发速度。1.2 核心组件与依赖关系要使用 Agents CLI你的环境中需要以下几个关键组件协同工作AI 开发工具这是与用户交互的入口。它接收你的自然语言指令理解意图并决定调用哪个 Agents CLI 技能。常见的工具包括 Antigravity、Gemini CLI、Claude Code、Codex 等。Agents CLI 技能包这是一系列预定义的、可执行特定任务如创建项目、运行评估、部署的模块。它们通过uvx google-agents-cli setup安装。Agent Development Kit (ADK)一个开源的、代码优先的框架用于构建复杂的 AI 代理。Agents CLI 生成的代理代码基于 ADK。Google Cloud 项目与 Agent Platform这是代理的运行时和部署目标。你需要一个已启用 Agent Platform API 的 Google Cloud 项目。Python 与 uvAgents CLI 通过uv一个快速的 Python 包安装器进行安装和管理。它们之间的关系可以概括为AI 开发工具作为指挥官根据你的指令调度Agents CLI 技能去操作ADK 框架生成代码并最终将产物部署到Google Cloud Agent Platform。1.3 典型工作流解析一次完整的代理创建与部署通常遵循以下标准化流程环境准备安装 uv、设置 Agents CLI、确保 AI 开发工具就绪。项目脚手架AI 工具调用scaffold技能创建包含标准目录结构、基础依赖和示例代码的新项目。代理构建AI 工具编辑核心代理文件如app/agent.py根据你的需求实现具体逻辑。本地运行与测试通过agents-cli run命令在本地验证代理的基本功能。评估与迭代AI 工具创建评估集.evalset.json和评估配置运行agents-cli eval run并根据结果反馈调整代理指令或逻辑。部署AI 工具添加部署配置如针对 Cloud Run并执行agents-cli deploy将代理发布到云端。观测在 Google Cloud Console 中查看代理的追踪Traces、日志和指标。2. 环境准备与前置条件检查在开始构建“Caveman Compressor”之前必须确保所有基础组件都已正确安装和配置。遗漏任何一步都可能导致后续流程失败。2.1 创建并配置 Google Cloud 项目这是代理能够部署和运行的基石。创建新项目或选择现有项目访问 Google Cloud Console 在顶部导航栏的项目选择器中点击“新建项目”或选择一个已有项目。启用计费确保项目已关联有效的结算账号。Agent Platform 的部分服务如 Cloud Run、Vector Search会产生费用。启用必要 API在 Console 中进入“API 和服务” - “库”。搜索并启用以下 APIAgent Platform APICloud Run APICloud Build API部署时需要Artifact Registry API存储容器镜像配置服务账号可选但推荐为安全起见可以创建一个专用于代理部署的服务账号并授予其必要的权限如Cloud Run Admin,Service Account User,Storage Object Admin等。在本地开发时通过gcloud auth application-default login命令进行身份验证。注意对于快速原型和教程直接使用个人账号通过gcloud登录通常更方便。但在生产环境中务必使用具有最小权限的服务账号。2.2 安装 Python 包管理器 uvAgents CLI 通过uv安装这是一个比传统pip更快的 Python 包管理工具。在 macOS/Linux 上安装curl -LsSf https://astral.sh/uv/install.sh | sh安装完成后重启终端或运行source ~/.bashrc或source ~/.zshrc使uv命令生效。在 Windows 上安装通过 PowerShellpowershell -c irm https://astral.sh/uv/install.ps1 | iex验证安装uv --version应输出类似uv 0.4.x的版本信息。2.3 安装并设置 Agents CLI这是唯一一个需要你直接在终端执行的 Agents CLI 命令。它通过uvxuv 的全局脚本运行器来安装google-agents-cli及其所有技能。uvx google-agents-cli setup这个命令会下载google-agents-cli包。将其安装到一个隔离的虚拟环境中。将agents-cli命令行工具注册到你的系统路径中。安装完成后验证是否成功agents-cli --help你应该能看到完整的命令列表包括create,install,run,eval,deploy等。2.4 准备 AI 开发工具你需要一个能够理解并调用 Agents CLI 技能的 AI 开发工具。以下以Claude Code或类似工具为例其工作方式具有代表性。安装 Claude Code根据其官方文档进行安装。通常这可能是一个 IDE 插件如 VS Code 扩展或一个桌面应用程序。确保工具已识别 Agents CLI大多数这类工具会自动检测系统路径中的agents-cli命令。你可以尝试在工具中询问“你能使用 agents-cli 吗” 或 “列出可用的 agents-cli 技能”。工具应该能回应并展示相关能力。配置工具上下文如果需要有些工具可能需要你明确指定项目路径或 Python 环境。确保工具的工作目录是你计划创建代理项目的地方。环境检查清单[ ] Google Cloud 项目已创建且计费已启用。[ ]Agent Platform API等必要 API 已启用。[ ]gcloudCLI 已安装并登录 (gcloud auth application-default login)。[ ]uv已安装且版本 0.4。[ ]agents-cli --help能正常显示帮助信息。[ ] AI 开发工具如 Claude Code已安装并可正常交互。3. 实战构建“Caveman Compressor”代理现在我们将按照标准工作流一步步构建我们的文本压缩代理。请打开你的 AI 开发工具下文以“工具”代称并跟随操作。3.1 启动项目通过自然语言指令生成脚手架在 AI 开发工具的聊天界面中输入以下精确的指令使用 agents-cli 构建一个代理将冗长的文本压缩成简洁的、原始人风格的摘要。工具接收到指令后会激活google-agents-cli-workflow和google-agents-cli-scaffold技能。接下来工具可能会与你进行几轮交互以澄清需求部署目标工具会问“您希望将代理部署到哪里” 对于本教程选择Cloud Run。这是 Google Cloud 上完全托管的无服务器容器平台适合快速部署和扩展。安全约束工具可能会询问是否有特定的内容安全策略或模型防护Model Armor要求。对于原型通常可以先选择默认或“无”。项目名称与路径工具会确认项目名称。它可能会建议caveman-agent并询问创建路径。确认后工具将自动执行以下命令序列你可以在工具的“终端”或“执行日志”面板中观察到# 1. 创建项目脚手架 agents-cli create caveman-agent --prototype --yes # 2. 进入项目目录 cd caveman-agent # 3. 安装项目依赖ADK等 agents-cli install生成的目录结构解析执行完成后你的当前目录下会生成一个caveman-agent文件夹其结构如下caveman-agent/ ├── app/ │ ├── __init__.py │ ├── agent.py # 代理的核心逻辑定义文件 │ └── tools.py # 可选自定义工具定义 ├── tests/ │ ├── __init__.py │ ├── test_agent.py # 单元测试 │ └── eval/ # 评估相关文件 │ ├── eval_config.json │ └── evalsets/ │ └── example.evalset.json ├── infrastructure/ # 部署基础设施配置如Terraform │ └── cloud_run/ ├── DESIGN_SPEC.md # 工具自动生成的代理设计规范 ├── pyproject.toml # Python项目依赖管理 ├── requirements.txt └── README.md关键文件是app/agent.py和DESIGN_SPEC.md。后者记录了工具根据你的指令理解的需求是后续迭代的重要依据。3.2 编写代理逻辑编辑app/agent.py项目创建后工具会自动打开app/agent.py文件。初始内容是一个简单的“回声”代理。现在你需要指示工具将其替换为“原始人压缩器”的逻辑。在工具中输入编辑 app/agent.py 文件实现一个 caveman compressor 代理。它应该使用 Gemini 模型指令是将冗长输入文本转换为简短、简单的摘要带有原始人般的语气。规则省略冠词、填充词和礼貌用语使用短句和简单词汇保留技术术语语气应该是突兀和有趣的但核心含义必须保留。给出一个输入输出示例。工具会调用google-agents-cli-adk-code技能利用其对 ADK 设计模式的理解生成类似下面的代码# app/agent.py from agents import Agent from agents.models import Gemini # 定义根代理 root_agent Agent( namecaveman_agent, modelGemini(modelgemini-flash-latest), # 使用 Gemini Flash 模型速度快成本低 instructionYou are a text compressor. Convert verbose input text into short, simple summaries with a caveman-like tone. Rules: - Omit articles, filler words, and politeness. - Use short sentences and simple words. - Preserve technical terms. - The tone should be abrupt and funny, but the core meaning must be retained. Example input: I would like to deploy the application to production environment. Example output: Me deploy. Production. Now. , # 可以在此处添加 tools[] 来集成搜索、计算等工具 )代码关键点解释from agents import Agent从 ADK 导入核心的Agent类。Gemini(modelgemini-flash-latest)指定使用 Gemini Flash 模型的最新版本。这是一个在响应速度和成本间取得良好平衡的模型适合此类文本转换任务。你也可以根据需要换成gemini-pro-latest或其他模型。instruction这是代理的“人格”和任务描述。清晰、具体的指令对于获得稳定输出至关重要。我们给出了明确的规则和示例。name代理的名称用于日志和追踪。3.3 本地运行测试验证代理基本功能在将代码提交或部署之前必须在本地进行快速测试确保代理能正确响应。在工具中输入在本地运行代理测试一下。输入是“Please help me understand the deployment options available for my project.”工具会执行命令agents-cli run Please help me understand the deployment options available for my project.你将在工具的输出中看到类似的结果Deploy options: Agent Runtime, Cloud Run, GKE. Pick one. Ship.这个输出符合预期它去掉了礼貌用语“Please help me understand”将“deployment options”简化为“Deploy options”列出了核心选项并以突兀、有趣的命令式语气“Pick one. Ship.”结尾。注意agents-cli run命令会在本地启动一个轻量级的运行时加载你的app/agent.py中定义的代理处理输入并返回输出。这是快速迭代代理指令instruction的最有效方式。4. 评估代理创建与运行评估集本地测试通过只意味着代理能运行。要衡量其输出质量是否稳定、是否符合所有规则需要系统性的评估。Agents CLI 集成了评估框架支持使用 LLM 作为评判官LLM-as-Judge。4.1 创建评估集评估集Eval Set是一个 JSON 文件包含了一系列输入和期望的输出或评判标准。指示你的工具创建评估集为这个原始人代理编写评估并运行它们。评估需要覆盖压缩质量、技术术语保留和语气。工具会激活google-agents-cli-eval技能执行以下操作在tests/eval/evalsets/目录下创建caveman.evalset.json文件。根据你的要求生成多个测试用例。让我们查看一下工具可能生成的评估集内容// tests/eval/evalsets/caveman.evalset.json { name: caveman_compressor_evals, evals: [ { input: The quarterly financial report indicates a substantial increase in revenue growth year-over-year, primarily driven by our strategic partnerships in the Asian market., eval: { type: llm_judge, criteria: The output must be a concise, caveman-style summary that preserves the key terms quarterly financial report, revenue growth, and Asian market. It must omit polite phrases and articles. } }, { input: Could you possibly assist me in resetting my forgotten password for the user portal?, eval: { type: llm_judge, criteria: The output must be abrupt and funny, converting the polite request into a direct command like Reset password. Portal. It should not contain please, could you, or assist. } }, { input: We are experiencing a critical outage in the us-east1 region due to a network partition. The SRE team is actively working on mitigation., eval: { type: llm_judge, criteria: The output must retain the technical terms outage, us-east1 region, network partition, SRE team, and mitigation. The tone should be urgent but caveman-like. } } ] }评估集解析每个eval对象包含一个input给代理的输入和一个eval配置。type: llm_judge表示使用一个 LLM通常是另一个 Gemini 模型来根据criteria评判标准判断代理的输出是否合格。criteria需要清晰、可衡量明确指出输出的必要元素和禁止元素。4.2 配置与运行评估工具在创建评估集后还会检查或创建tests/eval/eval_config.json文件用于配置评估运行时例如指定作为评判官的 LLM 模型。然后工具会运行评估agents-cli eval run命令执行后你会在终端看到评估进度和结果。输出会显示每个测试用例是否通过以及评判官LLM的反馈理由。例如Running evaluation for caveman_compressor_evals... - [PASS] Test Case 1: Output Report good. Revenue up. Asia partners. meets criteria. - [FAIL] Test Case 2: Output Help reset password? is still too polite. Missing caveman tone. - [PASS] Test Case 3: Output Outage! us-east1. Network broke. SRE fix. meets criteria. Evaluation completed. 2 passed, 1 failed.4.3 迭代优化代理当出现失败用例时正是迭代改进的时候。根据评估反馈如“语气仍然太礼貌”你可以指示工具调整代理的instruction。在工具中输入第二个测试用例失败了反馈说输出太礼貌。请修改 agent.py 中的指令让语气更粗鲁、更突兀确保它完全省略任何请求性词语。工具会修改app/agent.py中的instruction例如在规则中增加一条“-Neveruse words like could, would, please, help. Use imperative commands only.”。修改后再次运行agents-cli eval run直到所有测试用例通过。这个“构建-评估-迭代”的循环是提升代理质量的核心。5. 部署到 Google Cloud Cloud Run当代理在本地通过评估后就可以部署到生产环境了。我们将使用 Cloud Run因为它无需管理服务器自动扩缩容并且与 Agents CLI 集成良好。5.1 添加部署配置在工具中输入部署指令将这个代理部署到 Cloud Run。工具会激活google-agents-cli-deploy技能执行以下操作增强项目脚手架运行agents-cli scaffold enhance --deployment-target cloud_run。这个命令会在infrastructure/目录下生成或更新 Cloud Run 部署所需的配置文件可能包括 Dockerfile、Cloud Build 配置、以及 IaC如 Terraform模板。这些文件定义了如何将你的代理代码打包成容器并部署到 Cloud Run。检查并配置权限工具会确保当前gcloud认证的用户或服务账号拥有部署到 Cloud Run 的权限Cloud Run Admin,Service Account User,Cloud Build Editor等。5.2 执行部署命令配置完成后工具会执行部署命令agents-cli deploy这个命令在后台会触发一系列 Google Cloud 服务容器构建使用 Cloud Build 根据Dockerfile将你的代理代码及其依赖打包成一个容器镜像并推送到 Artifact Registry。服务部署在 Cloud Run 上创建一个新的 Revision版本使用上一步构建的镜像并配置必要的环境变量、内存、CPU 等。URL 生成部署成功后Cloud Run 会为该服务分配一个唯一的 HTTPS URL。部署过程可能需要几分钟。完成后你会在终端看到类似下面的输出Deployment successful! Service URL: https://caveman-agent-xyz-uc.a.run.app You can send requests to: POST https://caveman-agent-xyz-uc.a.run.app/agent5.3 验证线上服务获得 Service URL 后你可以立即测试部署的代理。使用curl或任何 HTTP 客户端如 Postman发送请求curl -X POST \ -H Content-Type: application/json \ -d {message: I am writing to kindly request an extension for the project deadline, as we have encountered some unforeseen complexities during the integration phase.} \ https://caveman-agent-xyz-uc.a.run.app/agent预期的响应应该是一个符合“原始人”风格的 JSON{ response: Need more time. Project hard. Integration tricky. }6. 观测、排错与生产环境考量部署成功只是第一步。在生产环境中你需要监控代理的运行状况、理解其行为、并能够快速排查问题。6.1 启用与查看追踪Cloud TraceAgents CLI 在部署到 Cloud Run 时默认会启用 Cloud Trace。这是 Google Cloud 的分布式追踪服务。在 Google Cloud Console 中导航到Cloud Trace。在 Trace 列表中你应该能看到以你的服务名如caveman-agent开头的追踪记录。每条记录对应一次向代理发送的请求。点击一条追踪你可以看到详细的时序图包括总耗时。LLM 调用花了多长时间使用了哪个模型。工具执行如果代理调用了工具每个工具的执行耗时。内部处理逻辑。追踪是排查“代理响应慢”问题的首要工具。如果一次请求耗时过长你可以立即看到是 LLM 调用慢还是某个自定义工具拖慢了整体流程。6.2 配置高级可观测性默认的 Trace 提供了请求链路视图。对于更深入的分析你可能需要将日志和指标导出到 BigQuery 和 Cloud Storage 进行长期存储和分析。在工具中输入为我的代理设置可观测性基础设施。工具会调用相关技能自动执行以下任务可能需要你的确认创建服务账号一个具有特定权限如写入 BigQuery 和 Cloud Storage的服务账号。创建 Cloud Storage 存储桶用于存储详细的代理执行日志。创建 BigQuery 数据集和表用于结构化存储指标和事件方便进行 SQL 查询和分析。更新部署配置修改 Cloud Run 服务的环境变量或侧车sidecar配置使其将追踪和日志数据发送到新创建的资源。完成这些设置后你可以在 BigQuery 中编写查询来分析代理的每日调用量、平均响应时间、不同输入的输出分布等。6.3 常见问题与排查路径在开发和使用 Agents CLI 工作流时你可能会遇到以下典型问题问题现象可能原因检查步骤解决方案uvx google-agents-cli setup失败网络问题uv 未正确安装Python 环境冲突。1. 检查网络连接。2. 运行uv --version确认 uv 已安装。3. 尝试使用pipx install google-agents-cli如果已安装 pipx。确保 uv 安装正确或使用备用的 pipx 安装方式。检查代理设置。AI 开发工具不识别agents-cli命令工具的工作环境 PATH 中不包含agents-cli工具未在项目目录中运行。1. 在工具集成的终端中手动运行agents-cli --help。2. 确认工具当前的工作目录是项目根目录。在工具设置中指定正确的 Python 解释器或环境路径。在工具中显式切换到项目目录。agents-cli run无响应或报错app/agent.py中存在语法错误ADK 依赖未正确安装模型配置错误。1. 检查app/agent.py的 Python 语法。2. 在项目目录运行agents-cli install重装依赖。3. 检查Gemini(model...)中的模型名称是否有效。修复代码错误。确保网络可访问 Gemini API。确认 Google Cloud 项目已正确设置且 API 已启用。agents-cli deploy失败缺乏 Google Cloud 部署权限gcloud未登录或项目未设置infrastructure/配置有误。1. 运行gcloud config get-value project确认当前项目。2. 运行gcloud auth list确认已登录。3. 检查infrastructure/cloud_run/下的配置文件。使用gcloud auth application-default login重新登录。在gcloud中设置正确的项目gcloud config set project PROJECT_ID。检查并修复 IaC 配置。部署后访问 Service URL 返回 5xx 错误容器启动失败代码运行时错误内存不足。1. 在 Cloud Console 中进入 Cloud Run 服务详情页查看“日志”标签页。2. 查看容器启动日志和运行时日志。根据日志错误修复代码或调整 Cloud Run 配置如增加内存。检查是否缺少环境变量。评估agents-cli eval run全部失败评估配置 (eval_config.json) 中的 LLM 评判官模型不可用或权限不足评估集 JSON 格式错误。1. 检查tests/eval/eval_config.json中judge_model的配置。2. 手动运行一个简单评估查看详细错误信息。确保评判官模型配置正确且当前环境有权限调用该模型。验证caveman.evalset.json的 JSON 格式。6.4 生产环境最佳实践将原型转化为稳定生产服务还需要考虑以下几点版本管理与回滚Cloud Run 每次部署都会创建一个新的 Revision。利用此功能为每次变更打上标签并配置流量分配。如果新版本出现问题可以立即将 100% 流量切回之前的稳定版本。安全加固身份认证为 Cloud Run 服务启用 IAM 认证只允许特定的服务账号或用户访问。网络将 Cloud Run 服务配置为仅允许内部访问通过 VPC 网络或使用 API 网关、负载均衡器作为入口。密钥管理不要将 API 密钥等敏感信息硬编码在代码中。使用 Google Cloud Secret Manager 存储并通过环境变量注入到 Cloud Run 服务。性能与成本优化模型选择根据任务复杂度选择模型。gemini-flash适合简单任务gemini-pro能力更强但更贵。通过评估确定性价比最高的模型。容器优化优化Dockerfile使用多阶段构建减小镜像体积加快部署速度。自动扩缩容根据 QPS 和并发请求数合理配置 Cloud Run 的自动扩缩容参数在性能和成本间取得平衡。持续集成/持续部署将agents-cli eval run和agents-cli deploy集成到你的 CI/CD 流水线如 Cloud Build、GitHub Actions中。确保代码合并前通过所有评估并自动部署到测试环境。通过 Agents CLI 构建和部署 AI 代理核心价值在于将自然语言意图转化为一套标准化、可重复、可观测的工程实践。它抽象了底层基础设施的复杂性让开发者能更专注于代理本身的逻辑和效果优化。从“Caveman Compressor”这个简单示例出发你可以探索更复杂的场景例如为代理添加联网搜索工具、构建多代理协作系统、或者集成企业知识库进行检索增强生成从而打造出真正解决实际业务问题的智能体。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度