模块 5：使用 agents-cli 构建 ADK 代理¶

📖 参考资料：agents-cli GitHub · agents-cli 文档 · ADK · PyPI

什么是 agents-cli？¶

agents-cli 不是一个编码代理。它是编码代理的工具包 —— 它为你的 Antigravity CLI 会话提供构建、评估和在 Google Cloud 上部署 ADK（代理开发套件）代理的技能和命令。

可以这样理解：agy 是你的双手，agents-cli 是电动工具。

5.1 — 环境设置 10 min¶

先决条件¶

• Python 3.11+
• uv (Python 包管理器)
• Node.js (用于技能安装)
• Google Cloud 项目或 AI Studio API 密钥

安装 agents-cli¶

uvx google-agents-cli setup

这将执行三项操作：

1. 安装 agents-cli 二进制文件
2. 将 7 项技能安装到您的编码代理中 (Antigravity CLI、Gemini CLI、Claude Code)
3. 配置身份验证

验证¶

agents-cli info

5.2 — 7 阶段生命周期 10 分钟¶

agents-cli 强制执行结构化的开发生命周期。每个阶段都有一个专用的技能，当你的编码代理到达该阶段时就会加载它：

graph LR
    P0[Phase 0<br/>Understand] --> P1[Phase 1<br/>Study Samples]
    P1 --> P2[Phase 2<br/>Scaffold]
    P2 --> P3[Phase 3<br/>Build]
    P3 --> P4[Phase 4<br/>Evaluate]
    P4 --> P5[Phase 5<br/>Deploy]
    P5 --> P6[Phase 6<br/>Publish]
    P6 --> P7[Phase 7<br/>Observe]
    P4 -.->|fix & iterate| P3

关键见解： 阶段 4（评估）是最关键的。预计需要进行 5–10 次以上的评估-修复循环迭代。这是正常的，也是代理质量的来源。

5.3 — 搭建项目脚手架 10 min¶

原型优先模式¶

始终以 --prototype 开始，以跳过 CI/CD 和 Terraform。先让代理运行起来，稍后再添加部署：

# Step 1: Create a prototype
agents-cli scaffold create my-agent --agent adk --prototype

# Step 2: Iterate on agent code...

# Step 3: Add deployment when ready
agents-cli scaffold enhance . --deployment-target agent_runtime

模板选项¶

部署目标¶

脚手架创建的内容¶

my-agent/
├── app/
│   ├── __init__.py          ← App entry point (name must match directory)
│   ├── agent.py             ← Agent definition (instruction, tools, model)
│   └── tools.py             ← Custom tool functions
├── tests/
│   └── eval/
│       ├── datasets/
│       │   └── basic-dataset.json  ← Starter eval cases
│       └── eval_config.yaml        ← Metrics configuration
├── .env                     ← Environment variables (project ID, API keys)
├── agents-cli-manifest.yaml ← Project metadata (CLI reads this)
├── pyproject.toml           ← Python dependencies
├── GEMINI.md                ← Coding agent guidance file
└── Makefile                 ← Common task shortcuts

5.4 — 构建代理代码 15 min¶

代理定义模式¶

脚手架生成的 app/agent.py 是你的起点：

from google.adk import Agent

root_agent = Agent(
    name="my_agent",
    model="gemini-3.5-flash",
    instruction="""You are a helpful assistant that...""",
    tools=[my_tool_function],
)

工具定义¶

工具是普通的 Python 函数，带有类型注解的参数和文档字符串：

def get_weather(city: str) -> dict:
    """Get current weather for a city.

    Args:
        city: The city name to look up weather for.

    Returns:
        A dict with temperature and conditions.
    """
    # Your implementation here
    return {"temp_f": 72, "conditions": "sunny"}

快速测试¶

# One-off smoke test
agents-cli run "What's the weather in Tokyo?"

# Interactive playground (web UI)
agents-cli playground

5.5 — 评估循环 20 分钟¶

这是最重要的部分。 评估是区分演示和生产级代理的关键。

质量飞轮¶

┌─ 1. Prepare Data ─────── Write eval cases or synthesize them
│
├─ 2. Run Inference ────── agents-cli eval generate
│
├─ 3. Grade Traces ─────── agents-cli eval grade
│
├─ 4. Analyze Failures ──── Read results, identify root causes
│
└─ 5. Fix & Iterate ────── Fix agent code, go back to step 2

评估数据集格式¶

评估用例是包含提示词和可选预期行为的 JSON 文件：

{
  "eval_cases": [
    {
      "eval_case_id": "greeting",
      "prompt": {
        "role": "user",
        "parts": [{"text": "Hello, what can you help me with?"}]
      }
    },
    {
      "eval_case_id": "weather_query",
      "prompt": {
        "role": "user",
        "parts": [{"text": "What's the weather in San Francisco?"}]
      }
    }
  ]
}

内置指标¶

运行评估¶

# One command: generate traces + grade them
agents-cli eval run

# Or two-step for more control
agents-cli eval generate
agents-cli eval grade

# Compare before/after a fix
agents-cli eval compare baseline.json candidate.json

当分数不佳时¶

自定义指标¶

当内置指标无法覆盖您的领域时，请在 eval_config.yaml 中定义自定义指标：

metrics_to_run:
  - multi_turn_task_success
  - response_politeness    # custom metric below

custom_metrics:
  - name: response_politeness
    prompt_template: |
      Rate the agent's response 1-5 for professional politeness.
      Prompt: {prompt}
      Response: {response}
      Return JSON: {"score": <1|2|3|4|5>, "explanation": "<reason>"}

5.6 — 部署 10 分钟¶

一旦评估通过，添加部署并发布：

# Add deployment support (if prototype)
agents-cli scaffold enhance . --deployment-target agent_runtime

# Deploy
agents-cli deploy

添加 CI/CD¶

# GitHub Actions
agents-cli scaffold enhance . --cicd-runner github_actions

# Google Cloud Build
agents-cli scaffold enhance . --cicd-runner google_cloud_build

部署目标决策矩阵¶

5.7 — 在 Antigravity CLI 中使用 agents-cli 5 分钟¶

真正的强大之处在于将 agy 和 agents-cli 结合使用。在一次 Antigravity CLI 会话中：

> Use agents-cli to scaffold an ADK agent called "expense-tracker"
  that processes receipts and categorizes expenses.
  Start with a prototype.

agy 将会：

1. 加载 google-agents-cli-workflow 技能
2. 向您询问澄清问题（阶段 0）
3. 检查匹配的 adk-samples（阶段 1）
4. 运行 agents-cli scaffold create expense-tracker --agent adk --prototype
5. 使用 ADK 模式实现代理代码（阶段 3）
6. 设置评估用例并运行它们（阶段 4）
7. 迭代直到通过质量阈值

您负责引导高层意图；agents-cli 技能负责处理实现细节。

技能参考¶

由 agents-cli setup 安装的 7 个技能：

练习¶

下一步： 模块 4 — 多代理与高级模式，用于编排多个代理、子代理模式以及 /btw 调度系统。