release v1.5.0 at 2026-09-01 19:21:09 UTC

Author: pwkowalski

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "google-agents-cli",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Scaffold, develop, evaluate, and deploy AI agents with Google ADK. Bundles skills for the agent development lifecycle.",
   "author": { "name": "Google LLC" },
   "homepage": "https://github.com/google/agents-cli",

README.md

@@ -76,7 +76,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | Command | What it does |
 |---------|-------------|
 | `agents-cli setup` | Install CLI + skills to coding agents |
-| `agents-cli scaffold <name>` | Create a new agent project |
+| `agents-cli create <name>` | Create a new agent project |
 | `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
 | `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
@@ -89,8 +89,8 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli login` | Authenticate with Google Cloud or AI Studio |
 | `agents-cli login --status` | Show authentication status |
 | **Scaffold** | |
-| `agents-cli scaffold <name>` | Create a new agent project |
-| `agents-cli scaffold enhance` | Add deployment, CI/CD, or RAG to an existing project |
+| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli scaffold enhance` | Add deployment or CI/CD to an existing project |
 | `agents-cli scaffold upgrade` | Upgrade project to a newer agents-cli version |
 | **Develop** | |
 | `agents-cli run "prompt"` | Run agent with a single prompt |
@@ -110,9 +110,6 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
 | `agents-cli infra single-project` | Provision single-project infrastructure |
 | `agents-cli infra cicd` | Set up CI/CD pipeline + staging/prod infrastructure |
-| **Data** | |
-| `agents-cli infra datastore` | Provision datastore infrastructure for RAG |
-| `agents-cli data-ingestion` | Run data ingestion pipeline |
 | **Other** | |
 | `agents-cli info` | Show project config and CLI version |
 | `agents-cli update` | Force reinstall skills to all IDEs |

RELEASE_NOTES.md

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 
 
+## [1.5.0] - 2026-09-01
+
+- **Extension system with a LangChain template.** `agents-cli` can now be extended with custom commands and add-on agent templates, shipped with a LangChain extension and authoring guides. Extensions install from GitHub, other git hosts (including self-hosted and enterprise servers), or a local path for development.
+- Add `agents-cli infra show` to inspect the Terraform configuration provisioned by `agents-cli infra single-project`.
+- Add `--update-only` to `agents-cli deploy`, so a deploy updates an existing Agent Runtime engine instead of creating a duplicate.
+- Add a `--labels` flag to `agents-cli deploy` to tag Agent Runtime and Cloud Run deployments.
+- Add `--qps` to `agents-cli eval` that controls the request rate instead of being throttled to the default value.
+- Name the scaffolded root agent after its project instead of a generic default.
+- `agents-cli deploy` now retries throttled Agent Platform calls.
+- `agents-cli create` now reports precondition failures as clear errors instead of exiting successfully or printing a traceback.
+  - https://github.com/google/agents-cli/issues/68
+- Fix background server reuse ignoring the requested session mode.
+  - https://github.com/google/agents-cli/issues/70
+- Fix `reasoning_engine_adapter` streaming returning an empty response.
+  - https://github.com/google/agents-cli/issues/80
+- Prevent multi-region deployments in scaffold and deploy.
+  - https://github.com/google/agents-cli/issues/81
+- Give a clear error for malformed project manifests instead of silently defaulting or printing a traceback.
+  - https://github.com/google/agents-cli/issues/74
+- Fix stale command references in docs and CLI hints.
+  - https://github.com/google/agents-cli/issues/77
+- Scaffolded A2A agents now forward tool calls and responses to clients, not just text.
+- `agents-cli setup` now works without network or git access, with skills bundled into the package.
+- Fix a Windows failure loading a scaffolded project whose config points at a local path.
+
 ## [1.4.2] - 2026-08-28
 
 - Adds upper-bound for google-cloud-aiplatform dependency.

docs/hooks/skills_reference.py

@@ -17,7 +17,11 @@
 import re
 from pathlib import Path
 
-SKILLS_DIR = Path(__file__).resolve().parent.parent.parent / "skills"
+# Canonical IDE skills live inside the package so they ship in the wheel.
+SKILLS_DIR = (
+    Path(__file__).resolve().parent.parent.parent
+    / "src/google/agents/cli/skills/data"
+)
 OUTPUT_FILE = Path(__file__).resolve().parent.parent / "src" / "reference" / "skills.md"
 
 HEADER = """# Skills Reference

docs/mkdocs.yml

@@ -100,6 +100,11 @@ nav:
     - Development:
       - Development Guide: guide/development.md
       - Project Structure: guide/project-structure.md
+      - Extensions:
+        - Overview: guide/extensions/index.md
+        - Using Extensions: guide/extensions/using.md
+        - Authoring Extensions: guide/extensions/authoring.md
+        - First-party frameworks: guide/extensions/first-party.md
     - Evaluation:
       - Evaluation Guide: guide/evaluation.md
     - Deployment & Operations:
@@ -108,7 +113,7 @@ nav:
       - Observability:
         - Overview: guide/observability/index.md
         - Cloud Trace: guide/observability/cloud-trace.md
-        - BigQuery Plugin: guide/observability/bq-agent-analytics.md
+        - BigQuery Analytics Plugin: guide/observability/bq-agent-analytics.md
   - Reference:
     - reference/index.md
     - CLI: cli/index.md

docs/src/guide/extensions/authoring.md

@@ -0,0 +1,53 @@
+# Authoring Extensions
+
+The quickest path is ad-hoc: drop a single `agents-cli-extension.yaml` at your project root (next to `agents-cli-manifest.yaml`). It's **auto-loaded** at project scope — no `extension add` needed. Commit it, and teammates and CI get the same overrides. To share it across repos later, move the same file into its own git repo and `extension add` it — the schema doesn't change.
+
+!!! warning "Auto-loaded extensions run with the repo's trust"
+    A project-root `agents-cli-extension.yaml` executes its own local code the first time you run an overridden command — with no trust prompt, because you're trusted to run code in a repo you've opened. Treat it like any other code in the repo: review it before running `agents-cli` commands in an untrusted checkout. Each invocation logs which extension took over the command as the compensating control.
+
+---
+
+## Schema (`agents-cli-extension/v1alpha1`)
+
+```yaml
+schema: agents-cli-extension/v1alpha1
+name: my-extension
+description: What this extension does.
+requires:                 # optional: the agents-cli range this extension supports
+  agents_cli: ">=1.1,<2"  # optional; omitted means no constraint
+  on_incompatible: warn   # warn (install + warn) | error (refuse at add/update)
+
+commands:
+  override:               # replace a built-in; user argv passes through verbatim
+    deploy:
+      run: ["uv", "run", "scripts/custom_deploy.py"]
+      description: SBOM upload, then the built-in deploy.
+    eval.generate:        # dotted name = a subcommand (group.sub)
+      run: ["uv", "run", "scripts/eval_generate.py"]
+      description: Framework-specific inference runner.
+  add:                    # a brand-new command that doesn't exist yet
+    compliance-report:
+      run: ["bash", "scripts/compliance_report.sh"]
+      description: Generate the quarterly compliance report.
+```
+
+---
+
+## Rules that matter
+
+- **`run:` is a command vector** executed with **no shell**; your argv is appended verbatim. Relative paths resolve against the extension directory, and `$AGENTS_CLI_EXTENSION_DIR` locates sibling scripts and templates.
+- **You can't override a top-level command *group*** (e.g. `eval`) — override a specific subcommand (`eval.generate`). Peers like `eval grade` keep their built-in behavior.
+- **Re-invoke the built-in safely.** An override runs with `AGENTS_CLI_DISABLE_OVERRIDES=1` set, so calling `agents-cli deploy` inside your wrapper hits the built-in — no infinite recursion.
+- **Chaining lives in a wrapper script**, since `run:` is a single vector, not a shell line. Point `run:` at a script that sequences the steps (check, then `agents-cli deploy "$@"`).
+- **`name` is a single path component** matching `[A-Za-z0-9._-]+` (it becomes a directory under `extensions/`); slashes, `.`, and `..` are rejected.
+- **Conflicts** (same scope, surfaced in `agents-cli extension list` and `agents-cli info`): two extensions claiming one command is first-wins, and the later one is ignored. Cross-scope is not a conflict — project wins over user (`--global`).
+- **Ship your own agent** as a template built on the `empty_py` base — shared project scaffolding (infra + deps, no `app/`, no ADK) you drop your own `app/` onto, keeping the `app.fast_api_app:app` entrypoint so deploy is unchanged. Put an `agents-cli-extension.yaml` at the template root and users get its overrides by scaffolding from it, with nothing installed. The [LangChain template](first-party.md#langchain) is the worked example.
+- **A root `AGENTS.md` in your template becomes the project's coding-agent guide**, written under whatever the project calls it (`GEMINI.md` by default, or `--agent-guidance-filename`), so it replaces the base guide instead of landing beside it. Keep it to what differs; the rest belongs in the skill your template ships.
+- **Commit a `uv.lock` in your template.** It is copied into the project as-is, so without one two scaffolds a week apart resolve differently, and so do two Docker builds of the same commit.
+- **List every deployment target you support**, including `none`, in your template's `.template/templateconfig.yaml` under `settings.deployment_targets`. The CLI enforces that list, and `--prototype` resolves to `none`, so a template that omits it cannot be scaffolded in prototype mode.
+
+---
+
+## Compatibility
+
+Upgrades are safe by design: the command surface stays backward-compatible within a major (`1.x`; breaking changes wait for `2.0`), the extension schema is additive-only within `agents-cli-extension/v1alpha1`, and your extension runs its own SHA-pinned code, so a CLI upgrade never silently changes it.

docs/src/guide/extensions/first-party.md

@@ -0,0 +1,82 @@
+# First-party frameworks
+
+A framework is delivered as a **template you scaffold from**, not as an extension you install. The template carries its own `agents-cli-extension.yaml`, so the project gets the framework's command overrides with nothing installed machine-wide.
+
+| Framework | What it does |
+|--------|--------------|
+| [LangChain](#langchain) | Run a LangChain agent through the `agents-cli` lifecycle. |
+
+---
+
+## LangChain
+
+The LangChain template runs a [LangChain](https://python.langchain.com) agent through the `agents-cli` lifecycle. It overrides only the framework-coupled commands and leaves everything else — `deploy`, `infra`, `eval grade` — running natively.
+
+!!! warning "Experimental: deploy to Cloud Run or GKE"
+
+    On Agent Runtime the container serves and traces normally, but the integrations that
+    expect an ADK app do not work, because this project serves A2A and no `reasoning_engine`
+    routes: `publish gemini-enterprise` is refused (registration invokes `:streamQuery`), the
+    Console playground cannot invoke the agent, and the Console's session and trace views stay
+    empty. Traces still reach Cloud Trace.
+
+### Create a project
+
+```bash
+agents-cli create my-agent \
+    --agent google/agents-cli/extensions/langchain/template@v1.5.0 \
+    -d cloud_run
+cd my-agent && agents-cli install
+```
+
+The scaffolded project contains `agents-cli-extension.yaml` at its root. That file is auto-loaded at project scope, so the overrides below are active in this project and nowhere else. Commit it.
+
+### What it overrides
+
+| Command | Behavior in a LangChain project |
+|---------|---------------------------------|
+| `playground` | `uv run langgraph dev` — the local LangGraph dev server (also serves A2A). |
+| `publish gemini-enterprise` | Runs the built-in, except on Agent Runtime, where it refuses with the reason. |
+| `run` | Invokes the compiled graph in-process. |
+| `eval generate` | Produces the standard `EvaluationDataset` shape, so `eval grade` is unchanged. |
+| `eval dataset synthesize`, `eval optimize` | Refused with an explanation: both drive the agent through ADK. |
+
+Everything else stays native — **do not override** `deploy` (the target-appropriate native deploy, e.g. `gcloud run deploy --source .` on Cloud Run), `eval grade` / `compare` / `analyze` (framework-agnostic), `infra`, or `publish`.
+
+### The scaffolded agent
+
+The default `app/agent.py` is a Gemini ReAct agent built with `langchain.agents.create_agent` and a sample `get_weather` tool. It calls Gemini via Vertex AI using Application Default Credentials; set `GOOGLE_API_KEY` or `GEMINI_API_KEY` in `.env` to use AI Studio instead (the scaffolded `.env.example` names the latter).
+
+Because the project rides the framework-neutral `empty_py` substrate, the generated code contains **no ADK dependency**, and the template ships its own coding-agent skill.
+
+### Serving over A2A
+
+The deployed agent is served over the [Agent2Agent (A2A) protocol](https://a2a-protocol.org) — the same contract the rest of the toolchain expects — so it works unchanged:
+
+- **Entrypoint:** `uvicorn app.fast_api_app:app` (the scaffold Dockerfile `CMD`).
+- **Endpoints:** JSON-RPC at `POST /a2a/app`; Agent Card at `/a2a/app/.well-known/agent-card.json`.
+- **Streaming:** the executor streams LLM token chunks as incremental A2A task artifacts (`capabilities.streaming=True`), so a real chat model streams token-by-token. Graphs whose nodes don't stream tokens fall back to a single final artifact.
+
+Query a deployed (or locally served) agent over A2A. Because the project overrides `run` with in-process graph invocation, set `AGENTS_CLI_DISABLE_OVERRIDES=1` to reach the built-in A2A client:
+
+```bash
+AGENTS_CLI_DISABLE_OVERRIDES=1 agents-cli run --url https://<service-url> --mode a2a --app-name app "hello"
+```
+
+### Full journey
+
+```bash
+agents-cli create my-agent --agent google/agents-cli/extensions/langchain/template@v1.5.0 -d cloud_run
+cd my-agent && agents-cli install
+agents-cli run "what's the weather in San Francisco?"       # in-process graph
+agents-cli eval generate --dataset tests/eval/datasets/basic-dataset.json -o tests/eval/output/
+agents-cli eval grade --traces tests/eval/output/<dataset>.json --config tests/eval/eval_config.yaml
+agents-cli deploy                                            # native Cloud Run deploy
+```
+
+### Notes
+
+- **Credentials:** `run` and `eval` call Gemini, so they need credentials — `GOOGLE_CLOUD_PROJECT` plus ADC, or `GOOGLE_API_KEY` / `GEMINI_API_KEY` for AI Studio.
+- **Run the built-in instead of an override:** prefix with `AGENTS_CLI_DISABLE_OVERRIDES=1` (e.g. `AGENTS_CLI_DISABLE_OVERRIDES=1 agents-cli run "hi"`).
+- **Deploy contract:** `app/fast_api_app.py` must keep exposing `app`. If you restructure the agent, keep that import working.
+- **Compatibility:** the template's manifest declares no `requires` range, so its overrides apply on any CLI version. See [Authoring → Compatibility](authoring.md#compatibility) for declaring one in your own.

docs/src/guide/extensions/index.md

@@ -0,0 +1,7 @@
+# Extensions
+
+An **extension** overrides or adds an `agents-cli` command — to run a different agent framework, apply an org's deploy policy, or add a command of your own, without forking the tool.
+
+- **[Using extensions](using.md)** — what extensions can do, how they work, and how to adopt, scope, and operate one.
+- **[Authoring extensions](authoring.md)** — write the `agents-cli-extension.yaml` schema.
+- **[First-party frameworks](first-party.md)** — the framework templates we maintain (LangChain today).