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.

uvx google-agents-cli setup

Requires: google-agents-cli = 0.1.0 If version is behind, run: uv tool install "google-agents-cli=0.1.0" Check version: agents-cli info Install uv first if needed.

DESIGN_SPEC.md

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?

• 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? Enables the agent as an A2A-compatible service.
• 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?

DESIGN_SPEC.md

/google-agents-cli-scaffold

undefined

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

agents-cli playground

/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 run

for systematic validation.

/google-agents-cli-eval

uv run pytest

agents-cli eval run

• 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 run

  — 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. Use this for fast iteration, not pytest.

1. Start small: Begin with 1-2 sample eval cases, not a full suite
2. Run evaluations:

   agents-cli eval run

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

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

   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

1. Target Identification: Clearly define the exact lines or expressions to change, based solely on the user's explicit instructions.
2. Preservation Check: Confirm that all code, configuration values (e.g.,

   model

   ,

   version

   ,

   api_key

   ), comments, and formatting outside the identified target remain identical.

• User Request: "Change the agent's instruction to be a recipe suggester."
• Incorrect (VIOLATION):
  python

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

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

• 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:
    bash

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

1. Reproduce — Run the exact command that failed. Save the full error output. If you can't reproduce it, you can't fix it.
2. 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.
3. 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).
4. Verify — Rerun the exact reproduction command. Don't assume the fix worked.
5. Guard — If it was a non-obvious bug, add an eval case to catch regressions.

• 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

agents-cli login --interactive

-i

--interactive

agents-cli login --status

[!NOTE] When using an API key to authenticate, the

login

command does not persist them automatically, it just aids in retrieving them and providing instructions on how they can be persisted.

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.

• /google-agents-cli-scaffold

  — Project creation, requirements gathering, and enhancement

• /google-agents-cli-adk-code

  — ADK Python API quick reference and production sample agents

• /google-agents-cli-eval

  — Evaluation methodology, evalset schema, and the eval-fix loop

• /google-agents-cli-deploy

  — Deployment targets, CI/CD pipelines, and production workflows

• /google-agents-cli-publish

  — Gemini Enterprise registration

• /google-agents-cli-observability

  — Cloud Trace, logging, BigQuery Analytics, and third-party integrations