# https://github.com/google/agents-cli Project Manual

Generated at: 2026-07-05 16:04:39 UTC

## Table of Contents

- [Introduction and Installation](#page-1)
- [CLI Commands and Agent Lifecycle](#page-2)
- [Agent Skills Reference](#page-3)
- [Templates, Deployment Targets, and Known Issues](#page-4)

<a id='page-1'></a>

## Introduction and Installation

### Related Pages

Related topics: [CLI Commands and Agent Lifecycle](#page-2), [Agent Skills Reference](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/google/agents-cli/blob/main/README.md)
- [docs/src/index.md](https://github.com/google/agents-cli/blob/main/docs/src/index.md)
- [docs/src/guide/getting-started.md](https://github.com/google/agents-cli/blob/main/docs/src/guide/getting-started.md)
- [docs/src/guide/quickstart-tutorial.md](https://github.com/google/agents-cli/blob/main/docs/src/guide/quickstart-tutorial.md)
- [docs/src/guide/authentication.md](https://github.com/google/agents-cli/blob/main/docs/src/guide/authentication.md)
</details>

# Introduction and Installation

Agents CLI (`agents-cli`) is a Google-maintained command-line toolkit for the complete lifecycle of AI agents built on the Agent Development Kit (ADK) and the Agent2Agent (A2A) protocol. It packages scaffolding, local build, evaluation, deployment, infrastructure provisioning, and skill-driven workflow guidance into a single binary, targeting Google Cloud Agent Runtime, Cloud Run, and GKE as primary deployment surfaces `Source: [README.md:1-40]()`. As of v1.0.0 the project is Generally Available, with redeploys preserving existing deployment specs on Agent Runtime and Cloud Run, and `agent_runtime` deploys honoring `.gcloudignore`/`.gitignore` when packaging source `Source: [README.md:1-25]()`.

## Purpose and Scope

The CLI is organized around a fixed lifecycle that is also surfaced as machine-readable skills:

```
spec -> scaffold -> build -> evaluate -> deploy -> publish/observe
```

The aim is to keep every phase addressable both interactively and programmatically, so that the same commands used by a developer at the terminal can be invoked by an automated coding agent through the bundled skill files `Source: [docs/src/index.md:1-60]()`. The shipped skills (`google-agents-cli-workflow`, `google-agents-cli-deploy`, `google-agents-cli-adk-code`, etc.) explicitly describe these phases and tell the consuming agent when to re-verify against the official Google docs before generating code, a behavior proposed in community discussion `#44` to reduce stale-output drift `Source: [docs/src/index.md:30-90]()`.

The CLI is not a generic Python agent framework. It is an opinionated automation layer over `google-adk`, the Vertex AI Agent Engine SDK, Cloud Run, GKE, and Terraform, with first-class templates such as `adk`, `adk_a2a`, `tool`, `sub_agent`, and the new clone-and-study RAG recipes (`rag-vector-search`, etc.) introduced in v1.0.0 `Source: [README.md:1-30]()`.

## Prerequisites

The installation and first-run experience assumes a working Python toolchain, the Google Cloud CLI, and Application Default Credentials. The minimum surface area is:

| Component | Purpose |
|---|---|
| Python (matching the project's expected range) | Runs the CLI; mismatched interpreter versions on `agent_runtime` deploys are a known failure mode (see `#36`) |
| `uv` (recommended) or `pip` | Installs and isolates the CLI |
| Google Cloud CLI (`gcloud`) | Required for ADC and Cloud Run / Agent Runtime / GKE deploys |
| Git | Used by `scaffold create --agent <remote>` to fetch templates |
| Terraform | Required only for the `infra` subcommands |

On Windows, several users have reported friction with Python version management, `gcloud` PATH handling, and ADC setup; the `infra` commands are also called out for lacking a safe-by-default dry-run mode, tracked in `#4` and `#21` `Source: [docs/src/guide/getting-started.md:1-80]()`.

## Installation

The supported installation path uses `uv`, which both manages the Python interpreter and installs the CLI as an isolated tool:

```bash
# Install uv if not already present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install agents-cli as a global uv tool
uv tool install agents-cli

# Verify
agents-cli --version
```

If `uv` is not desired, the project can be installed from a clone with `pip install -e .`, but the project README and guide both recommend the `uv tool` route because it avoids polluting the system interpreter and makes Python-version mismatches during `agent_runtime` deploys easier to diagnose `Source: [docs/src/guide/getting-started.md:40-120]()`. Once installed, the `agents-cli` binary exposes a help tree organized around the lifecycle commands (`scaffold`, `build`, `eval`, `deploy`, `infra`, `update`) `Source: [README.md:40-120]()`.

For updates, `agents-cli update` re-resolves and reinstalls the tool. On non-UTF-8 Windows consoles this command historically flooded output with `UnicodeDecodeError` tracebacks; the fix is to launch the terminal with `chcp 65001` or to install under a modern Windows Terminal session, as documented in issue `#37` `Source: [docs/src/guide/getting-started.md:80-140]()`.

## Authentication

All cloud-touching commands (`deploy`, `infra`, `eval` against Vertex, etc.) require authenticated access to Google Cloud. The canonical path is Application Default Credentials:

```bash
gcloud auth login
gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
```

The CLI additionally honors a service-account key path and an explicit `GOOGLE_APPLICATION_CREDENTIALS` environment variable for CI environments `Source: [docs/src/guide/authentication.md:1-60]()`. After authentication, the project ID can be passed to most commands via `--project`, but setting it once with `gcloud config` is the recommended default so that `agent_runtime` deploys land in the expected region `Source: [docs/src/guide/authentication.md:30-90]()`. Region selection matters: the `adk_a2a` template historically stamped the A2A Agent Card `url` with `us-central1` regardless of the deployment region, a regression tracked in `#28` and resolved by setting the Vertex location before building the agent `Source: [docs/src/guide/authentication.md:50-120]()`.

## First-Run Workflow

A typical first run follows the lifecycle directly:

1. **Scaffold** — `agents-cli scaffold create my-agent --template adk` produces a ready-to-run ADK project. Remote templates can be fetched with `--agent <git-url>`; be aware that the manifest's `settings.agent_directory` is used to write files into the local tree, which has been a path-traversal vector and should only be pointed at trusted repositories (see `#50`) `Source: [docs/src/guide/quickstart-tutorial.md:1-80]()`.
2. **Build & run locally** — `agents-cli build` and `agents-cli run` exercise the agent on the developer machine using the project's own virtualenv.
3. **Evaluate** — `agents-cli eval generate`, `eval grade`, and `eval dataset synth` build and score eval sets; per-case ADK session state is a community-requested addition tracked in `#52` `Source: [docs/src/guide/quickstart-tutorial.md:40-120]()`.
4. **Deploy** — `agents-cli deploy --deployment-target agent_runtime|cloud_run|gke` ships the project. v1.0.0 redeploys preserve the existing deployment spec instead of resetting unspecified settings `Source: [README.md:5-25]()`.
5. **Operate** — `agents-cli infra` (Terraform-backed) provisions supporting resources, and observability hooks are surfaced for the publish/observe phase `Source: [docs/src/index.md:60-140]()`.

This progression is the same flow that the `google-agents-cli-workflow` skill encodes for coding agents, ensuring human-driven and agent-driven usage stay aligned.

---

<a id='page-2'></a>

## CLI Commands and Agent Lifecycle

### Related Pages

Related topics: [Introduction and Installation](#page-1), [Agent Skills Reference](#page-3), [Templates, Deployment Targets, and Known Issues](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/google/agents/cli/main.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/main.py)
- [src/google/agents/cli/setup/cmd_setup.py](https://github.com/google/agents/cli/setup/cmd_setup.py)
- [src/google/agents/cli/scaffold/commands/create.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/commands/create.py)
- [src/google/agents/cli/scaffold/commands/enhance.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/commands/enhance.py)
- [src/google/agents/cli/scaffold/commands/upgrade.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/commands/upgrade.py)
- [src/google/agents/cli/eval/cmd_generate.py](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/eval/cmd_generate.py)
</details>

# CLI Commands and Agent Lifecycle

## Overview

`agents-cli` is a command-line toolkit for building, evaluating, and deploying AI agents on Google Cloud. The CLI exposes a layered set of subcommands that correspond to the agent development lifecycle described in the project's skill workflow:

```
spec → scaffold → build → evaluate → deploy → publish
```

This lifecycle contract is proposed as an optional machine-readable AISP specification in [#47](https://github.com/google/agents-cli/issues/47), and the CLI itself is the operational surface that drives each phase. The top-level entry point wires these phases into a single Click/Typer application. Source: [src/google/agents/cli/main.py:1-60]().

The CLI is intentionally split across several command groups so that each lifecycle phase can evolve independently while sharing a common agent manifest and config layer.

## Command Groups and Lifecycle Phases

### Setup and Self-Update

The `setup` group bootstraps the local environment. It manages authentication, ADC configuration, and prerequisite checks before any other command is usable. Source: [src/google/agents/cli/setup/cmd_setup.py:1-40]().

The top-level `agents-cli update` command refreshes the CLI installation. On non-UTF-8 Windows consoles this command has been observed to emit Python `UnicodeDecodeError` tracebacks because the update stream is decoded without an explicit encoding. This is tracked in [#37](https://github.com/google/agents-cli/issues/37) and motivates safer stream decoding for Windows users (see also [#21](https://github.com/google/agents-cli/issues/21) for the broader Windows-friction discussion).

### Scaffold — `spec` and `build`

The `scaffold` group materializes a project from a template. Three subcommands drive this phase:

- `agents-cli scaffold create <project>` — generates a new agent project from a built-in or remote template. Source: [src/google/agents/cli/scaffold/commands/create.py:1-80]().
- `agents-cli scaffold enhance` — incrementally improves an existing scaffolded project. Source: [src/google/agents/cli/scaffold/commands/enhance.py:1-60]().
- `agents-cli scaffold upgrade` — migrates an older scaffold to the current template version. Source: [src/google/agents/cli/scaffold/commands/upgrade.py:1-60]().

Scaffolding accepts both built-in templates (e.g. `adk`, `adk_a2a`, `tool`, `sub_agent`) and remote Git repositories via `--agent <remote-repo>`. The remote path is a documented convenience, but it is also a security boundary: a malicious `agents-cli-manifest.yaml` can set `settings.agent_directory` to a path-traversal value, producing arbitrary file writes on the host. This is the root cause of the vulnerability reported in [#50](https://github.com/google/agents-cli/issues/50), and the recommended mitigation is path validation plus an interactive confirmation prompt when the template source is remote.

A long-standing limitation in the `adk_a2a` template is that the Vertex region is not propagated into the generated A2A Agent Card. Deploys to non-`us-central1` regions therefore stamp `us-central1` into the card's `url` even though the `reasoningEngines/<id>` resource is created in the correct region. See [#28](https://github.com/google/agents-cli/issues/28).

### Evaluate — `evaluate`

The `eval` group covers dataset synthesis, generation, and grading. The generation subcommand runs the agent against eval cases and emits traces. Source: [src/google/agents/cli/eval/cmd_generate.py:1-90]().

Community requests in this area focus on richer per-case configuration and contract coverage:

- Per-eval-case ADK session state initialization via `EvalCase.session_input.state` is requested in [#52](https://github.com/google/agents-cli/issues/52).
- An optional AISP eval quality contract (dataset coverage, grading rubric, failure analysis, optimization traces) is proposed in [#49](https://github.com/google/agents-cli/issues/49).

Together, these requests point toward making `eval generate` a first-class reproducibility surface rather than a one-shot runner.

### Deploy — `deploy`

The `deploy` group ships agents to a target environment. The supported `--deployment-target` values are `agent_runtime` (Vertex AI Agent Engine), `cloud_run`, and `gke`. v1.0.0 preserves the existing deployment spec on Agent Runtime and Cloud Run during redeploys, and now honors `.gcloudignore` and `.gitignore` when packaging source for Agent Runtime uploads.

Two deployment-target-specific limitations are tracked in the issue tracker:

1. The build/runtime Python version for `agent_runtime` is taken from `sys.version_info` of the interpreter running the CLI, not from the target project's Python. A `uv`-installed CLI on Python 3.14 against a project pinned to Python 3.11 (with `litellm` wheels only for 3.11) fails. See [#36](https://github.com/google/agents-cli/issues/36) and the related feature request for an explicit `--python-version` flag in [#45](https://github.com/google/agents-cli/issues/45).
2. A2A agents on `agent_runtime` are scaffolded with in-memory session and task stores, and the Agent Runtime Console Playground does not yet surface full A2A controls. See [#5](https://github.com/google/agents-cli/issues/5).

An optional AISP deployment readiness contract — covering eval, approval, deploy, rollback, and observability gates — is proposed in [#48](https://github.com/google/agents-cli/issues/48) to make `deploy` safe-by-default.

### Infra and Cross-Cutting Commands

The `infra` group wraps Terraform for supporting resources. Unlike other commands, `infra` currently proceeds straight to `terraform apply`, which the community has flagged as a safety regression; [#4](https://github.com/google/agents-cli/issues/4) requests that `infra` default to `terraform plan` and require explicit confirmation before applying.

The cross-cutting workflow skill `google-agents-cli-workflow` ties these phases together. [#44](https://github.com/google/agents-cli/issues/44) proposes a "verify against official docs" step that runs before any code generation in the workflow and in phase-specific skills, to prevent the CLI from drifting away from upstream ADK and Agent Engine semantics.

## Lifecycle Diagram

```mermaid
flowchart LR
    A[spec] --> B[scaffold create/enhance/upgrade]
    B --> C[build]
    C --> D[eval generate/grade]
    D --> E[deploy agent_runtime/cloud_run/gke]
    E --> F[observe / publish]
    F -. feedback .-> A
```

## Cross-References

- Lifecycle contract proposal: [#47](https://github.com/google/agents-cli/issues/47)
- Eval quality contract: [#49](https://github.com/google/agents-cli/issues/49)
- Deployment readiness contract: [#48](https://github.com/google/agents-cli/issues/48)
- Scaffold security advisory: [#50](https://github.com/google/agents-cli/issues/50)
- `update` Windows encoding bug: [#37](https://github.com/google/agents-cli/issues/37)
- A2A on `agent_runtime` gaps: [#5](https://github.com/google/agents-cli/issues/5), [#28](https://github.com/google/agents-cli/issues/28)
- `infra` safe-by-default: [#4](https://github.com/google/agents-cli/issues/4)
- Docs verification step: [#44](https://github.com/google/agents-cli/issues/44)

---

<a id='page-3'></a>

## Agent Skills Reference

### Related Pages

Related topics: [CLI Commands and Agent Lifecycle](#page-2), [Templates, Deployment Targets, and Known Issues](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [skills/README.md](https://github.com/google/agents-cli/blob/main/skills/README.md)
- [skills/google-agents-cli-workflow/SKILL.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-workflow/SKILL.md)
- [skills/google-agents-cli-workflow/references/commands.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-workflow/references/commands.md)
- [skills/google-agents-cli-workflow/references/terminology.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-workflow/references/terminology.md)
- [skills/google-agents-cli-workflow/references/spec-template.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-workflow/references/spec-template.md)
- [skills/google-agents-cli-adk-code/SKILL.md](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-adk-code/SKILL.md)
</details>

# Agent Skills Reference

## Overview and Purpose

Agent Skills are the structured, machine-readable guidance documents that teach a coding agent how to use `agents-cli`. They live under the top-level [`skills/`](https://github.com/google/agents-cli/blob/main/skills/README.md) directory and are consumed by an Agent Development Kit (ADK)-compatible agent to drive the full lifecycle of an agent project. The skills index in [`skills/README.md`](https://github.com/google/agents-cli/blob/main/skills/README.md) catalogs each available skill and explains the load order the host agent should use when multiple skills apply to the same task.

Skills are organized around a single master workflow skill plus several phase-specific skills, one per lifecycle phase. The lifecycle they collectively support is:

```
spec → scaffold → build → evaluate → deploy → publish → observe
```

This lifecycle is the conceptual spine of the project and is referenced from nearly every skill body. It is also the basis of several community proposals to add optional machine-readable contracts, such as an AISP lifecycle contract (issue #47) that would formalize each transition as a schema-validated artifact.

## Workflow Skill (`google-agents-cli-workflow`)

The orchestrating skill is [`skills/google-agents-cli-workflow/SKILL.md`](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-workflow/SKILL.md). It is loaded first by the host agent and is responsible for routing the user's intent to the correct phase skill. The SKILL.md body declares the entry conditions, exit conditions, and required artifacts for each phase, plus a short prose description of what the host agent is allowed to do autonomously versus what must be confirmed with the user.

The workflow skill defers all command-level detail to a `references/` subdirectory:

| Reference | Purpose |
| --- | --- |
| `references/commands.md` | Authoritative listing of every `agents-cli` subcommand, its flags, and example invocations. |
| `references/terminology.md` | Glossary of canonical terms (e.g. *agent*, *skill*, *spec*, *scaffold*) that phase skills must use consistently. |
| `references/spec-template.md` | The Markdown template the host agent fills in during the `spec` phase before scaffolding begins. |

The workflow skill also enforces a "verify against official docs" step before any code is generated, which is tracked as an explicit feature request in issue #44 for the `google-agents-cli-workflow`, `google-agents-cli-deploy`, and `google-agents-cli-adk-code` skills.

## Phase-Specific Skills

Each lifecycle phase has its own skill folder whose `SKILL.md` is loaded on demand by the host agent. Phase-specific skills are scoped narrowly so they can be swapped or extended independently. Examples referenced in the community context include:

- **`google-agents-cli-adk-code`** — coding conventions for ADK agents. Defined in [`skills/google-agents-cli-adk-code/SKILL.md`](https://github.com/google/agents-cli/blob/main/skills/google-agents-cli-adk-code/SKILL.md), this skill prescribes the Python patterns, file layout, and module boundaries a generated ADK project must follow.
- **`google-agents-cli-deploy`** — production deployment concerns (Agent Runtime, Cloud Run, GKE, CI/CD, secrets, service accounts). Community issue #48 proposes a deployment readiness contract layered on top of this skill, covering eval, approval, rollback, and observability gates.
- **`google-agents-cli-evaluate`** — eval dataset coverage, grading, failure analysis, and optimization traces; community issue #49 proposes an AISP eval quality contract to formalize these checks.

Additional phase skills cover `scaffold`, `build`, and `publish`, and follow the same folder convention.

## Skill Anatomy and Conventions

Every skill follows the same on-disk layout, which keeps the host agent's loader uniform:

```
skills/<skill-name>/
  SKILL.md                  # Required: loadable instructions + front-matter
  references/               # Optional: Markdown docs the SKILL.md can cite
  assets/                   # Optional: templates, schemas, fixtures
  examples/                 # Optional: worked invocations and outputs
```

The `SKILL.md` file begins with a YAML front-matter block declaring the skill's name, a one-line description, the lifecycle phase it owns, and an ordered list of prerequisite skills. Following the front matter, the body is plain Markdown subdivided into *When to load*, *Inputs*, *Steps*, *Outputs*, and *Done when*. Phase skills keep all command syntax inline (or cite `commands.md` from the workflow skill) so that the host agent never has to read CLI source to recover an argument name.

Source: [skills/README.md:1-50]()
Source: [skills/google-agents-cli-workflow/SKILL.md:1-120]()
Source: [skills/google-agents-cli-workflow/references/commands.md:1-80]()
Source: [skills/google-agents-cli-workflow/references/terminology.md:1-60]()
Source: [skills/google-agents-cli-workflow/references/spec-template.md:1-80]()
Source: [skills/google-agents-cli-adk-code/SKILL.md:1-100]()

---

<a id='page-4'></a>

## Templates, Deployment Targets, and Known Issues

### Related Pages

Related topics: [CLI Commands and Agent Lifecycle](#page-2), [Agent Skills Reference](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/google/agents/cli/scaffold/base_templates/_shared/agents-cli-manifest.yaml](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/_shared/agents-cli-manifest.yaml)
- [src/google/agents/cli/scaffold/base_templates/python/pyproject.toml](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/python/pyproject.toml)
- [src/google/agents/cli/scaffold/base_templates/python/Dockerfile](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/python/Dockerfile)
- [src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/cicd/telemetry.tf](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/cicd/telemetry.tf)
- [src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/shared/genai_logs_schema.json](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/shared/genai_logs_schema.json)
- [src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/shared/completions.sql](https://github.com/google/agents-cli/blob/main/src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/shared/completions.sql)
</details>

# Templates, Deployment Targets, and Known Issues

## Overview

`agents-cli` ships a curated set of project **templates** that are rendered by `agents-cli scaffold create <project> --agent <template>`. Each template is parameterized through a shared metadata file, `agents-cli-manifest.yaml`, which controls template-engine variables, the target agent directory layout, and the set of deployment artifacts that get emitted. Templates emit both application code (Python `pyproject.toml`, `Dockerfile`, agent entrypoints) and infrastructure-as-code (Terraform modules under `deployment/terraform/`), allowing a single scaffold command to produce a project that is ready for evaluation and deployment. Source: [src/google/agents/cli/scaffold/base_templates/_shared/agents-cli-manifest.yaml]()

A **deployment target** selects which runtime the generated project will be built and pushed to. Targets influence the contents of the Dockerfile, the Terraform variables, and the CI/CD pipeline produced under `deployment/terraform/cicd/`. The current target surface includes Vertex AI Agent Engine (`agent_runtime`), Cloud Run, and GKE, with `agent_runtime` being the path used for ADK- and A2A-style agents generated from the `adk` and `adk_a2a` templates.

## Template Manifest and Base Layout

The shared manifest is the contract between the scaffold command and every template in `base_templates/`. It declares template-level settings such as `settings.agent_directory`, which the scaffold engine substitutes into cookiecutter/Jinja-style paths when rendering. Because the manifest value is interpolated into filesystem paths during scaffolding, it must be treated as untrusted input when sourcing templates from remote Git repositories. Source: [src/google/agents/cli/scaffold/base_templates/_shared/agents-cli-manifest.yaml]()

The Python base template provides the structural backbone used by all Python-language scaffolds (`adk`, `adk_a2a`, `tool`, `sub_agent`, RAG recipes). It establishes:

- A standard `pyproject.toml` defining the agent's runtime dependencies and entrypoint.
- A `Dockerfile` used for containerized deployment to Cloud Run, GKE, and Agent Engine.
- A `deployment/terraform/` tree split into `cicd/` (pipelines and telemetry) and `shared/` (reusable modules, BigQuery log schemas, and BigQuery analytics SQL).

Source: [src/google/agents/cli/scaffold/base_templates/python/pyproject.toml]() · [src/google/agents/cli/scaffold/base_templates/python/Dockerfile]()

## Deployment Targets and IaC Surface

The Terraform surface emitted by the Python base template is organized into two subtrees. The `cicd/` subtree contains pipeline definitions and an opinionated `telemetry.tf` module that wires Cloud Logging → BigQuery for GenAI traces. The `shared/` subtree holds the canonical BigQuery schema for GenAI logs (`genai_logs_schema.json`) and an analytics view (`completions.sql`) used by evaluation and observability workflows. Source: [src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/cicd/telemetry.tf]() · [src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/shared/genai_logs_schema.json]() · [src/google/agents/cli/scaffold/base_templates/python/deployment/terraform/shared/completions.sql]()

Each deployment target selects a subset of these modules and sets the variables that govern region, project, and service-account wiring. When `--deployment-target agent_runtime` is used, the scaffold produces a `vertexai._genai.AgentEngine`-oriented build path; for `cloud_run`, the same Python code is packaged into a Cloud Run service via the generated Dockerfile. Redeploys to either Agent Engine or Cloud Run preserve the existing deployment spec rather than resetting unspecified settings, which is the v1.0.0 behavior change.

The following table summarizes the matrix of common agent templates versus supported deployment targets.

| Template   | agent_runtime | cloud_run | gke |
|------------|:-------------:|:---------:|:---:|
| `adk`      | ✓             | ✓         | ✓   |
| `adk_a2a`  | ✓             | ✓         | ✓   |
| `tool`     | ✓             | ✓         | ✓   |
| `sub_agent`| ✓             | ✓         | ✓   |
| `rag-*`    | ✓ (recipe)    | ✓         | ✓   |

## Known Issues and Limitations

Several issues tracked in the repository affect how templates and deployment targets behave in practice. They are summarized here so that users picking a template/target combination can plan mitigations.

- **Path traversal via remote templates (#50).** `agents-cli scaffold create <project> --agent <remote-repo>` clones the remote repository and renders `agents-cli-manifest.yaml` without a confirmation prompt. A crafted `settings.agent_directory` value (e.g. one containing `../`) can cause files to be written outside the intended project directory. Until this is fixed upstream, prefer local templates or pin remote templates to trusted refs.
- **`adk_a2a` agent_runtime region mismatch (#28).** Agents generated from the `adk_a2a` template with `--deployment-target agent_runtime` stamp the A2A Agent Card's `url` with `us-central1` even when the `reasoningEngines/<id>` resource is created in a different region (e.g. `us-east1`). Workaround: set the Vertex location explicitly in the generated code before building.
- **Deploy Python version pinned to CLI interpreter (#36).** `agents-cli deploy --deployment-target agent_runtime` reads `sys.version_info` from the interpreter running the CLI rather than from the target project's Python. Dependencies without wheels for that interpreter version (e.g. `litellm` under Python 3.14) will fail at build time.
- **Missing `agents-cli deploy --python-version` flag (#45).** There is no explicit `--python-version` option on `agents-cli deploy`. Until one is added, users must align the CLI's interpreter with the project's target Python to avoid #36.
- **Windows console Unicode errors (#37).** `agents-cli update` emits Python `UnicodeDecodeError` tracebacks when run on non-UTF-8 Windows consoles. Running from a UTF-8-aware terminal (or `chcp 65001`) mitigates the noise.
- **`infra` commands default to apply (#4).** `agents-cli infra` operations run `terraform apply` rather than `terraform plan` by default. Pass an explicit dry-run/plan flag until safe-by-default is shipped.
- **A2A on agent_runtime: in-memory stores (#5).** `adk-a2a`-scaffolded agents default to in-memory session and task stores rather than a managed service, which limits durability on Agent Engine.
- **Java/TypeScript/Go ADK support (#9).** Templates and skills currently target ADK-Python patterns; ADK-Java, TypeScript, and Go are not first-class.
- **Setup friction on Windows (#21).** Initial environment setup on Windows remains heavy (Python version management, `gcloud` install, ADC auth, PATH tuning). A bundled GUI/desktop client has been proposed as an alternative onboarding path.

For upgrade planning, v1.0.0 (GA) is the current stable line: redeploys preserve existing deployment specs on Agent Engine and Cloud Run, Agent Engine deploys now honor `.gcloudignore` and `.gitignore` when packaging, and the RAG templates ship as clone-and-study recipes rather than interactive scaffolds.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: google/agents-cli

Summary: Found 40 structured pitfall item(s), including 15 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/44

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/42

## 3. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/29

## 4. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/9

## 5. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/28

## 6. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/39

## 7. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/36

## 8. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/25

## 9. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/37

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and observability gates
- User impact: Developers may expose sensitive permissions or credentials: Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and observability gates
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/48

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: Support Antigravity SDK as a first-class agent implementation framework
- User impact: Developers may expose sensitive permissions or credentials: Support Antigravity SDK as a first-class agent implementation framework
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/41

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/21

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/45

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/41

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/46

## 16. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe
- User impact: Developers may fail before the first successful local run: Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/47

## 17. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Deployment fails to resolve the `litellm` package version and fails
- User impact: Developers may fail before the first successful local run: Deployment fails to resolve the `litellm` package version and fails
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/42

## 18. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Path traversal in remote-template scaffolding → arbitrary file write (agents-cli scaffold create --agent <remote>)
- User impact: Developers may fail before the first successful local run: Path traversal in remote-template scaffolding → arbitrary file write (agents-cli scaffold create --agent <remote>)
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/50

## 19. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups
- User impact: Developers may fail before the first successful local run: Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/21

## 20. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Python version option for agents-cli deploy
- User impact: Developers may fail before the first successful local run: Python version option for agents-cli deploy
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/45

## 21. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host
- User impact: Developers may fail before the first successful local run: run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/46

## 22. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dependency lacks a wheel for that version (e.g. Python 3.14 +...
- User impact: Developers may fail before the first successful local run: v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dependency lacks a wheel for that version (e.g. Python 3.14 +...
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/36

## 23. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/47

## 24. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/43

## 25. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/google/agents-cli

## 26. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Add a proactive "verify against official docs" step before code generation
- User impact: Developers may misconfigure credentials, environment, or host setup: Add a proactive "verify against official docs" step before code generation
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/44

## 27. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Add an init command to create agents-cli-manifest.yaml for existing ADK projects
- User impact: Developers may misconfigure credentials, environment, or host setup: Add an init command to create agents-cli-manifest.yaml for existing ADK projects
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/25

## 28. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Add an optional AISP eval quality contract for dataset coverage, grading, failure analysis, and optimization traces
- User impact: Developers may misconfigure credentials, environment, or host setup: Add an optional AISP eval quality contract for dataset coverage, grading, failure analysis, and optimization traces
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/49

## 29. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: `adk_a2a` (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys
- User impact: Developers may misconfigure credentials, environment, or host setup: `adk_a2a` (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/28

## 30. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: repo init with cicd, for a2a ,adk , tool, and sub agent init.
- User impact: Developers may misconfigure credentials, environment, or host setup: repo init with cicd, for a2a ,adk , tool, and sub agent init.
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/39

## 31. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/google/agents-cli

## 32. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles
- User impact: Developers may hit a documented source-backed failure mode: agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/37

## 33. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: packet_text.keyword_scan | https://github.com/google/agents-cli

## 34. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: Support per-eval-case ADK session state in `agents-cli eval generate`
- User impact: Developers may hit a documented source-backed failure mode: Support per-eval-case ADK session state in `agents-cli eval generate`
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/52

## 35. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/52

## 36. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/google/agents-cli

## 37. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/google/agents-cli

## 38. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/google/agents-cli

## 39. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/google/agents-cli

## 40. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/google/agents-cli

<!-- canonical_name: google/agents-cli; human_manual_source: deepwiki_human_wiki -->