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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.3.0
+Version: 1.3.1
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11

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

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.3.0"
+version = "1.3.1"
 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.3.1}/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.3.1
   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.3.1}/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
 
@@ -603,7 +604,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
@@ -842,7 +843,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 +950,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.3.1/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.3.1}/skills/google-agents-cli-deploy/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.3.0
+  version: 1.3.1
   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`.
 
 ---
 
@@ -164,7 +164,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.
 
 ---
 

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

@@ -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.3.1}/skills/google-agents-cli-eval/SKILL.md

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

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/skills/google-agents-cli-observability/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.3.0
+  version: 1.3.1
   requires:
     bins:
       - agents-cli

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/skills/google-agents-cli-publish/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.3.0
+  version: 1.3.1
   requires:
     bins:
       - agents-cli

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/skills/google-agents-cli-scaffold/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.3.0
+  version: 1.3.1
   requires:
     bins:
       - agents-cli
@@ -39,7 +39,7 @@ Use the `agents-cli` CLI to create new ADK agent projects or enhance existing on
 
 | Choice | CLI flag |
 |--------|----------|
-| RAG (vector or document search) | Not a scaffold flag — clone-and-study `rag-vector-search` / `rag-agent-search` (see `/google-agents-cli-workflow` Phase 1) |
+| Retrieval/RAG, sandboxed execution, cross-session memory, OAuth consent, guardrails, scheduled runs | **No flag** — these come from clone-and-study recipes; see the topic index in `/google-agents-cli-adk-code` → `references/samples.md` |
 | A2A protocol | built into every ADK agent — scaffold normally (`--agent adk`) |
 | Prototype (no deployment) | `--prototype` |
 | Deployment target | `--deployment-target <agent_runtime\|cloud_run\|gke>` |
@@ -52,7 +52,10 @@ Older names → CLI values (`vertexai` SDK package name unchanged):
 
 - Agent Engine / Vertex AI Agent Engine → `--deployment-target agent_runtime`
 - Agent Engine sessions / Agent Platform Sessions → `--session-type agent_platform_sessions`
-- Vertex AI Search / Vertex AI Vector Search / RAG → clone-and-study recipe, not a flag (see `/google-agents-cli-workflow` Phase 1)
+- Vertex AI Search / Vertex AI Vector Search / RAG → clone-and-study recipe, not a flag
+
+> **Removed flags.** `--datastore`, the `agentic_rag` template, and `agents-cli infra datastore` /
+> `agents-cli data-ingestion` no longer exist. If you reach for one, you want a recipe instead.
 
 ---
 
@@ -124,9 +127,9 @@ agents-cli scaffold enhance . --cicd-runner github_actions
 |----------|------------|-------------|
 | `adk` | Agent Runtime, Cloud Run, GKE | Standard ADK agent (default); A2A protocol built in |
 
-> **RAG is a clone-and-study recipe, not a template.** Build it by studying `rag-vector-search` or
-> `rag-agent-search` and adapting the sample into your project — see `/google-agents-cli-workflow`
-> Phase 1.
+> **`adk` is the only template.** Capabilities beyond it — retrieval, sandboxed execution, memory,
+> OAuth, guardrails — are clone-and-study recipes, not templates. See the topic index in
+> `/google-agents-cli-adk-code` → `references/samples.md`.
 
 ---
 
@@ -166,11 +169,9 @@ After scaffolding, immediately load `/google-agents-cli-workflow` — it contain
 **Key files to customize:** `app/agent.py` (instruction, tools, model), `app/tools.py` (custom tool functions), `.env` (project ID, location, API keys).
 **Files to preserve:** `agents-cli-manifest.yaml` (CLI reads this), deployment configs under `deployment/`, `Makefile`, `app/__init__.py` (the `App(name=...)` must match the directory name — default `app`), and the generated runtime/A2A infra (`app/fast_api_app.py`, `app/app_utils/a2a.py`, `app/app_utils/services.py`, `Dockerfile`) — these wire up serving, sessions, and the built-in A2A surface; don't hand-edit them.
 
-**RAG projects — clone-and-study, not a template:**
-RAG isn't a scaffold option. Build it by studying `rag-vector-search` or `rag-agent-search` (see
-`/google-agents-cli-workflow` Phase 1) and adapting the sample's `app/`, `infra/terraform/`, and
-ingestion into your project. Provisioning and ingestion run from the sample's own `Makefile`
-(`make setup-infra`, `make data-ingestion`).
+**Adapting a recipe:** copy its `app/`, `infra/terraform/`, and any ingestion or provisioning into
+your scaffolded project, then run provisioning from the recipe's own `Makefile` (e.g.
+`make setup-infra`). Start from its `AGENTS.md`.
 
 **Verifying your agent works:** Use `agents-cli run "test prompt"` for quick smoke tests, then `agents-cli eval generate` and `agents-cli eval grade` for systematic validation. Do NOT write pytest tests that assert on LLM response content — that belongs in eval.
 

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/skills/google-agents-cli-scaffold/references/flags.md

@@ -4,7 +4,7 @@
 
 | Flag | Short | Default | Description |
 |------|-------|---------|-------------|
-| `--agent` | `-a` | `adk` | Agent template — local name (e.g. `adk`), local path (`local@/path`), adk-samples shortcut (`adk@deep-search`), or remote Git URL |
+| `--agent` | `-a` | `adk` | Agent template — local name (e.g. `adk`), local path (`local@/path`), adk-samples shortcut (`adk@<name>`, legacy `python/agents/` tree only), or remote Git URL |
 | `--deployment-target` | `-d` | `agent_runtime` | Deployment target (`agent_runtime`, `cloud_run`, `gke`, `none`) |
 | `--region` | | `us-east1` | GCP region |
 | `--prototype` | `-p` | off | Skip CI/CD and Terraform (recommended for first pass) |

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/skills/google-agents-cli-workflow/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.3.0
+  version: 1.3.1
   requires:
     bins:
       - agents-cli
@@ -26,8 +26,8 @@ metadata:
 > **Before writing agent code, make sure a scaffolded project exists (see Phase 2).** Skipping scaffolding loses eval boilerplate, CI/CD config, and project conventions.
 
 
-> Requires: google-agents-cli ~= 1.3.0
-> If version is behind, run: uv tool install "google-agents-cli~=1.3.0"
+> Requires: google-agents-cli ~= 1.3.1
+> If version is behind, run: uv tool install "google-agents-cli~=1.3.1"
 
 > Check version: agents-cli info
 > [Install uv](https://docs.astral.sh/uv/getting-started/installation/index.md) first if needed.
@@ -39,7 +39,7 @@ Re-read the relevant skill **before** each phase — not after you've already st
 | Phase | Skill | When to load |
 |-------|-------|--------------|
 | 0 — Understand | — | No skill needed — read `.agents-cli-spec.md` if present, else clarify goals with the user |
-| 1 — Study samples | — | Check the Notable Samples catalog in `references/samples.md` — clone and study matching samples before scaffolding |
+| 1 — Study recipes | `/google-agents-cli-adk-code` | **Load it during design** — its `references/samples.md` topic index maps a need to the recipe that implements it. Yes, this early: the catalog lives there. |
 | 2 — Scaffold | `/google-agents-cli-scaffold` | Before creating or enhancing a project |
 | 3 — Build | `/google-agents-cli-adk-code` | Before writing agent code — API patterns, tools, callbacks, state |
 | 4 — Evaluate | `/google-agents-cli-eval` | Before running any eval — dataset schema, metrics, eval-fix loop |
@@ -85,10 +85,10 @@ Do NOT proceed to planning, scaffolding, or coding until the user approves the s
 
 **Ask based on context:**
 
-- If the agent needs **retrieval/search over data** (RAG, semantic/vector search, embeddings) → RAG is a **clone-and-study recipe**, not a scaffold flag. In Phase 1, study `rag-vector-search` (embeddings / similarity search) or `rag-agent-search` (managed document search) from `references/samples.md` and adapt one into your project.
+- If the agent needs a **capability the scaffold doesn't ship** — retrieval over your data, sandboxed code execution, memory across sessions, OAuth consent, safety guardrails, event-driven triggers — that capability comes from a **clone-and-study recipe**, not a scaffold flag. Look the need up in the topic index in `/google-agents-cli-adk-code` → `references/samples.md` and study the matching recipe in Phase 1.
 - If agent should be **available to other agents** → **A2A protocol** is built into every Python agent scaffolded by agents-cli; no separate choice needed — just scaffold normally.
 - If **full deployment** chosen → **CI/CD runner?** GitHub Actions (default) or Google Cloud Build?
-- If agent should **remember user preferences or facts across sessions** → **Memory Bank?** Long-term memory across conversations. See `/google-agents-cli-adk-code`.
+- If agent should **remember user preferences or facts across sessions** → long-term memory across conversations. Load `/google-agents-cli-adk-code` — it has both the recipe (in `references/samples.md`) and the ADK memory API details.
 - If **Cloud Run** or **GKE** chosen → **Session storage?** In-memory (default), Cloud SQL (persistent), or Agent Platform Sessions (managed).
 - If **deployment with CI/CD** chosen → **Git repository?** Does one already exist, or should one be created? If creating, public or private?
 
@@ -96,15 +96,27 @@ Once the design is agreed, write the spec to `.agents-cli-spec.md` using the tem
 
 Once you have a clear understanding, proceed to **Phase 1**.
 
-## Phase 1: Study Reference Samples
+## Phase 1: Study Reference Recipes
 
-Ask yourself: is there a sample that can help me design this and cut time? Scan the keyword-indexed catalog in `references/samples.md` — it lists the samples and how to clone one. Multiple samples can match — clone and study all that are relevant.
+> **Trigger.** If the request involves any of: searching your
+> own documents · running shell or Python code on a user's behalf · a sandboxed or isolated per-user
+> environment · loading skills the agent picks up at runtime · work that spans days, resumes, or runs
+> unattended · remembering across conversations · approving a risky action before it executes ·
+> blocking harmful content or moderating what agents say · acting with a user's own API keys or
+> credentials · OAuth consent to reach a user's own data · delegating to sub-agents with isolated
+> context · speaking A2A to other agents · reacting to events or a schedule · researching a topic
+> online and reporting it with citations · generating images or video — then a recipe already
+> implements it. Look it up **before you commit to an implementation.**
+>
+> This list covers the same capabilities as the topic index in `/google-agents-cli-adk-code` → `references/samples.md`. If you extend one, extend the other.
 
-If no sample matches, proceed to Phase 2. But first — are you sure? Re-read the user's request and compare it against the sample catalog in `references/samples.md`. Skipping a matching sample means rebuilding patterns that already exist.
+**Load `/google-agents-cli-adk-code` now** — the catalog lives there, at `references/samples.md`. Load it even though nothing is scaffolded and you are not writing code yet; "wrong phase for the code skill" is the rationalisation that makes agents skip this step, and that skill's *Prerequisites for writing code* does not apply to you. Look each capability the design calls for up in its **topic index**. It maps needs (retrieval, sandboxed execution, memory, approval gates, guardrails, per-user credentials, scheduling) to the recipe that teaches them, and shows how to clone one. Multiple recipes can match — clone and study all that are relevant, starting with each one's `AGENTS.md`.
 
-> **IMPORTANT — Exit criteria:** After studying a sample, ask yourself: can I apply anything from this sample to help me deliver the design? Note what you'll reuse before moving on. Do NOT proceed until you've answered this.
+If no recipe matches, proceed to Phase 2. But first — are you sure? Re-read the user's request and re-check the topic index in `/google-agents-cli-adk-code`. Skipping a matching recipe means rebuilding patterns that already exist, usually worse.
 
-> **This list is useful at any phase** — revisit it when you hit deployment, publishing, or infrastructure questions. A sample's Terraform or registration pattern may be exactly what you need later.
+> **IMPORTANT — Exit criteria:** After studying a recipe, ask yourself: can I apply anything from it to help me deliver the design? Note what you'll reuse before moving on. Do NOT proceed until you've answered this.
+
+> **This catalog is useful at any phase** — revisit it when you hit deployment, publishing, or infrastructure questions. A recipe's Terraform or registration pattern may be exactly what you need later.
 
 ## Phase 2: Scaffold (if needed)
 
@@ -130,12 +142,12 @@ For ADK API patterns and code examples, use `/google-agents-cli-adk-code`.
 
 > **Smoke-test only here — do not write behavioral pytest.** LLM output is non-deterministic; behavioral checks belong in eval (Phase 4), not pytest. Use `agents-cli run "prompt"` for quick checks.
 
-### Provision a datastore (RAG, if the agent uses one)
+### Provision recipe infrastructure (if you adapted one)
 
-RAG is a clone-and-study recipe (Phase 1). Datastore provisioning and ingestion live in the sample's
-own `Makefile` (e.g. `make setup-infra`, `make data-ingestion`) and its `README.md` / `AGENTS.md` —
-follow those, adapting the sample's `infra/terraform/` and `.env` into your project. (The former
-`agents-cli infra datastore` / `agents-cli data-ingestion` commands have been removed.)
+A recipe that needs backing infrastructure (a datastore, an index, a sandbox, a queue) ships its own
+provisioning: follow its `Makefile` (e.g. `make setup-infra`, `make data-ingestion`) and its
+`AGENTS.md` / `README.md`, adapting the recipe's `infra/terraform/` and `.env` into your project.
+`agents-cli` has no command for this.
 
 ## Phase 4: Evaluate
 
@@ -197,6 +209,7 @@ Agents routinely skip steps with plausible-sounding excuses. Recognize these and
 | "The user's request is clear enough, no need to clarify" | You're guessing at requirements. Phase 0 exists to confirm intent before scaffolding — even one question can prevent a full rework. |
 | "The agent responded correctly in `agents-cli run`, so eval isn't needed" | One prompt is not a test suite. Eval catches regressions, edge cases, and tool trajectory issues that a single run never will. |
 | "I'll use a newer/better model" | The scaffolded model was chosen deliberately. Changing it without being asked violates code preservation (Principle 1) and often breaks things — wrong location, deprecated version, or 404. Your training data is likely out of date — rely on the skills and the model listing command, not your knowledge of model names. |
+| "I already know how to build this — sandbox, memory, approval gates" | You are about to reinvent a recipe, worse. These capabilities are already implemented and battle-tested in `/google-agents-cli-adk-code` → `references/samples.md`; check the topic index and open the matching recipe's `AGENTS.md` before designing anything custom. |
 | "I can skip the scaffold and set up manually" | Manual setup misses eval boilerplate, CI/CD config, and project configuration manifest conventions. Use `agents-cli create` even for quick experiments. |
 
 ## Principle 1: Code Preservation & Isolation
@@ -291,7 +304,6 @@ When you need specific infrastructure files (Terraform, CI/CD, Dockerfile) but d
 | File | Contents |
 |------|----------|
 | `references/internals.md` | Underlying tools and commands that `agents-cli` wraps (adk, pytest, ruff, uvicorn) |
-| `references/samples.md` | Keyword-indexed catalog of ADK reference samples to study before scaffolding |
 | `references/spec-template.md` | `.agents-cli-spec.md` template and optional sections |
 | `references/brainstorming.md` | Phase 0 design-dialogue playbook (one-at-a-time Q&A, approaches, gates) |
 | `references/terminology.md` | Product-name → CLI-value mapping |

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/skills/google-agents-cli-workflow/references/brainstorming.md

@@ -5,8 +5,10 @@ Turn the user's idea into an agreed `.agents-cli-spec.md` through a collaborativ
 
 ## HARD-GATE
 
-Do NOT study samples, scaffold, run `agents-cli create`, or write any code until the user has
-approved the spec. This applies even to "obvious" agents — unexamined assumptions cause the most
+Do NOT clone a sample, scaffold, run `agents-cli create`, or write any code until the user has
+approved the spec. **Reading the recipe index is exempt** — it is not "studying a sample". Scan it
+before your first reply and name any matching recipe there, even when that reply is only a
+clarifying question. This applies even to "obvious" agents — unexamined assumptions cause the most
 wasted work.
 
 ## Scale to complexity
@@ -43,8 +45,8 @@ spec body**. Always check the axes users most often leave implicit: **data sourc
 schedule/cadence, and which model.**
 
 Non-interactive ≠ skip the thinking. For non-trivial agents you must still record the approaches you
-weighed and the one you chose, flag oversized scope, and route any retrieval need to the RAG recipe —
-then commit to a design. The user-review gate is how they catch a wrong assumption.
+weighed and the one you chose, flag oversized scope, and route any capability the scaffold doesn't
+ship to its recipe (`/google-agents-cli-adk-code` → `references/samples.md`) — then commit to a design. The user-review gate is how they catch a wrong assumption.
 
 ## Propose 2–3 approaches (non-trivial agents)
 
@@ -56,12 +58,13 @@ or override. Typical axes:
 - **Single-agent vs multi-agent / orchestration** — one agent with tools, or a coordinator delegating
   to sub-agents.
 - **Tool / integration choices** — which APIs or data sources, and how auth is handled.
-- **Retrieval / RAG** — if any capability is "search / look up over our docs, incidents, tickets, or
-  knowledge base", that is retrieval: route it to the `rag-vector-search` / `rag-agent-search`
-  clone-and-study recipes and list the recipe in the spec's Reference Samples (RAG is not a scaffold
-  flag, and is never a removed `agentic_rag` template / `--datastore` / `infra datastore`). Don't
-  silently downgrade a stated retrieval need to a plain tool call, and flag retrieval even when it's
-  deferred to a later phase.
+- **Capabilities the scaffold doesn't ship** — retrieval ("search / look up over our docs, incidents,
+  tickets, or knowledge base"), sandboxed shell or code execution, memory across sessions, approval
+  gates before risky actions, OAuth consent, safety guardrails, event-driven or scheduled runs. Each
+  is a **clone-and-study recipe, never a scaffold flag**: look the need up in the topic index in
+  `/google-agents-cli-adk-code` → `references/samples.md` and list every matching recipe in the spec's
+  Reference Samples, to study in Phase 1. Don't silently downgrade a stated need to a plain tool
+  call, and flag it even when it's deferred to a later phase.
 - **Deployment shape** — prototype-first (recommended) vs a deployment target.
 
 ## Present the design in sections

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/skills/google-agents-cli-workflow/references/spec-template.md

@@ -19,7 +19,10 @@ Specific rules — not just generic statements.
 Measurable outcomes for evaluation.
 
 ## Reference Samples
-Check the Notable Samples in Phase 1 — list any that match this use case.
+Recipes to study in Phase 1, from the topic index (`/google-agents-cli-adk-code` →
+`references/samples.md`). List every one that looks relevant — several is normal and better than
+guessing at one.
+- `core/python/<recipe>` — <what you expect to take from it>
 ```
 
 Optional sections for more detailed specs: **Edge Cases to Handle**, **Architecture & Sub-Agents**, **Data Sources & Auth**, **Non-Functional Requirements**.

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/skills/google-agents-cli-workflow/references/terminology.md

@@ -6,6 +6,6 @@ The platform formerly known as "Vertex AI" is now **Gemini Enterprise Agent Plat
 |-------------|-----------|
 | Agent Engine, Vertex AI Agent Engine, Agent Runtime | `--deployment-target agent_runtime` |
 | Agent Engine sessions, Agent Platform Sessions | `--session-type agent_platform_sessions` |
-| Vertex AI Search, Vertex AI Vector Search, RAG | clone-and-study recipe, not a flag (see `references/samples.md`) |
+| Vertex AI Search, Vertex AI Vector Search, RAG | clone-and-study recipe, not a flag (see `/google-agents-cli-adk-code` → `references/samples.md`) |
 
 The `vertexai` Python SDK package name is unchanged.

{google_agents_cli-1.3.0 → google_agents_cli-1.3.1}/src/google/agents/cli/_skills_check.py

@@ -25,7 +25,7 @@ import click
 import yaml
 
 # Pin the skills npm package to avoid executing an unverified version.
-SKILLS_NPX_PACKAGE = "skills@1.5.18"
+SKILLS_NPX_PACKAGE = "skills@1.5.9"
 
 _SKILLS_CHECK_INTERVAL = 12 * 60 * 60  # 12 hours in seconds
 _SKILLS_CHECK_STAMP = Path.home() / ".agents" / ".acli_skills_check"