How debbyliu0206/agents-cli works
1. What this repo is
agents-cli is a Python CLI package that helps a coding agent create, evaluate, deploy, and publish Gemini Enterprise Agent Platform projects. The repo is not the agent app itself; it is the control plane plus packaged guidance that drives generation of agent projects and cloud infrastructure.
2. Primary runtime boundary
The executable code lives under src/google/agents/cli and is organized as a command-oriented Python package. The top-level entrypoint (main.py) routes into subcommands for setup, scaffold, run, eval, deploy, publish, infra, data, dev, info, and authentication. Most other directories are support assets rather than runtime services.
3. Command layers and responsibilities
The CLI is split into focused subsystems:
- setup installs the CLI skills into coding-agent environments.
- scaffold creates or upgrades agent project layouts.
- run launches local agent execution and local servers.
- eval handles dataset generation, inference, grading, comparison, analysis, and optimization.
- deploy and infra provision cloud deployment and supporting resources.
- publish registers agents with Gemini Enterprise.
- data supports ingestion workflows for retrieval/RAG projects.
- dev contains developer utilities like install, lint, and playground.
4. Scaffolding is the biggest architectural subsystem
src/google/agents/cli/scaffold is a template factory. It contains:
- base project templates for Python, Go, Java, and TypeScript
- deployment-target templates for Agent Runtime, Cloud Run, GKE, and “none”
- sample agent implementations, tests, load tests, Dockerfiles, and CI configs
- shared Terraform modules for single-project and CI/CD setups
The scaffold layer is what turns abstract “agent project” choices into concrete repo files.
5. Generated project shapes
The templates cover multiple project types, each with a different boundary:
- simple agent apps
- ADK-based agents
- A2A variants
- agentic RAG projects with data ingestion and vector search
- cloud-deployed services on Cloud Run or GKE
- Agent Runtime deployments
This means the CLI does not assume one deployment model; it emits different architecture patterns depending on target runtime and language.
6. Evaluation pipeline
The eval package models a multi-step offline workflow: generate inference traces, synthesize datasets or scenarios, grade outputs with metrics, compare runs, analyze failure modes, and optimize prompts/configuration. The important flow is from an agent implementation plus an eval dataset into traces and scored results, not from live user traffic. This is a distinct analytics boundary from deployment.
7. Deployment and infrastructure
deploy and infra are responsible for production-bound artifacts and provisioning logic. The templates and helpers generate Terraform for:
- Agent Runtime
- Cloud Run
- GKE
- CI/CD staging/prod pipelines
- datastore/vector-search support for RAG
External dependencies here are Google Cloud services, Google Cloud auth, and Terraform-driven infrastructure.
8. Data ingestion and retrieval support
The data package and the agentic RAG templates form a separate data plane. They include ingestion pipelines, preprocessing steps, connector setup/teardown scripts, and vector-search/datastore provisioning. The architecture boundary is: source data is ingested and transformed first, then queried at runtime by the agent through retrievers.
9. Skills are the product interface for coding agents
The skills/ directory is a set of Markdown-based instruction bundles, not executable application code. These skills teach an external coding assistant how to use the CLI effectively for workflow, ADK coding, scaffold, eval, deploy, publish, observability, and the added discovery workflow in this fork. The repo also includes integration manifests like gemini-extension.json and .claude-plugin/plugin.json to attach those skills to agent tools.
10. Docs and distribution
docs/ is a full MkDocs documentation site with guides, reference pages, and observability notes; a GitHub Actions workflow publishes it. The documentation mirrors the CLI lifecycle: getting started, auth, development, evaluation, deployment, and project structure. So the repo has two outputs: a CLI package for automation and a docs/skills layer for agent instruction.
11. Fork-specific architecture change
This fork adds a discovery-first gate before scaffolding. The new google-agents-cli-discovery skill is meant to capture requirements and produce a complete spec before code generation. That changes the lifecycle from “scaffold early, refine later” to “resolve design decisions first, then generate,” which affects how the CLI’s workflow, scaffold, and downstream project templates should be understood.
12. Mental model for an architecture diagram
Draw the repo as three connected planes:
- a Python CLI orchestration layer
- a template/skill asset layer that generates agent projects and guidance
- a Google Cloud execution layer for runtime, deployment, data, and observability
Most flows start with user/coding-agent intent, go through CLI commands and templates, then end in generated projects or cloud resources.
Main entry points: main.py Main CLI · cmd_scaffold_group.py Scaffold · src Docs Site · cmd_eval_group.py Eval CLI
Components 23
CLI Runtime
Executable Python command layer and shared helpers.
- Main CLI · Top-level command router for all CLI subcommands.
src/google/agents/cli/main.py - Core Helpers · Common click, output, project, runner, tools, trust, and experiments helpers.
src/google/agents/cli/_click.py - Setup · Installs skills and manages auth/update flows for agent environments.
src/google/agents/cli/setup/cmd_setup.py - Scaffold · Creates, enhances, and upgrades agent project layouts.
src/google/agents/cli/scaffold/cmd_scaffold_group.py - Run Local · Launches local agent execution and local servers.
src/google/agents/cli/run/cmd_run.py - Eval CLI · Eval commands for dataset, generate, run, grade, compare, analyze, optimize, and submit.
src/google/agents/cli/eval/cmd_eval_group.py - Dev Tools · Developer utilities such as install, lint, and playground.
src/google/agents/cli/dev/cmd_install.py
Scaffold Assets
Templates, target layouts, and generation utilities.
- Gen Utils · Template, merge, backup, version, lock, language, GCP, and metadata utilities.
src/google/agents/cli/scaffold/utils/template.py - Base Templates · Language-agnostic project templates and shared deployment scaffolding.
src/google/agents/cli/scaffold/base_templates - Deploy Targets · Target-specific layouts for Agent Runtime, Cloud Run, GKE, and none.
src/google/agents/cli/scaffold/deployment_targets - RAG Template · Agentic RAG template with retrievers, ingestion pipeline, and vector search provisioning.
src/google/agents/cli/scaffold/agents/agentic_rag - ADK Templates · Python, Go, Java, TypeScript, and A2A agent starter templates.
src/google/agents/cli/scaffold/agents/adk
Evaluation
Offline evaluation, grading, comparison, and optimization pipeline.
- Eval Engine · Inference runner, synthesis runner, path handling, and optimization utilities.
src/google/agents/cli/eval/_inference_runner.py - Eval Commands · Dataset, generate, run, grade, metric, compare, analyze, optimize, and submit stages.
src/google/agents/cli/eval/cmd_dataset.py
Deploy & Data
Production deployment, infrastructure, and data ingestion.
- Deploy · Production deployment commands and agent runtime operations.
src/google/agents/cli/deploy/cmd_deploy.py - Infra · Terraform and CI/CD provisioning commands.
src/google/agents/cli/infra/cmd_infra.py - Data Ingestion · Data ingestion workflow support for retrieval and RAG projects.
src/google/agents/cli/data/cmd_data_ingestion.py - Publish · Registers agents with Gemini Enterprise.
src/google/agents/cli/publish/cmd_publish.py - Deploy Core · Operation handling and runtime-specific deployment utilities.
src/google/agents/cli/deploy/_operation.py - Infra Core · CI/CD and single-project provisioning helpers for infrastructure generation.
src/google/agents/cli/infra/_cicd_utils.py
Skills & Docs
Instruction bundles, docs site, and integration manifests.
Connections 25
- Main CLI → Core Helpers: shared runtime · Main dispatches through common CLI helpers.
- Main CLI → Setup: routes · Entry point routes to setup/auth/update commands.
- Main CLI → Scaffold: routes · Entry point routes to scaffold create/enhance/upgrade commands.
- Main CLI → Run Local: routes · Entry point routes to local run commands.
- Main CLI → Eval CLI: routes · Entry point routes to evaluation workflows.
- Main CLI → Deploy: routes · Entry point routes to deployment commands.
- Main CLI → Infra: routes · Entry point routes to infra provisioning commands.
- Main CLI → Data Ingestion: routes · Entry point routes to ingestion workflows.
- Main CLI → Publish: routes · Entry point routes to publishing commands.
- Main CLI → Dev Tools: routes · Entry point routes to developer utilities.
- Scaffold → Gen Utils: uses · Scaffold commands rely on generation and merge utilities.
- Scaffold → Base Templates: renders · Scaffold creates language-agnostic base projects from templates.
- Scaffold → Deploy Targets: combines · Scaffold attaches deployment-target layouts to generated projects.
- Scaffold → ADK Templates: creates · Scaffold emits ADK and multi-language agent starters.
- Scaffold → RAG Template: creates · Scaffold emits the RAG project shape with ingestion and retrieval.
- Eval CLI → Eval Engine: drives · Eval commands orchestrate inference, synthesis, grading, and optimization.
- Deploy → Deploy Core: uses · Deployment commands use operation and runtime helpers.
- Infra → Infra Core: uses · Infra commands generate Terraform and CI/CD artifacts.
- Data Ingestion → RAG Template: supports · Data ingestion workflows align with the RAG template's data plane.
- Setup → Skills: installs · Setup installs skills into coding-agent environments.
- Skills → Manifests: attached by · Skills are exposed through extension and plugin manifests.
- Docs Site → Skills: documents · Docs reference the available skills and lifecycle guidance.
- Eval CLI → Docs Site: mirrors · Evaluation docs explain the offline workflow represented by CLI commands.
- Deploy → Docs Site: mirrors · Deployment docs describe cloud/runtime provisioning flows.
- Scaffold → Docs Site: mirrors · Template docs explain generated project shapes and flags.