google-agents-cli 1.3.0__tar.gz → 1.4.0__tar.gz

{google_agents_cli-1.3.0 → google_agents_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.3.0
+Version: 1.4.0
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -112,8 +112,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 |---------|-------------|
 | `agents-cli setup` | Install CLI + skills to coding agents |
 | `agents-cli scaffold <name>` | Create a new agent project |
-| `agents-cli eval generate` | Run agent on eval dataset, produce traces |
-| `agents-cli eval grade` | Run agent evaluations on the traces |
+| `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
 | `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
 
@@ -133,6 +132,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli install` | Install project dependencies |
 | `agents-cli lint` | Run code quality checks (Ruff) |
 | **Evaluate** | |
+| `agents-cli eval run` | Run agent inference and grade the traces |
 | `agents-cli eval generate` | Run agent inference over eval cases |
 | `agents-cli eval grade` | Grade generated traces against metrics |
 | `agents-cli eval dataset synthesize` | Synthesize multi-turn eval scenarios for your local agent |

{google_agents_cli-1.3.0 → google_agents_cli-1.4.0}/README.md

@@ -77,8 +77,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 |---------|-------------|
 | `agents-cli setup` | Install CLI + skills to coding agents |
 | `agents-cli scaffold <name>` | Create a new agent project |
-| `agents-cli eval generate` | Run agent on eval dataset, produce traces |
-| `agents-cli eval grade` | Run agent evaluations on the traces |
+| `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
 | `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
 
@@ -98,6 +97,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli install` | Install project dependencies |
 | `agents-cli lint` | Run code quality checks (Ruff) |
 | **Evaluate** | |
+| `agents-cli eval run` | Run agent inference and grade the traces |
 | `agents-cli eval generate` | Run agent inference over eval cases |
 | `agents-cli eval grade` | Grade generated traces against metrics |
 | `agents-cli eval dataset synthesize` | Synthesize multi-turn eval scenarios for your local agent |

{google_agents_cli-1.3.0 → google_agents_cli-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.3.0"
+version = "1.4.0"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"
@@ -64,6 +64,7 @@ lint = [
 ]
 
 [tool.pytest.ini_options]
+pythonpath = ["."]
 testpaths = ["tests"]
 addopts = "-s -v --ignore=tests/integration --ignore=tests/cicd"
 log_cli = true

{google_agents_cli-1.3.0 → google_agents_cli-1.4.0}/skills/google-agents-cli-adk-code/SKILL.md

@@ -6,13 +6,13 @@ description: >
   "use state management", or needs ADK (Agent Development Kit) Python API patterns
   and code examples. Part of the Google ADK skills suite.
   It provides a quick reference for agent types, tool definitions, orchestration
-  patterns, callbacks, and state management.
-  Do NOT use for creating new projects (use google-agents-cli-scaffold) or deployment
+  patterns, callbacks, state management, and reference recipes to study.
+  Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment
   (use google-agents-cli-deploy).
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.3.0
+  version: 1.4.0
   requires:
     bins:
       - agents-cli
@@ -21,18 +21,23 @@ metadata:
 
 # ADK Code Reference
 
-> **Before using this skill**, activate `/google-agents-cli-workflow` first — it contains the required development phases and scaffolding steps.
+Activate `/google-agents-cli-workflow` first for required development phases and scaffolding steps.
 
-## Prerequisites
+## 1. Study Recipes (No Project Needed)
 
-1. Run `agents-cli info` — if it shows project config, skip to the reference below
-2. If no project exists: run `agents-cli scaffold create <name>`
-3. If user has existing code: run `agents-cli scaffold enhance .`
+**Read the topic index in `references/samples.md` before answering "how do I build X".** Worked implementations exist for: sandboxed/per-user code execution, agent-loadable `SKILL.md` skills, cross-session memory, approval gates before risky actions, tool guardrails, per-user credentials, and scheduled/event-driven runs.
+
+The index only gives you a name; the recipe is the code. Clone it and read its `AGENTS.md` before you implement anything it covers. Hand-writing a Docker or E2B sandbox wrapper, a skill loader, a moderation callback or a memory store — for a capability the index lists — means you stopped at the name.
+
+## 2. Prerequisites for Writing Code
 
 Do NOT write agent code until a project is scaffolded.
 
-> **Python only for now.** This reference currently covers the Python ADK SDK.
-> Support for other languages is coming soon.
+1. Verify project: run `agents-cli info` (proceed if config exists).
+2. New project: run `agents-cli scaffold create <name>`.
+3. Existing code: run `agents-cli scaffold enhance .`.
+
+> **Language Support:** This reference covers the Python ADK SDK. Support for other languages coming soon.
 
 ## Quick Reference — Most Common Patterns
 
@@ -55,10 +60,11 @@ root_agent = Agent(
 
 ## References
 
-The first two are cheatsheets for common patterns; for broad or deep knowledge, go to the source (docs index or installed package).
+Use cheatsheets for common patterns. For deep knowledge, fetch the docs index or inspect the installed package.
 
 | Reference | When to read |
 |------|-------------|
+| `references/samples.md` | **Topic-indexed catalog of ADK reference recipes.** Read in workflow Phase 1 — before scaffolding and before writing code — maps a capability to the recipe that implements it. |
 | `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. |

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

@@ -202,7 +202,7 @@ refinement_loop = LoopAgent(
 )
 ```
 
-For a production LoopAgent with EscalationChecker, BuiltInPlanner, and grounding citations, see `/google-agents-cli-workflow` Phase 1.
+For a production LoopAgent with EscalationChecker, BuiltInPlanner, and grounding citations, look it up in the topic index in `references/samples.md`.
 
 ---
 
@@ -405,13 +405,14 @@ agent = Agent(tools=[load_web_page], ...)
 # Code execution (model-internal)
 agent = Agent(code_executor=BuiltInCodeExecutor(), ...)
 
-# Managed sandbox (Vertex AI Code Interpreter) — see /google-agents-cli-workflow Phase 1
+# Managed sandbox (Vertex AI Code Interpreter). For a per-user sandbox an agent works
+# in across sessions, this primitive is not it — see the topic index in references/samples.md
 # from google.adk.code_executors import VertexAiCodeExecutor
 # agent = Agent(code_executor=VertexAiCodeExecutor(optimize_data_file=True, stateful=True), ...)
 
 ```
 
-> **`google_search` is model-internal grounding, not a regular tool.** Mixing it with FunctionTools disables Automatic Function Calling (AFC) for all tools. If you need search alongside custom tools, consider a sub-agent architecture or a custom search function — see the [deep-search sample](https://github.com/google/adk-samples/tree/main/python/agents/deep-search) for a working pattern. For eval implications, see the eval guide's `builtin-tools-eval` reference.
+> **`google_search` is model-internal grounding, not a regular tool.** Mixing it with FunctionTools disables Automatic Function Calling (AFC) for all tools. If you need search alongside custom tools, consider a sub-agent architecture or a custom search function — see the [deep-search sample](https://github.com/google/adk-samples/tree/main/core/python/deep-search) for a working pattern. For eval implications, see the eval guide's `builtin-tools-eval` reference.
 
 ### Tool Confirmation
 
@@ -469,11 +470,11 @@ Pass `auth_scheme` + `auth_credential` from the auth helpers above for authentic
 
 ### MCP Tools
 
-Connect to MCP servers to use external tools. Use `StdioConnectionParams` for local dev, `SseConnectionParams` for production.
+Connect to MCP servers to use external tools (needs the `mcp` extra: scaffolded projects ship `google-adk[gcp,otel-gcp]`, so add `mcp` and re-sync). Use `StdioConnectionParams` for local dev, `StreamableHTTPConnectionParams` for remote HTTP servers.
 
 ```python
 from google.adk.tools.mcp_tool import McpToolset
-from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams, SseConnectionParams
+from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams, StreamableHTTPConnectionParams
 from mcp import StdioServerParameters
 
 # Local MCP server via stdio
@@ -493,9 +494,17 @@ agent = Agent(
     ...
 )
 
-# Remote MCP server via SSE (production)
+# Remote MCP server, e.g. Cloud Run with --no-allow-unauthenticated. ID tokens
+# expire in ~1h, so mint per call via `header_provider` (ADK calls it on every
+# tool call); a static `headers` dict goes stale. Audience = root, not /mcp.
+from google.auth.transport.requests import Request
+from google.oauth2.id_token import fetch_id_token
+
 McpToolset(
-    connection_params=SseConnectionParams(url="https://mcp.example.com/sse"),
+    connection_params=StreamableHTTPConnectionParams(url=f"{MCP_SERVER_URL}/mcp"),
+    header_provider=lambda ctx: {
+        "Authorization": f"Bearer {fetch_id_token(Request(), MCP_SERVER_URL)}"
+    },
 )
 ```
 
@@ -603,7 +612,7 @@ results = await memory_service.search_memory(app_name=app_name, user_id=user_id,
 
 #### Memory Bank (Long-term Memory)
 
-Managed cross-session memory that persists user preferences, remembers facts across sessions, and learns from conversations over time. See the [`memory-bank` sample](https://github.com/google/adk-samples/tree/main/python/agents/memory-bank) for a complete implementation.
+Managed cross-session memory that persists user preferences, remembers facts across sessions, and learns from conversations over time. See the [`cross-session-memory` recipe](https://github.com/google/adk-samples/tree/main/core/python/cross-session-memory) for a complete implementation.
 
 ```python
 from google.adk.agents.callback_context import CallbackContext
@@ -647,7 +656,7 @@ app = App(
 
 ### Context Compaction
 
-Prevent context overflow on long sessions by summarizing older events in a sliding window:
+Prevent context overflow on long sessions by compacting older events into summaries. Use **token-based** compaction: it triggers on actual prompt-token volume, so it handles unpredictable inputs (pasted code, large tool results) better than a fixed turn count.
 
 ```python
 from google.adk.apps import App
@@ -659,8 +668,8 @@ app = App(
     name="my_app",
     root_agent=root_agent,
     events_compaction_config=EventsCompactionConfig(
-        compaction_interval=20,  # summarize every 20 events
-        overlap_size=3,          # include last 3 events in next window for continuity
+        token_threshold=32000,   # compact once prompt tokens reach this
+        event_retention_size=5,  # keep the last 5 raw events un-compacted
         # Optional: custom summarizer model
         summarizer=LlmEventSummarizer(llm=Gemini(model="gemini-3.6-flash")),
     ),
@@ -842,7 +851,7 @@ Sessions are ephemeral by default (`InMemorySessionService`); use `DatabaseSessi
 
 Since ambient agents have no interactive user, route outputs via structured logging (JSON stdout → Cloud Logging → Cloud Monitoring alerts), Pub/Sub, or tool-based integrations (email, Jira, Slack).
 
-**Before implementing an ambient agent, clone and study the production sample** — it covers trigger wiring, middleware, structured logging, and Terraform. See the Notable Samples catalog in `/google-agents-cli-workflow` Phase 1. [Full docs](https://adk.dev/runtime/ambient-agents/).
+**Before implementing an ambient agent, clone and study the production sample** — it covers trigger wiring, middleware, structured logging, and Terraform. Look it up in the topic index in `references/samples.md`. [Full docs](https://adk.dev/runtime/ambient-agents/).
 
 ---
 
@@ -949,7 +958,7 @@ Data flows between sequential sub-agents via conversation history and `output_ke
 
 - [ADK Documentation](https://adk.dev/llms.txt)
 - [ADK Samples](https://github.com/google/adk-samples)
-- `/google-agents-cli-workflow` Phase 1 — curated production patterns (VertexAiCodeExecutor, BuiltInPlanner, grounding metadata, rate limiting, state capture)
+- `references/samples.md` — topic index of the reference recipes, and how to clone one
 
 ---
 

google_agents_cli-1.4.0/skills/google-agents-cli-adk-code/references/samples.md

@@ -0,0 +1,96 @@
+# Reference recipes
+
+Recipes live in [google/adk-samples](https://github.com/google/adk-samples). **`core/python/`** is the
+curated tier — canonical ADK patterns maintained by the agents-cli team.
+
+**Reading this page is not studying a recipe.** Every `core/` recipe ships an **`AGENTS.md`** —
+intent, a ranked "study in this order" file tour, what to copy as-is versus what is recipe-specific,
+and the gotchas. Until you have opened it you are answering from memory.
+
+**Study and adapt — don't scaffold from a recipe.**
+
+```bash
+[ -d /tmp/adk-samples ] || git clone --filter=blob:none --depth 1 --sparse \
+  https://github.com/google/adk-samples /tmp/adk-samples
+cd /tmp/adk-samples
+git sparse-checkout add core/python/<recipe>
+cat core/python/<recipe>/AGENTS.md
+```
+
+(The `--agent adk@<name>` scaffold shortcut reaches only the legacy `python/agents/` tree, not
+`core/`.)
+
+## Topic → recipe
+
+Capabilities below are **not** scaffold flags — they come from studying a recipe and adapting it.
+
+| You need | Study |
+|---|---|
+| Retrieval / search over your own documents (RAG) | `rag-agent-search` (managed ingestion) · `rag-vector-search` (custom chunking + embeddings) |
+| Running shell commands or Python on a user's behalf; a sandboxed, isolated or per-user environment or workspace | `long-horizon-harness` |
+| Agent-loadable skills — `SKILL.md` folders discovered at runtime, rebound mid-session, promoted and demoted from memory | `long-horizon-harness` |
+| Long-running autonomy — works across days, resumes, unattended, compacts context | `long-horizon-harness` |
+| Approval gate, escalation or human sign-off before a risky, high-value or irreversible action (human-in-the-loop) | `long-horizon-harness` (durable, mid-turn) · `ambient-expense-agent` (workflow pause) · `deep-search` (plan approval) |
+| Memory across conversations | `cross-session-memory` (the primitive) · `long-horizon-harness` (self-improvement loop built on it) |
+| Blocking harmful content or risky calls — moderation in one place, covering a coordinator and every sub-agent without editing them | `safety-plugins` (runner-wide plugins) · `long-horizon-harness` (per-tool guard chain + exfil detection) |
+| Per-user credentials the model must never see | `long-horizon-harness` |
+| OAuth user consent to act on a user's data | `oauth-user-consent-flow` |
+| Sub-agent delegation with isolated context windows | `long-horizon-harness` |
+| No chat interface — records or messages land on a queue and are processed automatically; event-driven, scheduled, batch or headless worker | `ambient-expense-agent` (Pub/Sub queue consumer) · `long-horizon-harness` (routines + scheduler) |
+| Iterative research with cited sources | `deep-search` |
+| Generating images or video — product photography, a model wearing the item (virtual try-on), 360° spins, background replacement — and MCP toolsets | `genmedia-for-commerce` |
+| A2A interop, incl. Gemini Enterprise client quirks | `long-horizon-harness` |
+
+In Phase 1, clone the recipes named above and read `/tmp/adk-samples/core/python/<recipe>/AGENTS.md`
+before you write any code. During Phase 0, naming them in the spec is enough — the clone waits for
+approval. A bare how-question has no spec to wait for: clone before you answer it.
+
+## The recipes
+
+These nine are the **complete** set of `core/` python recipes. If a capability isn't listed here,
+there is no core recipe for it — don't guess at a plausible name (`core/python/code-execution` and
+`core/python/human-in-the-loop` do not exist). Check `contrib/` or build it yourself.
+
+- **`long-horizon-harness`** — a complete agent *harness*: per-user sandbox, runtime-discovered `SKILL.md`
+  skills, cross-session memory with a self-improvement loop, layered tool guardrails, sub-agent delegation
+  with durable HITL, and per-user secrets. Its `AGENTS.md` maps each interface to the real function
+  that implements it, so lift one pattern without adopting the whole harness.
+  - Key files: `AGENTS.md`, `horizon/agent.py`, `horizon/fast_api_app.py`, `docs/architecture.md`, `docs/quickstart.md`
+  - Keywords: harness, sandbox, shell execution, code execution, isolated environment, long-horizon, long-running, multi-day, autonomous, resumable, compaction, guardrails, exfil, egress, approval gate, human-in-the-loop, HITL, per-user secrets, credentials, sub-agents, delegation, self-improving, memory bank, routines, scheduler, a2a, skills, model routing
+- **`rag-agent-search`** — managed document search via Agent Platform Search (Discovery Engine) with a
+  fully-managed GCS Data Connector: drop files in a bucket, no ingestion code to maintain.
+  - Key files: `AGENTS.md`, `app/agent.py`, `infra/terraform/agent_platform_search.tf`, `infra/terraform/scripts/setup_data_connector.py`
+  - Keywords: RAG, document search, Discovery Engine, Agent Platform Search, managed ingestion, GCS data connector, PDF, HTML, grounding
+- **`rag-vector-search`** — RAG with Vertex AI Vector Search 2.0 and a KFP ingestion pipeline (chunking +
+  BigQuery staging; embeddings auto-generated server-side).
+  - Key files: `AGENTS.md`, `app/agent.py`, `data_ingestion/data_ingestion_pipeline/pipeline.py`, `infra/terraform/scripts/setup_vector_search_collection.py`
+  - Keywords: RAG, retrieval, vector search, embeddings, similarity search, ScaNN, semantic search, document Q&A, ingestion pipeline, chunking
+- **`cross-session-memory`** — remembers user preferences and facts across sessions via Vertex AI Memory
+  Bank: written after each turn, recalled at the start of a later one.
+  - Key files: `AGENTS.md`, `app/app_utils/memory_config.py`, `app/agent.py`, `app/fast_api_app.py`
+  - Keywords: memory, cross-session, recall, remember, preferences, Memory Bank, PreloadMemoryTool
+- **`oauth-user-consent-flow`** — reads a user's Google Drive on their behalf behind an OAuth 2.0 consent
+  flow; the same code path works in local ADK Web and in production Gemini Enterprise.
+  - Key files: `AGENTS.md`, `app/auths.py`, `app/tools.py`, `tools/register_oauth.py`
+  - Keywords: OAuth, user consent, authentication, Google Drive, Workspace, Agent Runtime, Gemini Enterprise
+- **`ambient-expense-agent`** — no chat loop: Pub/Sub events drive a graph-based `Workflow`, business
+  rules stay in code, and only high-value cases reach an LLM that pauses for human approval.
+  - Key files: `AGENTS.md`, `expense_agent/agent.py`, `expense_agent/fast_api_app.py`, `terraform/pubsub.tf`
+  - Keywords: ambient, event-driven, scheduled, cron, Pub/Sub, workflow, human-in-the-loop, approval, alerts, no UI
+- **`deep-search`** — research agent that plans (with an approval step), loops search → critique → refine
+  until a quality bar is met, then writes a report with inline citations.
+  - Key files: `AGENTS.md`, `app/agent.py`, `app/config.py`, `frontend/src/App.tsx`
+  - Keywords: research, citations, iterative, critique, grounding, multi-agent, human-in-the-loop, web search, report
+- **`safety-plugins`** — runner-wide safety guardrails as ADK `BasePlugin`s: attached to the `Runner`, they
+  wrap every agent and sub-agent beneath it and keep harmful content out of session state.
+  - Key files: `AGENTS.md`, `safety_plugins/plugins/model_armor.py`, `safety_plugins/plugins/agent_as_a_judge.py`, `safety_plugins/main.py`
+  - Keywords: safety, guardrails, harmful content, moderation, content filtering, Model Armor, LLM-as-a-judge, session poisoning, plugins, runner-wide, applies to all sub-agents
+- **`genmedia-for-commerce`** — full-stack multi-agent retail media: virtual try-on, 360° product spins and
+  background swaps, orchestrated through an MCP tool server and Veo pipelines.
+  - Key files: `AGENTS.md`, `genmedia4commerce/mcp_server/server.py`, `genmedia4commerce/workflows/shared/vector_search.py`, `genmedia4commerce/agent.py`
+  - Keywords: MCP, media, image generation, video generation, product photography, on-model imagery, virtual try-on, 360° spin, background replacement, Veo, retail, e-commerce, catalogue, full-stack, React, Gemini Enterprise
+
+**Nothing above matches?** [`contrib/`](https://github.com/google/adk-samples/tree/main/contrib) holds
+community- and partner-contributed recipes — broader in scope (complete solutions, not isolated patterns)
+and not curated by the agents-cli team, so there is no guaranteed `AGENTS.md` to guide the lift. Check
+there when you need something specific `core/` doesn't cover.

{google_agents_cli-1.3.0 → google_agents_cli-1.4.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, or awareness of Agent Gateway.
+  Cloud Run, or GKE deployment targets, or binding an agent to an 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.3.0
+  version: 1.4.0
   requires:
     bins:
       - agents-cli
@@ -63,7 +63,7 @@ All three targets are container-based, so any language works.
 
 > **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 the `/google-agents-cli-workflow` sample catalog (Phase 1).
+> **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. For a worked example, look up OAuth user consent in the topic index in `/google-agents-cli-adk-code` → `references/samples.md`.
 
 ---
 
@@ -74,7 +74,7 @@ All three targets are container-based, so any language works.
 **Task tracking:** Deployment involves multiple sequential steps (infra setup, CI/CD configuration, deploy, verification). Use a task list to track progress through these steps — skipping one often causes failures in later steps that are hard to trace back.
 
 1. If prototype (no deployment target), first enhance: `agents-cli scaffold enhance . --deployment-target <target>`
-2. **Notify the human**: "Eval scores meet thresholds and tests pass. Ready to deploy to dev?"
+2. **Notify the human**: paste the eval scores and test results, then ask "Ready to deploy to dev?"
 3. **Wait for explicit approval**
 4. Once approved: `agents-cli deploy`
 
@@ -110,6 +110,8 @@ agents-cli infra single-project
 | `--dns-peering-domain` | DNS peering domain suffix, e.g. `my-internal.corp.` (requires `--network-attachment`) | Agent Runtime |
 | `--dns-peering-project` | Project ID hosting the Cloud DNS managed zone for DNS peering (requires `--network-attachment`) | Agent Runtime |
 | `--dns-peering-network` | VPC network name in the target project for DNS peering (requires `--network-attachment`) | Agent Runtime |
+| `--agent-gateway-egress` | Bind the agent to an [Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview) governing outbound traffic. Full resource name of a gateway with `governedAccessPath=AGENT_TO_ANYWHERE`. Empty value unbinds; omit to leave unchanged. See [Agent Gateway](#agent-gateway) | Agent Runtime |
+| `--agent-gateway-ingress` | Bind the agent to an Agent Gateway governing inbound traffic. Full resource name of a gateway with `governedAccessPath=CLIENT_TO_AGENT`. Empty value unbinds; omit to leave unchanged | Agent Runtime |
 | `--memory` | Memory limit (default: `4Gi`) | Agent Runtime, Cloud Run |
 | `--cpu` | CPU limit (default: `1`) | Agent Runtime, Cloud Run |
 | `--min-instances` | Minimum number of instances (default: `1`) | Agent Runtime, Cloud Run |
@@ -164,7 +166,7 @@ For the full CI/CD pipeline setup guide — prerequisites, `infra cicd` flags, r
 
 For detailed infrastructure configuration (scaling defaults, Dockerfile, FastAPI endpoints, session types, networking), see `references/cloud-run.md`. For ADK docs on Cloud Run deployment, fetch `https://adk.dev/deploy/cloud-run/index.md`.
 
-For event-driven / ambient agent deployment on Cloud Run, see the [`ambient-expense-agent`](https://github.com/google/adk-samples/tree/main/python/agents/ambient-expense-agent) sample and `/google-agents-cli-adk-code` (`references/adk-python.md`, section "12. Event-Driven / Ambient Agents") for the `trigger_sources` pattern.
+For event-driven / ambient agent deployment on Cloud Run, see the [`ambient-expense-agent`](https://github.com/google/adk-samples/tree/main/core/python/ambient-expense-agent) sample and `/google-agents-cli-adk-code` (`references/adk-python.md`, section "12. Event-Driven / Ambient Agents") for the `trigger_sources` pattern.
 
 ---
 
@@ -172,7 +174,7 @@ For event-driven / ambient agent deployment on Cloud Run, see the [`ambient-expe
 
 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`. Query via the Python `vertexai.Client` SDK.
+> **No `gcloud` CLI exists for Agent Runtime.** Deploy via `agents-cli deploy`. Query via the Python `agentplatform.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`:
 
@@ -360,22 +362,49 @@ For registering deployed agents with Gemini Enterprise, see `/google-agents-cli-
 
 ---
 
-## Agent Gateway & Semantic Governance (Gemini Enterprise Agent Platform)
+## Agent Gateway
 
-> **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).
+> **Note:** There are no `agents-cli` commands for creating or managing Agent Gateways or
+> Semantic Governance policies — set those up separately (via Terraform or the Cloud Console).
+> `agents-cli deploy` is the only gateway-aware command, and its support is a passthrough: it
+> binds the agent to an *existing* gateway as part of the Agent Runtime create/update call.
 
 **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:
+connectivity (ingress/egress). It is not a deployment target.
 
-- **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.
+To set up a gateway, follow [Set up an Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/set-up-agent-gateway)
+and [Route Agent Runtime traffic through Agent Gateway](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-gateway-runtime-deploy). You may also 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).
+
+Once a gateway exists, `agents-cli deploy` binds an agent to it with `--agent-gateway-egress`
+and/or `--agent-gateway-ingress`, each taking a full resource name
+(`projects/PROJECT/locations/REGION/agentGateways/GATEWAY`). Only Agent Runtime deployment is
+supported, and the agent must have Agent Identity (the `--agent-identity` flag), which can only
+be set when the agent is created.
+
+An egress gateway performs TLS decryption and inspection on outbound agent communications,
+so the image must trust the gateway's root CA. That setup is opt-in at scaffold time. If you're
+creating a new project, pass `--agent-gateway` flag to `agents-cli create`:
+
+```bash
+agents-cli create my-agent -d agent_runtime --agent-gateway
+```
+
+Alternatively, you can pass the same flag to `agents-cli scaffold enhance` to upgrade an
+existing project:
+```bash
+agents-cli scaffold enhance . --agent-gateway
+```
+
+Either writes a Dockerfile that consumes the `AGENT_GATEWAY_ROOT_CERTIFICATES` build arg the
+platform injects, and records `agent_gateway: true` under `create_params` so `scaffold upgrade`
+keeps it. Deploying with `--agent-gateway-egress` against a Dockerfile that lacks the build arg
+fails with a pointer to the command above; `--no-agent-gateway` removes the setup again.
 
 Background: [Agent Gateway overview](https://docs.cloud.google.com/gemini-enterprise-agent-platform/govern/gateways/agent-gateway-overview).
 
+## Semantic Governance
+
 **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.

{google_agents_cli-1.3.0 → google_agents_cli-1.4.0}/skills/google-agents-cli-deploy/references/agent-runtime.md

@@ -18,7 +18,7 @@ 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
+routes under `/a2a/{app_name}` (JSON-RPC + agent card), 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
@@ -106,9 +106,9 @@ agents-cli run --url https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJ
 To query Agent Runtime programmatically:
 
 ```python
-import vertexai
+import agentplatform
 
-client = vertexai.Client(location="us-east1")
+client = agentplatform.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"):
@@ -125,7 +125,7 @@ Environment variables set during deployment come from `agents-cli deploy` (the C
 
 ### 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.
+To enable cross-session memory on Agent Runtime, configure `memory_bank_config` via `context_spec`. See the [`cross-session-memory` recipe](https://github.com/google/adk-samples/tree/main/core/python/cross-session-memory) for the full pattern.
 
 ## Networking (PSC Interface)
 

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

@@ -16,7 +16,7 @@ Scaffolded projects include a `Dockerfile` using single-stage build with `uv` fo
 
 ## FastAPI Endpoints
 
-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`.
+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). Exact routes vary by template; check `app/fast_api_app.py`.
 
 ## Session Types
 

{google_agents_cli-1.3.0 → google_agents_cli-1.4.0}/skills/google-agents-cli-deploy/references/gke.md

@@ -50,7 +50,7 @@ Cloud SQL in GKE uses a **proxy sidecar container** in the pod (unlike Cloud Run
 
 ## FastAPI Endpoints
 
-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`.
+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). Exact routes vary by template; check `app/fast_api_app.py`.
 
 ## Testing Your Deployed Agent
 

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

@@ -35,12 +35,12 @@ Beyond the `run --url` quick test above, you can query the deployment directly.
 **Option 1: Python Script**
 ```python
 import json
-import vertexai
+import agentplatform
 
 with open("deployment_metadata.json") as f:
     engine_id = json.load(f)["remote_agent_runtime_id"]
 
-client = vertexai.Client(location="us-east1")
+client = agentplatform.Client(location="us-east1")
 agent = client.agent_engines.get(name=engine_id)
 
 async for event in agent.async_stream_query(message="Hello!", user_id="test"):