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

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

通过将 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。请选择一项。Ship.”

评估代理

如需评估智能体，请使用以下提示向 AI 开发者工具发出指令：

Write evaluations for the caveman agent and run them.

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

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

  • 运行评估：

    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 探索器，然后向已部署的代理发送请求。您会看到 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：