The Problem

Developers building Gemini Enterprise agents must juggle many Google‑Cloud services (Cloud Run, GKE, Terraform, CI/CD) and keep the tooling in sync with the coding assistant they use. Manually wiring authentication, scaffolding, evaluation, and deployment scripts is error‑prone and slows iteration.

What This Does

agents-cli supplies a single Python‑based command line that bundles scaffolding, evaluation, deployment, and observability primitives for agents. The source tree groups related concerns:

  • src/google/agents/cli/main.py – top‑level CLI entry point (agents-cli …).
  • src/google/agents/cli/_runner.py – core command dispatcher (run, run_resolved).
  • src/google/agents/cli/scaffold/ – templates for Go, Java, Python, TypeScript projects and the create, enhance, upgrade commands.
  • src/google/agents/cli/eval/ – dataset handling, trace generation, grading, and metric calculation.
  • src/google/agents/cli/deploy/ – runtime building, secret parsing, and GKE/Cloud‑Run deployment helpers.
  • src/google/agents/cli/infra/ – CI/CD Terraform generation and GitHub‑Actions utilities.

Documentation lives under docs/ and the agent‑specific skills are shipped in skills/ for direct consumption by coding assistants.

How It Is Wired

Execution begins in src/google/agents/cli/main.py at line 80 (main). main parses the invoked sub‑command and eventually calls run from src/google/agents/cli/_runner.py (line 47).

  • run → run_resolved (12 distinct callers) → subprocess.run (external command) – this is the only path that leaves the process, used for invoking tools like gcloud, uv, or Docker.
  • The dispatcher (run) also calls utility functions such as require_tool (12 callers) and read_project_config (12 callers) from _tools.py and _project.py.
  • read_project_config loads the project manifest (pyproject.toml in docs/) and feeds data to scaffold commands (create, enhance, upgrade).
  • Scaffold commands live in src/google/agents/cli/scaffold/commands/. The most connected module is scaffold/commands/enhance (imports 10 others, no inbound imports) and scaffold/commands/create (2 inbound, 5 outbound). Both rely heavily on scaffold/utils/template.py (30 functions, 3 callers) for file copying, conditional inclusion, and dependency injection.
  • scaffold/utils/template.py participates in a circular import with scaffold/utils/remote_template.py; breaking this cycle would reduce the instability of those two modules (instability 0.6/0.33).
  • Evaluation commands (eval/cmd_*) ultimately call eval_utils.py and optimize_utils.py, which invoke model inference (9 functions across the repo).
  • Deployment (deploy/cmd_deploy.py) calls deploy/agent_runtime.py, which builds environment variables and may invoke a model for secret handling (parse_secrets).

The internal call graph shows 704 resolved edges, with the highest‑fan‑out functions (run_resolved, run, find_project_root) called from 20+ locations, indicating they are change‑impact hotspots.

How To Use It

# Clone the repository
git clone https://github.com/moses-y/agents-cli
cd agents-cli

# Install the CLI and its skills (requires uv)
uvx google-agents-cli setup

Configuration – The CLI expects Google Cloud ADC credentials (gcloud auth application-default login) and, for Gemini Enterprise, an API key placed in ~/.config/gemini/api_key. The scaffold templates read optional .env.example files in src/google/agents/cli/scaffold/base_templates/* for local development.

Scaffolding a new agent

agents-cli scaffold my-agent
# creates a project under ./my-agent using the selected language template

Running evaluation

cd my-agent
agents-cli eval generate   # produces trace files
agents-cli eval grade      # scores the traces

Deploying

agents-cli deploy          # builds Docker image, pushes to Artifact Registry,
                           # and creates GKE or Cloud Run resources via Terraform

All commands are defined under src/google/agents/cli/ and invoked through the agents-cli entry point.

Real‑World Use

A data‑science team can ask their coding assistant to “create a Gemini agent that classifies support tickets”. The assistant runs agents-cli scaffold to generate a Python ADK project, adds evaluation datasets via agents-cli eval generate, iterates locally, then runs agents-cli deploy to push the container to Cloud Run with Terraform‑managed IAM and monitoring. The entire lifecycle is driven by the same CLI, reducing context‑switching and manual cloud‑setup.

Code Health & Issues

  • HIGH – GitHub Actions use mutable tags (astral-sh/setup-uv@v6). Pin to commit SHA.
  • HIGH – No lockfile alongside docs/pyproject.toml; generate and commit one.
  • HIGH – CI workflow does not run the test suite despite 37 test files. Add a test step.
  • MEDIUM – Dependabot not configured; add .github/dependabot.yml.
  • MEDIUM – Dockerfiles use mutable base images (golang:1.26-alpine, distroless/static-debian12). Pin by digest.
  • MEDIUM – No vulnerability scan in CI; add dependency-review-action or osv-scanner.
  • MEDIUM – Containers run as root; add a non‑root USER.
  • LOW – Workflow jobs lack timeout-minutes.
  • LOW – Missing convention files (.editorconfig, formatter config).

Static analysis also reports 21 deep‑nesting hotspots, 13 broad exception catches, and two import cycles (template.py ↔ remote_template.py). These increase cognitive load and risk of regression when modifying scaffold utilities.

The Bottom Line

agents-cli provides a cohesive, language‑agnostic workflow for building, testing, and deploying Gemini Enterprise agents, with a clear entry point and well‑structured command modules. However, the codebase suffers from high‑impact health issues (unpinned CI actions, missing lockfile, absent test execution) and architectural smells (deep nesting, import cycles) that should be addressed before using it in production environments. Teams comfortable fixing those gaps will find the CLI a practical bridge between coding assistants and Google Cloud agent services.