Effective Commerce Agents — an embeddable Claude shopping & merchant agent for any store

A working implementation of the patterns from Anthropic's The anatomy of effective commerce agents and the anthropics/commerce-agents blueprint — but pointed at real stores instead of a fictional ACME:

• Shopping agent in a one-line widget for any website: searches the catalog, compares, fills the cart with server-issued product IDs only, hands off to your checkout, collects leads.
• Merchant agent in an owner console: explains sales, audits listings, drafts price and inventory changes — every write is staged until you press Apply.
• Catalog from whatever you already have: Shopify, WooCommerce, Magento, Squarespace, any site with JSON-LD / microdata, Google Merchant or YML feeds, CSV/XLSX — plus posts from Telegram, TikTok and Instagram turned into products.

Don't want to run a server? The same agent runs as a hosted service with a multi-store cabinet, billing and support: comag.vibevox.pro. Questions and custom work: t.me/GuruAppSheet.

The article's patterns → this code

Pattern from the article	Where it lives here
One model, one agent loop, no intent router or sub-agents	server/src/commerce/agent.ts — runAgentTurn()
Skills for long-tail tasks, loaded as tool results	prompts.ts — SHOPPING_SKILLS, MERCHANT_SKILLS, load_skill tool
UI components as tool calls (cards, comparison, checkout, lead form)	tools.ts + web/src/components/commerce/AgentComponents.tsx
Tool results are context: only reasoning-relevant fields	tools.ts, catalog.ts — trimmed product projections
Parallel tool use within a round	agent.ts — Promise.all over a round's tool calls
Three-segment prompt caching (tools + static system → history → dynamic context)	agent.ts — cache_control breakpoints, prompts.ts — buildShoppingSystem / buildShoppingContext
Server-issued ID validation: the cart accepts only IDs the session has seen	shopping.ts — seen_ids gate
Caps and variants: ≤10 per line, ≤20 lines, no variant family without a chosen option	shopping.ts
Staged writes with human approval	merchant.ts — stage_* tools, checkGuardrails(), applyChange() (±30 % price cap, ≤25 items, re-check at apply time)
Fence-wrapping untrusted content (pages, reviews, posts, chats)	fence.ts — STOREFRONT_FENCE, MERCHANT_FENCE, sanitizeChips()
Memory as facts in a database, retrieved by topic / constraints	store.ts — listMemory(), saveMemory(), commerce_memory
Regulated content supplied by the server, never invented	prices, stock and checkout URLs come only from catalog.ts / settings.ts
Rate limits on public endpoints	router.ts — /w/:slug/chat 30/min, /lead 6/min, /event 120/min

What the article asks for and this repo does not ship yet: a snapshot-eval suite. The blueprint's /author-commerce-evals guide applies unchanged; PRs with evals are the most welcome kind.

How it works

Shopper on your site ──► <script src=".../comag.js" data-shop="my-store">  (iframe widget)
                              │ SSE  /api/commerce/w/:slug/chat
                              ▼
                    shopping agent (Claude Sonnet) ── tools ──► Postgres catalog, cart gates, leads
                              ▲
Owner console (/commerce) ────┘ merchant agent (Claude Opus) ── stage_* ──► staged changes → Apply / Discard
Catalog sources: site crawler · feeds · CSV/XLSX · Telegram channel · TikTok profile · Instagram (optional sidecar)

Quick start (Docker)

git clone https://github.com/DanikVR/effective-commerce-agents.git && cd effective-commerce-agents
cp .env.example .env            # set ANTHROPIC_API_KEY, ADMIN_TOKEN, APP_SECRET
docker compose up --build       # Postgres + app on http://localhost:3001

Open http://localhost:3001/commerce, paste your ADMIN_TOKEN, then:

1. Settings → Store: brand, currency, site URL, checkout URL.
2. Catalog: Analyze site (Shopify / WooCommerce / Magento / JSON-LD / sitemap), or upload CSV/XLSX, or import a Telegram channel / TikTok profile.
3. Widget: copy the snippet and put it on your site:

<script async src="https://YOUR-HOST/comag.js" data-shop="my-store"></script>

4. Agent: talk to the merchant agent — "what sold this week?", "find listings without images", "raise prices on the summer line by 5 %" → review the staged change → Apply.

The shareable chat page lives at /c/my-store (OG preview, installable as a PWA); the purchase pixel for your thank-you page is in Widget → Pixel.

Quick start (without Docker)

createdb commerce                                   # Postgres 13+
cd server && npm install && npm run dev             # applies sql/schema.sql, listens on :3001
cd web && npm install && npm run build              # console + widget → web/dist (npm run dev for Vite HMR on :3000)

Layout

server/src/commerce/   the agent: agent.ts · shopping.ts · merchant.ts · tools.ts · prompts.ts · fence.ts
                       catalog.ts · crawler.ts (site adapters) · social.ts (Telegram / TikTok / Instagram)
                       store.ts (conversations, leads, memory, stats) · notify.ts (Telegram to the owner)
                       push.ts / pwa.ts (web push, installable chat) · i18n.ts · router.ts (API)
server/src/            db.ts · config.ts (env) · safe_fetch.ts (anti-SSRF) · encryption.ts (AES-256-GCM for saved keys)
web/src/               owner console (React, Tailwind) · pages/embed/CommerceWidgetPage.tsx (the widget)
public/comag.js        one-line loader: bubble, iframe, page context (JSON-LD product), cart bridge, purchase pixel
sql/schema.sql         Postgres schema (idempotent)
locales/               console + widget strings (en, ru; the hosted edition ships 108 languages)

Configuration

Everything is in .env.example. Required: DATABASE_URL, ANTHROPIC_API_KEY, ADMIN_TOKEN, APP_SECRET. Optional: GEMINI_API_KEY (video → text for social imports), COMMERCE_TELEGRAM_BOT_TOKEN (lead notifications), VAPID keys (web push), IG_GATEWAY_URL / IG_GATEWAY_SECRET (Instagram sidecar — see instagram-sales-agent), YTDLP_BIN (TikTok — see tiktok-sales-agent).

Models default to claude-sonnet-5 for shoppers (latency) and claude-opus-5 for the merchant (analysis); override with COMMERCE_SHOPPING_MODEL / COMMERCE_MERCHANT_MODEL or per store in Settings → Keys.

Security model

• Prices, stock and product IDs exist only server-side; the model proposes, the server validates every cart line against the IDs it issued in this session.
• Merchant writes are staged in commerce_changes and applied only from the console; the price is re-read at apply time and the change is refused if it moved.
• Third-party text (crawled pages, reviews, posts, shopper messages) enters the prompt only inside a fence with control phrases stripped (fence.ts).
• Outbound fetches go through safe_fetch.ts (no private networks, redirects re-checked).
• Saved API keys are encrypted with AES-256-GCM (APP_SECRET).

Sister repositories

• tiktok-sales-agent — the same agent with a TikTok profile as the catalog source.
• instagram-sales-agent — the same agent with Instagram posts and reels as the catalog source (Python sidecar included).

Hosted edition

comag.vibevox.pro runs this agent for you: multi-store cabinet, 108 interface languages, one-click Telegram notifications, hosted widget and share pages, updates and support. Contact the author: t.me/GuruAppSheet.

Requirements

Node.js 20+, Postgres 13+, an Anthropic API key. Optional: ffmpeg + yt-dlp (pip install yt-dlp curl_cffi) for video posts, a Gemini key for transcription.

Credits & license

Apache-2.0 © DanikVR. Built on the patterns and guardrails of anthropics/commerce-agents (Apache-2.0) — see NOTICE. Russian README: README.ru.md.