google-agents-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -21,6 +21,7 @@ Requires-Dist: backoff>=2.2.1
 Requires-Dist: requests>=2.31.0
 Requires-Dist: a2a-sdk~=0.3.22
 Requires-Dist: tomlkit>=0.13.0,<1
+Requires-Dist: psutil>=5.9.0
 Requires-Dist: ruff ; extra == "lint"
 Requires-Dist: ty ; extra == "lint"
 Requires-Dist: codespell ; extra == "lint"
@@ -196,7 +197,7 @@ We value your input — it helps us improve `agents-cli` for the community.
 
 ## Contributing
 
-The best way to contribute is through feedback: bug reports, feature requests, and ideas shared via [issues](https://github.com/google/agents-cli/issues) to directly shape our roadmap. The CLI is distributed as a pre-built wheel rather than as source in the repository, which lets us iterate quickly while keeping the public interface stable. The code is not obfuscated — you can inspect any release by extracting the `.whl` file (a standard zip archive).
+The best way to contribute is through feedback: bug reports, feature requests, and ideas shared via [issues](https://github.com/google/agents-cli/issues) to directly shape our roadmap.
 
 See the [contributing guide](CONTRIBUTING.md) for details.
 

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/README.md

@@ -164,7 +164,7 @@ We value your input — it helps us improve `agents-cli` for the community.
 
 ## Contributing
 
-The best way to contribute is through feedback: bug reports, feature requests, and ideas shared via [issues](https://github.com/google/agents-cli/issues) to directly shape our roadmap. The CLI is distributed as a pre-built wheel rather than as source in the repository, which lets us iterate quickly while keeping the public interface stable. The code is not obfuscated — you can inspect any release by extracting the `.whl` file (a standard zip archive).
+The best way to contribute is through feedback: bug reports, feature requests, and ideas shared via [issues](https://github.com/google/agents-cli/issues) to directly shape our roadmap.
 
 See the [contributing guide](CONTRIBUTING.md) for details.
 

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"
@@ -24,6 +24,7 @@ dependencies = [
   "requests>=2.31.0",
   "a2a-sdk~=0.3.22",
   "tomlkit>=0.13.0,<1",
+  "psutil>=5.9.0",
 ]
 
 [project.urls]

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-adk-code/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.5.0
+  version: 0.6.0
   requires:
     bins:
       - agents-cli
@@ -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`. 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`, 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-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-adk-code/references/adk-python.md

@@ -767,7 +767,7 @@ Requires `pip install google-adk[a2a]`.
 
 ```python
 # Expose an agent as an A2A service
-# Prefer scaffolding over manual code — use --agent adk_a2a (see /google-agents-cli-scaffold)
+# Prefer scaffolding over manual code — scaffold a normal `adk` agent; A2A is built in (see /google-agents-cli-scaffold)
 from google.adk.a2a.utils.agent_to_a2a import to_a2a
 from a2a.types import AgentCard
 to_a2a(root_agent, port=8001)
@@ -781,13 +781,36 @@ remote = RemoteA2aAgent(
 )
 ```
 
+### A2UI
+
+Agents can return declarative UI via [a2ui](https://github.com/google/A2UI) (cards, forms, charts; rendered client-side over A2A) instead of plain text. Public preview; current release v0.9.1 (v1.0 release candidate). Docs: https://github.com/google/A2UI/tree/main/docs · ADK guide: https://adk.dev/integrations/a2ui/index.md
+
+```python
+# pip install a2ui-agent-sdk
+from a2ui.core.schema.manager import A2uiSchemaManager
+from a2ui.basic_catalog.provider import BasicCatalog
+from a2ui.a2a import create_a2ui_part, parse_response_to_parts
+
+# 1. Build the system prompt from a component catalog
+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)
+
+# 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.
+```
+
+Runnable samples: https://github.com/google/A2UI/tree/main/samples/agent/adk
+
 ---
 
 ## 12. Event-Driven / Ambient Agents
 
 Ambient agents process events (Pub/Sub, Eventarc, schedules) autonomously. ADK provides built-in trigger endpoints that handle payload decoding, session creation, concurrency, and retries.
 
-> **Deployment:** Trigger endpoints require **Cloud Run** or **GKE**. Agent Runtime does not support event-driven or scheduled triggers.
+> **Deployment:** `trigger_sources` registers `/apps/{app}/trigger/*` on the standard FastAPI app, so it works on **all** targets. On **Cloud Run** / **GKE** the endpoints are public HTTP routes you point a Pub/Sub push subscription or Eventarc trigger at. On **Agent Runtime** the same routes are reachable through Agent Engine's `/api` passthrough (`https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/apps/{app}/trigger/pubsub`). The scaffolded `fast_api_app.py` does not pass `trigger_sources` by default — add it to enable these endpoints.
 
 ```python
 from google.adk.cli.fast_api import get_fast_api_app
@@ -795,7 +818,7 @@ from google.adk.cli.fast_api import get_fast_api_app
 app = get_fast_api_app(
     agents_dir=AGENTS_DIR,
     web=False,
-    trigger_sources=["pubsub", "eventarc"],  # enables /apps/{app}/trigger/pubsub and /trigger/eventarc
+    trigger_sources=["pubsub", "eventarc"],  # enables /apps/{app}/trigger/pubsub and /apps/{app}/trigger/eventarc
 )
 ```
 

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-deploy/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.5.0
+  version: 0.6.0
   requires:
     bins:
       - agents-cli
@@ -30,7 +30,7 @@ metadata:
 For deeper details, consult these reference files in `references/`:
 
 - **`cloud-run.md`** — Scaling defaults, Dockerfile, session types, networking
-- **`agent-runtime.md`** — deploy.py CLI, AdkApp pattern, Terraform resource, deployment metadata, CI/CD differences
+- **`agent-runtime.md`** — container-based deploy, unified FastAPI app, the `/api` passthrough, Terraform resource, deployment metadata, CI/CD differences
 - **`gke.md`** — GKE Autopilot cluster, Kubernetes manifests, Workload Identity, session types, networking
 - **`terraform-patterns.md`** — Custom infrastructure, IAM, state management, importing resources
 - **`batch-inference.md`** — BigQuery Remote Function trigger; for Pub/Sub / Eventarc see `/google-agents-cli-adk-code`
@@ -49,18 +49,18 @@ Choose the right deployment target based on your requirements:
 |----------|-------------|-----------|-----|
 | **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|
+| **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 |
-| **Batch/event processing** | Not supported | Native trigger endpoints (Pub/Sub, Eventarc); see `/google-agents-cli-adk-code` | Custom (Kubernetes Jobs, Pub/Sub) |
-| **Cost model** | vCPU-iours + memory-iours (not billed when idle) | Per-instance-second + min instance costs | Node pool costs (always-on or auto-provisioned) |
+| **Batch/event processing** | Trigger endpoints reachable via the Agent Engine `/api` passthrough | Native trigger endpoints (Pub/Sub, Eventarc); see `/google-agents-cli-adk-code` | Custom (Kubernetes Jobs, Pub/Sub) |
+| **Cost model** | vCPU-hours + memory-hours (not billed when idle) | Per-instance-second + min instance costs | Node pool costs (always-on or auto-provisioned) |
 | **Setup complexity** | Lower (managed, purpose-built for agents) | Medium (Dockerfile, Terraform, networking) | Higher (Kubernetes expertise required) |
-| **Best for** | Managed infrastructure, minimal ops | Custom infra, event-driven workloads | Full Kubernetes control |
+| **Best for** | Managed infrastructure, minimal ops | Custom infra, full networking control | Full Kubernetes control |
 
 **Ask the user** which deployment target fits their needs. Each is a valid production choice with different trade-offs.
 
 > **Product name mapping:** "Agent Engine" / "Vertex AI Agent Engine" is now **Agent Runtime**. Use `--deployment-target agent_runtime`.
 
-> **Ambient / scheduled / event-driven agents:** Agent Runtime does not support Pub/Sub, Eventarc, or Cloud Scheduler triggers. Use **Cloud Run** (recommended) or **GKE** for these workloads. See `/google-agents-cli-adk-code` (`references/adk-python.md`, section "12. Event-Driven / Ambient Agents") for the `trigger_sources` pattern.
+> **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.
 
 > **OAuth / user consent agents:** Use **Agent Runtime** with Gemini Enterprise for agents that need OAuth 2.0 user consent (e.g., accessing Google Drive, Calendar, or other user-scoped APIs). Cloud Run does not currently support managed OAuth flows. See the `adk-ae-oauth` sample in `/google-agents-cli-workflow` Phase 1.
 
@@ -92,7 +92,7 @@ Choose the right deployment target based on your requirements:
 agents-cli infra single-project
 ```
 
-> **Note:** `agents-cli deploy` doesn't automatically use the Terraform-created `app_sa`. Pass the service account via `agents-cli deploy --service-account SA_EMAIL` or `uv run -m app.app_utils.deploy --service-account SA_EMAIL` for Agent Runtime targets.
+> **Note:** `agents-cli deploy` doesn't automatically use the Terraform-created `app_sa`. Pass the service account explicitly: `agents-cli deploy --service-account SA_EMAIL`.
 
 ### Deploy Flag Reference
 
@@ -115,9 +115,10 @@ agents-cli infra single-project
 | `--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 |
+| `--port` | Container port | Cloud Run, Agent Runtime |
+| `--build-args` | Comma-separated `KEY=VALUE` Docker build args | Agent Runtime |
 | `--iap` | Enable Identity-Aware Proxy | Cloud Run |
-| `--image` | Container image URI (skips source build) | Cloud Run, GKE |
+| `--image` | Container image URI (skips source build; not supported for Agent Runtime) | Cloud Run, GKE |
 | `--no-wait` | Start deployment and return immediately | Agent Runtime, Cloud Run |
 | `--status` | Check the status of a pending `--no-wait` deployment | Agent Runtime, Cloud Run |
 | `--list` | List existing deployments and exit | All |
@@ -169,9 +170,9 @@ For event-driven / ambient agent deployment on Cloud Run, see the [`ambient-expe
 
 ## Agent Runtime Specifics
 
-Agent Runtime is a managed Vertex AI service for deploying Python ADK agents. Uses source-based deployment (no Dockerfile) via `deploy.py` and the `AdkApp` class.
+Agent Runtime is a managed Vertex AI service for deploying Python ADK agents. Uses container-based deployment: `agents-cli deploy` packages your project and Agent Engine builds the image from your project's `Dockerfile` (required) — the same `fast_api_app:app` image that serves Cloud Run and GKE.
 
-> **No `gcloud` CLI exists for Agent Runtime.** Deploy via `agents-cli deploy` or `deploy.py`. Query via the Python `vertexai.Client` SDK.
+> **No `gcloud` CLI exists for Agent Runtime.** Deploy via `agents-cli deploy`. Query via the Python `vertexai.Client` SDK.
 
 Deployments can take 5-10 minutes. Use `--no-wait` to start a deployment and return immediately, then check on it later with `--status`:
 
@@ -185,7 +186,7 @@ agents-cli deploy --status
 
 When `--status` detects the operation has completed, it writes `deployment_metadata.json` and prints the same success output as a normal deploy.
 
-For detailed infrastructure configuration (deploy.py flags, AdkApp pattern, Terraform resource, deployment metadata, session/artifact services, CI/CD differences), see `references/agent-runtime.md`. For ADK docs on Agent Runtime deployment, fetch `https://adk.dev/deploy/agent-runtime/index.md`.
+For detailed infrastructure configuration (container deploy flow, the unified FastAPI app and `/api` passthrough, Terraform resource, deployment metadata, session/artifact services, CI/CD differences), see `references/agent-runtime.md`. For ADK docs on Agent Runtime deployment, fetch `https://adk.dev/deploy/agent-runtime/index.md`.
 
 ---
 

google_agents_cli-0.6.0/skills/google-agents-cli-deploy/references/agent-runtime.md

@@ -0,0 +1,129 @@
+# Agent Runtime Infrastructure
+
+> **Assumes `/google-agents-cli-scaffold` scaffolding.** If your project isn't scaffolded yet, see `/google-agents-cli-scaffold` first.
+
+## Deployment Architecture
+
+Agent Runtime uses **container-based deployment**. `agents-cli deploy` packages your project (all git-tracked files) and Agent Engine builds a container image from your project's `Dockerfile` — the same `fast_api_app:app` image that serves Cloud Run and GKE. A `Dockerfile` at the project root is required (scaffolded projects ship one).
+
+**App object:** `fast_api_app.py` builds a single FastAPI `app` via
+`get_fast_api_app(web=True, lifespan=...)`. The lifespan builds one `Runner`
+from the shared session/artifact services (`app_utils/services.py`) and mounts
+A2A routes (`attach_a2a_routes`); `attach_reasoning_engine_routes(app)` adds the
+reasoning_engine contract routes. There is no top-level `AgentEngineApp`/`AdkApp`
+deployment entrypoint anymore — the container serves HTTP directly (the
+reasoning_engine adapter still constructs an `AdkApp` internally to dispatch the
+native `:streamQuery`/`:query` contract).
+
+The container serves the ADK HTTP surface (`/run_sse`, `/apps/...`), the A2A
+routes under `/a2a/{app_name}` (JSON-RPC + agent card), `/feedback`, and the
+reasoning_engine adapter routes `/api/reasoning_engine` +
+`/api/stream_reasoning_engine` (the native `:streamQuery`/`:query` contract used
+by the Console Playground and Gemini Enterprise ADK registration). It deploys as
+the `google-adk` agent framework (see `service.tf`).
+
+### The `/api` HTTP passthrough
+
+Agent Engine exposes the container's HTTP routes externally under an
+`/api` prefix, so deployed agents are reachable without a public Cloud Run URL:
+
+```
+https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/{container_path}
+```
+
+where `{resource}` is the full `projects/.../reasoningEngines/...` name. For
+example, the A2A agent card (container route `/a2a/{agent_directory}/.well-known/agent-card.json`)
+is reachable at:
+
+```
+https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/a2a/{agent_directory}/.well-known/agent-card.json
+```
+
+`{agent_directory}` is the app name (the project's `agent_directory`, recorded in
+`deployment_metadata.json`). This is the exact URL `deploy` advertises on
+success, `publish` registers with Gemini Enterprise, and `run` constructs for
+`--mode a2a` against an Agent Runtime URL. All three build it from the shared
+`_agent_runtime_a2a` helper.
+
+## Deploying
+
+Deploy with `agents-cli deploy` (run `agents-cli deploy --help` for the full flag reference). CI/CD pipelines invoke the same command.
+
+**Deployment flow:**
+1. `agents-cli deploy` packages the project's git-tracked files (including the `Dockerfile`)
+2. Agent Engine builds the container image and creates/updates the Agent Runtime instance
+3. Writes `deployment_metadata.json` with the engine resource ID
+
+## Terraform Resource
+
+Agent Runtime uses `google_vertex_ai_reasoning_engine` in `deployment/terraform/single-project/service.tf` (and the `cicd/service.tf` variant for CI/CD-managed deployments). Check those files for current scaling, concurrency, and resource limit settings.
+
+Key difference from Cloud Run: the `lifecycle.ignore_changes` (covering `container_spec`, `source_code_spec`, and `deployment_spec`) is critical — the image and source are updated by `agents-cli deploy` / CI/CD, not Terraform.
+
+## deployment_metadata.json
+
+Written by `agents-cli deploy` after a successful deployment:
+
+```json
+{
+  "remote_agent_runtime_id": "projects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID",
+  "deployment_target": "agent_runtime",
+  "is_a2a": true,
+  "agent_directory": "app",
+  "deployment_timestamp": "2025-02-25T10:30:00.000+00:00"
+}
+```
+
+Used by: subsequent deploys (update vs create), `agents-cli run --url`, and `agents-cli publish` (to construct the A2A card URL). Cloud Run does not use this file.
+
+If deployment times out but the engine was created, manually populate this file with the engine resource ID.
+
+## CI/CD Differences from Cloud Run
+
+| Aspect | Agent Runtime | Cloud Run |
+|--------|-------------|-----------|
+| **Build** | Dockerfile → image (built by Agent Engine) | Dockerfile → image (`gcloud builds`) |
+| **Deploy command** | `agents-cli deploy` | `gcloud run deploy --image ...` |
+| **Artifact** | Container image | Container image in Artifact Registry |
+| **Python version** | Configurable in Dockerfile | Configurable in Dockerfile |
+| **Load testing** | Via `locust` against Agent Runtime endpoint | Direct HTTP to Cloud Run URL |
+
+## Playground & Remote Testing
+
+```bash
+# Local mode (uses local agent instance)
+agents-cli playground
+
+# Query your deployed Agent Runtime remotely (ADK agent)
+agents-cli run --url https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/reasoningEngines/ID --mode adk "Hello, what can you do?"
+```
+
+`--mode` is required with `--url`: use `adk` for the ADK streaming API (`:streamQuery`) or `a2a` for the A2A protocol. Add `-v` for full JSON event payloads. Auth is auto-detected via Google Cloud credentials.
+
+To query Agent Runtime programmatically:
+
+```python
+import vertexai
+
+client = vertexai.Client(location="us-east1")
+agent = client.agent_engines.get(name="projects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID")
+
+async for event in agent.async_stream_query(message="Hello!", user_id="test"):
+    print(event)
+```
+
+## Session & Artifact Services
+
+Agent Runtime always uses in-memory sessions at scaffold time; at runtime `app_utils/services.py` upgrades to `VertexAiSessionService` when Agent Engine injects `GOOGLE_CLOUD_AGENT_ENGINE_ID`. `get_fast_api_app` receives the `shared://session` URI, resolved by `services.py`.
+
+Artifacts use `GcsArtifactService` when `LOGS_BUCKET_NAME` is set, otherwise `InMemoryArtifactService`.
+
+Environment variables set during deployment come from `agents-cli deploy` (the CLI's `deploy/agent_runtime.py`) for SDK deploys, and from `deployment/terraform/single-project/service.tf` (or the `cicd/` variant) for Terraform-managed deploys. Check those for current values.
+
+### Memory Bank
+
+To enable cross-session memory on Agent Runtime, configure `memory_bank_config` via `context_spec`. See the [`memory-bank` sample](https://github.com/google/adk-samples/tree/main/python/agents/memory-bank) for the full pattern.
+
+## Networking (PSC Interface)
+
+Agent Runtime cannot reach your VPC by default. To enable private connectivity, create a [network attachment](https://cloud.google.com/vpc/docs/create-manage-network-attachments) and deploy with `--network-attachment`. Add `--dns-peering-domain`, `--dns-peering-project`, and `--dns-peering-network` if you need private DNS resolution. PSC config is immutable after deployment — delete and redeploy to change it. See the [GCP docs](https://cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/private-service-connect-interface) for prerequisites and setup.

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-deploy/references/cloud-run.md

@@ -16,15 +16,17 @@ Scaffolded projects include a `Dockerfile` using single-stage build with `uv` fo
 
 ## FastAPI Endpoints
 
-Available endpoints vary by project template. Check `app/fast_api_app.py` for the exact routes in your project.
+Scaffolded apps serve the ADK HTTP surface (`/run_sse`, `/apps/...`), A2A routes under `/a2a/{app_name}` (JSON-RPC + agent card — A2A is built into every ADK agent), and `/feedback`. Exact routes vary by template; check `app/fast_api_app.py`.
 
 ## Session Types
 
 | Type | Configuration | Use Case |
 |------|--------------|----------|
-| **In-memory** | Default (`session_service_uri = None`) | Local dev only; lost on instance restart |
+| **In-memory** | Default (`shared://session` resolved by `app_utils/services.py` (in-memory)) | Local dev only; lost on instance restart |
 | **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 |
+| **Agent Runtime** | Managed Agent Engine sessions (`agentengine://{resource_name}`) | When using Agent Runtime as session backend |
+
+The concrete session URI for `cloud_sql` / `agent_platform_sessions` is now built inside `app_utils/services.py`, not `fast_api_app.py`.
 
 Cloud SQL session infrastructure (instance, database, Cloud SQL Unix socket volume mount) is configured in `deployment/terraform/single-project/service.tf`.
 

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-deploy/references/gke.md

@@ -40,15 +40,17 @@ This lets pods authenticate as `app_sa` without service account keys — same se
 
 | Type | Configuration | Use Case |
 |------|--------------|----------|
-| **In-memory** | Default (`session_service_uri = None`) | Local dev only; lost on pod restart |
+| **In-memory** | Default (`shared://session` resolved by `app_utils/services.py` (in-memory)) | Local dev only; lost on pod restart |
 | **Cloud SQL** | `--session-type cloud_sql` at scaffold time | Production persistent sessions (Cloud SQL proxy sidecar in pod) |
-| **Agent Runtime** | `session_service_uri = agentengine://{resource_name}` | When using Agent Runtime as session backend |
+| **Agent Runtime** | Managed Agent Engine sessions (`agentengine://{resource_name}`) | When using Agent Runtime as session backend |
+
+The concrete session URI for `cloud_sql` / `agent_platform_sessions` is now built inside `app_utils/services.py`, not `fast_api_app.py`.
 
 Cloud SQL in GKE uses a **proxy sidecar container** in the pod (unlike Cloud Run which uses a Unix socket volume mount). The sidecar is configured in the `kubernetes_deployment_v1` Terraform resource.
 
 ## FastAPI Endpoints
 
-Available endpoints vary by project template. Check `app/fast_api_app.py` for the exact routes in your project.
+Scaffolded apps serve the ADK HTTP surface (`/run_sse`, `/apps/...`), A2A routes under `/a2a/{app_name}` (JSON-RPC + agent card — A2A is built into every ADK agent), and `/feedback`. Exact routes vary by template; check `app/fast_api_app.py`.
 
 ## Testing Your Deployed Agent
 

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-deploy/references/testing-deployed-agents.md

@@ -20,6 +20,8 @@ agents-cli run --url https://my-agent.run.app --mode a2a -H "Authorization: Bear
 
 The `--mode` flag is required with `--url`: use `adk` for the ADK streaming API (`/run_sse`, or `:streamQuery` for Agent Runtime) or `a2a` for the A2A protocol. Agent Runtime URLs are detected automatically. Add `-v` for full JSON event payloads.
 
+> On Agent Runtime, Agent Engine exposes the whole container under an `/api/...` HTTP passthrough (`https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/<path>`), so the container's own routes — `/run_sse`, `/a2a/{app_name}`, etc. — are also reachable there. (This is separate from the reasoning_engine adapter, which serves only `/api/reasoning_engine` + `/api/stream_reasoning_engine` for the native `:streamQuery` contract.)
+
 Auth is auto-detected via Google Cloud credentials. Use `--header` / `-H` to override.
 
 For more control (scripting, direct curl), see the target-specific sections below.

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-eval/SKILL.md

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

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-eval/references/builtin-tools-eval.md

@@ -23,7 +23,7 @@ Search results come back as `grounding_metadata`, not function call/response eve
 }
 ```
 
-This causes `multi_turn_tool_use_quality` to ALWAYS fail for agents using `google_search`.
+This causes `multi_turn_tool_use_quality` to fail for agents whose **only** tool is `google_search` — the evaluator flags an unexpected tool call it can never see in the trace. For agents that also call function tools, the metric still scores those function-tool calls (see metric compatibility below).
 
 **Metric compatibility for `google_search` agents:**
 

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-observability/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.5.0
+  version: 0.6.0
   requires:
     bins:
       - agents-cli
@@ -75,8 +75,8 @@ invocation
 | Deployment | Setup |
 |-----------|-------|
 | **Agent Runtime** | Automatic — traces are exported to Cloud Trace by default |
-| **Cloud Run (scaffolded)** | Automatic — `otel_to_cloud=True` in the FastAPI app |
-| **GKE (scaffolded)** | Automatic — `otel_to_cloud=True` in the FastAPI app |
+| **Cloud Run (scaffolded)** | Automatic — `setup_telemetry()` configures Cloud Trace/Logging exporters |
+| **GKE (scaffolded)** | Automatic — `setup_telemetry()` configures Cloud Trace/Logging exporters |
 | **Cloud Run / GKE (manual)** | Configure OpenTelemetry exporter in your app |
 | **Local dev** | Works with `agents-cli playground`; traces visible in Cloud Console |
 
@@ -126,7 +126,7 @@ ADK supports several third-party observability platforms. Each uses OpenTelemetr
 
 | Issue | Solution |
 |-------|----------|
-| No traces in Cloud Trace | Verify `otel_to_cloud=True` in FastAPI app; check service account has `cloudtrace.agent` role |
+| No traces in Cloud Trace | Verify `setup_telemetry()` runs at startup and the service account 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 |
 | BigQuery Analytics not logging | Verify plugin is configured in `app/agent.py`; check `BQ_ANALYTICS_DATASET_ID` env var is set |

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-observability/references/bigquery-agent-analytics.md

@@ -14,7 +14,7 @@ An optional plugin that logs structured agent events directly to BigQuery via th
 | Method | How |
 |--------|-----|
 | **At scaffold time** | `agents-cli scaffold create <project-name> --bq-analytics` |
-| **Post-scaffold** | Add the plugin manually to `app/agent.py` (see ADK docs) |
+| **Post-scaffold** | Add the plugin manually to `app/agent.py` (see [ADK docs](https://adk.dev/integrations/bigquery-agent-analytics/index.md)) |
 
 Infrastructure (BigQuery dataset, GCS offloading) is provisioned automatically by Terraform when enabled at scaffold time.
 

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

@@ -4,7 +4,7 @@
 
 ## Cloud Trace
 
-Always-on distributed tracing via `otel_to_cloud=True` in the FastAPI app. Tracks requests through LLM calls and tool executions with latency analysis and error visibility.
+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.
 
 View traces: **Cloud Console → Trace → Trace explorer**
 

{google_agents_cli-0.5.0 → google_agents_cli-0.6.0}/skills/google-agents-cli-publish/SKILL.md

@@ -5,14 +5,17 @@ description: >
   "publish my ADK agent", "register an agent with Gemini Enterprise",
   "publish to Gemini Enterprise", or needs guidance on the agents-cli
   publish gemini-enterprise command.
+  Also use when the user wants to "manage agents in Agent Registry" or
+  "list/update/delete registered agents".
   Covers ADK vs A2A registration modes, programmatic and interactive usage,
-  flag reference, auto-detection from deployment metadata, and troubleshooting.
+  flag reference, auto-detection from deployment metadata, Agent Registry
+  fleet management, and troubleshooting.
   Part of the Google ADK (Agent Development Kit) skills suite.
   Do NOT use for deployment (use google-agents-cli-deploy).
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.5.0
+  version: 0.6.0
   requires:
     bins:
       - agents-cli
@@ -27,7 +30,7 @@ metadata:
 
 1. **Agent must be deployed** — the agent must be running and reachable
 2. **Gemini Enterprise app must exist** — Create one in Google Cloud Console → Gemini Enterprise → Apps before registering
-3. **`deployment_metadata.json`** (Agent Runtime only) — Created automatically by `agents-cli deploy`; contains the agent runtime ID, deployment target, and A2A flag
+3. **`deployment_metadata.json`** (Agent Runtime only) — Created automatically by `agents-cli deploy`; contains the agent runtime ID, deployment target, the A2A flag, and the agent directory
 
 ## Required Permissions for A2A on Cloud Run
 
@@ -37,35 +40,38 @@ metadata:
 
 ## Registration Modes
 
-### ADK Registration (default)
+### A2A Registration (default)
 
-For standard ADK agents deployed to Agent Runtime. The agent is registered directly via its reasoning engine resource name.
+Every scaffolded agent serves the Agent-to-Agent protocol, so A2A is the default on **every** deployment target — Agent Runtime included. Pass the agent card URL and the command fetches the card and registers it; display name and description default to the card's `name`/`description`.
 
 ```bash
+# A2A on Agent Runtime (card served through the /api passthrough)
 agents-cli publish gemini-enterprise \
-  --agent-runtime-id projects/123456/locations/us-east1/reasoningEngines/789 \
-  --gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app \
-  --display-name "My Agent" \
-  --description "Handles customer queries" \
-  --tool-description "Answers questions about products"
+  --agent-card-url "https://us-east1-aiplatform.googleapis.com/reasoningEngines/v1/projects/123456/locations/us-east1/reasoningEngines/789/api/a2a/app/.well-known/agent-card.json" \
+  --gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app
+
+# A2A on Cloud Run / GKE
+agents-cli publish gemini-enterprise \
+  --agent-card-url https://my-service-abc123.us-east1.run.app/a2a/app/.well-known/agent-card.json \
+  --gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app
 ```
 
-### A2A Registration
+Pass `--display-name` / `--description` to override the card defaults. On Agent Runtime, `--agent-card-url` can be omitted when `deployment_metadata.json` is present — see [Auto-Detection from Metadata](#auto-detection-from-metadata).
+
+> **OAuth authorization is not supported yet for A2A on Agent Runtime.** If your agent needs an OAuth authorization (`--authorization-id`), register it as ADK instead (`--registration-type adk`) — Gemini Enterprise invokes it natively via `:streamQuery`, which does support authorizations.
+
+### ADK Registration
 
-For agents using the Agent-to-Agent protocol. Requires an agent card URL — the command fetches the card and registers it.
+Opt in with `--registration-type adk` for Agent Runtime agents you want Gemini Enterprise to invoke natively via `:streamQuery` instead of over A2A — also the path to use when the agent needs an OAuth authorization (`--authorization-id`), which A2A on Agent Runtime does not yet support. The agent is registered directly via its reasoning engine resource name.
 
 ```bash
-# A2A on Cloud Run
 agents-cli publish gemini-enterprise \
-  --registration-type a2a \
-  --agent-card-url https://my-service-abc123.us-east1.run.app/a2a/app/.well-known/agent-card.json \
+  --registration-type adk \
+  --agent-runtime-id projects/123456/locations/us-east1/reasoningEngines/789 \
   --gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app \
-  --display-name "My A2A Agent"
-
-# A2A on Agent Runtime (card URL is auto-constructed from metadata)
-agents-cli publish gemini-enterprise \
-  --registration-type a2a \
-  --gemini-enterprise-app-id projects/123456/locations/global/collections/default_collection/engines/my-app
+  --display-name "My Agent" \
+  --description "Handles customer queries" \
+  --tool-description "Answers questions about products"
 ```
 
 ---
@@ -118,7 +124,7 @@ agents-cli publish gemini-enterprise --interactive
 | `--display-name` | `GEMINI_DISPLAY_NAME` | Display name in Gemini Enterprise |
 | `--description` | `GEMINI_DESCRIPTION` | Agent description |
 | `--tool-description` | `GEMINI_TOOL_DESCRIPTION` | Tool description (ADK mode only, defaults to description) |
-| `--registration-type` | `REGISTRATION_TYPE` | `adk` or `a2a` (auto-detected from metadata if not set) |
+| `--registration-type` | `REGISTRATION_TYPE` | `adk` or `a2a` (defaults to `a2a` for scaffolded agents if not set) |
 | `--agent-card-url` | `AGENT_CARD_URL` | Agent card URL for A2A registration |
 | `--deployment-target` | `DEPLOYMENT_TARGET` | `agent_runtime`, `cloud_run`, or `gke` (affects A2A auth method) |
 | `--project-id` | `GOOGLE_CLOUD_PROJECT` | GCP project ID for billing |
@@ -135,11 +141,11 @@ agents-cli publish gemini-enterprise --interactive
 When `deployment_metadata.json` exists, the command automatically:
 
 - Reads the **agent runtime ID** (`remote_agent_runtime_id`)
-- Detects the **registration type** (`is_a2a` flag)
-- Constructs the **agent card URL** for A2A agents on Agent Runtime
+- Determines the **registration type**: defaults to **A2A** on every deployment target, since every scaffolded agent serves A2A. Opt into native ADK invocation (`:streamQuery`) with `--registration-type adk` on Agent Runtime.
+- Constructs the **agent card URL** for A2A registrations on Agent Runtime. The card is served through the Agent Engine `/api` passthrough, so the URL is `https://{location}-aiplatform.googleapis.com/reasoningEngines/v1/{resource}/api/a2a/{agent_directory}/.well-known/agent-card.json` — built from `remote_agent_runtime_id` and `agent_directory` in `deployment_metadata.json` (re-deploy if the metadata predates `agent_directory`).
 - Determines the **deployment target** for authentication
 
-This means that for the simplest case (ADK agent on Agent Runtime), you only need to provide the Gemini Enterprise app ID:
+This means that for the simplest case (an A2A agent on Agent Runtime), you only need to provide the Gemini Enterprise app ID:
 
 ```bash
 agents-cli publish gemini-enterprise \
@@ -154,6 +160,35 @@ Agent Runtime deployments may encounter "Session not found" errors with `google-
 
 ---
 
+## Managing Agents in Agent Registry
+
+Agent Registry (Preview) is the Google Cloud fleet-wide record of your agents.
+Agents deployed to a managed runtime (Agent Runtime on Gemini Enterprise
+Agent Platform) are **auto-registered** — no extra step after `agents-cli deploy`.
+Manage them with `gcloud` (requires `roles/agentregistry.editor`):
+
+```bash
+# List / filter
+gcloud alpha agent-registry agents list --project PROJECT --location LOCATION
+gcloud alpha agent-registry agents list --filter="displayName:my-agent"
+
+# Inspect
+gcloud alpha agent-registry agents describe AGENT_NAME
+
+# Update endpoint/metadata — edit the Service resource, not the Agent
+gcloud alpha agent-registry services update AGENT_NAME \
+  --display-name "..." --description "..." \
+  --interfaces "url=ENDPOINT_URL,protocol=HTTP_JSON"
+
+# Remove: delete the underlying runtime agent (auto-registered) OR, for
+# manually registered agents, delete the Service resource
+gcloud alpha agent-registry services delete AGENT_NAME
+```
+
+Docs: https://docs.cloud.google.com/agent-registry/manage-agents
+
+---
+
 ## Troubleshooting
 
 | Issue | Solution |