README

Claude Commerce Agents

Two commerce agents built on Claude: a shopping agent a business embeds in its app for
customers, and a merchant agent its staff use to run the back office. Each is defined
once (prompt, skills, tool contracts, gates) and runs on the Messages API, the Claude Agent
SDK, and Managed Agents; four runnable verticals show both over the same libraries.

 [!NOTE]
 Every company, brand, product, and person here is fictional; the only company is ACME.
 Nothing places an order, charges a card, or changes a live listing: checkout renders
 the cart for the host to complete, and every merchant write is staged until a person
 approves it. Business rules, authorization, and compliance are the deployment's.

 Quick start: run the demos

Python 3.11+ and Node 22. Clone, install, add a key, run a vertical:

bash
git clone https://github.com/anthropics/commerce-agents.git && cd commerce-agents
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt        the seven packages and their pinned dependencies
cp .env.example .env                   add ANTHROPIC_API_KEY
(cd examples && npm ci)                the eight web apps share one workspace
python scripts/run_demo.py retail      API :8000 + storefront :3000


--merchant starts the portal instead of the storefront and --all starts both. The
verticals are retail (:3000, portal :3100), travel (:3001, :3101), telecom (:3002,
:3102), and entertainment (:3003, :3103); each README lists prompts to try on both surfaces.

 Quick start: build your own

The Claude Code plugin scaffolds an agent on these packages against your systems, or reviews
one you have. With the repo cloned as above (the plugin reads it as the reference):

bash
claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude
/scaffold-commerce-agent a shopping assistant for our store


The command asks about your stack, plays the plan back, and builds the project; /add-commerce-flow
and /author-commerce-evals continue from there, and /review-commerce-agent starts from an agent
that already exists (plugins/commerce-builder/). Each command also
runs when a request matches its description, so naming it is optional.

 The two agents

The shopping agent searches, compares, plans, fills the cart, answers order and policy
questions, and remembers what a customer tells it. Its five flows are the skills in
shopping-agent/skills/; a deployment implements
StorefrontBackend over its catalog,
cart, order, and policy systems.

The merchant agent explains performance, maintains listings, acts on inventory and order
alerts, prices and promotes, and drafts campaigns; every write is a staged change the host's
approval surface applies. Its five flows are the skills in merchant-agent/skills/;
a deployment implements MerchantBackend over
its analytics, catalog, inventory, pricing, and campaign systems.

 Layout

| Directory | Contents | pip package, import name |
|-