Google Agents CLI Workflow

Agent Development Workflow & Guidelines

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

Before writing agent code, make sure a scaffolded project exists (see Phase 2). Skipping scaffolding loses eval boilerplate, CI/CD config, and project conventions.

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

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

Users name products inconsistently (Vertex AI → Agent Platform, Agent Engine → Agent Runtime, etc.). Map user terms to CLI values using references/terminology.md.

Phase 0: Understand

Before writing or scaffolding anything, understand what you're building — through a design dialogue, not a checklist. Load references/brainstorming.md and follow it: ask one question at a time, propose 2–3 architecture approaches for non-trivial agents, and validate the design before any scaffolding.

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 until the user approves the spec. Do not assume, research, or fill in the blanks yourself — the user's intent drives everything.

Scale the ceremony to complexity: a trivial agent (single tool, fixed persona) needs only a couple of questions, a 2–3 sentence spec, and one approval; a complex agent (multi-agent, RAG, external APIs/auth, safety-critical) gets the full treatment in references/brainstorming.md.

Topics to cover (one question at a time, adapting to the user — see the playbook):

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 the agent needs a capability the scaffold doesn't ship — retrieval over your data, sandboxed code execution, memory across sessions, OAuth consent, safety guardrails, event-driven triggers — that capability comes from a clone-and-study recipe, not a scaffold flag. Look the need up in the topic index in /google-agents-cli-adk-code → references/samples.md and study the matching recipe in Phase 1.
• If agent should be available to other agents → A2A protocol is built into every Python agent scaffolded by agents-cli; 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 → long-term memory across conversations. Load /google-agents-cli-adk-code — it has both the recipe (in references/samples.md) and the ADK memory API details.
• 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 the design is agreed, write the spec to .agents-cli-spec.md using the template in references/spec-template.md, self-review it, then get the user's approval. See /google-agents-cli-scaffold for how these choices map to CLI flags.

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

Phase 1: Study Reference Recipes

Trigger. If the request involves any of: searching your own documents · running shell or Python code on a user's behalf · a sandboxed or isolated per-user environment · loading skills the agent picks up at runtime · work that spans days, resumes, or runs unattended · remembering across conversations · approving a risky action before it executes · blocking harmful content or moderating what agents say · acting with a user's own API keys or credentials · OAuth consent to reach a user's own data · delegating to sub-agents with isolated context · speaking A2A to other agents · reacting to events or a schedule · researching a topic online and reporting it with citations · generating images or video — then a recipe already implements it. Look it up before you commit to an implementation. This list covers the same capabilities as the topic index in /google-agents-cli-adk-code → references/samples.md. If you extend one, extend the other.

Load `/google-agents-cli-adk-code` now — the catalog lives there, at references/samples.md. Load it even though nothing is scaffolded and you are not writing code yet; "wrong phase for the code skill" is the rationalisation that makes agents skip this step, and that skill's Prerequisites for writing code does not apply to you. Look each capability the design calls for up in its topic index. It maps needs (retrieval, sandboxed execution, memory, approval gates, guardrails, per-user credentials, scheduling) to the recipe that teaches them, and shows how to clone one. Multiple recipes can match — clone and study all that are relevant, starting with each one's AGENTS.md.

If no recipe matches, proceed to Phase 2. But first — are you sure? Re-read the user's request and re-check the topic index in /google-agents-cli-adk-code. Skipping a matching recipe means rebuilding patterns that already exist, usually worse.

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

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

Phase 2: Scaffold (if needed)