release v0.5.0 at 2026-06-15 22:44:07 UTC

Author: eliasecchig

.claude-plugin/plugin.json

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

RELEASE_NOTES.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2026-06-15
+- chore(deps): bump @grpc/grpc-js
+- Update publish script to mirror and publish source
+- Smart fixture to find tests broken by pyfakefs / patching conflicts
+- fix: don't tear down a reused local server on a plain run
+- fix: upgrade builds the prior-version template via uvx
+- docs: fix pre-existing inaccuracies in skills and generated READMEs
+- Make publish script a bit more robust
+- fix: only announce the project root when chdir actually moves
+- feat: print a copy-pasteable resume command in the run session footer
+- feat: surface machine-shape params as deploy flags (Agent Runtime + Cloud Run)
+- feat(deploy): add --service-name override
+- Refactor for more consistent project resolution
+- fix: drain npx stderr concurrently to avoid pipe-buffer deadlock
+- docs: codify recurring review feedback in agent guidance
+- Clean up remaining adk_live stuff
+
 ## [0.4.0] - 2026-06-10
 - Scaffolded Python templates now use **ADK 2.0 GA**. New `adk`, `adk_a2a`, and `agentic_rag` projects pin `google-adk[gcp]>=2.0.0,<3.0.0`; the `[gcp]` extra restores the OpenTelemetry GCP exporters and bundles the BigQuery client, so the separate `[bigquery-analytics]` extra is no longer needed. Cloud SQL sessions on Cloud Run and GKE keep working under 2.0. The bundled ADK coding skill and its reference docs were refreshed for 2.0.
   - https://github.com/google/agents-cli/issues/24

docs/src/guide/lifecycle.md

@@ -48,7 +48,7 @@ The loop expands to eight phases when you walk through it slowly. Each phase has
 
 ### 0 · Spec
 
-A `.agents-cli-spec.md` names the agent's tools, constraints, and success criteria. The whole rest of the lifecycle reads from it: the scaffold flags, the eval rubrics, the safety guardrails, the trace attributes you'll watch in production. Don't start from blank — browse [Agent Garden](https://cloud.google.com/products/agent-garden) for an existing template close to what you want, then customize.
+A `.agents-cli-spec.md` names the agent's tools, constraints, and success criteria. The whole rest of the lifecycle reads from it: the scaffold flags, the eval rubrics, the safety guardrails, the trace attributes you'll watch in production. Don't start from blank — browse [Agent Garden](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/agent-garden) for an existing template close to what you want, then customize.
 
 A typical spec is one screen of markdown:
 

gemini-extension.json

@@ -1,5 +1,5 @@
 {
   "name": "google-agents-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Scaffold, develop, evaluate, and deploy AI agents with Google ADK. Bundles 7 skills for the agent development lifecycle."
 }

skills/google-agents-cli-adk-code/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.4.0
+  version: 0.5.0
   requires:
     bins:
       - agents-cli

skills/google-agents-cli-deploy/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.4.0
+  version: 0.5.0
   requires:
     bins:
       - agents-cli
@@ -101,14 +101,20 @@ agents-cli infra single-project
 | `--project` | GCP project ID | All |
 | `--region` | GCP region | All |
 | `--service-account` | Service account email for the deployed agent | All |
+| `--service-name` | Override the deployed service name (Cloud Run service or Agent Runtime display name); defaults to the project name. If you override it, consider updating your Terraform and CI (if present) — they name resources from the project name. Not supported for GKE, whose names are fully owned by Terraform. | Agent Runtime, Cloud Run |
 | `--secrets` | Comma-separated `ENV=SECRET` or `ENV=SECRET:VERSION` pairs | Agent Runtime, Cloud Run |
 | `--update-env-vars` | Comma-separated `KEY=VALUE` environment variables | Agent Runtime, Cloud Run |
 | `--agent-identity` | Enable [agent identity](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity) (Preview) | Agent Runtime |
 | `--network-attachment` | Network attachment resource name for [PSC interface](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/private-service-connect-interface) (enables private VPC connectivity) | Agent Runtime |
 | `--dns-peering-domain` | DNS peering domain suffix, e.g. `my-internal.corp.` (requires `--network-attachment`) | Agent Runtime |
 | `--dns-peering-project` | Project ID hosting the Cloud DNS managed zone for DNS peering (requires `--network-attachment`) | Agent Runtime |
 | `--dns-peering-network` | VPC network name in the target project for DNS peering (requires `--network-attachment`) | Agent Runtime |
-| `--memory` | Memory limit (default: `4Gi`) | Cloud Run |
+| `--memory` | Memory limit (default: `4Gi`) | Agent Runtime, Cloud Run |
+| `--cpu` | CPU limit (default: `1`) | Agent Runtime, Cloud Run |
+| `--min-instances` | Minimum number of instances (default: `1`) | Agent Runtime, Cloud Run |
+| `--max-instances` | Maximum number of instances (default: `10`) | Agent Runtime, Cloud Run |
+| `--concurrency` | Concurrent requests per container (default: `8`; see [Sizing a deployment](#sizing-a-deployment)) | Agent Runtime, Cloud Run |
+| `--num-workers` | Worker processes per container (default: `1`) | Agent Runtime |
 | `--port` | Container port | Cloud Run |
 | `--iap` | Enable Identity-Aware Proxy | Cloud Run |
 | `--image` | Container image URI (skips source build) | Cloud Run, GKE |
@@ -126,6 +132,27 @@ Run `agents-cli deploy --help` for the full flag reference.
 
 ---
 
+## Sizing a deployment
+
+Defaults (same on Agent Runtime, Cloud Run, and the generated `service.tf`): `--cpu 1`, `--memory 4Gi`, `--num-workers 1`, `--concurrency 8`, `--min-instances 1`, `--max-instances 10`.
+
+The params are coupled — scale them together:
+
+- **Workers = vCPUs.** Each worker is one GIL-bound process that saturates one core, so raise `--num-workers` with `--cpu` (e.g. `--cpu 4` → `--num-workers 4`) or you pay for idle cores.
+- **Memory bounds concurrency.** Each concurrent request keeps its full working set (context window, history, RAG chunks, response buffer) in memory while it waits on the model, so peak ≈ base + `concurrency × per-request memory`. Memory — not CPU — is the first limit, so raising `--concurrency` without `--memory` is the main OOM cause.
+- **Concurrency default is conservative.** An async worker can serve many concurrent requests while it waits on the model, but per-request memory is agent-specific, so `8` protects a memory-heavy (RAG/multimodal) agent. Light agents can raise it to 16–32+ after load-testing. See [Underutilized asynchronous workers](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/optimize-and-scale#underutilized-workers).
+
+```bash
+# 4x throughput: scale every param, not just one
+agents-cli deploy --cpu 4 --num-workers 4 --concurrency 16 --memory 16Gi
+```
+
+**Tune with the scaffolded load test** (`tests/load_test/`, run locally or in the CI/CD staging pipeline): drive load, watch *max* latency and memory/OOM restarts, then adjust — high max latency → raise concurrency (+ workers/cpu); OOM → raise memory or lower concurrency.
+
+> `--num-workers` is Agent-Runtime-only (Cloud Run runs one uvicorn process). On **GKE** these flags are rejected — size via the Terraform manifests + HorizontalPodAutoscaler under `deployment/terraform/`.
+
+---
+
 ## Production Deployment — CI/CD Pipeline
 
 For the full CI/CD pipeline setup guide — prerequisites, `infra cicd` flags, runner comparison, WIF authentication, pipeline stages, and production approval — see `references/cicd-pipeline.md`.

skills/google-agents-cli-deploy/references/cicd-pipeline.md

@@ -73,7 +73,7 @@ The pipeline has three stages:
 
 1. **CI (PR checks)** — Triggered on pull request. Runs unit and integration tests.
 2. **Staging CD** — Triggered on merge to `main`. Builds container, deploys to staging, runs load tests.
-   > **Path filter:** Staging CD uses `paths: ['app/**']` — it only triggers when files under `app/` change. The first push after `infra cicd` won't trigger staging CD unless you modify something in `app/`. If nothing happens after pushing, this is why.
+   > **Path filter:** Staging CD only triggers when relevant paths change — the agent directory (`app/**` by default), `data_ingestion/**`, `tests/**`, `deployment/**`, or `uv.lock`. The first push after `infra cicd` won't trigger staging CD unless one of these changes. If nothing happens after pushing, this is why.
 3. **Production CD** — Triggered after successful staging deploy via `workflow_run`. Might require **manual approval** before deploying to production.
    > **Approving:** Go to GitHub Actions → the production workflow run → click "Review deployments" → approve the pending `production` environment. This is GitHub's environment protection rules, not a custom mechanism.
 

skills/google-agents-cli-deploy/references/cloud-run.md

@@ -4,10 +4,12 @@
 
 ## Scaling & Resource Defaults
 
-Agents CLI scaffolds Cloud Run infrastructure in `deployment/terraform/service.tf`. Check that file for current resource limits, scaling configuration, concurrency, and session affinity settings.
+Agents CLI scaffolds Cloud Run infrastructure in `deployment/terraform/single-project/service.tf` (and the `cicd/` variant). Check that file for current resource limits, scaling configuration, concurrency, and session affinity settings.
 
 Key settings to be aware of: `cpu_idle` (CPU allocation strategy), `min_instance_count` (cold start avoidance), `max_instance_request_concurrency` (concurrency per instance), and `session_affinity` (sticky routing).
 
+For how to size cpu/memory/workers/concurrency together (and avoid OOM), see **Sizing a deployment** in the `/google-agents-cli-deploy` skill.
+
 ## Dockerfile
 
 Scaffolded projects include a `Dockerfile` using single-stage build with `uv` for dependency management. Check the project root `Dockerfile` for the exact configuration.
@@ -24,7 +26,7 @@ Available endpoints vary by project template. Check `app/fast_api_app.py` for th
 | **Cloud SQL** | `--session-type cloud_sql` at scaffold time | Production persistent sessions (Postgres 15, IAM auth) |
 | **Agent Runtime** | `session_service_uri = agentengine://{resource_name}` | When using Agent Runtime as session backend |
 
-Cloud SQL session infrastructure (instance, database, Cloud SQL Unix socket volume mount) is configured in `deployment/terraform/service.tf`.
+Cloud SQL session infrastructure (instance, database, Cloud SQL Unix socket volume mount) is configured in `deployment/terraform/single-project/service.tf`.
 
 > **Manual Deployment Warning:** When using Cloud SQL without Terraform (e.g., direct `gcloud run deploy` with `--add-cloudsql-instances`), you MUST manually grant `roles/cloudsql.client` to the runtime service account, otherwise the connection will fail with authorization errors.
 

skills/google-agents-cli-deploy/references/gke.md

@@ -26,7 +26,7 @@ All Kubernetes resources are managed by Terraform in `deployment/terraform/cicd/
 
 ## Terraform Infrastructure
 
-GKE infrastructure is provisioned in `deployment/terraform/service.tf`. Check that file for current configuration.
+GKE infrastructure is provisioned in `deployment/terraform/single-project/service.tf`. Check that file for current configuration.
 
 Key differences from Cloud Run: Terraform provisions a full networking stack (VPC, subnet, Cloud NAT for private node internet access) and a GKE Autopilot cluster with private nodes. Cloud SQL (optional, when `session_type == "cloud_sql"`) uses a proxy sidecar in the pod rather than Cloud Run's Unix socket volume mount.
 

skills/google-agents-cli-deploy/references/testing-deployed-agents.md

@@ -28,12 +28,9 @@ For more control (scripting, direct curl), see the target-specific sections belo
 
 ## Agent Runtime Deployment
 
-**Option 1: Testing Notebook**
-```bash
-jupyter notebook notebooks/adk_app_testing.ipynb
-```
+Beyond the `run --url` quick test above, you can query the deployment directly.
 
-**Option 2: Python Script**
+**Option 1: Python Script**
 ```python
 import json
 import vertexai
@@ -48,7 +45,7 @@ async for event in agent.async_stream_query(message="Hello!", user_id="test"):
     print(event)
 ```
 
-**Option 3: Playground**
+**Option 2: Playground**
 ```bash
 agents-cli playground
 ```