release v0.1.3 at 2026-05-06 19:33:03 UTC

sushicw · sushicw · commit f73062ca58ac · 2026-05-06T19:33:03.000Z
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -56,7 +56,7 @@ body:
     id: 'info'
     attributes:
       label: 'Client information'
-      description: 'Please paste the full text from `agents-cli info`. Also include which platform (macOS, Windows, Linux).'
+      description: 'Please paste the full text from `agents-cli info`.'
       value: |-
         <details>
         <summary>Client Information</summary>
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.3] - 2026-05-06
+- Default `infra` commands to terraform plan instead of apply
+- Fix `playground` to work for Cloud Shell and other similar envs and be more transparent about the underlying command
+- Update skills to cover need for cloud sql role
+- Make `agents-cli info` print OS info for easier bug reporting
+- Make `run` only start a background server when requested with `--start-server`
+- Clearer display string for ADC auth
+- Fix broken doc links
+- Fix missing target description for agent_runtime
+
 ## [0.1.2] - 2026-04-29
 - Document & image fixes
 - Project metadata fixes
diff --git a/docs/src/guide/templates.md b/docs/src/guide/templates.md
@@ -22,7 +22,7 @@ agents-cli create my-agent --agent adk
 
 ### adk_a2a
 
-Extends the base `adk` template with [Agent-to-Agent (A2A) protocol](https://google.github.io/A2A/) support. Use this when your agent needs to interoperate with agents built on other frameworks (LangGraph, CrewAI, etc.) or when building a distributed multi-agent system.
+Extends the base `adk` template with [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org) support. Use this when your agent needs to interoperate with agents built on other frameworks (LangGraph, CrewAI, etc.) or when building a distributed multi-agent system.
 
 ```bash
 agents-cli create my-agent --agent adk_a2a
diff --git a/skills/google-agents-cli-adk-code/SKILL.md b/skills/google-agents-cli-adk-code/SKILL.md
@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.1.2
+  version: 0.1.3
   requires:
     bins:
       - agents-cli
diff --git a/skills/google-agents-cli-deploy/SKILL.md b/skills/google-agents-cli-deploy/SKILL.md
@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.1.2
+  version: 0.1.3
   requires:
     bins:
       - agents-cli
@@ -177,6 +177,7 @@ Check `deployment/terraform/iam.tf` for exact role bindings. Cross-project permi
 - "Permission denied on Cloud Run" → `cicd_runner_sa` missing deployment role in the target project
 - "Cannot act as service account" → Missing `iam.serviceAccountUser` binding on `app_sa`
 - "Secret access denied" → `app_sa` missing `secretmanager.secretAccessor`
+- "Cloud SQL connection failed / Not authorized" → Runtime service account missing `roles/cloudsql.client`
 - "Artifact Registry read denied" → Cloud Run service agent missing read access in CI/CD project
 
 ---
@@ -225,6 +226,22 @@ Format: `ENV_VAR=SECRET_ID` or `ENV_VAR=SECRET_ID:VERSION` (defaults to latest).
 
 ---
 
+## Cloud SQL Permissions (Manual Deployment)
+
+When using Cloud SQL with Cloud Run in a **manual deployment** (e.g., adding `--add-cloudsql-instances` in non-Terraform setups), you must manually grant the `Cloud SQL Client` role to the runtime service account.
+
+Without this, the deployment may succeed but fail at runtime with `cloudsql.instances.get` authorization errors.
+
+```bash
+gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
+  --member="serviceAccount:YOUR_RUNTIME_SA_EMAIL" \
+  --role="roles/cloudsql.client"
+```
+
+> **Note:** In full Terraform-managed setups (`infra cicd` / `infra single-project`), this role is configured and managed automatically.
+
+---
+
 ## Observability
 
 See the **agents-cli-observability** skill for observability configuration (Cloud Trace, prompt-response logging, BigQuery Analytics, third-party integrations).
@@ -293,6 +310,7 @@ For custom infrastructure patterns, consult `references/terraform-patterns.md` f
 | Resource already exists | `terraform import` (see `references/terraform-patterns.md`) |
 | Agent Runtime deploy timeout / hangs | Deployments take 5-10 min; check if engine was created (see Agent Runtime Specifics) |
 | Secret not available | Verify `secretAccessor` granted to `app_sa` (not the default compute SA) |
+| Cloud SQL connection failed / 403 | Grant `roles/cloudsql.client` to the runtime service account when using manual deployments |
 | 403 on deploy | Check `deployment/terraform/iam.tf` — `cicd_runner_sa` needs deployment + SA impersonation roles in the target project |
 | 403 when testing Cloud Run | Default is `--no-allow-unauthenticated`; include `Authorization: Bearer $(gcloud auth print-identity-token)` header |
 | Cold starts too slow | Set `min_instance_count > 0` in Cloud Run Terraform config |
diff --git a/skills/google-agents-cli-deploy/references/cloud-run.md b/skills/google-agents-cli-deploy/references/cloud-run.md
@@ -26,6 +26,8 @@ Available endpoints vary by project template. Check `app/fast_api_app.py` for th
 
 Cloud SQL session infrastructure (instance, database, Cloud SQL Unix socket volume mount) is configured in `deployment/terraform/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.
+
 ## Network & Ingress
 
 Default ingress is `INGRESS_TRAFFIC_ALL` (public). To restrict, change the `ingress` setting in `service.tf` to `INGRESS_TRAFFIC_INTERNAL_ONLY` (VPC only) or `INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER` (internal + GCLB).
diff --git a/skills/google-agents-cli-eval/SKILL.md b/skills/google-agents-cli-eval/SKILL.md
@@ -13,7 +13,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.1.2
+  version: 0.1.3
   requires:
     bins:
       - agents-cli
diff --git a/skills/google-agents-cli-observability/SKILL.md b/skills/google-agents-cli-observability/SKILL.md
@@ -13,7 +13,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.1.2
+  version: 0.1.3
   requires:
     bins:
       - agents-cli
diff --git a/skills/google-agents-cli-publish/SKILL.md b/skills/google-agents-cli-publish/SKILL.md
@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.1.2
+  version: 0.1.3
   requires:
     bins:
       - agents-cli
diff --git a/skills/google-agents-cli-scaffold/SKILL.md b/skills/google-agents-cli-scaffold/SKILL.md
@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.1.2
+  version: 0.1.3
   requires:
     bins:
       - agents-cli
diff --git a/skills/google-agents-cli-workflow/SKILL.md b/skills/google-agents-cli-workflow/SKILL.md
@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.1.2
+  version: 0.1.3
   requires:
     bins:
       - agents-cli
@@ -25,8 +25,8 @@ metadata:
 
 **agents-cli** is a CLI and skills toolkit for building, evaluating, and deploying agents on Google Cloud using the [Agent Development Kit (ADK)](https://adk.dev/). It works with any coding agent — Gemini CLI, Claude Code, Codex, or others. Install with `uvx google-agents-cli setup`.
 
-> Requires: google-agents-cli ~= 0.1.2
-> If version is behind, run: uv tool install "google-agents-cli~=0.1.2"
+> Requires: google-agents-cli ~= 0.1.3
+> If version is behind, run: uv tool install "google-agents-cli~=0.1.3"
 > Check version: agents-cli info
 > [Install uv](https://docs.astral.sh/uv/getting-started/installation/index.md) first if needed.
 
@@ -200,7 +200,7 @@ It contains the evalset schema, config format, and critical gotchas. Do NOT skip
 **`uv run pytest` vs `agents-cli eval run` — know the difference:**
 - **`uv run pytest`** — Tests *code correctness*: imports work, functions return expected types, API contracts hold. Does NOT test whether the agent behaves well.
 - **`agents-cli eval run`** — Tests *agent behavior*: response quality, tool usage, persona consistency, safety compliance. This is what validates your agent actually works.
-- **`agents-cli run "prompt"`** — Quick one-off smoke test during development. Use this for fast iteration, not pytest.
+- **`agents-cli run "prompt"`** — Quick one-off smoke test during development. If testing multiple prompts use the `--start-server` option to persist the local server, which reduces overhead for repeated calls and allows resuming local sessions via `--session-id`. Use this for fast iteration, not pytest.
 
 **NEVER write pytest tests that check LLM response content** (e.g., asserting pirate keywords appear, checking if the agent mentions allergies). LLM outputs are non-deterministic. Use eval with LLM-as-judge criteria instead.
 
diff --git a/skills/google-agents-cli-workflow/references/internals.md b/skills/google-agents-cli-workflow/references/internals.md
@@ -8,7 +8,7 @@ by the CLI — for debugging, customization, or edge cases — use these directl
 | `agents-cli` command | Underlying command |
 |---|---|
 | `agents-cli playground` | `uv run adk web .` |
-| `agents-cli run "prompt"` | `uv run adk api_server .` (background), then HTTP queries to `/run_sse` |
+| `agents-cli run "prompt"` | Starts a local server, queries it, then shuts it down (unless using --start-server) |
 | `agents-cli run --url URL --mode MODE "prompt"` | HTTP requests to URL (`/run_sse` for adk, A2A protocol for a2a) |
 | `agents-cli playground --port PORT` | `uv run adk web . --port PORT` |
 | `agents-cli lint` | `uv run ruff check . && uv run ruff format . --check` |
