The Problem

Building a production commerce agent means solving the same hard problems every time: tool contracts that stay in sync with a backend, memory that persists across turns, safety gates on writes, and prompt/skill organization. Most teams hand-roll this per project and end up with agents that are hard to audit or move across runtimes.

What This Does

Two agent definitions — a customer-facing shopping agent and a staff-facing merchant agent — each defined once and runnable on three runtimes (Messages API, Agent SDK, Managed Agents). Four runnable verticals (retail, travel, telecom, entertainment) demonstrate both over the same libraries.

The shared package commerce-common/ holds the cross-cutting machinery: config, memory, fencing (safety gates), grounding, skills, delegation, streaming, presentation. Each agent core (shopping-agent/core/, merchant-agent/core/) defines prompts, skills, tool contracts, and a backend interface a deployment implements.

How It Is Wired

A run starts at scripts/run_demo.py, which boots an API (e.g. examples/retail/api/main.py) and a Next.js storefront or merchant portal. The API hosts the agent runtime; the web apps render the generative UI.

The turn loop: runtime receives a message → commerce_common/turn.py drives the loop → skills (shopping-agent/skills/, merchant-agent/skills/) invoke tool contracts → the backend interface routes to the host's real systems. Nothing leaves the process except through the deployment's backend implementation and the Anthropic API.

Key files and their responsibility:

  • commerce_common/turn.py — the turn loop both agents route through
  • commerce_common/fencing.py — gates on writes; merchant writes are staged until a human approves
  • commerce_common/memory.py — customer facts and session state
  • commerce_common/mcp_server.py — exposes agents over MCP
  • shopping-agent/core/shopping_agent/backend.py — StorefrontBackend contract (catalog, cart, orders, policy)
  • merchant-agent/core/merchant_agent/backend.py — MerchantBackend contract (analytics, catalog, inventory, pricing, campaigns)
  • plugins/commerce-builder/ — Claude Code plugin that scaffolds agents

Blast radius: commerce_common is the hub — 15 modules shared by both agents and all four verticals; a change there touches every consumer. The two backend interfaces are the second choke point: they define what a deployment must implement.

How To Use It

git clone https://github.com/moses-y/commerce-agents && cd commerce-agents
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                  # add ANTHROPIC_API_KEY
(cd examples && npm ci)
python scripts/run_demo.py retail     # API :8000 + storefront :3000

--merchant starts the portal instead of the storefront; --all starts both. Verticals map to ports: retail (:3000/:3100), travel (:3001/:3101), telecom (:3002/:3102), entertainment (:3003/:3103). To build your own, install the Claude Code plugin and run /scaffold-commerce-agent.

Real-World Use

A retailer implements StorefrontBackend over its catalog, cart, and order systems. The shopping agent searches, compares, and fills the cart; checkout renders the cart for the host to complete — no charge is placed by the agent. Merchant staff get a portal where listing edits and price changes are staged until approved.

Code Health & Issues

100 test files across commerce-common/tests/, examples/demo_common/tests/, and per-vertical test suites. CI exists (.github/workflows/ci.yml), LICENSE is present, and a lockfile is committed. Only .env.example is checked in — no secrets. Deep static analysis has not run for this repo; this assessment is structural only.

The Bottom Line

A well-organized reference for teams building commerce agents on Claude — the shared library and backend contracts are the real value. The trade-off: it is a blueprint, not a product; you must implement the backends and own compliance, authorization, and approval flows. Best for teams that want a proven architecture rather than a from-scratch design.