Module 5: Building ADK Agents with agents-cli¶

📖 Sources: agents-cli GitHub · agents-cli Docs · ADK · PyPI

What is agents-cli?¶

agents-cli is not a coding agent. It's a toolkit for coding agents — it gives your Antigravity CLI session the skills and commands to build, evaluate, and deploy ADK (Agent Development Kit) agents on Google Cloud.

Think of it this way: agy is your hands, agents-cli is the power tools.

5.1 — Setup 10 min¶

Prerequisites¶

• Python 3.11+
• uv (Python package manager)
• Node.js (for skill installation)
• A Google Cloud project or AI Studio API key

Install agents-cli¶

uvx google-agents-cli setup

This does three things:

1. Installs the agents-cli binary
2. Installs 7 skills into your coding agents (Antigravity CLI, Gemini CLI, Claude Code)
3. Configures authentication

Verify¶

agents-cli info

5.2 — The 7-Phase Lifecycle 10 min¶

agents-cli enforces a structured development lifecycle. Each phase has a dedicated skill that your coding agent loads when it reaches that stage:

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

Key insight: Phase 4 (Evaluate) is the most critical. Expect 5–10+ iterations of the eval-fix loop. This is normal and where agent quality comes from.

5.3 — Scaffolding a Project 10 min¶

The Prototype-First Pattern¶

Always start with --prototype to skip CI/CD and Terraform. Get the agent working, then add deployment later:

# 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

Template Options¶

Deployment Targets¶

What the Scaffold Creates¶

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 — Building Agent Code 15 min¶

Agent Definition Pattern¶

The scaffolded app/agent.py is your starting point:

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],
)

Tool Definition¶

Tools are plain Python functions with typed parameters and docstrings:

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"}

Quick Testing¶

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

# Interactive playground (web UI)
agents-cli playground

5.5 — The Evaluation Loop 20 min¶

This is the most important section. Evaluation is what separates a demo from a production agent.

The Quality Flywheel¶

┌─ 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

Eval Dataset Format¶

Eval cases are JSON files with prompts and optional expected behavior:

{
  "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?"}]
      }
    }
  ]
}

Built-in Metrics¶

Running Evals¶

# 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

When Scores Fail¶

Custom Metrics¶

When built-in metrics don't cover your domain, define custom ones in 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 — Deployment 10 min¶

Once evals pass, add deployment and ship:

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

# Deploy
agents-cli deploy

Adding CI/CD¶

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

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

Deployment Targets Decision Matrix¶

5.7 — Using agents-cli from Antigravity CLI 5 min¶

The real power is combining agy + agents-cli. In an Antigravity CLI session:

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

agy will:

1. Load the google-agents-cli-workflow skill
2. Ask you clarifying questions (Phase 0)
3. Check for matching adk-samples (Phase 1)
4. Run agents-cli scaffold create expense-tracker --agent adk --prototype
5. Implement the agent code using ADK patterns (Phase 3)
6. Set up eval cases and run them (Phase 4)
7. Iterate until quality thresholds pass

You guide the high-level intent; agents-cli skills handle the implementation details.

Skills Reference¶

The 7 skills installed by agents-cli setup:

Exercises¶

Next: Module 4 — Multi-Agent & Advanced for orchestrating multiple agents, subagent patterns, and the /btw scheduling system.