# debbyliu0206/agents-cli architecture

> Architecture diagram of the GitHub repository debbyliu0206/agents-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/debbyliu0206/agents-cli
- Repository: https://github.com/debbyliu0206/agents-cli

## Overview

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: [`src/google/agents/cli/main.py`](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/main.py) (Main CLI), [`src/google/agents/cli/scaffold/cmd_scaffold_group.py`](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/scaffold/cmd_scaffold_group.py) (Scaffold), [`docs/src`](https://github.com/debbyliu0206/agents-cli/tree/main/docs/src) (Docs Site), [`src/google/agents/cli/eval/cmd_eval_group.py`](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/eval/cmd_eval_group.py) (Eval CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI Runtime"]
  node_main["Main CLI<br/>entrypoint<br/>[main.py]"]
  node_cli_core["Core Helpers<br/>shared runtime<br/>[_click.py]"]
  node_setup["Setup<br/>command suite<br/>[cmd_setup.py]"]
  node_scaffold_cmd["Scaffold<br/>command suite"]
  node_run["Run Local<br/>command suite<br/>[cmd_run.py]"]
  node_eval_cmds["Eval CLI<br/>command suite<br/>[cmd_eval_group.py]"]
  node_dev["Dev Tools<br/>command suite<br/>[cmd_install.py]"]
end

subgraph group_scaffold["Scaffold Assets"]
  node_scaffold_utils["Gen Utils<br/>generation helpers<br/>[template.py]"]
  node_base_templates["Base Templates<br/>template library"]
  node_deploy_targets["Deploy Targets<br/>target templates"]
  node_agentic_rag["RAG Template<br/>project template"]
  node_adk_templates["ADK Templates<br/>project templates"]
end

subgraph group_eval["Evaluation"]
  node_eval_engine["Eval Engine<br/>pipeline core"]
  node_eval_commands["Eval Commands<br/>workflow commands<br/>[cmd_dataset.py]"]
end

subgraph group_ops["Deploy & Data"]
  node_deploy_cmd["Deploy<br/>command suite<br/>[cmd_deploy.py]"]
  node_infra_cmd["Infra<br/>command suite<br/>[cmd_infra.py]"]
  node_data_cmd["Data Ingestion<br/>command suite"]
  node_publish["Publish<br/>command suite<br/>[cmd_publish.py]"]
  node_deploy_core["Deploy Core<br/>deployment helpers<br/>[_operation.py]"]
  node_infra_core["Infra Core<br/>terraform helpers<br/>[_cicd_utils.py]"]
end

subgraph group_guidance["Skills & Docs"]
  node_skills["Skills<br/>instruction bundles"]
  node_docs["Docs Site<br/>documentation"]
  node_manifests["Manifests"]
end

node_main -->|"shared runtime"| node_cli_core
node_main -->|"routes"| node_setup
node_main -->|"routes"| node_scaffold_cmd
node_main -->|"routes"| node_run
node_main -->|"routes"| node_eval_cmds
node_main -->|"routes"| node_deploy_cmd
node_main -->|"routes"| node_infra_cmd
node_main -->|"routes"| node_data_cmd
node_main -->|"routes"| node_publish
node_main -->|"routes"| node_dev
node_scaffold_cmd -->|"uses"| node_scaffold_utils
node_scaffold_cmd -->|"renders"| node_base_templates
node_scaffold_cmd -->|"combines"| node_deploy_targets
node_scaffold_cmd -->|"creates"| node_adk_templates
node_scaffold_cmd -->|"creates"| node_agentic_rag
node_eval_cmds -->|"drives"| node_eval_engine
node_deploy_cmd -->|"uses"| node_deploy_core
node_infra_cmd -->|"uses"| node_infra_core
node_data_cmd -->|"supports"| node_agentic_rag
node_setup -->|"installs"| node_skills
node_skills -->|"attached by"| node_manifests
node_docs -->|"documents"| node_skills
node_eval_cmds -.->|"mirrors"| node_docs
node_deploy_cmd -.->|"mirrors"| node_docs
node_scaffold_cmd -.->|"mirrors"| node_docs

click node_main "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/main.py"
click node_cli_core "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/_click.py"
click node_setup "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/setup/cmd_setup.py"
click node_scaffold_cmd "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/scaffold/cmd_scaffold_group.py"
click node_run "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/run/cmd_run.py"
click node_eval_cmds "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/eval/cmd_eval_group.py"
click node_deploy_cmd "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/deploy/cmd_deploy.py"
click node_infra_cmd "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/infra/cmd_infra.py"
click node_data_cmd "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/data/cmd_data_ingestion.py"
click node_publish "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/publish/cmd_publish.py"
click node_dev "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/dev/cmd_install.py"
click node_scaffold_utils "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/scaffold/utils/template.py"
click node_base_templates "https://github.com/debbyliu0206/agents-cli/tree/main/src/google/agents/cli/scaffold/base_templates"
click node_deploy_targets "https://github.com/debbyliu0206/agents-cli/tree/main/src/google/agents/cli/scaffold/deployment_targets"
click node_agentic_rag "https://github.com/debbyliu0206/agents-cli/tree/main/src/google/agents/cli/scaffold/agents/agentic_rag"
click node_adk_templates "https://github.com/debbyliu0206/agents-cli/tree/main/src/google/agents/cli/scaffold/agents/adk"
click node_eval_engine "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/eval/_inference_runner.py"
click node_eval_commands "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/eval/cmd_dataset.py"
click node_deploy_core "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/deploy/_operation.py"
click node_infra_core "https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/infra/_cicd_utils.py"
click node_skills "https://github.com/debbyliu0206/agents-cli/tree/main/skills"
click node_docs "https://github.com/debbyliu0206/agents-cli/tree/main/docs/src"
click node_manifests "https://github.com/debbyliu0206/agents-cli/blob/main/gemini-extension.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli_core,node_setup,node_scaffold_cmd,node_run,node_eval_cmds,node_dev toneBlue
class node_scaffold_utils,node_base_templates,node_deploy_targets,node_agentic_rag,node_adk_templates toneAmber
class node_eval_engine,node_eval_commands toneMint
class node_deploy_cmd,node_infra_cmd,node_data_cmd,node_publish,node_deploy_core,node_infra_core toneRose
class node_skills,node_docs,node_manifests toneIndigo
```

## Components

### CLI Runtime

Executable Python command layer and shared helpers.

- [Main CLI](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/main.py): entrypoint · Top-level command router for all CLI subcommands. · `src/google/agents/cli/main.py`
- [Core Helpers](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/_click.py): shared runtime · Common click, output, project, runner, tools, trust, and experiments helpers. · `src/google/agents/cli/_click.py`
- [Setup](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/setup/cmd_setup.py): command suite · Installs skills and manages auth/update flows for agent environments. · `src/google/agents/cli/setup/cmd_setup.py`
- [Scaffold](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/scaffold/cmd_scaffold_group.py): command suite · Creates, enhances, and upgrades agent project layouts. · `src/google/agents/cli/scaffold/cmd_scaffold_group.py`
- [Run Local](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/run/cmd_run.py): command suite · Launches local agent execution and local servers. · `src/google/agents/cli/run/cmd_run.py`
- [Eval CLI](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/eval/cmd_eval_group.py): command suite · Eval commands for dataset, generate, run, grade, compare, analyze, optimize, and submit. · `src/google/agents/cli/eval/cmd_eval_group.py`
- [Dev Tools](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/dev/cmd_install.py): command suite · 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](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/scaffold/utils/template.py): generation helpers · Template, merge, backup, version, lock, language, GCP, and metadata utilities. · `src/google/agents/cli/scaffold/utils/template.py`
- [Base Templates](https://github.com/debbyliu0206/agents-cli/tree/main/src/google/agents/cli/scaffold/base_templates): template library · Language-agnostic project templates and shared deployment scaffolding. · `src/google/agents/cli/scaffold/base_templates`
- [Deploy Targets](https://github.com/debbyliu0206/agents-cli/tree/main/src/google/agents/cli/scaffold/deployment_targets): target templates · Target-specific layouts for Agent Runtime, Cloud Run, GKE, and none. · `src/google/agents/cli/scaffold/deployment_targets`
- [RAG Template](https://github.com/debbyliu0206/agents-cli/tree/main/src/google/agents/cli/scaffold/agents/agentic_rag): project template · Agentic RAG template with retrievers, ingestion pipeline, and vector search provisioning. · `src/google/agents/cli/scaffold/agents/agentic_rag`
- [ADK Templates](https://github.com/debbyliu0206/agents-cli/tree/main/src/google/agents/cli/scaffold/agents/adk): project 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](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/eval/_inference_runner.py): pipeline core · Inference runner, synthesis runner, path handling, and optimization utilities. · `src/google/agents/cli/eval/_inference_runner.py`
- [Eval Commands](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/eval/cmd_dataset.py): workflow 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](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/deploy/cmd_deploy.py): command suite · Production deployment commands and agent runtime operations. · `src/google/agents/cli/deploy/cmd_deploy.py`
- [Infra](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/infra/cmd_infra.py): command suite · Terraform and CI/CD provisioning commands. · `src/google/agents/cli/infra/cmd_infra.py`
- [Data Ingestion](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/data/cmd_data_ingestion.py): command suite · Data ingestion workflow support for retrieval and RAG projects. · `src/google/agents/cli/data/cmd_data_ingestion.py`
- [Publish](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/publish/cmd_publish.py): command suite · Registers agents with Gemini Enterprise. · `src/google/agents/cli/publish/cmd_publish.py`
- [Deploy Core](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/deploy/_operation.py): deployment helpers · Operation handling and runtime-specific deployment utilities. · `src/google/agents/cli/deploy/_operation.py`
- [Infra Core](https://github.com/debbyliu0206/agents-cli/blob/main/src/google/agents/cli/infra/_cicd_utils.py): terraform helpers · 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.

- [Skills](https://github.com/debbyliu0206/agents-cli/tree/main/skills): instruction bundles · Markdown skills for workflow, scaffold, eval, deploy, publish, observability, discovery, and ADK coding. · `skills`
- [Docs Site](https://github.com/debbyliu0206/agents-cli/tree/main/docs/src): documentation · MkDocs documentation site and published guides. · `docs/src`
- [Manifests](https://github.com/debbyliu0206/agents-cli/blob/main/gemini-extension.json): integration manifests · Plugin and extension manifests that attach skills to coding-agent tools. · `gemini-extension.json`

## Connections

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