DEV Community

TechLatest
TechLatest

Posted on • Originally published at Medium on

Google agents-cli Agent Masterclass — Full Tutorial

#cliagents #google #agenticai #agents

Everything you need to install, run, and build extraordinary agents with Google agents-cli — the CLI and skills that turn your coding assistant into an ADK + Google Cloud expert.

Official: github.com/google/agents-cli · Docs: google.github.io/agents-cli · Quickstart: Build Your First Agent

What you’ll have at the end

  • agents-cli v1.0+ installed and verified
  • Skills loaded into your coding agent (Cursor, Claude Code, Codex, Antigravity)
  • A scaffolded ADK agent project with eval boilerplate
  • Understanding of scaffold → build → eval → deploy → observe lifecycle
  • Ideas for extraordinary multi-tool, multi-agent, and RAG projects

Introduction — agents-cli is not another chatbot

agents-cli is Google’s Agent Development Lifecycle toolchain for the Gemini Enterprise Agent Platform. It wraps the Agent Development Kit (ADK) with:

  • CLI commands  — scaffold, run, eval, deploy, publish
  • 7 agent skills  — workflow, ADK code, scaffold, eval, deploy, publish, observability
  • Coding-agent integration  — works with Claude Code, Codex, Antigravity — not instead of them

Official Google Cloud agent stack architecture

Source: google/agents-cli architecture

Part 1 — Prerequisites

uv: docs.astral.sh/uv

API access (local): AI Studio API key or agents-cli login for GCP

You do not need Google Cloud for local prototype work — an AI Studio key is enough for run and eval.

Part 2 — Install agents-cli

Full setup (CLI + skills) 

uvx google-agents-cli setup
Enter fullscreen mode Exit fullscreen mode

This installs the CLI and pushes skills to detected coding agents.

Skills only 

npx skills add google/agents-cli
Enter fullscreen mode Exit fullscreen mode

Your coding agent reads skills and invokes agents-cli Commands on your behalf.

Verify 

uvx google-agents-cli --version # agents-cli, version 1.0.0
uvx google-agents-cli --help
Enter fullscreen mode Exit fullscreen mode

Part 3 — Authenticate 

uvx google-agents-cli login --status
uvx google-agents-cli login -i # interactive: GCP or AI Studio
Enter fullscreen mode Exit fullscreen mode

For local dev , set it in your project .env:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your-aistudio-key
Enter fullscreen mode Exit fullscreen mode 


uvx google-agents-cli info
Enter fullscreen mode Exit fullscreen mode

Shows: project name, deployment target, agent directory, region, A2A support.

Part 4 — The 7 agent skills

Prompt pattern: “Use agents-cli to build …” activates the right skills automatically.

Part 5 — Scaffold your first agent

Prototype mode (no cloud deploy) 

uvx google-agents-cli create caveman-agent --prototype --yes
cd caveman-agent
uvx google-agents-cli install
Enter fullscreen mode Exit fullscreen mode

Creates:

caveman-agent/
├── app/agent.py # ADK root agent
├── agents-cli-manifest.yaml
├── tests/eval/ # eval datasets + config
├── pyproject.toml
├── Dockerfile
└── GEMINI.md # agent dev instructions
Enter fullscreen mode Exit fullscreen mode

Check project config 

uvx google-agents-cli info
Enter fullscreen mode Exit fullscreen mode

Shows: project name, deployment target, agent directory, region, A2A support.

Part 6 — Build the caveman compressor (official tutorial)

Google’s quickstart tutorial walks through a caveman compressor  — verbose text → terse grunts.

Tell your coding agent:

Use agents-cli to build a caveman-style agent that compresses verbose text into terse, technical grunts

Or edit app/agent.py directly — see examples/caveman-agent.py:

Save spec first: examples/agents-cli-spec.caveman.md → .agents-cli-spec.md

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

root_agent = Agent(
    name="caveman_agent",
    model=Gemini(
        model="gemini-flash-latest",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction="""You caveman compressor. Human give long words, you make short.
Rules:
- No articles. No filler. No fluff.
- Short grunts. Simple words.
- Keep technical terms but grunt around them.
- Funny but meaning stays.

Example input: "I would like to deploy the application to production"
Example output: "Me deploy. Production. Now."
""",
)

app = App(root_agent=root_agent, name="app")
Enter fullscreen mode Exit fullscreen mode

Part 7 — Run locally 

uvx google-agents-cli run "Please help me understand deployment options for my project"
Enter fullscreen mode Exit fullscreen mode

Starts a local server (default port 18080 ), runs one turn, stops.

uvx google-agents-cli playground # web UI for manual chat
uvx google-agents-cli run --start-server # keep server warm for repeated prompts
Enter fullscreen mode Exit fullscreen mode

Expected caveman output:

Deploy options: Agent Runtime, Cloud Run, GKE. Pick one. Ship.
Enter fullscreen mode Exit fullscreen mode

Part 8 — Evaluate (the most important phase)

agents-cli ships 17+ built-in metrics :

uvx google-agents-cli eval metric list
Enter fullscreen mode Exit fullscreen mode

Includes: FINAL_RESPONSE_QUALITY, INSTRUCTION_FOLLOWING, TOOL_USE_QUALITY, SAFETY, HALLUCINATION, multi-turn variants.

Run evals 

uvx google-agents-cli eval generate # run agent on dataset → traces
uvx google-agents-cli eval grade # LLM-as-judge scoring
# Or chained:
uvx google-agents-cli eval run
Enter fullscreen mode Exit fullscreen mode

Critical rule: Never assert LLM output in pytest — use eval, not unit tests, for behavioral quality.

Iterate 5–10+ times until thresholds are passed. Tell your coding agent:

The greeting test is too polite. Make it more caveman. Re-run eval.

Advanced: eval dataset synthesize, eval compare, eval analyze, eval optimize

Part 9 — Deploy to Google Cloud

After eval passes and you explicitly approve :

uvx google-agents-cli scaffold enhance . --deployment-target cloud_run
uvx google-agents-cli deploy
Enter fullscreen mode Exit fullscreen mode

Cloud Trace is enabled by default after deployment.

Part 10 — Publish & observe 

uvx google-agents-cli publish gemini-enterprise
uvx google-agents-cli infra single-project # observability infra
Enter fullscreen mode Exit fullscreen mode

Open Cloud Trace Explorer — see spans per LLM call and tool execution.

Part 11 — CLI command reference

Full list: agents-cli README

Part 12 — Mind-blowing project ideas

Use agents-cli skills + ADK to build these — each uses a different superpower:

1. Incident Gruntifier (caveman++)

On-call Slack bot that turns 500-word postmortem drafts into 3-line caveman summaries and opens a Jira ticket via a tool. Multi-tool agent with evals for brevity + accuracy.

2. Meeting → Action Agent

Ingests transcript → outputs ADK tool calls: calendar events, email drafts, Linear tasks. Eval on TOOL_USE_QUALITY and MULTI_TURN_TASK_SUCCESS.

3. RAG Doc Oracle

Clone rag-vector-search Sample from agents-cli catalog. Agent answers from your PDFs with grounding eval (GROUNDING, HALLUCINATION metrics).

4. A2A Agent Mesh

Two agents: Researcher (search tool) + Writer (compression). A2A protocol built into ADK scaffold — agents talk to each other.

5. Self-Optimizing Persona

Use eval optimize to auto-tune instructions until caveman tone scores 95%+ on INSTRUCTION_FOLLOWING — Watch prompts evolve across eval iterations.

6. Deploy-in-60-Seconds Demo

Prototype locally → scaffold enhance --deployment-target cloud_run → deploy → live public URL. Record the VHS GIF of the deploy output for your portfolio.

Prompt to start any of these:

Use agents-cli workflow skill. Read .agents-cli-spec.md.
Scaffold prototype, implement ADK tools, write 3 eval cases,
run eval generate + grade, show me failures before fixing.
Enter fullscreen mode Exit fullscreen mode

Part 13 — Work with Cursor / Claude Code

After uvx google-agents-cli setupSkills appear in your agent's skill directory.

Example prompts:

Pair with our MCP Visual Guide to expose deployed agents as MCP servers.

Part 14 — agents-cli vs raw ADK

Part 15 — Hands-on checklist 

# 1. Install
uvx google-agents-cli setup

# 2. Auth
uvx google-agents-cli login -i # or AI Studio key in .env

# 3. Scaffold
uvx google-agents-cli create my-agent --prototype --yes
cd my-agent && uvx google-agents-cli install

# 4. Run
uvx google-agents-cli run "Hello from ADK"

# 5. Eval
uvx google-agents-cli eval metric list
uvx google-agents-cli eval run

# 6. (Optional) Deploy — with human approval
uvx google-agents-cli scaffold enhance . --deployment-target cloud_run
uvx google-agents-cli deploy
Enter fullscreen mode Exit fullscreen mode

Summary

agents-cli turns your existing coding assistant into a Google Cloud agent factory. Install with uvx google-agents-cli setup, scaffold with create, smoke-test with run, prove quality with eval, ship with deploy. The skills handle ADK patterns, so you focus on what the agent does — caveman compressors, RAG oracles, or multi-agent meshes.

Every GIF in this guide was recorded from a real terminal. Clone the tapes, re-run them, and verify them.

Thank you so much for reading

Like | Follow | Subscribe to the newsletter.

Catch us on

Website: https://www.techlatest.net/

Newsletter: https://substack.com/@parvezmohammed

Twitter: https://twitter.com/TechlatestNet

LinkedIn: https://www.linkedin.com/in/techlatest-net/

YouTube:https://www.youtube.com/@techlatest_net/

Blogs: https://medium.com/@techlatest.net

Reddit Community: https://www.reddit.com/user/techlatest_net/

Top comments (0)