在尝试构建和部署 AI 智能体时你是否曾感到困惑面对 Agent Development Kit (ADK) 这样的开源框架虽然功能强大但学习曲线陡峭从环境配置、代码编写、测试评估到最终部署上线每一步都可能遇到意想不到的坑特别是当你想快速验证一个想法却不得不花费大量时间在基础设施和流程上而不是专注于智能体逻辑本身。这正是 Google 推出的 Agents CLI 旨在解决的问题。Agents CLI 并非一个独立的命令行工具而是一个为 AI 开发工具如 Gemini CLI、Claude Code、Codex 等设计的“技能包”或“上下文增强器”。它将这些工具与 Google Cloud 的 Agent Platform 深度集成让你能够通过自然语言指令直接完成从项目脚手架、代码生成、本地测试、评估优化到云端部署的完整智能体开发生命周期。本文将带你深入探索 Agents CLI 的核心概念、工作原理并通过一个完整的“洞穴人文本压缩器”实战案例手把手教你如何利用它高效构建和部署 AI 智能体。无论你是 AI 应用开发的新手还是希望提升智能体开发效率的资深工程师都能从中获得一套可直接复用的工程化方案。1. Agents CLI 核心概念与架构解析在深入实操之前我们有必要厘清 Agents CLI 究竟是什么以及它在 Google Cloud 的 AI 智能体生态中扮演何种角色。这有助于我们理解其设计哲学和适用场景。1.1 什么是 Agents CLIAgents CLI 是 Google Cloud Agent Platform 提供的一套“机器可读接口”或“技能集合”。它的核心目标是为 AI 驱动的开发工具如 Claude Code, Codex, Antigravity 等提供与 Agent Development Kit (ADK) 和 Google Cloud 服务交互的标准化能力。你可以将其理解为连接你的 AI 开发助手与 Google Cloud 智能体基础设施的“桥梁”或“插件”。它不是让你在终端直接输入agents-cli命令虽然有一个初始的uvx google-agents-cli setup命令而是赋能你的 AI 开发工具使其能够理解诸如“构建一个智能体”、“评估它”、“部署到 Cloud Run”这样的高级指令并自动执行背后一系列复杂的操作。这些操作封装了关于 ADK 最佳实践、评估框架和 Google Cloud 部署的专家知识。1.2 Agents CLI 与 ADK、Agent Platform 的关系要理解 Agents CLI必须将其放在 Google Cloud 的智能体开发生态中来看Agent Development Kit (ADK)一个开源的、代码优先的 Python 框架用于构建复杂的、多步骤的 AI 智能体。它提供了定义智能体、工具、工作流和记忆的核心抽象。ADK 是构建智能体的“地基”。Agent PlatformGoogle Cloud 上托管和管理 AI 智能体的平台。它提供了运行时环境Agent Runtime、评估工具、可观测性、安全治理等一系列服务。这是智能体运行和管理的“云环境”。Agents CLI连接上述两者的“自动化工具链”。它知道如何用 ADK 的正确模式来脚手架一个新项目。编写符合 ADK 规范的智能体代码。创建并运行基于 LLM 的评估测试集。配置并将智能体部署到 Agent Platform 的运行时如 Cloud Run。设置可观测性基础设施如 Cloud Trace, Cloud Storage, BigQuery。因此你的开发流程变成了用自然语言向你的 AI 开发工具描述需求 - AI 工具调用 Agents CLI 封装的技能 - 自动生成代码、运行测试、部署上线。1.3 核心工作流程与“技能”Agents CLI 通过一系列“技能”来工作。当你在 AI 开发工具中输入特定指令时它会激活对应的技能。根据官方文档主要技能包括google-agents-cli-workflowgoogle-agents-cli-scaffold: 用于项目初始化和脚手架。理解你的需求生成项目结构、基础代码和评估文件。google-agents-cli-adk-code: 用于编写和修改 ADK 智能体代码。它理解 ADK 的设计模式能生成符合规范的智能体定义、工具集成等。google-agents-cli-eval: 用于智能体评估。创建测试用例配置“LLM 作为裁判”的评估标准并运行评估。google-agents-cli-deploy: 用于部署。根据目标环境如 Cloud Run添加必要的配置并执行部署命令。这种设计将复杂的智能体开发流程模块化、自动化极大地降低了入门门槛和重复性劳动。2. 环境准备与工具安装开始实战之前我们需要准备好所有必要的工具和环境。这个过程是后续一切操作的基础。2.1 前置条件检查在开始使用 Agents CLI 之前请确保满足以下条件Google Cloud 项目你需要一个有效的 Google Cloud 项目。如果没有请先在 Google Cloud Console 创建。启用 API在你的项目中需要启用Agent Platform API。你可以在 Cloud Console 中搜索 “Agent Platform API” 并启用它。AI 开发工具这是与 Agents CLI 交互的核心。你需要安装并配置以下任一工具Gemini CLI: Google 官方的命令行工具。Claude Code: Anthropic 提供的 AI 编程助手。Codex: 或其他兼容的 AI 编码工具。Antigravity: 另一个流行的 AI 开发工具。 本文的示例将基于“使用 AI 开发工具”的通用流程不绑定到某一特定工具。请根据你的偏好安装并确保其能正常运行。2.2 安装 uv 和 Agents CLIAgents CLI 通过uv一个快速的 Python 包安装器来安装和运行。这是唯一需要你手动在终端执行的命令。步骤 1安装 uv访问 uv 的官方安装指南通常为https://github.com/astral-sh/uv根据你的操作系统选择安装方式。macOS/Linux (使用 curl):curl -LsSf https://astral.sh/uv/install.sh | sh安装后重启你的终端或运行source ~/.bashrc(或source ~/.zshrc) 使uv命令生效。Windows (使用 PowerShell):powershell -c irm https://astral.sh/uv/install.ps1 | iex使用 pip(如果已安装 Python):pip install uv安装完成后验证uv是否安装成功uv --version步骤 2设置 Agents CLI运行以下命令uvx是uv自带的一个工具用于运行远程可执行文件uvx google-agents-cli setup这个命令会完成 Agents CLI 所需的初始配置使其技能能够被你的 AI 开发工具识别和调用。执行成功后通常不会有太多输出但你的 AI 开发工具环境就已经准备好了。步骤 3启动你的 AI 开发工具打开你选择的 AI 开发工具例如在 IDE 中启动 Claude Code 插件或在终端启动 Gemini CLI。确保它运行在刚刚配置好的环境中。至此所有环境和工具准备就绪。接下来我们将进入激动人心的实战环节——构建一个有趣的“洞穴人文本压缩器”智能体。3. 实战构建“洞穴人文本压缩器”智能体我们将遵循智能体开发的完整生命周期脚手架 - 构建 - 评估 - 部署。请确保你的 AI 开发工具已打开并处于就绪状态。3.1 项目脚手架从想法到代码结构我们首先需要告诉 AI 开发工具我们的想法让它帮我们创建项目骨架。在你的 AI 开发工具中输入以下指令Prompt使用 agents-cli 构建一个智能体将冗长的文本压缩成简洁的、洞穴人风格的摘要。你的 AI 开发工具例如 Claude Code在接收到这个指令后会激活google-agents-cli-workflow和google-agents-cli-scaffold技能。接下来你可能会经历以下交互过程澄清问题工具可能会问你一些 clarifying questions例如“这个智能体的部署目标是什么”例如Cloud Run, Agent Runtime“是否有特定的安全或内容约束”“智能体的名称是什么”如果你没有在指令中指定 你可以根据实际情况回答例如部署到 Cloud Run没有特殊约束。对于名称我们可以接受默认或指定为caveman-agent。生成设计文档工具会首先创建一个DESIGN_SPEC.md文件记录智能体的目的、输入输出格式和约束条件。这是一个很好的实践确保了需求的明确性。执行脚手架命令接着工具会在后台执行类似以下的命令序列agents-cli create caveman-agent --prototype --yes cd caveman-agent agents-cli installagents-cli create: 创建一个新的智能体项目。--prototype标志表示这是一个原型项目会生成最简化的结构。--yes标志自动确认所有提示。cd caveman-agent: 进入新创建的项目目录。agents-cli install: 安装项目所需的所有 Python 依赖主要就是 ADK 和其他相关包。这个过程完成后你的当前目录下会生成一个名为caveman-agent的文件夹其结构大致如下caveman-agent/ ├── app/ │ ├── __init__.py │ ├── agent.py # 智能体的主逻辑文件 │ └── ... (可能还有其他模块文件) ├── tests/ │ ├── eval/ │ │ ├── evalsets/ # 存放评估测试集的目录 │ │ └── eval_config.json # 评估配置 │ └── ... (单元测试目录) ├── DESIGN_SPEC.md # 项目设计规范 ├── pyproject.toml # Python 项目依赖和配置 ├── requirements.txt # Python 依赖列表 └── ... (其他配置文件)项目骨架已经搭建完毕包含了智能体代码、测试和评估的基础设施。3.2 构建智能体编写核心逻辑现在我们需要实现智能体的核心功能。AI 开发工具会利用google-agents-cli-adk-code技能来帮助我们编写 ADK 代码。继续在你的 AI 开发工具中输入指令或者它可能已经自动开始编辑app/agent.py文件。我们的目标是创建一个接收文本并返回“洞穴人风格”摘要的智能体。工具会编辑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你是一个文本压缩器。将冗长的输入文本转换为简短、简单的摘要并带有洞穴人般的语气。规则 - 省略冠词、填充词和礼貌用语。 - 使用短句和简单的词语。 - 保留技术术语。 - 语气应该是突兀和有趣的但核心含义必须保留。 示例输入 “我希望将应用程序部署到生产环境。” 示例输出“我部署。生产环境。现在。” , # 注意一个完整的智能体通常还会定义 tools工具和 handlers处理器 # 但对于这个简单的文本转换任务仅靠指令和模型可能就足够了。 # 如果需要更复杂的逻辑如调用外部API可以在这里添加 tools。 )代码解析from adk.agents import Agent: 从 ADK 导入核心的Agent类。from adk.agents.models import Gemini: 从 ADK 导入 Gemini 模型集成。root_agent: 这是智能体的入口点。ADK 支持定义多个智能体并编排它们的工作流但这里我们只定义一个。name: 智能体的标识符。model: 指定智能体使用的大语言模型。这里使用了gemini-flash-latest这是一个快速且成本较低的 Gemini 模型适合原型开发。instruction: 这是智能体的“系统提示词”或角色定义。它详细描述了智能体的任务、规则和示例是引导其行为的关键。清晰的指令对于获得稳定、预期的输出至关重要。3.3 本地测试验证智能体行为在部署之前我们应该先在本地测试智能体是否按预期工作。AI 开发工具可以帮我们运行一个快速测试。你可以在 AI 开发工具中输入指令或者直接在你的项目终端中运行agents-cli run 请帮我理解一下我的项目有哪些部署选项或者你也可以让 AI 开发工具执行这个测试。这个命令会使用本地环境调用我们刚刚定义的caveman_agent并将引号内的文本作为输入。预期输出根据我们设定的“洞穴人”指令一个符合预期的输出可能是部署选项Agent Runtime, Cloud Run, GKE。选一个。上线。这个输出省略了原文中的礼貌用语“请帮我理解一下”将“deployment options”简化为“部署选项”并用短促、命令式的语气结尾符合“洞穴人”风格。如果输出不符合预期例如仍然很冗长或礼貌你可能需要回到app/agent.py文件进一步优化instruction中的提示词然后重新运行测试。这是一个迭代的过程。4. 评估与迭代确保智能体质量构建出原型只是第一步。一个健壮的智能体需要经过系统的评估以确保其在不同输入下都能稳定工作。Agents CLI 提供了强大的评估框架。4.1 创建评估集在 AI 开发工具中输入以下指令为洞穴人智能体编写评估并运行它们。AI 开发工具会激活google-agents-cli-eval技能并执行以下任务创建评估集文件在tests/eval/evalsets/目录下创建一个新的评估集文件例如caveman.evalset.json。这个文件包含了一系列测试用例每个用例有输入和期望的输出或评判标准。配置评估标准编辑tests/eval/eval_config.json文件配置“LLM 作为裁判”的评判标准。这意味着它会使用另一个 LLM通常是更强大的模型来根据我们设定的规则如“是否简洁”、“是否保留原意”、“语气是否像洞穴人”自动判断智能体的回答是否合格。一个简化的caveman.evalset.json可能如下所示{ name: Caveman Compression Evals, evals: [ { input: I would like to respectfully request an extension for the project deadline, as we are encountering unforeseen technical complexities., expected_output_patterns: [deadline, extend, tech, hard], criteria: [ Response must be extremely concise (under 10 words)., Response must drop polite phrases like respectfully request., Core meaning about deadline extension due to tech issues must be preserved. ] }, { input: The synergistic paradigm shift leveraging blockchain technology will fundamentally disrupt the incumbent financial infrastructure., expected_output_patterns: [blockchain, change, finance], criteria: [ Must simplify jargon (synergistic paradigm shift - big change)., Must retain key technical term blockchain., Tone should be blunt and primitive. ] }, { input: Hello, how are you doing today?, expected_output_patterns: [ugh, grunt, hello], criteria: [ Response should not be polite or conversational., Should be a caveman-style greeting. ] } ] }4.2 运行评估并迭代优化创建好评估集后AI 开发工具会运行评估命令agents-cli eval run这个命令会加载caveman.evalset.json中的每个测试用例。将input发送给我们的caveman_agent。使用eval_config.json中配置的 LLM 裁判根据criteria来评判智能体的实际输出。生成评估报告显示每个测试用例是通过还是失败并可能提供失败原因。迭代过程 如果某些测试用例失败了例如裁判认为回答“仍然太礼貌”你需要根据反馈调整智能体。你可以给 AI 开发工具这样的反馈对问候语的测试响应太礼貌了。让它更粗鲁一些。然后AI 开发工具会去修改app/agent.py中的instruction例如加强关于省略礼貌用语的规则。之后再次运行agents-cli eval run直到所有测试通过或达到满意的质量。这个“构建-评估-迭代”的循环是开发可靠智能体的关键Agents CLI 将其自动化大大提升了效率。5. 部署到 Google Cloud智能体通过本地测试和评估后就可以部署到生产环境了。我们将把它部署到 Google Cloud Run这是一个完全托管的无服务器计算平台。5.1 执行部署在 AI 开发工具中输入部署指令将此智能体部署到 Cloud Run。AI 开发工具会激活google-agents-cli-deploy技能并执行以下操作增强脚手架配置运行命令添加针对 Cloud Run 部署所需的基础设施配置。agents-cli scaffold enhance --deployment-target cloud_run这个命令可能会生成或修改诸如Dockerfile、.dockerignore、Cloud Run 服务配置文件等为部署做好准备。执行部署运行部署命令。agents-cli deploy这个命令会执行一系列操作构建智能体应用的 Docker 镜像。将镜像推送到 Google Container Registry (GCR) 或 Artifact Registry。在 Cloud Run 上创建或更新一个服务使用刚推送的镜像。配置必要的服务账户、网络设置等。最终输出一个 HTTPS 服务 URL。部署完成后你的终端或 AI 开发工具的输出中会包含类似以下的信息Service URL: https://caveman-agent-xyz-uc.a.run.app现在你的“洞穴人文本压缩器”智能体已经作为一个 Web 服务运行在 Google Cloud 上了你可以通过向这个 URL 发送 HTTP POST 请求通常是一个包含输入文本的 JSON来调用它。5.2 观察与监控部署后了解智能体如何运行至关重要。默认追踪Cloud Trace 在部署时默认启用。你可以前往 Google Cloud Console 中的 Cloud Trace 页面 查看智能体处理请求的详细追踪信息。你会看到 LLM 调用、函数执行等各个环节的耗时和状态这对于性能分析和调试非常有帮助。设置高级可观测性如果你需要更详细的数据如日志持久化、自定义指标可以指示 AI 开发工具为我的智能体设置可观测性基础设施。工具会调用相关技能自动配置一个服务账户、一个 Cloud Storage 存储桶和一个 BigQuery 数据集并更新已部署的服务以使用这些资源。这样你就可以将日志、追踪和指标数据导出进行深度分析了。6. 常见问题与排查思路在使用 Agents CLI 和 ADK 进行开发时你可能会遇到一些典型问题。下表列出了常见问题及其解决方法问题现象可能原因排查与解决思路运行uvx google-agents-cli setup失败1. 网络问题无法连接到 PyPI 或相关仓库。2.uv未正确安装或不在 PATH 中。3. Python 环境冲突。1. 检查网络连接尝试使用镜像源。2. 在终端输入uv --version确认安装成功。如果失败重新安装uv。3. 确保使用的是较新版本的 Python如 3.9。AI 开发工具无法识别agents-cli相关指令1. Agents CLI 设置未成功。2. AI 开发工具未在设置后的环境中运行。3. 该工具不支持或未集成 Agents CLI 技能。1. 重新运行uvx google-agents-cli setup并确认无报错。2. 关闭并重新启动你的 AI 开发工具确保它继承了新的环境变量。3. 查阅你所用的 AI 开发工具文档确认其是否支持 Google Agents CLI 集成。agents-cli create或agents-cli install失败1. 没有有效的 Google Cloud 项目或未启用 Agent Platform API。2. 本地认证gcloud未设置或过期。3. 项目目录权限问题。1. 在 Cloud Console 确认项目存在且 API 已启用。2. 运行gcloud auth application-default login进行本地应用默认凭据登录。3. 确保你对当前目录有读写权限。智能体本地运行 (agents-cli run) 无响应或报错1.app/agent.py中的代码有语法错误或逻辑错误。2. 缺少必要的环境变量如GOOGLE_API_KEY。3. 模型名称错误或不可用。1. 检查app/agent.py文件确保Agent定义正确特别是instruction的字符串格式。2. 如果你使用的模型需要 API 密钥请确保已在环境变量中设置。3. 确认model参数指定的模型名称是正确的如gemini-flash-latest。部署到 Cloud Run 失败1. Docker 构建失败依赖问题、Dockerfile 错误。2. 容器镜像推送权限不足。3. Cloud Run API 未启用或配额不足。1. 查看agents-cli deploy的详细错误日志通常会指出 Docker 构建哪一步出错。2. 确保使用的服务账户拥有Cloud Run Admin、Service Account User和Container Registry相关权限。3. 在 Cloud Console 启用 Cloud Run API 并检查配额。评估 (agents-cli eval run) 全部失败或评分异常1. 评估集 (evalset.json) 格式错误。2. LLM 裁判的评判标准 (criteria) 描述模糊。3. 评估使用的模型 API 调用失败。1. 验证evalset.json是否为合法的 JSON 格式且结构符合要求。2. 将评判标准修改得更具体、可衡量例如将“要简洁”改为“输出单词数必须少于 10 个”。3. 检查网络和 API 密钥确保评估过程能正常调用裁判 LLM。7. 进阶探索与最佳实践掌握了基础流程后你可以利用 Agents CLI 探索更复杂的智能体模式并遵循一些最佳实践来构建生产级应用。7.1 探索复杂智能体设计Agents CLI 和 ADK 支持多种高级模式你可以通过自然语言指令让 AI 开发工具帮你搭建添加工具智能体可以调用外部 API 或函数。尝试指令集成一个 Google 搜索工具让智能体能够获取实时信息。这会让工具在app/agent.py中为root_agent添加tools参数并配置相应的搜索工具。构建多智能体系统ADK 擅长编排多个协同工作的智能体。尝试指令创建一个可以与其他智能体交互的智能体使用 adk_a2a 模板。这会生成一个包含多个Agent实例和它们之间交互逻辑的复杂工作流。构建 RAG 智能体让智能体基于自定义知识库回答问题。尝试指令使用 agentic_rag 模板构建一个能基于我们的文档回答问题的智能体。这会引导你配置 RAG 引擎将文档切片、向量化并让智能体具备检索增强生成的能力。7.2 工程化最佳实践版本控制将你的caveman-agent项目目录纳入 Git 等版本控制系统。这包括app/、tests/、pyproject.toml、Dockerfile以及所有生成的配置文件。避免将 API 密钥、服务账户密钥等敏感信息提交到仓库。环境隔离为开发、测试和生产环境使用不同的 Google Cloud 项目或至少不同的配置。Agents CLI 部署时通常会使用当前gcloud配置的项目确保你在正确的环境下操作。提示词工程智能体的instruction是其灵魂。要持续迭代和优化具体明确避免模糊的指令。使用清晰的规则、正面和反面的例子。分步骤思考对于复杂任务在指令中鼓励模型“逐步思考”这能提高输出的可靠性和准确性。安全边界在指令中明确禁止智能体执行有害、偏见或超出其范围的操-作。评估驱动开发不要只依赖少数几个测试用例。建立全面的评估集覆盖核心功能正常用例。边界情况空输入、极长输入、特殊字符。对抗性测试试图让智能体产生有害、越权或不准确回应的输入。持续集成考虑将agents-cli eval run集成到你的 CI/CD 流水线中确保每次代码变更都不会导致质量回退。监控与告警对于生产环境中的智能体除了利用 Cloud Trace还应配置 Cloud Logging 来记录所有请求和响应注意隐私和合规。使用 Cloud Monitoring 设置关键指标的告警如延迟、错误率和调用次数。定期审查 Model Armor 等安全功能产生的报告确保智能体行为符合预期。成本优化在原型阶段使用gemini-flash-latest这类快速、低成本模型。对于评估中的“LLM 裁判”可以考虑使用更强大但更贵的模型如gemini-pro以确保评估质量而对于生产智能体根据性能-成本权衡选择模型。利用 ADK 的缓存机制和会话管理避免重复计算。通过 Agents CLIGoogle 将 AI 智能体开发的复杂性封装在了一套自然的、由 AI 驱动的交互流程之后。它降低了从创意到可部署原型的技术门槛让开发者能更专注于智能体本身的逻辑和价值。从本文的“洞穴人压缩器”这个简单例子出发你可以利用这套工具链去构建客服助手、代码审查员、数据分析师等各式各样强大的 AI 应用。记住清晰的指令、系统的评估和自动化的部署流程是构建可靠智能体的三大支柱。现在就打开你的 AI 开发工具开始构建你的第一个智能体吧。
Agents CLI实战：用自然语言指令高效构建与部署AI智能体
在尝试构建和部署 AI 智能体时你是否曾感到困惑面对 Agent Development Kit (ADK) 这样的开源框架虽然功能强大但学习曲线陡峭从环境配置、代码编写、测试评估到最终部署上线每一步都可能遇到意想不到的坑特别是当你想快速验证一个想法却不得不花费大量时间在基础设施和流程上而不是专注于智能体逻辑本身。这正是 Google 推出的 Agents CLI 旨在解决的问题。Agents CLI 并非一个独立的命令行工具而是一个为 AI 开发工具如 Gemini CLI、Claude Code、Codex 等设计的“技能包”或“上下文增强器”。它将这些工具与 Google Cloud 的 Agent Platform 深度集成让你能够通过自然语言指令直接完成从项目脚手架、代码生成、本地测试、评估优化到云端部署的完整智能体开发生命周期。本文将带你深入探索 Agents CLI 的核心概念、工作原理并通过一个完整的“洞穴人文本压缩器”实战案例手把手教你如何利用它高效构建和部署 AI 智能体。无论你是 AI 应用开发的新手还是希望提升智能体开发效率的资深工程师都能从中获得一套可直接复用的工程化方案。1. Agents CLI 核心概念与架构解析在深入实操之前我们有必要厘清 Agents CLI 究竟是什么以及它在 Google Cloud 的 AI 智能体生态中扮演何种角色。这有助于我们理解其设计哲学和适用场景。1.1 什么是 Agents CLIAgents CLI 是 Google Cloud Agent Platform 提供的一套“机器可读接口”或“技能集合”。它的核心目标是为 AI 驱动的开发工具如 Claude Code, Codex, Antigravity 等提供与 Agent Development Kit (ADK) 和 Google Cloud 服务交互的标准化能力。你可以将其理解为连接你的 AI 开发助手与 Google Cloud 智能体基础设施的“桥梁”或“插件”。它不是让你在终端直接输入agents-cli命令虽然有一个初始的uvx google-agents-cli setup命令而是赋能你的 AI 开发工具使其能够理解诸如“构建一个智能体”、“评估它”、“部署到 Cloud Run”这样的高级指令并自动执行背后一系列复杂的操作。这些操作封装了关于 ADK 最佳实践、评估框架和 Google Cloud 部署的专家知识。1.2 Agents CLI 与 ADK、Agent Platform 的关系要理解 Agents CLI必须将其放在 Google Cloud 的智能体开发生态中来看Agent Development Kit (ADK)一个开源的、代码优先的 Python 框架用于构建复杂的、多步骤的 AI 智能体。它提供了定义智能体、工具、工作流和记忆的核心抽象。ADK 是构建智能体的“地基”。Agent PlatformGoogle Cloud 上托管和管理 AI 智能体的平台。它提供了运行时环境Agent Runtime、评估工具、可观测性、安全治理等一系列服务。这是智能体运行和管理的“云环境”。Agents CLI连接上述两者的“自动化工具链”。它知道如何用 ADK 的正确模式来脚手架一个新项目。编写符合 ADK 规范的智能体代码。创建并运行基于 LLM 的评估测试集。配置并将智能体部署到 Agent Platform 的运行时如 Cloud Run。设置可观测性基础设施如 Cloud Trace, Cloud Storage, BigQuery。因此你的开发流程变成了用自然语言向你的 AI 开发工具描述需求 - AI 工具调用 Agents CLI 封装的技能 - 自动生成代码、运行测试、部署上线。1.3 核心工作流程与“技能”Agents CLI 通过一系列“技能”来工作。当你在 AI 开发工具中输入特定指令时它会激活对应的技能。根据官方文档主要技能包括google-agents-cli-workflowgoogle-agents-cli-scaffold: 用于项目初始化和脚手架。理解你的需求生成项目结构、基础代码和评估文件。google-agents-cli-adk-code: 用于编写和修改 ADK 智能体代码。它理解 ADK 的设计模式能生成符合规范的智能体定义、工具集成等。google-agents-cli-eval: 用于智能体评估。创建测试用例配置“LLM 作为裁判”的评估标准并运行评估。google-agents-cli-deploy: 用于部署。根据目标环境如 Cloud Run添加必要的配置并执行部署命令。这种设计将复杂的智能体开发流程模块化、自动化极大地降低了入门门槛和重复性劳动。2. 环境准备与工具安装开始实战之前我们需要准备好所有必要的工具和环境。这个过程是后续一切操作的基础。2.1 前置条件检查在开始使用 Agents CLI 之前请确保满足以下条件Google Cloud 项目你需要一个有效的 Google Cloud 项目。如果没有请先在 Google Cloud Console 创建。启用 API在你的项目中需要启用Agent Platform API。你可以在 Cloud Console 中搜索 “Agent Platform API” 并启用它。AI 开发工具这是与 Agents CLI 交互的核心。你需要安装并配置以下任一工具Gemini CLI: Google 官方的命令行工具。Claude Code: Anthropic 提供的 AI 编程助手。Codex: 或其他兼容的 AI 编码工具。Antigravity: 另一个流行的 AI 开发工具。 本文的示例将基于“使用 AI 开发工具”的通用流程不绑定到某一特定工具。请根据你的偏好安装并确保其能正常运行。2.2 安装 uv 和 Agents CLIAgents CLI 通过uv一个快速的 Python 包安装器来安装和运行。这是唯一需要你手动在终端执行的命令。步骤 1安装 uv访问 uv 的官方安装指南通常为https://github.com/astral-sh/uv根据你的操作系统选择安装方式。macOS/Linux (使用 curl):curl -LsSf https://astral.sh/uv/install.sh | sh安装后重启你的终端或运行source ~/.bashrc(或source ~/.zshrc) 使uv命令生效。Windows (使用 PowerShell):powershell -c irm https://astral.sh/uv/install.ps1 | iex使用 pip(如果已安装 Python):pip install uv安装完成后验证uv是否安装成功uv --version步骤 2设置 Agents CLI运行以下命令uvx是uv自带的一个工具用于运行远程可执行文件uvx google-agents-cli setup这个命令会完成 Agents CLI 所需的初始配置使其技能能够被你的 AI 开发工具识别和调用。执行成功后通常不会有太多输出但你的 AI 开发工具环境就已经准备好了。步骤 3启动你的 AI 开发工具打开你选择的 AI 开发工具例如在 IDE 中启动 Claude Code 插件或在终端启动 Gemini CLI。确保它运行在刚刚配置好的环境中。至此所有环境和工具准备就绪。接下来我们将进入激动人心的实战环节——构建一个有趣的“洞穴人文本压缩器”智能体。3. 实战构建“洞穴人文本压缩器”智能体我们将遵循智能体开发的完整生命周期脚手架 - 构建 - 评估 - 部署。请确保你的 AI 开发工具已打开并处于就绪状态。3.1 项目脚手架从想法到代码结构我们首先需要告诉 AI 开发工具我们的想法让它帮我们创建项目骨架。在你的 AI 开发工具中输入以下指令Prompt使用 agents-cli 构建一个智能体将冗长的文本压缩成简洁的、洞穴人风格的摘要。你的 AI 开发工具例如 Claude Code在接收到这个指令后会激活google-agents-cli-workflow和google-agents-cli-scaffold技能。接下来你可能会经历以下交互过程澄清问题工具可能会问你一些 clarifying questions例如“这个智能体的部署目标是什么”例如Cloud Run, Agent Runtime“是否有特定的安全或内容约束”“智能体的名称是什么”如果你没有在指令中指定 你可以根据实际情况回答例如部署到 Cloud Run没有特殊约束。对于名称我们可以接受默认或指定为caveman-agent。生成设计文档工具会首先创建一个DESIGN_SPEC.md文件记录智能体的目的、输入输出格式和约束条件。这是一个很好的实践确保了需求的明确性。执行脚手架命令接着工具会在后台执行类似以下的命令序列agents-cli create caveman-agent --prototype --yes cd caveman-agent agents-cli installagents-cli create: 创建一个新的智能体项目。--prototype标志表示这是一个原型项目会生成最简化的结构。--yes标志自动确认所有提示。cd caveman-agent: 进入新创建的项目目录。agents-cli install: 安装项目所需的所有 Python 依赖主要就是 ADK 和其他相关包。这个过程完成后你的当前目录下会生成一个名为caveman-agent的文件夹其结构大致如下caveman-agent/ ├── app/ │ ├── __init__.py │ ├── agent.py # 智能体的主逻辑文件 │ └── ... (可能还有其他模块文件) ├── tests/ │ ├── eval/ │ │ ├── evalsets/ # 存放评估测试集的目录 │ │ └── eval_config.json # 评估配置 │ └── ... (单元测试目录) ├── DESIGN_SPEC.md # 项目设计规范 ├── pyproject.toml # Python 项目依赖和配置 ├── requirements.txt # Python 依赖列表 └── ... (其他配置文件)项目骨架已经搭建完毕包含了智能体代码、测试和评估的基础设施。3.2 构建智能体编写核心逻辑现在我们需要实现智能体的核心功能。AI 开发工具会利用google-agents-cli-adk-code技能来帮助我们编写 ADK 代码。继续在你的 AI 开发工具中输入指令或者它可能已经自动开始编辑app/agent.py文件。我们的目标是创建一个接收文本并返回“洞穴人风格”摘要的智能体。工具会编辑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你是一个文本压缩器。将冗长的输入文本转换为简短、简单的摘要并带有洞穴人般的语气。规则 - 省略冠词、填充词和礼貌用语。 - 使用短句和简单的词语。 - 保留技术术语。 - 语气应该是突兀和有趣的但核心含义必须保留。 示例输入 “我希望将应用程序部署到生产环境。” 示例输出“我部署。生产环境。现在。” , # 注意一个完整的智能体通常还会定义 tools工具和 handlers处理器 # 但对于这个简单的文本转换任务仅靠指令和模型可能就足够了。 # 如果需要更复杂的逻辑如调用外部API可以在这里添加 tools。 )代码解析from adk.agents import Agent: 从 ADK 导入核心的Agent类。from adk.agents.models import Gemini: 从 ADK 导入 Gemini 模型集成。root_agent: 这是智能体的入口点。ADK 支持定义多个智能体并编排它们的工作流但这里我们只定义一个。name: 智能体的标识符。model: 指定智能体使用的大语言模型。这里使用了gemini-flash-latest这是一个快速且成本较低的 Gemini 模型适合原型开发。instruction: 这是智能体的“系统提示词”或角色定义。它详细描述了智能体的任务、规则和示例是引导其行为的关键。清晰的指令对于获得稳定、预期的输出至关重要。3.3 本地测试验证智能体行为在部署之前我们应该先在本地测试智能体是否按预期工作。AI 开发工具可以帮我们运行一个快速测试。你可以在 AI 开发工具中输入指令或者直接在你的项目终端中运行agents-cli run 请帮我理解一下我的项目有哪些部署选项或者你也可以让 AI 开发工具执行这个测试。这个命令会使用本地环境调用我们刚刚定义的caveman_agent并将引号内的文本作为输入。预期输出根据我们设定的“洞穴人”指令一个符合预期的输出可能是部署选项Agent Runtime, Cloud Run, GKE。选一个。上线。这个输出省略了原文中的礼貌用语“请帮我理解一下”将“deployment options”简化为“部署选项”并用短促、命令式的语气结尾符合“洞穴人”风格。如果输出不符合预期例如仍然很冗长或礼貌你可能需要回到app/agent.py文件进一步优化instruction中的提示词然后重新运行测试。这是一个迭代的过程。4. 评估与迭代确保智能体质量构建出原型只是第一步。一个健壮的智能体需要经过系统的评估以确保其在不同输入下都能稳定工作。Agents CLI 提供了强大的评估框架。4.1 创建评估集在 AI 开发工具中输入以下指令为洞穴人智能体编写评估并运行它们。AI 开发工具会激活google-agents-cli-eval技能并执行以下任务创建评估集文件在tests/eval/evalsets/目录下创建一个新的评估集文件例如caveman.evalset.json。这个文件包含了一系列测试用例每个用例有输入和期望的输出或评判标准。配置评估标准编辑tests/eval/eval_config.json文件配置“LLM 作为裁判”的评判标准。这意味着它会使用另一个 LLM通常是更强大的模型来根据我们设定的规则如“是否简洁”、“是否保留原意”、“语气是否像洞穴人”自动判断智能体的回答是否合格。一个简化的caveman.evalset.json可能如下所示{ name: Caveman Compression Evals, evals: [ { input: I would like to respectfully request an extension for the project deadline, as we are encountering unforeseen technical complexities., expected_output_patterns: [deadline, extend, tech, hard], criteria: [ Response must be extremely concise (under 10 words)., Response must drop polite phrases like respectfully request., Core meaning about deadline extension due to tech issues must be preserved. ] }, { input: The synergistic paradigm shift leveraging blockchain technology will fundamentally disrupt the incumbent financial infrastructure., expected_output_patterns: [blockchain, change, finance], criteria: [ Must simplify jargon (synergistic paradigm shift - big change)., Must retain key technical term blockchain., Tone should be blunt and primitive. ] }, { input: Hello, how are you doing today?, expected_output_patterns: [ugh, grunt, hello], criteria: [ Response should not be polite or conversational., Should be a caveman-style greeting. ] } ] }4.2 运行评估并迭代优化创建好评估集后AI 开发工具会运行评估命令agents-cli eval run这个命令会加载caveman.evalset.json中的每个测试用例。将input发送给我们的caveman_agent。使用eval_config.json中配置的 LLM 裁判根据criteria来评判智能体的实际输出。生成评估报告显示每个测试用例是通过还是失败并可能提供失败原因。迭代过程 如果某些测试用例失败了例如裁判认为回答“仍然太礼貌”你需要根据反馈调整智能体。你可以给 AI 开发工具这样的反馈对问候语的测试响应太礼貌了。让它更粗鲁一些。然后AI 开发工具会去修改app/agent.py中的instruction例如加强关于省略礼貌用语的规则。之后再次运行agents-cli eval run直到所有测试通过或达到满意的质量。这个“构建-评估-迭代”的循环是开发可靠智能体的关键Agents CLI 将其自动化大大提升了效率。5. 部署到 Google Cloud智能体通过本地测试和评估后就可以部署到生产环境了。我们将把它部署到 Google Cloud Run这是一个完全托管的无服务器计算平台。5.1 执行部署在 AI 开发工具中输入部署指令将此智能体部署到 Cloud Run。AI 开发工具会激活google-agents-cli-deploy技能并执行以下操作增强脚手架配置运行命令添加针对 Cloud Run 部署所需的基础设施配置。agents-cli scaffold enhance --deployment-target cloud_run这个命令可能会生成或修改诸如Dockerfile、.dockerignore、Cloud Run 服务配置文件等为部署做好准备。执行部署运行部署命令。agents-cli deploy这个命令会执行一系列操作构建智能体应用的 Docker 镜像。将镜像推送到 Google Container Registry (GCR) 或 Artifact Registry。在 Cloud Run 上创建或更新一个服务使用刚推送的镜像。配置必要的服务账户、网络设置等。最终输出一个 HTTPS 服务 URL。部署完成后你的终端或 AI 开发工具的输出中会包含类似以下的信息Service URL: https://caveman-agent-xyz-uc.a.run.app现在你的“洞穴人文本压缩器”智能体已经作为一个 Web 服务运行在 Google Cloud 上了你可以通过向这个 URL 发送 HTTP POST 请求通常是一个包含输入文本的 JSON来调用它。5.2 观察与监控部署后了解智能体如何运行至关重要。默认追踪Cloud Trace 在部署时默认启用。你可以前往 Google Cloud Console 中的 Cloud Trace 页面 查看智能体处理请求的详细追踪信息。你会看到 LLM 调用、函数执行等各个环节的耗时和状态这对于性能分析和调试非常有帮助。设置高级可观测性如果你需要更详细的数据如日志持久化、自定义指标可以指示 AI 开发工具为我的智能体设置可观测性基础设施。工具会调用相关技能自动配置一个服务账户、一个 Cloud Storage 存储桶和一个 BigQuery 数据集并更新已部署的服务以使用这些资源。这样你就可以将日志、追踪和指标数据导出进行深度分析了。6. 常见问题与排查思路在使用 Agents CLI 和 ADK 进行开发时你可能会遇到一些典型问题。下表列出了常见问题及其解决方法问题现象可能原因排查与解决思路运行uvx google-agents-cli setup失败1. 网络问题无法连接到 PyPI 或相关仓库。2.uv未正确安装或不在 PATH 中。3. Python 环境冲突。1. 检查网络连接尝试使用镜像源。2. 在终端输入uv --version确认安装成功。如果失败重新安装uv。3. 确保使用的是较新版本的 Python如 3.9。AI 开发工具无法识别agents-cli相关指令1. Agents CLI 设置未成功。2. AI 开发工具未在设置后的环境中运行。3. 该工具不支持或未集成 Agents CLI 技能。1. 重新运行uvx google-agents-cli setup并确认无报错。2. 关闭并重新启动你的 AI 开发工具确保它继承了新的环境变量。3. 查阅你所用的 AI 开发工具文档确认其是否支持 Google Agents CLI 集成。agents-cli create或agents-cli install失败1. 没有有效的 Google Cloud 项目或未启用 Agent Platform API。2. 本地认证gcloud未设置或过期。3. 项目目录权限问题。1. 在 Cloud Console 确认项目存在且 API 已启用。2. 运行gcloud auth application-default login进行本地应用默认凭据登录。3. 确保你对当前目录有读写权限。智能体本地运行 (agents-cli run) 无响应或报错1.app/agent.py中的代码有语法错误或逻辑错误。2. 缺少必要的环境变量如GOOGLE_API_KEY。3. 模型名称错误或不可用。1. 检查app/agent.py文件确保Agent定义正确特别是instruction的字符串格式。2. 如果你使用的模型需要 API 密钥请确保已在环境变量中设置。3. 确认model参数指定的模型名称是正确的如gemini-flash-latest。部署到 Cloud Run 失败1. Docker 构建失败依赖问题、Dockerfile 错误。2. 容器镜像推送权限不足。3. Cloud Run API 未启用或配额不足。1. 查看agents-cli deploy的详细错误日志通常会指出 Docker 构建哪一步出错。2. 确保使用的服务账户拥有Cloud Run Admin、Service Account User和Container Registry相关权限。3. 在 Cloud Console 启用 Cloud Run API 并检查配额。评估 (agents-cli eval run) 全部失败或评分异常1. 评估集 (evalset.json) 格式错误。2. LLM 裁判的评判标准 (criteria) 描述模糊。3. 评估使用的模型 API 调用失败。1. 验证evalset.json是否为合法的 JSON 格式且结构符合要求。2. 将评判标准修改得更具体、可衡量例如将“要简洁”改为“输出单词数必须少于 10 个”。3. 检查网络和 API 密钥确保评估过程能正常调用裁判 LLM。7. 进阶探索与最佳实践掌握了基础流程后你可以利用 Agents CLI 探索更复杂的智能体模式并遵循一些最佳实践来构建生产级应用。7.1 探索复杂智能体设计Agents CLI 和 ADK 支持多种高级模式你可以通过自然语言指令让 AI 开发工具帮你搭建添加工具智能体可以调用外部 API 或函数。尝试指令集成一个 Google 搜索工具让智能体能够获取实时信息。这会让工具在app/agent.py中为root_agent添加tools参数并配置相应的搜索工具。构建多智能体系统ADK 擅长编排多个协同工作的智能体。尝试指令创建一个可以与其他智能体交互的智能体使用 adk_a2a 模板。这会生成一个包含多个Agent实例和它们之间交互逻辑的复杂工作流。构建 RAG 智能体让智能体基于自定义知识库回答问题。尝试指令使用 agentic_rag 模板构建一个能基于我们的文档回答问题的智能体。这会引导你配置 RAG 引擎将文档切片、向量化并让智能体具备检索增强生成的能力。7.2 工程化最佳实践版本控制将你的caveman-agent项目目录纳入 Git 等版本控制系统。这包括app/、tests/、pyproject.toml、Dockerfile以及所有生成的配置文件。避免将 API 密钥、服务账户密钥等敏感信息提交到仓库。环境隔离为开发、测试和生产环境使用不同的 Google Cloud 项目或至少不同的配置。Agents CLI 部署时通常会使用当前gcloud配置的项目确保你在正确的环境下操作。提示词工程智能体的instruction是其灵魂。要持续迭代和优化具体明确避免模糊的指令。使用清晰的规则、正面和反面的例子。分步骤思考对于复杂任务在指令中鼓励模型“逐步思考”这能提高输出的可靠性和准确性。安全边界在指令中明确禁止智能体执行有害、偏见或超出其范围的操-作。评估驱动开发不要只依赖少数几个测试用例。建立全面的评估集覆盖核心功能正常用例。边界情况空输入、极长输入、特殊字符。对抗性测试试图让智能体产生有害、越权或不准确回应的输入。持续集成考虑将agents-cli eval run集成到你的 CI/CD 流水线中确保每次代码变更都不会导致质量回退。监控与告警对于生产环境中的智能体除了利用 Cloud Trace还应配置 Cloud Logging 来记录所有请求和响应注意隐私和合规。使用 Cloud Monitoring 设置关键指标的告警如延迟、错误率和调用次数。定期审查 Model Armor 等安全功能产生的报告确保智能体行为符合预期。成本优化在原型阶段使用gemini-flash-latest这类快速、低成本模型。对于评估中的“LLM 裁判”可以考虑使用更强大但更贵的模型如gemini-pro以确保评估质量而对于生产智能体根据性能-成本权衡选择模型。利用 ADK 的缓存机制和会话管理避免重复计算。通过 Agents CLIGoogle 将 AI 智能体开发的复杂性封装在了一套自然的、由 AI 驱动的交互流程之后。它降低了从创意到可部署原型的技术门槛让开发者能更专注于智能体本身的逻辑和价值。从本文的“洞穴人压缩器”这个简单例子出发你可以利用这套工具链去构建客服助手、代码审查员、数据分析师等各式各样强大的 AI 应用。记住清晰的指令、系统的评估和自动化的部署流程是构建可靠智能体的三大支柱。现在就打开你的 AI 开发工具开始构建你的第一个智能体吧。
