在 Agent Platform 中使用 ADK 和 Agents CLI 构建智能体

本文档演示了如何在 Agent Platform 中使用 Agents CLI 和 智能体开发套件 (ADK) 构建、评估和部署 AI 代理原型。ADK 是一个代码优先的开源框架，用于构建复杂的 AI 代理。 Agents CLI 为 AI 开发工具提供了一个统一的机器可读接口，以便与 ADK 进行交互，从而实现端到端的代理生命周期管理。 它封装了 ADK、代理评估和部署方面的专业知识，使 AI 开发工具能够通过自然语言提示执行复杂操作。Google Cloud

通过将 Agents CLI 与您偏好的 AI 赋能的开发工具（例如 Gemini CLI、Claude Code 或 Codex）搭配使用，您可以使用自然语言 提示来定义代理原型、在本地对其进行测试，并将其部署到 Google Cloud 运行时。

本教程将指导您创建一个“穴居人 压缩器”代理，该代理的灵感 来自穴居人，可将冗长的文本转换为简洁的摘要。

准备工作

完成以下前提条件：

  1. 确保您拥有 Google Cloud 项目并已启用 Agent Platform API。 如果没有，请完成以下快速入门教程之一：

  2. 安装 AI 赋能的开发工具，例如 Antigravity、 Gemini CLI、Claude Code 或 Codex。 此工具是与 Agents CLI 交互所必需的。

设置

  1. 安装 uv（Python 软件包安装程序）。如需查看相关说明，请参阅 uv 安装指南。

  2. 使用 uvx（随 uv 一起提供）运行 Agents CLI 设置命令。这是您直接执行的唯一 Agents CLI 命令：

    uvx google-agents-cli setup

  3. 打开 AI 开发工具，例如 Antigravity。

搭建项目

使用以下提示指示 AI 开发工具：

Use agents-cli to build an agent that compresses verbose text into concise, caveman-style summaries.

AI 开发工具会激活 google-agents-cli-workflow 和 google-agents-cli-scaffold 技能。它执行以下操作：

  • 询问澄清性问题，例如其部署目标和安全限制。
  • 编写 DESIGN_SPEC.md 文件，以捕获代理的用途。

  • 搭建项目：

    agents-cli create caveman-agent --prototype --yes
cd caveman-agent && agents-cli install

此过程会创建一个包含样板代理代码、测试和评估集的项目。

构建代理

AI 开发工具会修改 app/agent.py，将默认代理替换为穴居人压缩器逻辑。它利用 google-agents-cli-adk-code 技能来实现 ADK 设计模式。

生成的代理定义类似于以下内容：

root_agent = Agent(
   name="caveman_agent",
   model=Gemini(model="gemini-3.5-flash"),
   instruction="""You 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."
   """,
)

然后，AI 开发工具会执行基本功能测试：

agents-cli run "Please help me understand the deployment options available for my project"

这是该测试的预期输出：

“部署选项：Agent Runtime、Cloud Run、GKE。选择一个。发货。”

评估代理

如需评估代理，请使用以下提示指示 AI 开发工具：

Write evaluations for the caveman agent and run them.

AI 开发工具会激活 google-agents-cli-eval 技能并执行以下任务：

  • 创建 tests/eval/evalsets/caveman.evalset.json，其中包含涵盖压缩质量、技术术语保留和语气的测试用例。
  • 在 tests/eval/eval_config.json 中配置 LLM 作为评判标准。

  • 运行评估：

    agents-cli eval run

如果测试用例失败，请向 AI 开发工具提供纠正性反馈。 例如：

对问候语测试的回答过于礼貌。让它更粗鲁一些。

AI 开发工具会调整代理的说明，重新运行 agents-cli eval run，并进行迭代，直到达到所需的质量。

部署代理

如需在 Google Cloud上部署和运行代理，请按如下方式指示 AI 开发 工具：

Deploy this agent to Cloud Run.

AI 开发工具会激活 google-agents-cli-deploy 技能并执行以下操作：

  • 添加必要的部署基础架构配置：

    agents-cli scaffold enhance --deployment-target cloud_run

  • 部署代理：

    agents-cli deploy

代理现已部署在 Cloud Run 上。输出内容会包含服务网址，您可以使用该网址访问代理。

观察代理

Cloud Trace 默认处于启用状态。如需查看跟踪记录，请在 Google Cloud 控制台中打开 Cloud Trace Explorer，并向已部署的代理发送请求。您将看到 LLM 调用和工具执行的 span。

如需启用更详细的可观测性，请指示 AI 开发工具：

Set up observability infrastructure for my agent.

AI 开发工具会预配服务帐号、Cloud Storage 存储桶和 BigQuery 数据集，并更新已部署的服务以使用这些资源。如需了解详情，请参阅 可观测性指南 。

操作摘要

下表总结了提示以及 AI 开发工具执行的相应操作：

用户指令 AI 开发工具操作
“构建穴居人压缩器代理” 搭建项目、编写代理代码、在本地进行测试。
“编写评估并运行它们” 创建评估集、配置 LLM 作为评判标准、运行 agents-cli eval run。
“将其部署到 Cloud Run” 添加部署目标配置，部署到 Cloud Run。
“设置可观测性” 预配服务帐号、Cloud Storage 存储桶和 BigQuery 数据集。

Agents CLI 技能为 AI 开发工具提供了必要的上下文，以便其使用适当的 ADK 模式、构建评估和配置部署。

后续步骤

使用以下提示探索更复杂的代理设计：

  • 添加工具：“集成 Google 搜索工具，以便代理可以访问当前信息。”
  • 多智能体系统：“创建一个可以使用 adk_a2a 模板与其他代理交互的代理。”
  • RAG：“使用 agentic_rag 模板构建一个根据我们的文档回答问题的代理。”

详细了解 Agent Platform：