convez.ai
AgenteBusca & PesquisaIntermediário
tusharc

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 GitHub
InicialPluginScore · de 0 a 100

Um 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-showcase

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

GARRAG
Shape of taskSelection / recommendationOpen-domain QA / summarization
Backend requiredQueryable, structured catalogVector index over documents
Hallucination guardVerify step drops anything not in the catalog"Stick to retrieved text" prompt + chunks
AttributionImplicit (entity IDs, links)Explicit (cited passages)
LLM passes per turnHigher (propose + tool-call + compose)Lower (one generate over chunks)
Scales past context window?Yes — only proposed candidates are fetchedConstrained by what fits after retrieval
Failure modeModel proposes plausible-but-nonexistent entities — caught at verifyRetriever 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])
  1. Propose — the LLM drafts what a great answer looks like for the query.
  2. Enrich — it calls tools (searchProducts, searchBrands, suggestBrandModels, narrowWithReasoning) that hit the catalog.
  3. Rank — candidates are scored (BM25 over titles/tags + heuristics) and diversified.
  4. Compose — composePicks assembles 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

LayerTech
Agent backendTypeScript, Express, tool-use loop
LLMAWS Bedrock (Claude) — with a credential-free mock mode
Search/rankingBM25 + heuristic scoring, reasoning-based narrowing
FrontendReact, 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

Ver o original no GitHub

Bom para

Relacionados