google-agents-cli 1.0.0__tar.gz → 1.2.0__tar.gz

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.0.0
+Version: 1.2.0
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -46,7 +46,7 @@ Provides-Extra: lint
     <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>
 
@@ -207,12 +207,3 @@ See the [contributing guide](CONTRIBUTING.md) for details.
 
 `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).
-

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/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).

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.0.0"
+version = "1.2.0"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-adk-code/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.0.0
+  version: 1.2.0
   requires:
     bins:
       - agents-cli
@@ -45,7 +45,7 @@ def get_weather(city: str) -> dict:
 
 root_agent = Agent(
     name="my_agent",
-    model="gemini-flash-latest",
+    model="gemini-3.6-flash",
     instruction="You are a helpful assistant that ...",
     tools=[get_weather],
 )
@@ -59,7 +59,7 @@ The first two are cheatsheets for common patterns; for broad or deep knowledge,
 
 | Reference | When to read |
 |------|-------------|
-| `references/adk-python.md` | Core ADK API: `Agent`, tools, callbacks, plugins, state, artifacts, multi-agent systems, `SequentialAgent` / `ParallelAgent` / `LoopAgent`, custom `BaseAgent`, A2A protocol, A2UI. Default for most agents. |
+| `references/adk-python.md` | Core ADK API: `Agent`, tools, callbacks, plugins, state, artifacts, multi-agent systems, `SequentialAgent` / `ParallelAgent` / `LoopAgent`, custom `BaseAgent`, `ManagedAgent` (server-hosted first-party agents), A2A protocol, A2UI. Default for most agents. |
 | `references/adk-workflows.md` | Graph-based Workflow API (ADK 2.0): nodes, edges, fan-out/fan-in, HITL, parallel processing. Use when you need explicit graph topology. |
 | `curl https://adk.dev/llms.txt` | Docs index (every page title + URL). Fetch it, then `WebFetch` the specific page for anything beyond the cheatsheets. |
 | Installed ADK package | Exact signatures and symbols — inspect the source (see "Inspecting ADK Source Code" in `references/adk-python.md`). |

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-adk-code/references/adk-python.md

@@ -44,7 +44,7 @@ def get_weather(city: str) -> dict:
 
 my_agent = Agent(
     name="weather_agent",
-    model="gemini-flash-latest",
+    model="gemini-3.6-flash",
     instruction="You help users check the weather. Use the get_weather tool.",
     description="Provides weather information.",  # Important for multi-agent delegation
     tools=[get_weather]
@@ -59,7 +59,7 @@ from google.adk.agents import Agent
 
 agent = Agent(
     name="my_agent",
-    model="gemini-flash-latest",
+    model="gemini-3.6-flash",
     instruction="Your instructions here. Use {state_key} for dynamic injection.",
     description="Description for delegation.",
 
@@ -109,7 +109,7 @@ class Evaluation(BaseModel):
 
 evaluator = Agent(
     name="evaluator",
-    model="gemini-flash-latest",
+    model="gemini-3.6-flash",
     instruction="Evaluate the input and provide structured feedback.",
     output_schema=Evaluation,
     output_key="evaluation_result",
@@ -147,14 +147,14 @@ from google.adk.agents import SequentialAgent, Agent
 
 summarizer = Agent(
     name="summarizer",
-    model="gemini-flash-latest",
+    model="gemini-3.6-flash",
     instruction="Summarize the input.",
     output_key="summary"
 )
 
 question_gen = Agent(
     name="question_generator",
-    model="gemini-flash-latest",
+    model="gemini-3.6-flash",
     instruction="Generate questions based on: {summary}"
 )
 
@@ -240,13 +240,13 @@ For a production LoopAgent with EscalationChecker, BuiltInPlanner, and grounding
 
     researcher = Agent(
         name="researcher",
-        model="gemini-flash-latest",
+        model="gemini-3.6-flash",
         mode="task",                        # 'chat' (default) | 'task' | 'single_turn'
         output_schema=ResearchOutput,
         description="Researches a topic.",  # required for delegation
         instruction="Research the topic, then call finish_task.",
     )
-    coordinator = Agent(name="coordinator", model="gemini-flash-latest", sub_agents=[researcher])
+    coordinator = Agent(name="coordinator", model="gemini-3.6-flash", sub_agents=[researcher])
     ```
     Modes: `task` (multi-turn, structured I/O) · `single_turn` (autonomous, no user turn). Sub-agents need a `description`; default I/O schemas (`goal`/`background` in, `result` out) are used if none set. Disabled inside graph `Workflow`s.
 
@@ -304,7 +304,7 @@ class EscalationChecker(BaseAgent):
 # Vertex AI (prod)
 # Set: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, GOOGLE_GENAI_USE_VERTEXAI=True
 
-agent = Agent(model="gemini-flash-latest", ...)
+agent = Agent(model="gemini-3.6-flash", ...)
 ```
 
 ### Other Models via LiteLLM
@@ -323,7 +323,7 @@ agent = Agent(model=LiteLlm(model="ollama_chat/llama3:instruct"), ...)
 from google.adk.models import Gemini
 
 # Vertex AI hosted Gemini (set GOOGLE_GENAI_USE_VERTEXAI=True)
-agent = Agent(model=Gemini(model="gemini-flash-latest"), ...)
+agent = Agent(model=Gemini(model="gemini-3.6-flash"), ...)
 ```
 
 Provider guides: [Anthropic](https://adk.dev/agents/models/anthropic/index.md), [Ollama](https://adk.dev/agents/models/ollama/index.md), [vLLM](https://adk.dev/agents/models/vllm/index.md), [LiteLLM](https://adk.dev/agents/models/litellm/index.md)
@@ -662,7 +662,7 @@ app = App(
         compaction_interval=20,  # summarize every 20 events
         overlap_size=3,          # include last 3 events in next window for continuity
         # Optional: custom summarizer model
-        summarizer=LlmEventSummarizer(llm=Gemini(model="gemini-flash-latest")),
+        summarizer=LlmEventSummarizer(llm=Gemini(model="gemini-3.6-flash")),
     ),
 )
 ```
@@ -796,7 +796,7 @@ manager = A2uiSchemaManager(...)        # loads catalog(s) + few-shot examples
 instruction = manager.generate_system_prompt(...)
 
 # 2. Use it as the agent instruction
-root_agent = Agent(name="ui_agent", model="gemini-flash-latest", instruction=instruction)
+root_agent = Agent(name="ui_agent", model="gemini-3.6-flash", instruction=instruction)
 
 # 3. Validate the model's JSON output, then wrap as an A2A DataPart
 #    (MIME application/a2ui+json) via a2ui.a2a before streaming to the client.
@@ -846,6 +846,55 @@ Since ambient agents have no interactive user, route outputs via structured logg
 
 ---
 
+## 13. Managed Agents (server-hosted, first-party)
+
+> **Requires ADK ≥ 2.4.0.** `ManagedAgent` connects to Google's first-party, server-hosted agents (e.g. the Antigravity agent) via the Managed Agents API: reasoning, tools, and execution all run in Google's managed environment, so there's no local sandbox to provision. It's a `BaseAgent`, so a standard `Runner` runs it like any other agent.
+
+### When to use it
+
+- **Managed agent** — powerful out-of-the-box capabilities (server-side web search, code execution) without operating the environment yourself. Trade-off: predefined server-side toolset, no client-side tools, runs only in the managed environment.
+- **`LlmAgent` (§2)** — when you need control over the model, instructions, custom/MCP tools, or where execution happens.
+
+### Setup
+
+Two backends — satisfy the prerequisites for whichever you use, then supply an `agent_id`:
+- **Gemini API:** set `GEMINI_API_KEY`. Use an out-of-the-box id (e.g. `antigravity-preview-05-2026`) or create your own (see below).
+- **Agent Platform (GEAP, formerly Vertex):** authenticate with ADC (`gcloud auth application-default login`). The Managed Agents API is served only from the `global` location, and `ManagedAgent` enforces it.
+
+### Create & use
+
+```python
+from google import genai
+from google.adk.agents import ManagedAgent
+from google.adk.tools import google_search
+
+# Create your own agent (google-genai SDK, NOT ADK — ManagedAgent has no create()).
+# Get-or-create keeps it idempotent; or skip entirely and use an out-of-the-box id like "antigravity-preview-05-2026".
+client = genai.Client()
+if "researcher" not in {a.id for a in (client.agents.list().agents or [])}:  # id must be unique, no gemini-/google-/... prefixes
+    client.agents.create(
+        id="researcher", base_agent="antigravity-preview-05-2026",
+        system_instruction="Answer with fresh, grounded info from the web.",
+    )
+
+# Connect + use. A ManagedAgent is a BaseAgent: set it as root_agent, drop it in a
+# workflow, or wrap it as AgentTool. Only server-side tools are allowed.
+managed = ManagedAgent(
+    name="researcher", agent_id="researcher",
+    environment={"type": "remote"},        # tools run in the managed sandbox
+    tools=[google_search],                 # or types.Tool(code_execution=types.ToolCodeExecution())
+)
+```
+
+### Limits
+
+- **Client-side tools raise `NotImplementedError`:** Python functions/callables and client-side MCP (`McpToolset`). Server-side tools work — ADK built-ins, raw `types.Tool` configs, and server-side remote MCP via `RemoteMcpServer`.
+- **Backends differ:** the Gemini API and GEAP behave slightly differently today — test against your target backend.
+
+Docs: [Gemini API agents](https://ai.google.dev/gemini-api/docs/agents) · [Agent Platform managed agents](https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/managed-agents) · [Interactions API](https://ai.google.dev/gemini-api/docs/interactions-overview) · [building custom agents](https://ai.google.dev/gemini-api/docs/custom-agents). Samples: [basic](https://github.com/google/adk-python/tree/main/contributing/samples/managed_agent/basic), [code execution](https://github.com/google/adk-python/tree/main/contributing/samples/managed_agent/code_execution).
+
+---
+
 ## Quick Reference
 
 ### Running Agents Programmatically

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-adk-code/references/adk-workflows.md

@@ -192,7 +192,7 @@ class DraftOutput(BaseModel):
 
 writer = LlmAgent(
     name="writer",
-    model="gemini-flash-latest",
+    model="gemini-3.6-flash",
     instruction="Write a draft based on the user's request.",
     output_schema=DraftOutput,  # Always set for structured output
     output_key="draft",         # Also store in state['draft']

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-deploy/SKILL.md

@@ -4,7 +4,7 @@ description: >
   This skill should be used when the user wants to "deploy an agent",
   "deploy my ADK agent", "set up CI/CD", "configure secrets",
   "troubleshoot a deployment", or needs guidance on Agent Runtime,
-  Cloud Run, or GKE deployment targets.
+  Cloud Run, or GKE deployment targets, or awareness of Agent Gateway.
   Covers deployment workflows, service accounts, rollback, and production infrastructure.
   Part of the Google ADK (Agent Development Kit) skills suite.
   Do NOT use for API code patterns (use google-agents-cli-adk-code), evaluation
@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.0.0
+  version: 1.2.0
   requires:
     bins:
       - agents-cli
@@ -47,7 +47,6 @@ Choose the right deployment target based on your requirements:
 
 | Criteria | Agent Runtime | Cloud Run | GKE |
 |----------|-------------|-----------|-----|
-| **Languages** | Python | Python | Python (+ others via custom containers) |
 | **Scaling** | Managed auto-scaling (configurable min/max, concurrency) | Fully configurable (min/max instances, concurrency, CPU allocation) | Full Kubernetes scaling (HPA, VPA, node auto-provisioning) |
 | **Networking** | VPC-SC and PSC-I supported (private VPC connectivity via network attachments) | Full VPC support, direct VPC egress, IAP, ingress rules | Full Kubernetes networking |
 | **Session state** | Native `VertexAiSessionService` (persistent, managed) | In-memory (dev), Cloud SQL, or Agent Platform Sessions backend | In-memory (dev), Cloud SQL, or Agent Platform Sessions backend |
@@ -58,6 +57,8 @@ Choose the right deployment target based on your requirements:
 
 **Ask the user** which deployment target fits their needs. Each is a valid production choice with different trade-offs.
 
+All three targets are container-based, so any language works.
+
 > **Product name mapping:** "Agent Engine" / "Vertex AI Agent Engine" is now **Agent Runtime**. Use `--deployment-target agent_runtime`.
 
 > **Ambient / scheduled / event-driven agents:** ADK's `trigger_sources` registers `/apps/{app}/trigger/*` endpoints on the same FastAPI app for **all** targets. On **Cloud Run** / **GKE** these are public HTTP routes you point a Pub/Sub push subscription or Eventarc trigger at; on **Agent Runtime** the same routes are reachable through the Agent Engine `/api` passthrough (e.g. `.../reasoningEngines/v1/{resource}/api/apps/{app}/trigger/pubsub`). Cloud Run remains the simplest target for unauthenticated trigger sources. See `/google-agents-cli-adk-code` (`references/adk-python.md`, section "12. Event-Driven / Ambient Agents") for the `trigger_sources` pattern.
@@ -359,6 +360,31 @@ For registering deployed agents with Gemini Enterprise, see `/google-agents-cli-
 
 ---
 
+## Agent Gateway & Semantic Governance (Gemini Enterprise Agent Platform)
+
+> **Note:** There are no `agents-cli` commands for these yet. Deploy your agent as usual
+> with `agents-cli deploy`, then configure Agent Gateway and Semantic Governance separately
+> (via Terraform or the Cloud Console).
+
+**Agent Gateway** is the networking + security entry/exit point for all agent interactions
+(user↔agent, agent↔tool, agent↔agent) — it centralizes access control and governed
+connectivity (ingress/egress). It is not a deployment target. Deploy your agent with
+`agents-cli deploy`, then attach it to a gateway one of two ways:
+
+- **Add the existing agent to a gateway** via the Console / docs flow — see [Route Agent Runtime traffic through Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-gateway-runtime-deploy) ("For existing agents").
+- **Manage the gateway in Terraform** with [`google_network_services_agent_gateway`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/network_services_agent_gateway) (currently in the `google-beta` provider) — recommended for production, so `agents-cli deploy` owns the agent version and CI/CD handles updates.
+
+Background: [Agent Gateway overview](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview).
+
+**Semantic Governance Policies (SGP)** add a natural-language security/compliance layer
+that keeps an agent's tool invocations aligned with user intent and organizational
+constraints.
+
+- Overview: https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/semantic-governance-overview
+- Configure: https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/policies/configure-semantic-governance
+
+---
+
 ## Related Skills
 
 - `/google-agents-cli-workflow` — Development workflow, coding guidelines, and operational rules

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-eval/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.0.0
+  version: 1.2.0
   requires:
     bins:
       - agents-cli

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-eval/references/metrics-guide.md

@@ -44,7 +44,7 @@ Custom metrics are declared in `eval_config.yaml` (or `.json`) under `custom_met
 
 Code-based metrics default to **local in-process execution** (no GCP project or region required); opt into the Vertex AI sandbox with `execution: "remote"`.
 
-> **Scaffolded default metric.** The scaffolded `eval_config.yaml` ships `custom_response_quality` as a local LLM-judge in `tests/eval/metrics.py` (referenced via `custom_function_file`, run in-process via `google-genai`). It grades on either backend — `genai.Client()` uses `GEMINI_API_KEY` (AI Studio) or ADC (Vertex) — and reads each case's `reference` (ground truth) when present. To grade with the managed Vertex eval service instead, replace it with a built-in metric or an `LLMMetric` (`prompt_template`).
+> **Scaffolded default metric.** The scaffolded `eval_config.yaml` ships `custom_response_quality` as a local LLM-judge in `tests/eval/response_quality.py` (referenced via `custom_function_file`, run in-process via `google-genai`). It grades on either backend — `genai.Client()` uses `GEMINI_API_KEY` (AI Studio) or ADC (Vertex) — and reads each case's `reference` (ground truth) when present. To grade with the managed Vertex eval service instead, replace it with a built-in metric or an `LLMMetric` (`prompt_template`).
 
 ### Example
 
@@ -129,7 +129,7 @@ Evaluates responses using an LLM judge driven by a prompt template.
 | `name` | yes | Unique identifier for the metric. |
 | `prompt_template` | yes | Prompt template used by the judge model. With agents-cli's file-based `EvaluationDataset` use `{prompt}`, `{response}`, and `{agent_data}` (the full trajectory). `{reference}` and `{context}` resolve only when the eval case has those fields populated. |
 | `rubric_group_name` | no | Name of the rubric group containing rubrics this metric uses. **Must match a key under `rubric_groups` in your dataset's `EvalCase` entries** (see `dataset_schema.md`). When set, the judge prompt is augmented with the rubrics from the matching group; when omitted, the metric runs without per-case rubrics. |
-| `judge_model` | no | Judge model (e.g., `gemini-flash-latest`). |
+| `judge_model` | no | Judge model (e.g., `gemini-3.6-flash`). |
 | `judge_model_sampling_count` | no | Number of judge samples to compute the score (1–32). |
 | `judge_model_system_instruction` | no | System instruction for the judge model. |
 | `judge_model_generation_config` | no | Generation config for the judge LLM (e.g., `temperature`). |

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-eval/references/multimodal-eval.md

@@ -71,7 +71,7 @@ custom_metrics:
       Image: {response}
 
       Return JSON: {"score": <0.0-1.0>, "explanation": "<reason>"}
-    judge_model: gemini-flash-latest
+    judge_model: gemini-3.6-flash
     judge_model_sampling_count: 3
 ```
 
@@ -125,7 +125,7 @@ custom_metrics:
 
       User input: {prompt}
       Agent response: {response}
-    judge_model: gemini-flash-latest
+    judge_model: gemini-3.6-flash
     judge_model_sampling_count: 3
 ```
 
@@ -136,7 +136,7 @@ Run with `agents-cli eval grade --config tests/eval/eval_config.yaml`.
 ## Notes
 
 - **Built-in adaptive metrics (`final_response_quality`, etc.) skip media parts.** They extract only `.text` parts when constructing the judge prompt. Use a custom `LLMMetric` for true multimodal grading.
-- **Choose a vision-capable `judge_model`.** `gemini-flash-latest` and `gemini-pro-latest` both handle images and video; verify capability before relying on it.
+- **Choose a vision-capable `judge_model`.** `gemini-3.6-flash` handles images and video; verify capability before relying on it.
 - **Sampling count** (`judge_model_sampling_count`) of 3–5 reduces variance for multimodal judges, which can be noisier than text-only.
 
 For the full custom-metric field reference, see `references/metrics-guide.md`. For dataset schema and the `inline_data` / `file_data` part types, see `references/dataset_schema.md`.

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-observability/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.0.0
+  version: 1.2.0
   requires:
     bins:
       - agents-cli
@@ -26,12 +26,12 @@ metadata:
 
 ### Order of operations for `agent_runtime` deployments
 
-For `deployment_target = agent_runtime`, run `agents-cli infra single-project` **before** the first `agents-cli deploy`. The Terraform module owns the entire Reasoning Engine resource (display_name, service account, deployment spec, env vars), so applying it after a SDK-based deploy creates a state mismatch — Terraform has no record of the SDK-deployed instance and cannot layer env vars onto it without taking ownership of the whole resource.
+For `deployment_target = agent_runtime`, run `agents-cli infra single-project` **before** the first `agents-cli deploy`. The Terraform module owns the entire Reasoning Engine resource (service account, deployment spec, env vars), so applying it after an SDK-based deploy creates a state mismatch Terraform can't reconcile without taking ownership of the whole resource.
 
-If you have already run `agents-cli deploy`, you have two options:
+Already ran `agents-cli deploy`? Two options:
 
-1. **Switch to Terraform-managed.** Delete the SDK-deployed Reasoning Engine, then run `agents-cli infra single-project` followed by `agents-cli deploy`. Sessions and any in-flight state on the previous instance are lost.
-2. **Keep the SDK-deployed instance.** Skip `infra single-project` and set the observability env vars on the running instance directly via the `vertexai` client `update` API. You will also need to grant the instance's service account the IAM permissions required to emit telemetry — writing to the logs GCS bucket, BigQuery dataset access, log writer, etc. See `deployment/terraform/single-project/iam.tf` and `telemetry.tf` in your scaffolded project for the full set of bindings the Terraform module would otherwise provision. Terraform-managed env vars are not available in this mode.
+1. **Switch to Terraform-managed** — delete the SDK-deployed Reasoning Engine, then run `agents-cli infra single-project` and `agents-cli deploy` (sessions and in-flight state are lost).
+2. **Keep the SDK-deployed instance** — skip `infra single-project` and set the observability env vars by re-running `agents-cli deploy --update-env-vars "KEY=VALUE,..."`; deploy matches the existing Reasoning Engine by display name and updates it in place, preserving env vars set outside the deploy. You must also grant its service account the telemetry IAM roles the Terraform module would otherwise provision: `roles/storage.admin` (write completions to the logs bucket), `roles/logging.logWriter`, `roles/cloudtrace.agent`, plus `roles/bigquery.dataOwner` + `roles/bigquery.jobUser` when scaffolded with `--bq-analytics`. The full set lives in `deployment/terraform/single-project/iam.tf` (from `app_sa_roles`) and `telemetry.tf`. Terraform-managed env vars aren't available in this mode.
 
 ### Reference Files
 
@@ -64,9 +64,10 @@ ADK uses OpenTelemetry to emit distributed traces. Every agent invocation produc
 ### Span Hierarchy
 
 ```
-invocation
-  └── agent_run (one per agent in the chain)
-        ├── call_llm (model request/response)
+invoke_workflow (top-level run)
+  └── invoke_agent (one per agent in the chain)
+        ├── call_llm (model request)
+        │     └── generate_content (underlying GenAI model call)
         └── execute_tool (tool execution)
 ```
 
@@ -74,9 +75,8 @@ invocation
 
 | Deployment | Setup |
 |-----------|-------|
-| **Agent Runtime** | Automatic — traces are exported to Cloud Trace by default |
-| **Cloud Run (scaffolded)** | Automatic — `setup_telemetry()` configures Cloud Trace/Logging exporters |
-| **GKE (scaffolded)** | Automatic — `setup_telemetry()` configures Cloud Trace/Logging exporters |
+| **Agent Runtime** | Automatic — `get_fast_api_app(otel_to_cloud=True)`, gated on `GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY` (set by deploy); exports to Cloud Trace/Logging + Agent Engine console |
+| **Cloud Run / GKE (scaffolded)** | Automatic — `get_fast_api_app(otel_to_cloud=True)` exports to Cloud Trace/Logging |
 | **Cloud Run / GKE (manual)** | Configure OpenTelemetry exporter in your app |
 | **Local dev** | Works with `agents-cli playground`; traces visible in Cloud Console |
 
@@ -88,13 +88,21 @@ For detailed setup instructions (Agent Runtime CLI/SDK, Cloud Run, custom deploy
 
 ## Prompt-Response Logging
 
-Captures GenAI interactions (model name, tokens, timing) and exports to GCS (JSONL) and BigQuery (via direct log sinks and external tables). Privacy-preserving by default — only metadata is logged unless explicitly configured otherwise.
+Captures GenAI interactions and exports to GCS (JSONL) and BigQuery (via log sinks + external tables). Content is governed by **two independent tiers**; the net Terraform-deploy default is **full content in GCS/BigQuery, none in traces**:
 
-Key env var: `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` — OTel GenAI semantic-conventions standard (modes: `span_only`, `event_only`, `span_and_event`, `no_content`). The scaffolded `setup_telemetry()` collapses every non-`false` value to `NO_CONTENT` (metadata-only); `false` disables capture. Logging is disabled locally unless `LOGS_BUCKET_NAME` is set.
+| Tier | Captures | Controlled by | Default (Terraform deploy) |
+|------|----------|---------------|----------------------------|
+| **GCS/BigQuery completions** | Full prompts/responses (the prompt-response logging feature) | `OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload` + `LOGS_BUCKET_NAME` | **On** — full content |
+| **Trace spans / Cloud Logging events** | Span/event content | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` + `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false` | **Off** — `NO_CONTENT` |
 
-For scaffolded project details (Terraform resources, env vars, privacy modes, enabling/disabling, verification commands), see `references/cloud-trace-and-logging.md`.
+The tiers are independent: GCS/BigQuery uploads capture full content whenever their upload vars are set and do **not** honor `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`, which governs the traces/events tier only. Its valid (experimental-semconv) values:
 
-For ADK logging docs (log levels, configuration, debugging), fetch `https://adk.dev/observability/logging/index.md`.
+- `NO_CONTENT` — no content in spans/events (scaffolded default)
+- `EVENT_ONLY` — content in Cloud Logging events
+- `SPAN_ONLY` / `SPAN_AND_EVENT` — content in trace spans
+- `true` / `false` — **invalid**; fall back to `NO_CONTENT`
+
+For the full mechanics (semconv opt-in, declarative Terraform config, env-var table, enabling/disabling, verification commands), see `references/cloud-trace-and-logging.md`. For ADK logging docs (log levels, configuration, debugging), fetch `https://adk.dev/observability/logging/index.md`.
 
 ---
 
@@ -106,7 +114,7 @@ Optional plugin that logs structured agent events to BigQuery. Enable with `--bq
 
 ## Third-Party Integrations
 
-ADK supports several third-party observability platforms. Each uses OpenTelemetry or custom instrumentation to capture agent behavior.
+ADK supports many third-party observability platforms (via OpenTelemetry or custom instrumentation). The table below covers common ones; the full list is larger (see the pointer below it).
 
 | Platform | Key Differentiator | Setup Complexity | Self-Hosted Option |
 |----------|-------------------|-----------------|-------------------|
@@ -118,7 +126,7 @@ ADK supports several third-party observability platforms. Each uses OpenTelemetr
 | **Weave** | W&B platform, team collaboration, timeline views | Low | No (SaaS) |
 | **Freeplay** | Prompt management + evals + observability in one platform | Low | No (SaaS) |
 
-**Ask the user** which platform they prefer — present the trade-offs and let them choose. For setup details, fetch the relevant ADK docs page from the Deep Dive table below.
+**Ask the user** which platform they prefer — present the trade-offs and let them choose. Fetch a platform's setup page at `https://adk.dev/integrations/<slug>/index.md` (slugs for the table above: `agentops`, `arize-ax`, `phoenix`, `mlflow-tracing`, `monocle`, `weave`, `freeplay`). ADK has more observability integrations (Datadog, Galileo, LangWatch, Latitude, Future AGI, Respan, Zespan, …) — browse the complete, current list at `https://adk.dev/integrations/` (observability topic).
 
 ---
 
@@ -126,9 +134,9 @@ ADK supports several third-party observability platforms. Each uses OpenTelemetr
 
 | Issue | Solution |
 |-------|----------|
-| No traces in Cloud Trace | Verify `setup_telemetry()` runs at startup and the service account has the `cloudtrace.agent` role |
+| No traces in Cloud Trace | Verify `fast_api_app.py` uses `get_fast_api_app(otel_to_cloud=True)` (Agent Runtime gates it on `GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY`) and the SA has the `cloudtrace.agent` role |
 | Prompt-response data not appearing | Check `LOGS_BUCKET_NAME` is set; verify SA has `storage.objectCreator` on the bucket; check app logs for telemetry setup warnings |
-| Privacy mode misconfigured | Check `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` value — use `NO_CONTENT` for metadata-only, `false` to disable |
+| Content in traces/events (unwanted) | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT` keeps content out of spans/events. NOTE: GCS/BigQuery completions still capture full content — to stop that, remove `LOGS_BUCKET_NAME`/`OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK` (drop the upload block in `service.tf`) |
 | BigQuery Analytics not logging | Verify plugin is configured in `app/agent.py`; check `BQ_ANALYTICS_DATASET_ID` env var is set |
 | Third-party integration not capturing spans | Check provider-specific env vars (API keys, endpoints); some providers (AgentOps) replace native telemetry |
 | Traces missing tool spans | Tool execution spans appear under `execute_tool` — check trace explorer filters |
@@ -146,13 +154,6 @@ For detailed documentation beyond what this skill covers, fetch these pages:
 | Agent activity logging | `https://adk.dev/observability/logging/index.md` |
 | Cloud Trace integration | `https://adk.dev/integrations/cloud-trace/index.md` |
 | BigQuery Agent Analytics | `https://adk.dev/integrations/bigquery-agent-analytics/index.md` |
-| AgentOps | `https://adk.dev/integrations/agentops/index.md` |
-| Arize AX | `https://adk.dev/integrations/arize-ax/index.md` |
-| Phoenix (Arize) | `https://adk.dev/integrations/phoenix/index.md` |
-| MLflow tracing | `https://adk.dev/integrations/mlflow-tracing/index.md` |
-| Monocle | `https://adk.dev/integrations/monocle/index.md` |
-| W&B Weave | `https://adk.dev/integrations/weave/index.md` |
-| Freeplay | `https://adk.dev/integrations/freeplay/index.md` |
 
 ---
 

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-observability/references/cloud-trace-and-logging.md

@@ -4,7 +4,7 @@
 
 ## Cloud Trace
 
-Always-on distributed tracing: Cloud export is configured by `setup_telemetry()` (Cloud Run/GKE) and by `setup_agent_engine_telemetry()` (Agent Runtime); `get_fast_api_app` is called with `otel_to_cloud=False`. Tracks requests through LLM calls and tool executions with latency analysis and error visibility.
+Always-on distributed tracing, exporting spans/logs to Cloud Trace and Cloud Logging via `get_fast_api_app(otel_to_cloud=True)`. For **Agent Runtime** it's gated on `GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY` (set by deploy), and traces also appear in the Agent Engine console. Content env vars are declared statically (Terraform `service.tf` for deployed, `.env` for local). Tracks requests through LLM calls and tool executions with latency analysis and error visibility.
 
 View traces: **Cloud Console → Trace → Trace explorer**
 
@@ -16,7 +16,7 @@ All provisioned automatically by `deployment/terraform/single-project/telemetry.
 
 - **Log sinks** — Route GenAI inference logs and feedback logs directly to BigQuery (partitioned tables)
 - **BigQuery dataset** — Telemetry dataset with external tables over GCS data and pre-created log export table
-- **Pre-created log export table** — `gen_ai_client_inference_operation_details` table with Cloud Logging BQ export schema (labels flattened: dots become underscores)
+- **Pre-created log export table** — Cloud Logging BQ export schema (labels flattened: dots become underscores). Cloud Logging names the sink table after the log id, so it varies by deployment target: `gen_ai_client_inference_operation_details` (Cloud Run / GKE) or `aiplatform_googleapis_com_reasoning_engine_stdout` (Agent Runtime, where GenAI logs arrive via stdout)
 - **GCS logs bucket** — Stores completions as NDJSON
 - **BigQuery connection** — Service account for GCS access from BigQuery
 - **Completions view** — Joins BQ log export data with GCS-stored prompt/response data
@@ -25,31 +25,38 @@ Check `deployment/terraform/single-project/telemetry.tf` for exact configuration
 
 ## Environment Variables
 
-Set automatically by Terraform on the deployed service:
+Set automatically by Terraform on the deployed service. The `OTEL_INSTRUMENTATION_GENAI_*` content-capture and upload variables (capture modes, `OTEL_SEMCONV_STABILITY_OPT_IN`, completion hook / upload) are documented in [`opentelemetry-util-genai`](https://github.com/open-telemetry/opentelemetry-python-genai/tree/main/util/opentelemetry-util-genai) and the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).
 
 | Variable | Purpose |
 |----------|---------|
 | `LOGS_BUCKET_NAME` | GCS bucket for completions and logs. Required to enable prompt-response logging |
-| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Controls logging state and content capture |
+| `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Controls content capture for the traces/events tier only (`NO_CONTENT`/`EVENT_ONLY`/`SPAN_ONLY`/`SPAN_AND_EVENT`; `true`/`false` invalid) |
+| `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS` | Keeps message content out of trace spans; Terraform sets `false` (ADK defaults to `true`) |
 | `BQ_ANALYTICS_DATASET_ID` | BigQuery dataset for telemetry (only when scaffolded with `--bq-analytics`) |
 | `BQ_ANALYTICS_CONNECTION_ID` | BigQuery connection for GCS access (only when scaffolded with `--bq-analytics`) |
 | `BQ_ANALYTICS_GCS_BUCKET` | GCS bucket for BigQuery Analytics multimodal offloading (only when scaffolded with `--bq-analytics`) |
-| `GENAI_TELEMETRY_PATH` | Optional: override upload path within bucket (default: `completions`) |
+| `OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK` | Set to `upload` to export full completions to GCS (the prompt-response logging feature) |
+| `OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH` | GCS path for uploaded completions (e.g. `gs://<bucket>/completions`) |
+| `OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT` | Upload format for completions (e.g. `jsonl`) |
 
 ## Enabling / Disabling
 
 ### Enable Locally
 
-Set these before running `agents-cli playground`:
+Telemetry config is env-var driven, so set the same vars Terraform sets for deployed agents before running `agents-cli playground`:
 
 ```bash
-export LOGS_BUCKET_NAME="your-bucket-name"
-export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="NO_CONTENT"
+export LOGS_BUCKET_NAME="your-bucket-name"                       # bare name, no gs://
+export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT="NO_CONTENT"  # or EVENT_ONLY (content in Cloud Logging events)
+export OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK="upload"
+export OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH="gs://your-bucket-name/completions"
+export OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT="jsonl"
+export OTEL_SEMCONV_STABILITY_OPT_IN="gen_ai_latest_experimental"
 ```
 
 ### Disable in Deployed Environments
 
-Set `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false` in `deployment/terraform/single-project/service.tf` (or the `cicd/` variant) and re-apply Terraform.
+Content in traces/events is already off by default (`NO_CONTENT`) — note `true`/`false` are **not** valid values under experimental semconv (they fall back to `NO_CONTENT`). To turn off prompt-response logging to GCS/BigQuery entirely, remove the upload block (`OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK`, `OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH`, `LOGS_BUCKET_NAME`) from `deployment/terraform/single-project/service.tf` (or the `cicd/` variant) and re-apply Terraform.
 
 ## BigQuery Dataset Naming Convention
 
@@ -58,7 +65,7 @@ BigQuery dataset names **cannot contain hyphens**. Terraform automatically conve
 - Project name `my-agent` → BQ dataset `my_agent_telemetry`
 
 One dataset is created:
-- **`{name}_telemetry`** — Contains external tables over GCS completions data (NDJSON), the pre-created log export table (`gen_ai_client_inference_operation_details`), and the `completions_view`
+- **`{name}_telemetry`** — Contains external tables over GCS completions data (NDJSON), the pre-created log export table (`gen_ai_client_inference_operation_details` on Cloud Run / GKE, `aiplatform_googleapis_com_reasoning_engine_stdout` on Agent Runtime), and the `completions_view`
 
 To discover the actual dataset name in your project:
 ```bash
@@ -76,7 +83,9 @@ PROJECT_NAME="your-app-name"  # The agents-cli project name (not the GCP project
 # Check GCS data
 gsutil ls gs://${PROJECT_ID}-${PROJECT_NAME}-logs/completions/
 
-# Check BigQuery log export table (logs arrive via sink, may take a few minutes)
+# Check BigQuery log export table (logs arrive via sink, may take a few minutes).
+# Table name varies by target: gen_ai_client_inference_operation_details on
+# Cloud Run / GKE, aiplatform_googleapis_com_reasoning_engine_stdout on Agent Runtime.
 bq query --use_legacy_sql=false \
   "SELECT COUNT(*) FROM \`${PROJECT_ID}.${PROJECT_NAME//-/_}_telemetry.gen_ai_client_inference_operation_details\`"
 

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-publish/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.0.0
+  version: 1.2.0
   requires:
     bins:
       - agents-cli
@@ -197,6 +197,6 @@ Docs: https://docs.cloud.google.com/agent-registry/manage-agents
 
 ## Related Skills
 
-- `/google-agents-cli-deploy` — Deployment targets, CI/CD pipelines, and production workflows
+- `/google-agents-cli-deploy` — Deployment targets, CI/CD pipelines, and production workflows (also covers Agent Gateway governed ingress/egress and Semantic Governance awareness)
 - `/google-agents-cli-workflow` — Development workflow, coding guidelines, and operational rules
 - `/google-agents-cli-scaffold` — Project creation and enhancement with `agents-cli scaffold create` / `scaffold enhance`

{google_agents_cli-1.0.0 → google_agents_cli-1.2.0}/skills/google-agents-cli-scaffold/SKILL.md

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