google/adk-recipes

Product Search Agent

Creates product search agents with semantic search and RAG on Google Cloud.

STOP — Q-MODE FIRST

If a catalog is already loaded (system context says "DEPLOYED search agent" or provides a <catalog> block), skip Q-MODE and answer product queries directly using the catalog.

Otherwise, your first message MUST be exactly this:

[skill: retail-product-search] active.
Q-MODE: Pick a setup mode? [default: 1]
  1. Quick start -- 2 questions, smart defaults, ~60s. Best for demos and first-timers.
  2. Full setup  -- 4 questions, ~2 min. Best for real builds.

Then stop and wait. Accept 1, quick, empty/Enter (Quick), or 2, full (Full).

Execution Rules

1. Q-MODE first. No preamble, no plan-proposing.
2. One question at a time. Show [default: ...]. Empty input = default.
3. Save answers to ./design-spec.md in the workspace as you collect them.
4. After interview, run scripts/setup.py (see Workspace Setup below).
5. User can say "configure more" mid-Quick-Start to switch to Full.

Workspace Setup

The skill has two locations:

• Install dir — where SKILL.md and scripts live (varies by host)
• Workspace — the agent's cwd; design-spec.md, .venv, and per-run state live here

By the end of this section the workspace must have .venv/ (with the skill installed editable), design-spec.md, and SKILL_DIR exported in the shell.

Run this as ONE shell command — splitting it across tool calls loses state:

SKILL_DIR=$(for d in ~/.claude/skills ~/.agents/skills ~/.gemini/skills ~/.cursor/skills; do
  [ -f "$d/retail-product-search/SKILL.md" ] && echo "$d/retail-product-search" && break
done)
bash "$SKILL_DIR/scripts/bootstrap.sh"

bootstrap.sh finds a Python 3.11+ interpreter (with absolute-path fallback for sandboxed shells), creates .venv, installs the skill editable, and copies design-spec.md into the workspace.

All scripts run from the install dir against the workspace config. Use .venv/bin/python, not bare python — bare python may resolve to a Python without the skill's editable install on sys.path.

.venv/bin/python "$SKILL_DIR/scripts/setup.py" --config ./design-spec.md
.venv/bin/python "$SKILL_DIR/scripts/cleanup.py" --config ./design-spec.md --confirm

Details in references/install-paths.md.

Skill Dependencies

This skill works in conjunction with the following core Google Cloud skills:

• bigquery-basics (for database configuration guidelines)
• gemini-api (for Gemini Enterprise Agent Platform / Google Gen AI SDK best practices)

Verify if these skills are installed in your active skills directory. If they are missing, recommend the developer to install them by running: npx skills add google/skills --skill bigquery-basics gemini-api

Mode 1: Quick Start (2 questions)

Q	Question	Default
Q-A	GCP project ID?	$GOOGLE_CLOUD_PROJECT or gcloud config get-value project
Q-B	Where's your product data?	assets/sample-products.csv (bundled)

Accepted for Q-B: empty / default (bundled), /path/to/file.csv, or gs://....

Silent defaults: Extended fields, us-central1.

After Q-A and Q-B, do this automatically (don't ask the user to copy/paste). Run these steps SEQUENTIALLY — do not parallelize. Steps 2-3 modify the file bootstrap copies in step 1; running them concurrently is a race.

1. Run bootstrap first and wait for completion. bash "$SKILL_DIR/scripts/bootstrap.sh" copies the YAML-frontmatter design-spec template into the workspace at ./design-spec.md. Do NOT touch ./design-spec.md until bootstrap exits.
2. Mutate the existing ./design-spec.md — do NOT rewrite it from scratch. setup.py parses YAML frontmatter via _setup_utils.py. A Markdown-only file fails with 'NoneType' object has no attribute 'get'. Use Edit / sed to replace specific lines:
   • gcp_project_id: "" → gcp_project_id: "<Q-A answer>"
   • data_source: assets/sample-products.csv → data_source: <Q-B answer> (only if user gave a non-default)
3. Say: "Taking defaults for the rest. Running setup — this takes 2-5 min to create a BigQuery dataset and Vector Search collection. Say 'configure more' to switch to Full setup."
4. Run .venv/bin/python "$SKILL_DIR/scripts/setup.py" --config ./design-spec.md
5. Stream output. On non-zero exit, surface the error and check references/troubleshooting.md
6. On success, set VECTOR_SEARCH_COLLECTION and proceed to Test

Mode 2: Full Setup

Adds two more questions: product fields level and GCP region.

Q	Question	Default	Notes
Q-fields	Product fields level	Extended	Basic / Standard / Extended / Full. Match this to your CSV's columns. Don't offer "Custom" — validate_schema.py rejects it.
Q-region	GCP region	us-central1	Only confirmed-working region for Vector Search 2.0. Other regions return 501 MethodNotImplemented.

Otherwise identical to Quick Start.

When to Use

• E-commerce product search, shopping assistants, semantic catalog discovery

Don't use for generic document search, simple keyword search, or non-retail.

Project Tree

retail-product-search/
  assets/
    design-spec.md            # Source of truth -- filled by Q-MODE
    sample-products.csv       # Bundled 5-product demo catalog
  references/                  # Deep-dive docs (load on demand)
  scripts/
    agent.py                  # Reference ADK agent
    retrievers.py             # Vector Search retrieval logic
    setup.py                  # Pipeline driver (reads design-spec.md)
    bootstrap.sh              # Workspace bootstrap (called from Workspace Setup)
    validate_schema.py
    ingest_bigquery.py
    ingest_vertex_search.py
    cleanup.py

Customize: rewrite scripts/agent.py (see references/agent-example.md) and scripts/retrievers.py with your product-specific fields.

Test

After setup.py succeeds, set the collection env var (one line, no newlines):

export VECTOR_SEARCH_COLLECTION="projects/$GOOGLE_CLOUD_PROJECT/locations/us-central1/collections/retail-skill-products-collection"

Then either:

With ADK (interactive UI):

# Use the WORKSPACE VENV's adk (not bare `adk`) so the skill's editable
# install is on sys.path. Bare `adk` may resolve to a global Python (pyenv,
# brew, etc.) whose ADK can't find the skill and reports an empty app list.
.venv/bin/adk web "$SKILL_DIR/scripts" --port 8765

Open http://127.0.0.1:8765, click scripts, query.

⚠️ Two things must be right:

• Point adk web at $SKILL_DIR/scripts, not at . — agent code lives in the install dir, not the workspace. adk web . fails with "No agents found in current folder".
• Use .venv/bin/adk, not bare adk — bare adk may launch the wrong Python and silently fail to load the agent (UI loads, but /list-apps returns [] and queries time out).

Without ADK (direct smoke test):

.venv/bin/python -c "from scripts.retrievers import search; print(search('laptop for video editing', top_k=3))"

Semantic-only retrieval — no structured filters on price, stock, or rating. For demo queries and how to add structured filtering, see references/architecture.md.

Evaluate

cd "$SKILL_DIR"
uv run pytest

EVAL.yaml declares rubric (LLM-as-judge) + assertions (deterministic checks). Target: 80%+ passing.

Deploy

Never deploy without explicit human approval.

Cloud Run service account needs roles/bigquery.dataViewer on the dataset and roles/aiplatform.user on the project. Deploy via gcloud run deploy or your org's existing tooling.

Gotchas

• No results: collection empty or VECTOR_SEARCH_COLLECTION not set
• Slow search: check region and top_k
• No structured filters: search() is pure semantic similarity. Price / stock / currency filters happen client-side in the LLM, so results may include items outside the constraint. Don't promise hard filters
• ADK session memory: if the retriever errored in earlier turns, the model "learns" the tool is broken. Click "New Session" in adk web after fixing the underlying issue

Troubleshooting

Most-common failures inline; full table in references/troubleshooting.md.

Error	Fix
setup.py exits with 'NoneType' object has no attribute 'get'	design-spec.md was rewritten as plain Markdown instead of mutating the YAML-frontmatter template bootstrap copied. Wait for bootstrap to finish, then edit (not rewrite) ./design-spec.md — only change the field values inside the existing ---...--- frontmatter
adk web starts but /list-apps returns [] / browser shows "No agents found"	Bare adk resolved to a global Python that lacks the editable install. Kill it and restart with .venv/bin/adk web "$SKILL_DIR/scripts" --port 8765
MethodNotImplemented: 501 from Vector Search	VECTOR_SEARCH_COLLECTION has a newline. Re-export on one line
ModuleNotFoundError: google.adk	pip install -e "$SKILL_DIR" — google-adk is an unconditional dependency, no [adk] extra needed
Package requires Python: 3.9.X	venv used system Python 3.9. Recreate with python3.12 -m venv .venv
BILLING_DISABLED / PERMISSION_DENIED / API has not been used	GCP project setup — see troubleshooting.md

MCP Migration

This skill uses gcloud CLI + Python SDKs (google-genai, google-cloud-bigquery, google-cloud-aiplatform). Per Phase 2 Skills guidelines, 1p skills should prefer remote MCP tools when available. Migration map:

Service	Where	Future MCP
BigQuery	ingest_bigquery.py, validate_schema.py	BigQuery MCP
Vector Search (Gemini Enterprise Agent Platform)	ingest_vertex_search.py, setup.py	Gemini Enterprise Agent Platform MCP
Embeddings (Gemini Enterprise Agent Platform)	retrievers.py	Gemini Enterprise Agent Platform MCP
Cloud Run	gcloud run deploy	Cloud Run MCP

Completion Checklist

• Product fields level and data source confirmed
• Data ingestion ran; Vector Search populated
• retrieve_docs returns results in ADK web UI
• Evaluation passes success criteria
• Deployed (if beyond prototype)

References

Load on demand:

• references/install-paths.md — host install dirs, Python fallback, bash -c rationale
• references/dependencies.md — pip deps and install quirks
• references/architecture.md — what retrieval does (semantic-only), demo queries, structured-filter strategies
• references/troubleshooting.md — full error table
• references/agent-example.md — how agent.py + retrievers.py fit together
• references/ingestion-scripts.md — per-script CLI reference