google-agents-cli-workflow

The running order for building an agent — the conversation that pins down what it should do, then building, testing, releasing, and watching it once it is live — with the sibling guide to open named at each stage.

WHEN TO USE

SCOPE

USE FOR

Work through the full build-evaluate-deploy lifecycle for a new agent built with Google's Agent Development Kit.
Decide which of the other agents-cli skills to load next for the phase you're in.
Recover from a coding-agent shortcut, like skipping eval or changing the model unasked.
Debug a broken agent by reproducing, localizing, and fixing one variable at a time.
Turn a vague feature request into an approved spec file before any code gets written.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (19)

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.

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 — its `references/samples.md` topic index maps a need to the recipe that implements it. Yes, this early: the catalog lives there.
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:

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

What problem will the agent solve? — Core purpose and capabilities
External APIs or data sources needed? — Tools, integrations, auth requirements
Safety constraints? — What the agent must NOT do, guardrails
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)

First check whether a project already exists: run agents-cli info from the project root. If one was already created or enhanced by agents-cli, skip this phase.

Otherwise, scaffold before writing any code:

No project yet → agents-cli scaffold create <name>
Existing code to import → agents-cli scaffold enhance . (adds the agents-cli structure)

Use /google-agents-cli-scaffold for the full workflow — it covers architecture choices (deployment target, agent type, session storage) and project creation or enhancement.

Phase 3: Build and Implement

Implement the agent logic:

Write/modify code in the agent directory (check GEMINI.md / CLAUDE.md for directory name)
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
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.

Smoke-test only here — do not write behavioral pytest. LLM output is non-deterministic; behavioral checks belong in eval (Phase 4), not pytest. Use agents-cli run "prompt" for quick checks.

Provision recipe infrastructure (if you adapted one)

A recipe that needs backing infrastructure (a datastore, an index, a sandbox, a queue) ships its own provisioning: follow its Makefile (e.g. make setup-infra, make data-ingestion) and its AGENTS.md / README.md, adapting the recipe's infra/terraform/ and .env into your project. agents-cli has no command for this.

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.

Start small: Begin with 1-2 sample eval cases, not a full suite
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.
Discuss results with the user
Fix issues and iterate on the core cases first
Only after core cases pass, add edge cases and new scenarios
Repeat until every case meets the bar you agreed with the user (eval run exits 0 whatever the scores are, so read them)

Expect 5-10+ iterations here.

Phase 5: Deploy

Once the user agrees the eval scores are good enough:

Check if the project has a deployment target configured — run agents-cli info to see current config
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).
Deploy when ready: agents-cli deploy

IMPORTANT: Never deploy without explicit human approval.

Phase 6: Publish (optional)

Not all agents require this — currently supporting Gemini Enterprise. See /google-agents-cli-publish for registration modes, flags, and troubleshooting.

Phase 7: Observe

After deploying, use observability tools to monitor agent behavior in production. See /google-agents-cli-observability for Cloud Trace, prompt-response logging, BigQuery Analytics, and third-party integrations.

Operational Guidelines for Coding Agents

Common Shortcuts to Resist

Agents routinely skip steps with plausible-sounding excuses. Recognize these and push back:

Shortcut	Why it fails
"The user's request is clear enough, no need to clarify"	You're guessing at requirements. Phase 0 exists to confirm intent before scaffolding — even one question can prevent a full rework.
"The agent responded correctly in `agents-cli run`, so eval isn't needed"	One prompt is not a test suite. Eval catches regressions, edge cases, and tool trajectory issues that a single run never will.
"I'll use a newer/better model"	The scaffolded model was chosen deliberately. Changing it without being asked violates code preservation (Principle 1) and often breaks things — wrong location, deprecated version, or 404. Your training data is likely out of date — rely on the skills and the model listing command, not your knowledge of model names.
"I already know how to build this — sandbox, memory, approval gates"	You are about to reinvent a recipe, worse. These capabilities are already implemented and battle-tested in `/google-agents-cli-adk-code` → `references/samples.md`; check the topic index and open the matching recipe's `AGENTS.md` before designing anything custom.
"I can skip the scaffold and set up manually"	Manual setup misses eval boilerplate, CI/CD config, and project configuration manifest conventions. Use `agents-cli create` even for quick experiments.

Principle 1: Code Preservation & Isolation

Code modifications require surgical precision — alter only the code segments directly targeted by the user's request and strictly preserve all surrounding and unrelated code.

Mandatory Pre-Execution Verification:

Before finalizing any code replacement, verify the following:

Target Identification: Clearly define the exact lines or expressions to change, based solely on the user's explicit instructions.
Preservation Check: Confirm that all code, configuration values (e.g., model, version, api_key), comments, and formatting outside the identified target remain identical.

Example:

User Request: "Change the agent's instruction to be a recipe suggester."

Incorrect (VIOLATION):

root_agent = Agent(
    name="recipe_suggester",
    model="gemini-1.5-flash",  # UNINTENDED - model was not requested to change
    instruction="You are a recipe suggester."
)

Correct (COMPLIANT):

root_agent = Agent(
    name="recipe_suggester",  # OK, related to new purpose
    model="gemini-3.7-flash",  # PRESERVED
    instruction="You are a recipe suggester."  # OK, the direct target
)

Principle 2: Execution Best Practices

Model Selection — CRITICAL:
- NEVER change the model unless explicitly asked.
- When creating NEW agents (not modifying existing), use the latest Gemini model. List available models to pick the newest one:
```
# Use 'global' or any supported region (e.g. 'us-east1')
uv run --with google-genai python -c "
from google import genai
client = genai.Client(vertexai=True, location='global')
for m in client.models.list(): print(m.name)
"
```
- Do NOT use older models unless explicitly requested. For model docs, fetch https://adk.dev/agents/models/google-gemini/index.md. See also stable model versions.
Running Python Commands:
- Always use uv to execute Python commands (e.g., uv run python script.py)
- Run uv sync before executing scripts
Breaking Infinite Loops:
- Stop immediately if you see the same error 3+ times in a row
- RED FLAGS: Lock IDs incrementing, names appending v5→v6→v7, "I'll try one more time" repeatedly
- State conflicts (Error 409): Use terraform import instead of retrying creation
- When stuck: Run underlying commands directly (e.g., terraform CLI)
Troubleshooting:
- Check /google-agents-cli-adk-code first — it covers most common patterns
- Use WebFetch on URLs from the ADK docs index (curl https://adk.dev/llms.txt) for deep dives
- When encountering persistent errors, a targeted web search often finds solutions faster
- CLI command failures: run agents-cli <command> --help — the output ends with a Source: line pointing to the exact source file implementing that command. Read it to understand the logic and diagnose failures. Use agents-cli info to get the full CLI install path if you need to browse across multiple files.

Systematic Debugging

When something breaks, follow this sequence — don't skip steps or shotgun fixes:

Reproduce — Run the exact command that failed. Save the full error output. If you can't reproduce it, you can't fix it.
Localize — Narrow the cause: is it the agent code, a tool, the config, or the environment? Use agents-cli run "prompt" to isolate agent behavior from deployment issues. Add -v (--verbose) to print the full JSON event payloads — useful for inspecting tool calls, intermediate steps, and silent failures.
Fix one thing — Change one variable at a time. If you change the instruction AND the tool AND the config simultaneously, you won't know what fixed it (or what broke something else).
Verify — Rerun the exact reproduction command. Don't assume the fix worked.
Guard — If it was a non-obvious bug, add an eval case to catch regressions.

Stop-the-line rule: If a change breaks something that was working, stop feature work and fix the regression first. Don't push forward hoping to circle back — regressions compound.

Environment Variables:
- .env files and env var assignments (e.g., GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION) are typically required for the agent to function — never remove or modify them unless the user explicitly asks
- If a .env file exists in the project root, treat it as essential configuration
- For secrets and API keys, prefer GCP Secret Manager over plain .env entries — see /google-agents-cli-deploy for secret management guidance

Using a Temporary Scaffold as Reference

When you need specific infrastructure files (Terraform, CI/CD, Dockerfile) but don't want to modify the current project, use /google-agents-cli-scaffold to create a temporary project in /tmp/ and copy over what you need.

Reference Files

File	Contents
`references/internals.md`	Underlying tools and commands that `agents-cli` wraps (adk, pytest, ruff, uvicorn)
`references/spec-template.md`	`.agents-cli-spec.md` template and optional sections
`references/brainstorming.md`	Phase 0 design-dialogue playbook (one-at-a-time Q&A, approaches, gates)
`references/terminology.md`	Product-name → CLI-value mapping
`references/commands.md`	Per-phase `agents-cli` command index
`references/extension.md`	Author an ad-hoc extension or adopt an existing one (override or add commands)

Development Commands

Run agents-cli --help or agents-cli <command> --help for the authoritative flag list. A per-phase command index lives in references/commands.md; per-phase usage is in the phase sections above.

To override a built-in command (e.g. wrap deploy with compliance checks) or add a new one, agents-cli has an extension system. To author an ad-hoc extension for this repo, or adopt an existing one, load references/extension.md.

Skills Version

Troubleshooting hint: If skills seem outdated or incomplete, reinstall:
agents-cli setup --skip-auth
Only do this when you suspect stale skills are causing problems.

Account or credentials required

1 FOR YOU · 1 FOR THE AGENT

All items below are required.

01
Install agents-cli through uv
Run uv tool install google-agents-cli, or uvx google-agents-cli setup to install the skills — install uv first if needed.
```
uv tool install google-agents-cli
```
```
uvx google-agents-cli setup
```
02
Approve a written spec before any code is written
Work through the Phase 0 design dialogue, write the agreed design to .agents-cli-spec.md using the spec template, and give explicit approval before scaffolding or writing any code.

Listed as free: Connected services may require an account or charge fees.

This skill ships inside the Google Agents CLI plugin.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add google/agents-cli --skill "google-agents-cli-workflow" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub

Same repository

google-agents-cli-adk-code
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management", or needs ADK (Agent Development Kit) Python API patterns and code examples. Part of the Google ADK skills suite. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).Read full description
google-agents-cli-deploy
This skill should be used when the user wants to "deploy an agent", "deploy my ADK agent", "set up CI/CD", "configure secrets", "troubleshoot a deployment", or needs guidance on Agent Runtime, Cloud Run, or GKE deployment targets, or binding an agent to an Agent Gateway. Covers deployment workflows, service accounts, rollback, and production infrastructure. Applies to any framework agents-cli deploys (ADK, LangChain, ...). Part of the agents-cli skills suite. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), evaluation (use google-agents-cli-eval), or project scaffolding (use google-agents-cli-scaffold).Read full description
google-agents-cli-eval
This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Agent Platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).Read full description
google-agents-cli-observability
This skill should be used when the user wants to "set up tracing", "monitor my agent", "configure logging", "add observability", "debug production traffic", or needs guidance on monitoring deployed agents, including ADK (Agent Development Kit) agents. Covers Cloud Trace, prompt-response logging, BigQuery Agent Analytics, third-party integrations (AgentOps, Phoenix, MLflow, etc.), and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment setup (use google-agents-cli-deploy) or API code patterns (use google-agents-cli-adk-code).Read full description
google-agents-cli-publish
This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini Enterprise", "publish to Gemini Enterprise", or needs guidance on the agents-cli publish gemini-enterprise command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).Read full description
google-agents-cli-scaffold
This skill should be used when the user wants to "create an agent project", "start a new ADK project", "build me a new agent", "add CI/CD to my project", "add deployment", "enhance my project", or "upgrade my project". Part of the agents-cli skills suite. Covers agents-cli scaffold create, scaffold enhance, and scaffold upgrade commands, template options, deployment targets, and the prototype-first workflow. Do NOT use for writing agent code (ADK projects: use google-agents-cli-adk-code) or deployment operations (use google-agents-cli-deploy).Read full description