ADK retail plugin

Retail AI Plugin (plugins/retail)

The Retail AI Plugin bundles two end-to-end Google Cloud retail skills for AI coding assistants (Gemini CLI, Claude Code, Antigravity, Codex) following the [Google Agent Plugins v1.0.0 specification][spec] (plugin.json + skills/<skill-name>/SKILL.md):

1. [retail-product-search](./skills/product-search/) — Semantic & hybrid e-commerce product catalog search powered by Vector Search 2.0 on Gemini Enterprise Agent Platform, BigQuery, gemini-embedding-001 (768-dim embeddings), and gemini-3.7-flash.
2. [retail-virtual-tryon](./skills/virtual-tryon/) — Generative image and 360° catwalk video virtual try-on across clothing, eyewear, footwear, jewelry, and cosmetics powered by Gemini image generation models and Veo (gemini-3.7-flash orchestration), with an automated pre-flight product-cutout catalog scanner.

Team: FDE/Blackbelt · Authors / Contributors: Tanvi Singhal (@tanvisinghal-0105), Gabriela (@gabrielahrlr) · License: Apache-2.0

Skills vs. Deployable Cloud Agents: Which Should You Use?

This repository provides the Retail capabilities in two complementary formats depending on your persona:

Included Skills Overview

Prerequisites

• Python 3.11+ and uv
• gcloud CLI authenticated with Application Default Credentials:

```bash

gcloud auth application-default login

export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

```

Quickstart & Installation

Option 1: Install via npx skills add (No Repo Clone Required)

Install either skill directly into your AI coding assistant (~/.agents/skills/):

npx skills add google/adk-recipes --skill retail-product-search
npx skills add google/adk-recipes --skill retail-virtual-tryon

Option 2: Surface Both Skills Locally from plugins/retail (make surface)

You can surface both skills at once directly from this plugins/retail/ directory without navigating into individual skill subfolders:

cd plugins/retail

# Default: surface both skills to ~/.gemini/skills and ~/.agents/skills
make surface

# Surface only to Gemini CLI / Gemini Enterprise Desktop (~/.gemini/skills):
make surface SURFACE_GEMINI_SKILL=true SURFACE_AGENTS_SKILL=false

# Surface only to ~/.agents/skills (Claude Code / Antigravity / ADK):
make surface SURFACE_GEMINI_SKILL=false SURFACE_AGENTS_SKILL=true

Option 3: Run Interactive Setup & Local Testing

Once installed, open your coding assistant in any workspace directory and prompt:

• For Product Search: *"Use the retail-product-search skill to set up a semantic product search agent for my catalog."*
• For Virtual Try-On: *"Use the retail-virtual-tryon skill to build a virtual try-on studio with image and catwalk video support."*

Or provision the sample GCP resources and run the runnability tests directly from plugins/retail/:

cd plugins/retail

# Run runnability tests (tests/test_runnability.py) across both skills:
make test

# Provision GCP resources for Product Search or Virtual Try-On:
make setup-product-search PROJECT_ID="$GOOGLE_CLOUD_PROJECT"
make setup-virtual-tryon PROJECT_ID="$GOOGLE_CLOUD_PROJECT"

Directory Structure

Why is there a skills/ subfolder? This plugin follows the [Agent Plugins v1.0.0 specification][spec], which places plugin.json at the plugin root (plugins/retail/plugin.json) and packages each skill under skills/<skill-name>/SKILL.md so multi-skill industry plugins can be discovered and installed as a single cohesive unit:

plugins/retail/
├── plugin.json                     # Agent Plugins v1.0.0 manifest & ownership metadata
├── README.md                       # Top-level Retail plugin overview & quickstart (this file)
├── Makefile                        # Top-level targets to surface, set up, and test both skills
└── skills/
    ├── product-search/             # retail-product-search skill
    │   ├── SKILL.md                # Conversational agent instructions (Q-MODE + setup workflow)
    │   ├── README.md               # Detailed product-search skill guide
    │   ├── EVAL.yaml               # Evaluation rubrics
    │   ├── Makefile                # Skill-level surface & setup targets
    │   ├── pyproject.toml          # Skill Python dependencies & project config
    │   ├── uv.lock                 # Locked dependency graph
    │   ├── assets/                 # Design spec template & 1,000-product sample CSV
    │   ├── references/             # Deep-dive docs (architecture, ingestion, troubleshooting)
    │   ├── scripts/                # BigQuery + Vector Search ingestion, retrieval & ADK agent
    │   └── tests/                  # Runnability smoke tests (test_runnability.py)
    └── virtual-tryon/              # retail-virtual-tryon skill
        ├── SKILL.md                # Conversational agent instructions (Q-MODE + setup workflow)
        ├── README.md               # Detailed virtual-tryon skill guide
        ├── EVAL.yaml               # Evaluation rubrics
        ├── Makefile                # Skill-level surface & setup targets
        ├── pyproject.toml          # Skill Python dependencies & project config
        ├── uv.lock                 # Locked dependency graph
        ├── assets/                 # Sample catalog cutouts, Studio web UI & Cloud Run export template
        ├── references/             # Virtual try-on architecture & safety reference
        ├── scripts/                # Catalog scanner, Gemini/Veo try-on processor, FastAPI server & exporter
        └── tests/                  # Runnability smoke tests (test_runnability.py)

Related Links

• Standalone Deployable Agents:
• [contrib/python/retail-product-search](../../contrib/python/retail-product-search/)
• [contrib/python/retail-virtual-tryon](../../contrib/python/retail-virtual-tryon/)
• Specifications & Handbook:
• [ADK Recipes Plugin Layout & Specification](../../docs/recipe-handbook/plugins.md)
• [Agent Plugins v1.0.0 Specification][spec]

[spec]: https://agent-plugins.org/specification