ShopAgent — Agent de Busca de Produtos com GAR
tusharc/shop-agent-showcase
Agente de busca conversacional que raciocina, busca e rankeia produtos em linguagem natural
Ver no GitHubUm agente conversacional que implementa o padrão Generation-Augmented Retrieval (GAR), onde o LLM propõe respostas ideais e ferramentas verificam contra um catálogo estruturado. Demonstra busca por linguagem natural, ranking de resultados e explicação de recomendações, funcionando com zero API keys via modo mock.
Instalação
npx convez-ai tusharc/shop-agent-showcase1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Implementação de busca por catálogo alimentada por LLM em e-commerce
- Prototipagem rápida de assistentes de recomendação de produtos
- Exploração do padrão GAR vs RAG para seleção em bases estruturadas
Veredito

Excelente referência prática do padrão GAR com código limpo e comentado. Ideal para quem quer entender como montar busca conversacional sobre catálogos estruturados sem depender de API keys na prototipagem inicial.
README
A tradução para o português deste README ainda está na fila.
🛍️ ShopAgent
A conversational, LLM-driven product-search agent
Ask in plain language. The agent reasons about what you want, calls tools to search a catalog, ranks the results, and explains its picks.
Quick start · How it works · Architecture · Tech stack
Ask in natural language → the agent reasons, searches, ranks, and explains its picks.
What this is
ShopAgent is a small, self-contained demo of an agentic search pattern I call Generation-Augmented Retrieval (GAR) — the inverse of classic RAG:
Instead of retrieving documents and stuffing them into a prompt, the LLM first proposes an ideal answer, then tools enrich and verify it against a real catalog, and a ranking pass annotates the result.
The agent runs a tool-use loop (search products, search brands, narrow by reasoning, compose picks), ranks candidates with a BM25 + heuristic scorer, and streams an explained set of recommendations back to a polished React UI.
It ships with a fully synthetic catalog (fictional brands and products) and a mock LLM mode, so you can clone and run it in 30 seconds with zero API keys.
When to reach for GAR (vs RAG)
GAR and RAG aren't competitors — they fit differently shaped problems. The question isn't which is better, it's which matches the shape of your task.
Reach for GAR when…
- The answer is a selection from a structured catalog (products, brands, listings, songs) rather than prose synthesized from documents.
- Your knowledge base is queryable by attribute — IDs, fields, tags, categories — not just by similarity over text.
- The catalog is larger than a context window, so dumping rows into a prompt doesn't scale.
- You're optimizing for relevance and ranking more than citation.
- The model already has enough domain knowledge to propose a good answer; the catalog's job is to verify, enrich, and rank.
Reach for RAG when…
- The answer is prose ("how does X work", "what does my policy cover"), grounded in source documents.
- Your knowledge base is unstructured text — docs, wikis, transcripts, support tickets.
- You need attribution — the user must see which source the answer came from.
- The model can't reasonably propose without seeing the corpus first (very specialized domains, fresh information).
Trade-offs
| GAR | RAG | |
|---|---|---|
| Shape of task | Selection / recommendation | Open-domain QA / summarization |
| Backend required | Queryable, structured catalog | Vector index over documents |
| Hallucination guard | Verify step drops anything not in the catalog | "Stick to retrieved text" prompt + chunks |
| Attribution | Implicit (entity IDs, links) | Explicit (cited passages) |
| LLM passes per turn | Higher (propose + tool-call + compose) | Lower (one generate over chunks) |
| Scales past context window? | Yes — only proposed candidates are fetched | Constrained by what fits after retrieval |
| Failure mode | Model proposes plausible-but-nonexistent entities — caught at verify | Retriever misses the right chunk — the model invents anyway |
The two compose: a GAR-style propose step can sit in front of a RAG-style retrieval if the underlying knowledge has both structured and unstructured components.
Quick start (30 seconds)
# 1. Backend — runs with a mock LLM, no credentials needed
cd server && npm install
SHOWCASE_MOCK_LLM=1 npm run dev # http://localhost:3000
# 2. Frontend — in a second terminal
cd web && npm install
npm run dev # http://localhost:5173
Open http://localhost:5173, go to Ask, and try "lightweight trail running shoes under $150".
Want real LLM responses? Set AWS Bedrock credentials and drop
SHOWCASE_MOCK_LLM. The mock path and the real path return the same shape, so the agent behaves identically.
How it works
A single user turn flows through the agent loop:
flowchart LR
U([User query]) --> A[Shop Agent<br/>LLM loop]
A -- proposes ideal answer --> A
A -- tool calls --> T{Tool registry}
T --> S1[searchProducts]
T --> S2[searchBrands]
T --> S3[narrowWithReasoning]
S1 & S2 & S3 --> C[(Synthetic catalog)]
C --> R[Ranking<br/>BM25 + heuristics]
R --> P[composePicks<br/>+ annotate]
P --> A
A -- streamed picks + rationale --> UI([React UI])
- Propose — the LLM drafts what a great answer looks like for the query.
- Enrich — it calls tools (
searchProducts,searchBrands,suggestBrandModels,narrowWithReasoning) that hit the catalog. - Rank — candidates are scored (BM25 over titles/tags + heuristics) and diversified.
- Compose —
composePicksassembles a final, explained set and streams it to the UI.
The UI
A clean React storefront with three surfaces: a conversational Ask page, a Products search page, and a landing page that routes natural-language queries into the agent.
Architecture
shop-agent-showcase/
├── server/ # TypeScript + Express agent backend
│ └── src/
│ ├── api/routes/ # catalog · search · conversation (agent)
│ ├── services/
│ │ ├── shopAgent.ts # the agent loop
│ │ ├── agentTools/ # tool-use registry + tools
│ │ ├── pickOrchestrator.ts # search + offer join
│ │ ├── ranking.ts # BM25 + heuristic scorer
│ │ ├── bedrockChat.ts # LLM (real Bedrock OR mock mode)
│ │ └── synthetic/ # fictional catalog + data adapters
│ └── server.ts
└── web/ # React + Vite + TypeScript UI
└── src/
├── pages/ # Landing · Catalog (search) · ShopAgent (chat)
├── components/ # product cards, brand rail, picks list
└── utils/ # streaming agent client, tracking
Design note — the data layer is an adapter. Every catalog/offer lookup goes through a thin module surface (productCatalogStore, brandOfferIndex, publicBrandService, …). Here those are backed by an in-memory synthetic fixture; in a production deployment they'd be backed by a real datastore. The agent and ranking code don't change.
Tech stack
| Layer | Tech |
|---|---|
| Agent backend | TypeScript, Express, tool-use loop |
| LLM | AWS Bedrock (Claude) — with a credential-free mock mode |
| Search/ranking | BM25 + heuristic scoring, reasoning-based narrowing |
| Frontend | React, Vite, TypeScript, streaming (SSE) UI |
Notes
- The catalog is entirely fictional (
server/src/synthetic/) — invented brands, products, and prices. - Mock LLM mode makes the demo deterministic and free to run; the real Bedrock path is intact behind the same interface.
License
MIT