google-agents-cli-workflow

[{"code":"api_key_mention","match":"api_key","path":"SKILL.md"},{"code":"oauth","match":"OAuth","path":"SKILL.md"},{"code":"oauth","match":"OAuth","path":"references/brainstorming.md"}]

# Phase 0 Brainstorming Playbook

Turn the user's idea into an agreed `.agents-cli-spec.md` through a collaborative dialogue —
*before* any sample study, scaffolding, or code. Adapt the depth to the agent's complexity.

## HARD-GATE

Do NOT clone a sample, scaffold, run `agents-cli create`, or write any code until the user has
approved the spec. **Reading the recipe index is exempt** — it is not "studying a sample". Scan it
before your first reply and name any matching recipe there, even when that reply is only a
clarifying question. This applies even to "obvious" agents — unexamined assumptions cause the most
wasted work.

## Scale to complexity

- **Trivial agent** — single tool or none, fixed persona, no external auth, no RAG, no multi-agent.
  → A couple of adaptive questions, a 2–3 sentence spec, one approval. Don't force the full process.
- **Complex agent** — multi-agent / orchestration, RAG, external APIs with auth, or safety-critical.
  → Full treatment below: adaptive Q&A across all topics, 2–3 approaches, sectioned design with
  approval per section, self-review, and a user-review gate.

When unsure, start light and escalate as complexity surfaces.

## One question at a 

# Development Commands

| Phase | Commands |
|---|---|
| Setup | `setup` (install skills) · `update` (refresh skills) |
| Scaffold | `scaffold create <name>` · `scaffold enhance .` · `scaffold upgrade` |
| Develop | `playground` (web UI) · `run "prompt"` (one-shot; `-v` = JSON events) · `lint` · `install` |
| Evaluate | `eval run` (default) · `eval dataset synthesize` · `eval generate` · `eval grade` · `eval compare` · `eval analyze` · `eval optimize` · `eval metric list` · `eval submit`/`eval results` (cloud) |
| Deploy | `deploy` (needs approval) · `infra single-project` · `infra cicd` · `publish gemini-enterprise` |
| Info / Auth | `info` · `login --interactive` · `login --status` |

`agents-cli info` prints the **CLI install path** (read it to inspect CLI internals/templates) plus, inside a scaffolded project, the project config.

# Underlying Commands Reference

`agents-cli` wraps lower-level tools. When you need flags or behavior not exposed
by the CLI — for debugging, customization, or edge cases — use these directly.

## Dev & Testing

| `agents-cli` command | Underlying command |
|---|---|
| `agents-cli playground` | `uv run adk web .` |
| `agents-cli run "prompt"` | Starts a local server, queries it, then shuts it down (unless using --start-server) |
| `agents-cli run --url URL --mode MODE "prompt"` | HTTP requests to URL (`/run_sse` for adk, A2A protocol for a2a) |
| `agents-cli playground --port PORT` | `uv run adk web . --port PORT` |
| `agents-cli lint` | `uv run ruff check .` + `ruff format . --check` + `ty check .` + codespell (skip via `--skip-ty` / `--skip-codespell`) |
| `agents-cli lint --fix` | `uv run ruff check . --fix && uv run ruff format .` |
| `agents-cli lint --mypy` | the default checks plus `uv run mypy .` |
| `agents-cli infra single-project` | `terraform init + apply in deployment/terraform/single-project/` |
| `agents-cli deploy` | Dispatches by target: `gcloud run deploy` (Cloud Run), `terraform` + `docker build` + `kubectl apply` (GKE), `vertexai` Agent Engines SDK in-process (

# Agent Spec Template

```markdown
# 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
Recipes to study in Phase 1, from the topic index (`/google-agents-cli-adk-code` →
`references/samples.md`). List every one that looks relevant — several is normal and better than
guessing at one.
- `core/python/<recipe>` — <what you expect to take from it>
```

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

# 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:

| User may say | CLI value |
|-------------|-----------|
| Agent Engine, Vertex AI Agent Engine, Agent Runtime | `--deployment-target agent_runtime` |
| Agent Engine sessions, Agent Platform Sessions | `--session-type agent_platform_sessions` |
| Vertex AI Search, Vertex AI Vector Search, RAG | clone-and-study recipe, not a flag (see `/google-agents-cli-adk-code` → `references/samples.md`) |

The `vertexai` Python SDK package name is unchanged.

---
name: google-agents-cli-workflow
description: >
  This skill should be used when the user wants to "develop an agent",
  "build an agent using ADK", "run the agent locally", "debug agent code",
  "test an agent", "deploy an agent", "publish an agent", "monitor an agent",
  or needs the ADK (Agent Development Kit) development lifecycle and coding
  guidelines. Entrypoint for building ADK agents.
  Always active — provides the full workflow (scaffold, build, evaluate,
  deploy, publish, observe), code preservation rules, model selection
  guidance, and troubleshooting steps for ADK or any agent development.
metadata:
  author: Google
  license: Apache-2.0
  version: 1.5.0
  requires:
    bins:
      - agents-cli
    install: "uv tool install google-agents-cli"
---

# 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