google-agents-cli 0.5.1__tar.gz → 0.6.1__tar.gz

{google_agents_cli-0.5.1 → google_agents_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 0.5.1
+Version: 0.6.1
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -55,7 +55,7 @@ Turn your favorite coding assistant into an expert at building and deploying age
 **Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
 
 **Works seamlessly with:**
-[Gemini CLI](https://github.com/google-gemini/gemini-cli) &nbsp;•&nbsp; [Claude Code](https://docs.anthropic.com/en/docs/claude-code) &nbsp;•&nbsp; [Codex](https://github.com/openai/codex) &nbsp;•&nbsp; [Antigravity](https://antigravity.google/) &nbsp;•&nbsp; *and any other coding agent.*
+[Antigravity CLI](https://antigravity.google/) &nbsp;•&nbsp; [Claude Code](https://docs.anthropic.com/en/docs/claude-code) &nbsp;•&nbsp; [Codex](https://github.com/openai/codex) &nbsp;•&nbsp; *and any other coding agent.*
 
 ## Get Started
 
@@ -78,7 +78,7 @@ npx skills add google/agents-cli
 
 ### 2. Open your coding agent
 
-Launch [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or any coding agent you prefer.
+Launch [Antigravity CLI](https://antigravity.google/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or any coding agent you prefer.
 
 ### 3. Build your first agent
 
@@ -170,7 +170,7 @@ The Google Cloud agent stack that `agents-cli` builds on:
 
 ## FAQ
 
-**Is this an alternative to Gemini CLI, Claude Code, or Codex?**<br>
+**Is this an alternative to Antigravity CLI, Claude Code, or Codex?**<br>
 No. **`agents-cli` is a tool *for* coding agents, not a coding agent itself.** It provides the CLI commands and skills that make your coding agent better at building, evaluating, and deploying ADK agents on Google Cloud.
 
 **How is this different from just using `adk` directly?**<br>

{google_agents_cli-0.5.1 → google_agents_cli-0.6.1}/README.md

@@ -22,7 +22,7 @@ Turn your favorite coding assistant into an expert at building and deploying age
 **Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
 
 **Works seamlessly with:**
-[Gemini CLI](https://github.com/google-gemini/gemini-cli)  •  [Claude Code](https://docs.anthropic.com/en/docs/claude-code)  •  [Codex](https://github.com/openai/codex)  •  [Antigravity](https://antigravity.google/)  •  *and any other coding agent.*
+[Antigravity CLI](https://antigravity.google/)  •  [Claude Code](https://docs.anthropic.com/en/docs/claude-code)  •  [Codex](https://github.com/openai/codex)  •  *and any other coding agent.*
 
 ## Get Started
 
@@ -45,7 +45,7 @@ npx skills add google/agents-cli
 
 ### 2. Open your coding agent
 
-Launch [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or any coding agent you prefer.
+Launch [Antigravity CLI](https://antigravity.google/), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or any coding agent you prefer.
 
 ### 3. Build your first agent
 
@@ -137,7 +137,7 @@ The Google Cloud agent stack that `agents-cli` builds on:
 
 ## FAQ
 
-**Is this an alternative to Gemini CLI, Claude Code, or Codex?**<br>
+**Is this an alternative to Antigravity CLI, Claude Code, or Codex?**<br>
 No. **`agents-cli` is a tool *for* coding agents, not a coding agent itself.** It provides the CLI commands and skills that make your coding agent better at building, evaluating, and deploying ADK agents on Google Cloud.
 
 **How is this different from just using `adk` directly?**<br>

{google_agents_cli-0.5.1 → google_agents_cli-0.6.1}/pyproject.toml

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

{google_agents_cli-0.5.1 → google_agents_cli-0.6.1}/skills/google-agents-cli-adk-code/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.5.1
+  version: 0.6.1
   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.1 → google_agents_cli-0.6.1}/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.1 → google_agents_cli-0.6.1}/skills/google-agents-cli-deploy/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.5.1
+  version: 0.6.1
   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.1/skills/google-agents-cli-deploy/references/agent-runtime.md

@@ -0,0 +1,130 @@
+# 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 and `run` constructs for `--mode a2a` against an Agent Runtime URL — both
+authenticate with your Google credentials. On Agent Runtime, `publish` registers
+with **ADK** (`:streamQuery` against the reasoning-engine resource name), not
+this card URL.
+
+## 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` (reads the runtime ID for the default ADK registration on Agent Runtime, and constructs the A2A card URL only when A2A registration is explicitly chosen). 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.1 → google_agents_cli-0.6.1}/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.1 → google_agents_cli-0.6.1}/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.1 → google_agents_cli-0.6.1}/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.1 → google_agents_cli-0.6.1}/skills/google-agents-cli-eval/SKILL.md

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

{google_agents_cli-0.5.1 → google_agents_cli-0.6.1}/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.1 → google_agents_cli-0.6.1}/skills/google-agents-cli-observability/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.5.1
+  version: 0.6.1
   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.1 → google_agents_cli-0.6.1}/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.1 → google_agents_cli-0.6.1}/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.1 → google_agents_cli-0.6.1}/skills/google-agents-cli-publish/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.5.1
+  version: 0.6.1
   requires:
     bins:
       - agents-cli
@@ -30,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
 
@@ -40,35 +40,31 @@ metadata:
 
 ## Registration Modes
 
-### ADK Registration (default)
+### A2A Registration (Cloud Run / GKE)
 
-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. A2A is the default — and only — registration type on **Cloud Run** and **GKE**, which have no reasoning engine, so Gemini Enterprise registers them over A2A. 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 Cloud Run / GKE
 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://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. For Agent Runtime, use ADK registration (below).
+
+### ADK Registration (default on Agent Runtime)
 
-For agents using the Agent-to-Agent protocol. Requires an agent card URL — the command fetches the card and registers it.
+This is the **default and recommended registration for Agent Runtime** deployments: Gemini Enterprise invokes the agent natively via `:streamQuery` on its reasoning engine resource, authenticating end-to-end. It's also the path to use when the agent needs an OAuth authorization (`--authorization-id`). The agent is registered directly via its reasoning engine resource name; no agent card URL is needed.
 
 ```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"
 ```
 
 ---
@@ -121,9 +117,9 @@ 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 `adk` on Agent Runtime, `a2a` on Cloud Run / GKE) |
 | `--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) |
+| `--deployment-target` | `DEPLOYMENT_TARGET` | `agent_runtime`, `cloud_run`, or `gke` (sets the default registration type — ADK on Agent Runtime, A2A on Cloud Run / GKE — and the A2A auth method) |
 | `--project-id` | `GOOGLE_CLOUD_PROJECT` | GCP project ID for billing |
 | `--project-number` | `PROJECT_NUMBER` | GCP project number (used for Gemini Enterprise lookup) |
 | `--authorization-id` | `GEMINI_AUTHORIZATION_ID` | OAuth authorization resource name |
@@ -138,11 +134,10 @@ 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 **ADK** (native `:streamQuery`) on **Agent Runtime**, and **A2A** on **Cloud Run / GKE** (which have no reasoning engine). Override with `--registration-type`.
 - 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 agent on Agent Runtime, registered as ADK), you only need to provide the Gemini Enterprise app ID:
 
 ```bash
 agents-cli publish gemini-enterprise \