anthropics/commerce-agents

anthropics/commerce-agents

Description: Reference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.

Language: Python

License: Apache-2.0

Stars: 789

Forks: 124

Open issues: 0

Created: 2026-09-01T12:30:12Z

Pushed: 2026-09-01T20:41:14Z

Default branch: main

Fork: no

Archived: no

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:

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):

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/](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/](shopping-agent/skills/); a deployment implements [StorefrontBackend](shopping-agent/core/shopping_agent/backend.py) 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/](merchant-agent/skills/); a deployment implements [MerchantBackend](merchant-agent/core/merchant_agent/backend.py) over its analytics, catalog, inventory, pricing, and campaign systems.

Layout

| Directory | Contents | pip package, import name | |---|---|---| | [commerce-common/](commerce-common/) | What both roles share: config, fencing, memory, skills, grounding, presentation, executor frame, events | commerce-common, commerce_common | | [shopping-agent/core/](shopping-agent/core/) | Shopping types, StorefrontBackend, prompt, tool contracts, gates, executor | shopping-agent-core, shopping_agent | | [shopping-agent/runtime-messages-api/](shopping-agent/runtime-messages-api/) | ShoppingAgent, the turn loop on the Messages API | shopping-agent-runtime, shopping_agent_runtime | | [shopping-agent/runtime-agent-sdk/](shopping-agent/runtime-agent-sdk/) | The shopping agent on the Agent SDK, with a console | shopping-agent-sdk, shopping_agent_sdk | | [shopping-agent/managed-agents/](shopping-agent/managed-agents/) | Manifest and storefront MCP server for Managed Agents | — | | [merchant-agent/core/](merchant-agent/core/) | Merchant types, MerchantBackend, prompt, tool contracts, change guardrails, gates, executor | merchant-agent-core, merchant_agent | | [merchant-agent/runtime-messages-api/](merchant-agent/runtime-messages-api/) | MerchantAgent and the analysis delegate on the Messages API | merchant-agent-runtime, merchant_agent_runtime | | [merchant-agent/runtime-agent-sdk/](merchant-agent/runtime-agent-sdk/) | The merchant agent on the Agent SDK, with an approving console | merchant-agent-sdk, merchant_agent_sdk | | [merchant-agent/managed-agents/](merchant-agent/managed-agents/) | Manifest, merchant MCP server, scheduled digest for Managed Agents | — | | [examples/](examples/) | Four verticals, shared host code (demo_common/), shared web code (web-shared/) | — | | [plugins/commerce-builder/](plugins/commerce-builder/) | The Claude Code plugin | — | | [docs/](docs/) | safety.md (enforced rules), backends.md (mapping your systems), deployment.md (other platforms) | — | | [tests/](tests/) | Cross-package suites; each package also has its own tests/ | — | | [scripts/](scripts/) | install.sh, run_demo.py, smoke_chat.py, screenshot_tour.py, check.py, deploy_managed_agent.sh, verify_all.py | — |

Three ways to run an agent

Messages API. The reference loop; the examples are host applications around it:

from pathlib import Path

from shopping_agent import ShoppingAgentConfig
from shopping_agent_runtime import ShoppingAgent

agent = ShoppingAgent(backend=your_backend, skills_dir=Path("shopping-agent/skills"),
config=ShoppingAgentConfig(brand_name="Your Store"))
async for event in agent.stream_turn(messages, session, state):
... # text_delta, tool_call, ui, cart_update (change_update on the merchant side), turn_complete
await agent.update_memory(messages, session) # memory extraction; this path only

The example hosts take the session id in an X-Session-Id header.

Agent SDK. The same...