Google Agents CLI Workflow

ADK Development Workflow & Guidelines

STOP — Do NOT write code yet. If no project exists, scaffold first with agents-cli scaffold create <name>. If the user already has code, use agents-cli scaffold enhance . to add the agents-cli structure. Run agents-cli info to check if a project already exists. Skipping this leads to missing eval boilerplate, CI/CD config, and project conventions.

agents-cli is a CLI and skills toolkit for building, evaluating, and deploying agents on Google Cloud using the Agent Development Kit (ADK). It works with any coding agent — Antigravity CLI, Claude Code, Codex, or others. Install with uvx google-agents-cli setup.

Requires: google-agents-cli = 0.6.1 If version is behind, run: uv tool install "google-agents-cli=0.6.1"

Check version: agents-cli info Install uv first if needed.

Session Continuity & Skill Cross-References

Re-read the relevant skill before each phase — not after you've already started and hit a problem. Context compaction may have dropped earlier skill content. If skills are not available, run uvx google-agents-cli setup to install them.

Setup

If agents-cli is not installed:

uv tool install google-agents-cli

uv command not found

Install uv following the official installation guide.

Product name mapping

The platform formerly known as "Vertex AI" is now Gemini Enterprise Agent Platform (short: Agent Platform). Users may refer to products by different names. Map them to the correct CLI values:

The vertexai Python SDK package name is unchanged.

Phase 0: Understand

Before writing or scaffolding anything, understand what you're building.

If .agents-cli-spec.md exists in the current directory, read it — it is your primary source of truth. Otherwise:

Do NOT proceed to planning, scaffolding, or coding. Ask the user the questions below and wait for their answers. You MUST have the user's answers before moving on. Do not assume, research, or fill in the blanks yourself. The user's intent drives everything — skipping this step leads to wasted work.

Always ask:

1. What problem will the agent solve? — Core purpose and capabilities
2. External APIs or data sources needed? — Tools, integrations, auth requirements
3. Safety constraints? — What the agent must NOT do, guardrails
4. Deployment preference? — Prototype first (recommended) or full deployment? If deploying: Agent Runtime, Cloud Run, or GKE?

Ask based on context:

• If retrieval or search over data mentioned (RAG, semantic search, vector search, embeddings, similarity search, data ingestion) → Datastore? Options: agent_platform_vector_search (embeddings, similarity search) or agent_platform_search (document search, search engine).
• If agent should be available to other agents → A2A protocol is built into every Python ADK agent; no separate choice needed — just scaffold normally.
• If full deployment chosen → CI/CD runner? GitHub Actions (default) or Google Cloud Build?
• If agent should remember user preferences or facts across sessions → Memory Bank? Long-term memory across conversations. See /google-agents-cli-adk-code.
• If Cloud Run or GKE chosen → Session storage? In-memory (default), Cloud SQL (persistent), or Agent Platform Sessions (managed).
• If deployment with CI/CD chosen → Git repository? Does one already exist, or should one be created? If creating, public or private?

Once you have the user's answers, write the spec to .agents-cli-spec.md in the current directory and get the user's approval. See /google-agents-cli-scaffold for how these choices map to CLI flags. At minimum include these sections — expand with more detail if the user wants a thorough spec:

# Agent Spec

## Overview
Describe the agent's purpose and how it works.

## Example Use Cases
Concrete examples with expected inputs and outputs.

## Tools Required
Each tool with its purpose, API details, and authentication needs.

## Constraints & Safety Rules
Specific rules — not just generic statements.

## Success Criteria
Measurable outcomes for evaluation.

## Reference Samples
Check the Notable Samples in Phase 1 — list any that match this use case.

Optional sections for more detailed specs: Edge Cases to Handle, Architecture & Sub-Agents, Data Sources & Auth, Non-Functional Requirements.

Once you have a clear understanding, proceed to Phase 1.

Phase 1: Study Reference Samples

Ask yourself: is there a sample that can help me design this and cut time? Scan the keywords below. Multiple samples can match — clone and study all that are relevant.

# Clone a sample to study — read the key files, understand the patterns, then apply
# them to your own scaffolded project. Do NOT use `adk@<sample>` scaffolding.
git clone --filter=tree:0 --sparse https://github.com/google/adk-samples /tmp/adk-samples 2>/dev/null; \
cd /tmp/adk-samples && git sparse-checkout add python/agents/<sample-name>

• ambient-expense-agent — Agent that runs on a schedule or reacts to events, with no interactive user. Keywords: scheduled, cron, daily, pubsub, event-driven, alerts, email, ambient Key files: expense_agent/fast_api_app.py, expense_agent/agent.py, expense_agent/config.py, terraform/
• adk-ae-oauth — Agent with OAuth 2.0 user consent, deployed to Agent Runtime with Gemini Enterprise. Keywords: OAuth, authentication, user consent, Google Drive, Agent Runtime, Gemini Enterprise Key files: README.md, adk_ae_oauth/tools.py, adk_ae_oauth/auths.py
• genmedia-for-commerce — Full-stack agent with React UI, MCP tools, media/image handling, and Gemini Enterprise registration. Keywords: MCP, media, video generation, Veo, virtual try-on, retail, full-stack, React, Gemini Enterprise Key files: genmedia4commerce/agent.py, genmedia4commerce/agent_utils.py, genmedia4commerce/fast_api_app.py
• deep-search — Research agent that iterates until quality is met, with source citations. Keywords: research, citations, iterative, grounding, multi-agent, human-in-the-loop, web search, report Key files: app/agent.py, app/config.py
• safety-plugins — Reusable safety guardrails that plug into any agent runner. Keywords: safety, guardrails, model armor, filters Key files: safety_plugins/plugins/model_armor.py, safety_plugins/plugins/agent_as_a_judge.py, safety_plugins/main.py
• data-science — Agent that executes code in a managed sandbox for data analysis. Keywords: SQL, BigQuery, code execution, sandbox Key files: data_science/sub_agents/analytics/agent.py
• memory-bank — Conversational agent with cross-session memory via Memory Bank (Cloud Run and Agent Runtime). Keywords: memory, cross-session, recall, context, remember, Memory Bank Key files: app/agent.py, app/fast_api_app.py

If no sample matches, proceed to Phase 2. But first — are you sure? Re-read the user's request and compare it against the keywords above. Skipping a matching sample means rebuilding patterns that already exist.

IMPORTANT — Exit criteria: After studying a sample, ask yourself: can I apply anything from this sample to help me deliver the design? Note what you'll reuse before moving on. Do NOT proceed until you've answered this.

This list is useful at any phase — revisit it when you hit deployment, publishing, or infrastructure questions. A sample's Terraform or registration pattern may be exactly what you need later.

Phase 2: Scaffold (if needed)

Use /google-agents-cli-scaffold to create a new project or import an existing one into the agents-cli format (adding deployment, CI/CD, infrastructure). It covers architecture choices (deployment target, agent type, session storage) and project creation or enhancement.

Skip this phase if the project was already created or enhanced by agents-cli — run agents-cli info from the project root to check.

Phase 3: Build and Implement

Implement the agent logic:

1. Write/modify code in the agent directory (check GEMINI.md / CLAUDE.md for directory name)
2. Quick smoke test: Use agents-cli run "your prompt" to verify the agent works after changes — this is the fastest way to check behavior without leaving the terminal
3. Iterate on the implementation based on user feedback

If the user asks for interactive testing, suggest agents-cli playground — it opens a web-based playground for manual conversation with the agent.

For ADK API patterns and code examples, use /google-agents-cli-adk-code.

NEVER write pytest tests that assert on LLM output content (e.g., checking for keywords in responses, verifying persona, validating tone). LLM outputs are non-deterministic — these tests are flaky by nature and belong in eval, not pytest. Use agents-cli run for quick checks and agents-cli eval generate followed by agents-cli eval grade for systematic validation.

Phase 3.5: Provision Datastore (RAG projects only)

For agentic_rag projects, provision the datastore before testing: agents-cli infra datastore, then agents-cli data-ingestion. Use infra datastore — not infra single-project (same datastore provisioning but faster, skips unrelated Terraform).

Phase 4: Evaluate

This is the most important phase. Evaluation validates agent behavior end-to-end.

MANDATORY: Activate /google-agents-cli-eval before running evaluation. It contains the dataset schema, config format, and critical gotchas. Do NOT skip this.

Do NOT skip this phase. After building the agent, you MUST proceed to evaluation.

uv run pytest vs agents-cli eval — know the difference:

• uv run pytest — Tests code correctness: imports work, functions return expected types, API contracts hold. Does NOT test whether the agent behaves well.
• agents-cli eval — Tests agent behavior: response quality, tool usage, persona consistency, safety compliance. This is what validates your agent actually works.
• agents-cli run "prompt" — Quick one-off smoke test during development. If testing multiple prompts use the --start-server option to persist the local server, which reduces overhead for repeated calls and allows resuming local sessions via --session-id. Use this for fast iteration, not pytest.

NEVER write pytest tests that check LLM response content (e.g., asserting pirate keywords appear, checking if the agent mentions allergies). LLM outputs are non-deterministic. Use eval with LLM-as-judge criteria instead.

1. Start small: Begin with 1-2 sample eval cases, not a full suite
2. Run evaluations: agents-cli eval run (chains generate + grade). For debugging or custom trace locations, use the two-step form: agents-cli eval generate then agents-cli eval grade.
3. Discuss results with the user
4. Fix issues and iterate on the core cases first
5. Only after core cases pass, add edge cases and new scenarios
6. Repeat until quality thresholds are met

Expect 5-10+ iterations here.

Phase 5: Deploy

Once evaluation thresholds are met:

1. Check if the project has a deployment target configured — run agents-cli info to see current config
2. If the project is a prototype (no deployment target), add deployment support first:

   agents-cli scaffold enhance . --deployment-target <target>

   See /google-agents-cli-deploy for the deployment target decision matrix (Agent Runtime vs Cloud Run vs GKE).
3. Deploy when ready: agents-cli deploy

IMPORTANT: Never deploy without explicit human approval.