Skip to content

ADK 的 Agents CLI 快速入门

本指南介绍如何使用 Agents CLI 快速上手 Agent Development Kit (ADK)。你可以将 Agents CLI 工具集与编码智能体（如 Antigravity、Claude Code 和 Codex）一起使用，来构建、评估和部署 ADK 智能体。有关更多信息，请参阅 Agents CLI 文档。

在开始之前，请确保已安装以下工具：

  • Python 3.11 或更高版本：Agents CLI 支持 Python 的 ADK 智能体
  • 用于管理环境和依赖的 uv 工具
  • Node.js，用于安装技能
  • 编码智能体，如 Antigravity、Claude Code 或 Codex

如果你想将 ADK 智能体部署到 Google Cloud 等服务，请确保还安装了以下工具：

安装

运行以下命令安装 Agents CLI。此步骤会将 agents-cli 命令、ADK Python 包和 ADK 技能安装到你机器上已有的任何编码智能体中：

uvx google-agents-cli setup
其他安装方式

pipx：

pipx install google-agents-cli && agents-cli setup

pip：

pip install google-agents-cli && agents-cli setup

仅安装技能：

npx skills add google/agents-cli

安装命令是你唯一需要自己运行的命令。安装完成后，你可以使用编码智能体来构建和运行 ADK 智能体。

身份验证

Agents CLI 需要生成式 AI API 的凭据来运行你的智能体。最简单的选择是使用来自 Google AI Studio 的 Gemini API 密钥。在 API Keys 页面创建密钥，然后在下一步创建项目后，打开其 .env 文件并设置：

更新：.env
GEMINI_API_KEY=YOUR_API_KEY

注释掉同一文件中的三行 GOOGLE_CLOUD_* 配置，以便 SDK 使用你的密钥而非 Vertex AI。

使用 Google Cloud Agent Platform 代替

如果你已有 Google Cloud 项目，Agents CLI 会自动获取你的应用默认凭据：

gcloud auth application-default login

确保生成的 .env 文件中的 GOOGLE_CLOUD_* 行未被注释，并将其设置为你的项目标识符。有关通过 ADK 连接 Google Cloud 服务和项目的更多信息，请参阅 ADK 的 Google Cloud 设置指南。

构建你的智能体

打开你的编码智能体并确认它能看到这些技能：

antigravity            # 从你的 IDE 或终端启动
# 然后验证 Agents CLI 技能列在你的环境中

claude
/skills                # 期望在列表中看到 google-agents-cli-* 条目

codex
/skills                # 期望在列表中看到 google-agents-cli-* 条目
使用其他编码智能体

Agents CLI 可与任何支持技能的编码智能体配合使用。大多数智能体通过 /skills 命令或设置面板来列出它们。

然后告诉编码智能体你想构建什么：

编码智能体提示词
Use agents-cli to build an agent that turns long text into short
bullet-point summaries

你的编码智能体会激活 google-agents-cli-workflow 和 google-agents-cli-scaffold 技能，询问关于智能体调用的工具、期望的输入输出以及评估成功标准的澄清问题，然后搭建项目。

接下来，你的编码智能体使用 google-agents-cli-adk-code 技能将你的智能体写入 app/agent.py。最终你将得到一个包含智能体代码、测试和评估数据集的可运行项目，文件结构如下：

my-agent/
    app/
        agent.py                # 主智能体代码
        fast_api_app.py         # 服务器、遥测和路由
        app_utils/              # 会话和制品服务
    tests/
        eval/                   # 评估数据集和指标
        integration/            # 端到端智能体测试
        unit/
    pyproject.toml              # 项目配置和依赖
    agents-cli-manifest.yaml    # Agents CLI 配置
    Dockerfile                  # 用于部署的容器镜像
    GEMINI.md                   # 编码智能体的项目指导
    .env                        # API 密钥或项目 ID

当你计划测试、评估和部署智能体时，请使用此项目结构。如果你想创建用于学习 ADK 的单文件智能体，请改用 adk create 命令。

运行你的智能体

请你的编码智能体启动本地交互环境，或自行运行：

agents-cli playground

此命令启动带有热重载的 ADK 网页界面，因此你在编辑时所做的更改会反映在项目中。你可以在 (http://localhost:8080) 访问交互环境。在左上角选择智能体，然后粘贴几段文本。智能体会回复一个简短的要点摘要。

后续：评估和部署你的智能体

现在你已安装了 Agents CLI 并运行了第一个智能体，你可以使用如下指令通过编码智能体进行评估和部署：

  • "Write evals for this agent and run them"（为此智能体编写评估并运行）以根据你设定的成功标准评估你的智能体。你的编码智能体会对结果进行评分，按原因分组失败项，并调整智能体的指令直到通过。
  • "Deploy this to Cloud Run"（部署到 Cloud Run）以将你的智能体部署到 Agent Runtime、Cloud Run 或 GKE。
  • "Set up observability infrastructure for my agent"（为我的智能体设置可观测性基础设施）以添加提示-响应日志和内容日志。

有关评估、部署和可观测性的完整演练，请参阅 Agents CLI 教程：构建你的第一个智能体。