release v1.2.0 at 2026-07-23 16:00:10 UTC

Author: mwiatrowski

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "google-agents-cli",
-  "version": "1.1.0",
+  "version": "1.2.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",

README.md

@@ -11,7 +11,7 @@
     <a href="https://github.com/google/agents-cli/issues">Issues</a> &nbsp;&nbsp;|&nbsp;&nbsp;
     <a href="https://google.github.io/agents-cli/">Docs</a> &nbsp;&nbsp;|&nbsp;&nbsp;
     <a href="https://github.com/google/agents-cli/blob/main/RELEASE_NOTES.md">Release Notes</a> &nbsp;&nbsp;|&nbsp;&nbsp;
-    <a href="https://github.com/google/agents-cli/stargazers">Star us</a>
+    <a href="https://github.com/google/agents-cli">Star us</a>
   </p>
 </div>
 
@@ -171,12 +171,3 @@ See the [contributing guide](CONTRIBUTING.md) for details.
 ## Terms of Service
 
 `agents-cli` leverages Google Cloud APIs. When you deploy agents, you'll be deploying resources in your own Google Cloud project and will be responsible for those resources. Please review the [Google Cloud Service Terms](https://cloud.google.com/terms/service-terms) for details.
-
-## Preview
-
-This feature is subject to the "Pre-GA Offerings Terms" in the General Service
-Terms section of the
-[Service Specific Terms](https://cloud.google.com/terms/service-terms#1).
-Pre-GA features are available "as is" and might have limited support. For more
-information, see the
-[launch stage descriptions](https://cloud.google.com/products?hl=en#product-launch-stages).

RELEASE_NOTES.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.0] - 2026-07-21
+
+- **Cloud telemetry moved to ADK's `otel_to_cloud`, across the CLI and deploys.** `playground` and `run` gain an `--otel-to-cloud` flag that forwards ADK's current `--otel_to_cloud`; the old `--trace-to-cloud` stays as a hidden, still-functional alias that warns when used. On the deployment side, Agent Runtime now exports through `otel_to_cloud` (gated on `GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY`) and generated projects configure Cloud telemetry declaratively in Terraform instead of at runtime. Bundled `google-adk` moves to `>=2.2.0` with the `otel-gcp` extra, and the observability skill was updated to match.
+- Scaffolds now default to `gemini-3.6-flash`.
+- **Agent Analytics now captures GenAI completions on Agent Runtime.** The BigQuery telemetry log sink is configured per deployment target, so Agent Runtime deployments route their GenAI request/response logs into BigQuery instead of leaving the completions view empty.
+- **Managed Agents guidance in the ADK code skill.** The bundled ADK cheatsheet gained a Managed Agents section covering when to use `ManagedAgent`, Gemini API vs Agent Platform (GEAP) setup, and a runnable create-and-use example.
+
 ## [1.1.0] - 2026-07-10
 
 - **Guided brainstorming for new agents.** The workflow skill's Phase 0 is now an interactive brainstorming dialogue that helps you shape an agent's spec before any code is written, and surfaces its assumptions for review when it can't ask.

docs/src/guide/evaluation.md

@@ -86,13 +86,13 @@ custom_metrics:
       Final response: {response}
       Full trace (for tool-call and reasoning context): {agent_data}
       Return JSON: {"score": <1|2|3|4|5>, "explanation": "<reason>"}
-    judge_model: gemini-flash-latest
+    judge_model: gemini-3.6-flash
     judge_model_sampling_count: 3
 ```
 
 Each custom metric must conform to either the **Code Execution Metric** or **LLM-as-a-Judge Metric** (`LLMMetric`) schema:
 - **Code Execution Metric**: Used to run custom Python code for evaluation. Must have a `name` and a `custom_function` (containing a `def evaluate(instance):` signature). By default, the function executes **locally in the CLI process** — no GCP project or region is required, but the user-supplied code runs with the CLI's privileges. Add `"execution": "remote"` to opt into Vertex AI's sandboxed `CodeExecutionMetric` (server-side), which requires a configured GCP project + region.
-- **LLM-as-a-Judge Metric**: Used to evaluate responses using an LLM judge. Must have a `name` and a `prompt_template`. Optional fields include `rubric_group_name`, `judge_model` (e.g., `gemini-flash-latest`), and `judge_model_sampling_count` (between `1` and `32`).
+- **LLM-as-a-Judge Metric**: Used to evaluate responses using an LLM judge. Must have a `name` and a `prompt_template`. Optional fields include `rubric_group_name`, `judge_model` (e.g., `gemini-3.6-flash`), and `judge_model_sampling_count` (between `1` and `32`).
 
 ### Quick Reference for Common Scenarios
 

docs/src/guide/hands-on-tutorial.md

@@ -62,7 +62,7 @@ The important file is `app/agent.py`. Open it and you'll see two tool functions
 ```python title="app/agent.py"
 root_agent = Agent(
     name="root_agent",
-    model=Gemini(model="gemini-flash-latest"),
+    model=Gemini(model="gemini-3.6-flash"),
     instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
     tools=[get_weather, get_current_time],
 )
@@ -111,7 +111,7 @@ Let's give the agent a personality. Open `app/agent.py` and change the instructi
 root_agent = Agent(
     name="root_agent",
     model=Gemini(
-        model="gemini-flash-latest",
+        model="gemini-3.6-flash",
         retry_options=types.HttpRetryOptions(attempts=3),
     ),
     instruction="""You are a cheerful weather reporter who speaks in short, 

docs/src/guide/lifecycle.md

@@ -95,7 +95,7 @@ from google.adk.models import Gemini
 
 root_agent = Agent(
     name="root_agent",
-    model=Gemini(model="gemini-flash-latest"),
+    model=Gemini(model="gemini-3.6-flash"),
     instruction="You are an SRE outage-recovery assistant...",
     tools=[query_logs, check_metrics, search_runbook],
 )

docs/src/guide/observability/cloud-trace.md

@@ -27,7 +27,7 @@ Open the Google Cloud Console and navigate to **Trace > Trace explorer**. You sh
 
 ### 3. Verify Prompt-Response Logging (Optional)
 
-Prompt-response logging captures model interactions to GCS and BigQuery. It's enabled by default in deployed environments.
+Prompt-response logging to GCS and BigQuery is provisioned by Terraform (`agents-cli infra single-project` or `agents-cli infra cicd`), which creates the logs bucket and dataset and sets `LOGS_BUCKET_NAME` — it's enabled automatically there. A bare `agents-cli deploy` does **not** create these resources, so the checks below apply only to Terraform-provisioned deployments.
 
 ```bash
 PROJECT_ID="your-dev-project-id"
@@ -51,11 +51,17 @@ If data isn't appearing:
 
 ## Enable Prompt-Response Logging Locally
 
-By default, `agents-cli playground` runs **without** prompt-response logging. To enable it locally (ADK agents only):
+By default, `agents-cli playground` runs **without** prompt-response logging. Telemetry is
+declarative (there's no runtime `setup_telemetry()`), so to enable completions logging locally set
+the same vars Terraform sets for deployed agents (ADK agents only):
 
 ```bash
-export LOGS_BUCKET_NAME="gs://your-dev-project-id-your-project-name-logs"
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="NO_CONTENT"
+export LOGS_BUCKET_NAME="your-dev-project-id-your-project-name-logs"   # bare bucket name, no gs://
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="NO_CONTENT"  # or EVENT_ONLY for full content in logs
+export OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK="upload"
+export OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH="gs://your-dev-project-id-your-project-name-logs/completions"
+export OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT="jsonl"
+export OTEL_SEMCONV_STABILITY_OPT_IN="gen_ai_latest_experimental"
 agents-cli playground
 ```
 
@@ -85,7 +91,11 @@ terraform apply -var-file=vars/env.tfvars
 
 | Variable | Values | Purpose |
 |---|---|---|
-| `LOGS_BUCKET_NAME` | GCS bucket path | Required for prompt-response logging. If not set, logging is disabled. |
-| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `false`, `NO_CONTENT`, `true` | `false` = disabled, `NO_CONTENT` = metadata only (default), `true` = full content |
-| `GENAI_TELEMETRY_PATH` | Path within bucket | Override upload path for prompt-response logs |
+| `LOGS_BUCKET_NAME` | GCS bucket **name** (no `gs://`) | Required for prompt-response logging. If not set, logging is disabled. |
+| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | `NO_CONTENT`, `EVENT_ONLY`, `SPAN_ONLY`, `SPAN_AND_EVENT` | Controls content in **traces/events only** (not the GCS/BigQuery completions, which always capture full content when a bucket is set). Experimental semconv (we set `OTEL_SEMCONV_STABILITY_OPT_IN`): `NO_CONTENT` = none in spans/events (default); `EVENT_ONLY` = content in Cloud Logging events; `SPAN_*` = content in trace spans. **`true`/`false` are invalid** — rejected, fall back to `NO_CONTENT`. |
+| `OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK` | `upload` | Enables uploading completion records |
+| `OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH` | `gs://<bucket>/completions` | Destination for completion records |
+| `OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT` | `jsonl` | Upload format |
+| `OTEL_SEMCONV_STABILITY_OPT_IN` | `gen_ai_latest_experimental` | Required for the GenAI completion/upload semconv |
+| `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS` | `false`, `true` | Keep prompt/response content out of trace spans (`false`, the default we set) |
 

docs/src/guide/observability/index.md

@@ -7,14 +7,17 @@ Every `agents-cli` project ships with OpenTelemetry instrumentation that automat
 - **Error visibility** — traces capture errors, helping pinpoint where failures occur.
 - **No configuration required** — works out-of-the-box in all environments.
 
-For ADK-based agents, **prompt-response logging** is also available. It captures model interactions (prompts, responses, tokens) and exports them to GCS, BigQuery, and Cloud Logging. Disabled locally by default, enabled automatically in deployed environments.
+For ADK-based agents, **prompt-response logging** captures full model interactions (prompts, responses, tokens) and uploads them to **GCS** (JSONL) + a **BigQuery** `completions` table. It's enabled whenever a logs bucket is configured (`LOGS_BUCKET_NAME` + the `OTEL_INSTRUMENTATION_GENAI_*` upload vars), which Terraform-provisioned deployments do by default.
+
+> **Two independent tiers.** Prompt-response logging (GCS/BigQuery completions) captures **full content**. Whether content *also* appears in **Cloud Trace spans / Cloud Logging events** is governed separately by `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` (default `NO_CONTENT` — content kept **out** of traces/events) and `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false`. So by default: **full content in GCS/BigQuery, no content in traces.**
 
 ### Logging Behavior by Environment
 
-| Environment | Tracing (Cloud Trace) | Prompt-Response Logging |
+| Environment | Cloud Trace spans | Prompt-Response Logging (GCS/BigQuery) |
 |---|---|---|
-| **Local** (`agents-cli playground`) | Enabled | Disabled (no `LOGS_BUCKET_NAME`) |
-| **Deployed** (Terraform) | Enabled | Enabled (`NO_CONTENT` mode — metadata only) |
+| **Local** (`agents-cli playground`) | Enabled, no content | Off (no `LOGS_BUCKET_NAME`) |
+| **Deployed** (Terraform-provisioned) | Enabled, no content | **On — full prompts/responses** |
+| **Deployed** (bare `agents-cli deploy`, no bucket) | Enabled, no content | Off (no `LOGS_BUCKET_NAME`) |
 
 ---
 

docs/src/guide/project-structure.md

@@ -13,11 +13,11 @@ my-agent/
 ├── app/                          # Your agent code
 │   ├── __init__.py               # Registers the app (exports `app`)
 │   ├── agent.py                  # Agent definition — instructions, model, tools
-│   └── app_utils/                # Utilities (telemetry, converters)
-│       ├── __init__.py
-│       ├── telemetry.py          # OpenTelemetry setup for Cloud Trace
-│       ├── typing.py             # Request/response Pydantic models
-│       └── gcs.py                # GCS utility functions
+│   ├── fast_api_app.py           # FastAPI server — telemetry setup, feedback/A2A routes
+│   └── app_utils/                # Utilities
+│       ├── services.py           # Shared session & artifact services
+│       ├── a2a.py                # A2A route wiring
+│       └── typing.py             # Request/response Pydantic models
 │
 ├── tests/
 │   ├── eval/                     # Evaluation test cases
@@ -51,6 +51,8 @@ from google.adk.apps import App
 from google.adk.models import Gemini
 from google.genai import types
 
+MODEL = "gemini-3.6-flash"
+
 
 def get_weather(query: str) -> str:
     """Simulates a web search. Use it get information on weather."""
@@ -68,7 +70,7 @@ def get_current_time(query: str) -> str:
 root_agent = Agent(
     name="root_agent",
     model=Gemini(
-        model="gemini-flash-latest",
+        model=MODEL,
         retry_options=types.HttpRetryOptions(attempts=3),
     ),
     instruction="You are a helpful AI assistant.",
@@ -86,7 +88,7 @@ The four key parts:
 1. **Tool functions** — plain Python functions with docstrings. The docstring tells the LLM when to use the tool.
 2. **`Agent`** — combines a model, instruction (system prompt), and tools.
 3. **`App`** — wraps the agent for serving. The `name` must match the directory name (`app`).
-4. **Model** — defaults to `gemini-flash-latest`. Change it in the `Gemini()` constructor.
+4. **Model** — defaults to `gemini-3.6-flash`. Change it via the `MODEL` constant at the top of `agent.py`.
 
 ### `pyproject.toml`
 

docs/src/guide/quickstart-tutorial.md

@@ -54,7 +54,7 @@ The agent definition ends up looking something like:
 ```python title="app/agent.py"
 root_agent = Agent(
     name="caveman_agent",
-    model=Gemini(model="gemini-flash-latest"),
+    model=Gemini(model="gemini-3.6-flash"),
     instruction="""You caveman compressor. Human give long words,
     you make short. Rules:
     - No articles. No filler. No fluff.