Index of every page on this site: llms.txt
All skills
google avatar

/product-search

@ead8d7f
by googlegoogle/adk-recipes11k stars
2,961
Run it yourself

Creates product search agents with semantic search and RAG on Google Cloud (Vector Search on Gemini Enterprise Agent Platform, BigQuery, embeddings). Use when the user wants to "build a product search agent", "create an e-commerce search", "make a shopping assistant", "set up semantic catalog discovery", "ingest products into Vector Search", or "deploy a retail RAG agent". Handles the full pipeline: catalog data ingestion to BigQuery, Gemini Enterprise Agent Platform Vector Search collection setup, ADK agent scaffolding, evaluation, and Cloud Run deployment.

  • 28 files
  • 586.9 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/google/adk-recipes/product-search

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈145 tokens for metadata: the name and description. ≈2.8k when used: this file. ≈9.8k more on demand in 11 files.

Description uses 7.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈588 characters, or 7.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at ead8d7f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 2 months ago
metadata
{
  "author": "Google",
  "license": "Apache-2.0",
  "version": "0.2.0"
}

README badge

README badge for google/adk-recipes/product-search