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)](https://adk.dev/) 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.7.0 > If version is behind, run: uv tool install "google-agents-cli~=1.7.0"

> Check version: agents-cli info > [Install uv](https://docs.astral.sh/uv/getting-started/installation/index.md) 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.

| Phase | Skill | When to load | |-------|-------|--------------| | 0 — Understand | — | No skill needed — read `.agents-cli-spec.md` if present, else clarify goals with the user | | 1 — Study recipes | `/google-agents-cli-adk-code` | **Load it during design**, before scaffolding. Python: the `references/samples.md` topic index maps a need to the recipe that implements it. Go: the upstream [examples/](https://github.com/google/adk-go/tree/main/examples) are the equivalent. Yes, load this early. | | 2 — Scaffold | `/google-agents-cli-scaffold` | Before creating or enhancing a project | | 3 — Build | `/google-agents-cli-adk-code` | Before writing agent code — API patterns, tools, callbacks, state | | 4 — Evaluate | `/google-agents-cli-eval` | Before running any eval — dataset schema, metrics, eval-fix loop | | 5 — Deploy | `/google-agents-cli-deploy` | Before deploying — target selection, troubleshooting 403/timeouts | | 6 — Publish | `/google-agents-cli-publish` | After deploying, if registering with Gemini Enterprise (optional) | | 7 — Observe | `/google-agents-cli-observability` | After deploying — traces, logging, monitoring setup |

---

## Setup

If `agents-cli` is not installed: ```bash uv tool install google-agents-cli ```

### `uv` command not found

Install `uv` following the [official installation guide](https://docs.astral.sh/uv/getting-started/installation/index.md).

### 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 the agent is a **live or voice agent** (Live API, spoken conversation, barge-in, telephony) → load `/google-agents-cli-adk-code` (`references/adk-python-live.md`) **before writing the spec**. Live rules out A2A, Gemini Enterprise, and the default model. - 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?** GitHu