Skip to content
Back to search

commerce-agents

SkillOfficial: AnthropicGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/anthropics/commerce-agents with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/anthropics/commerce-agents'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/anthropics--commerce-agents/badge.svg)](/listings/anthropics--commerce-agents)

HTML

<a href="/listings/anthropics--commerce-agents"><img src="/api/listings/anthropics--commerce-agents/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "claude-commerce-agents",
  4. "description": "Claude Commerce Agents: the commerce-builder plugin for building shopping and merchant agents on Claude.",
  5. "owner": {
  6. "name": "Anthropic"
  7. },
  8. "plugins": [
  9. {
  10. "name": "commerce-builder",
  11. "source": "./plugins/commerce-builder",
  12. "description": "Skills and scaffolding commands for building shopping and merchant agents on Claude, covering architecture, prompt caching, UI tools, trust and safety, evals, and merchant operations.",
  13. "author": {
  14. "name": "Anthropic"
  15. }
  16. }
  17. ]
  18. }
README.md · README · 193 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Claude Commerce Agents
  2. Two commerce agents built on Claude: a **shopping agent** a business embeds in its app for
  3. customers, and a **merchant agent** its staff use to run the back office. Each is defined
  4. once (prompt, skills, tool contracts, gates) and runs on the Messages API, the Claude Agent
  5. SDK, and Managed Agents; four runnable verticals show both over the same libraries.
  6. > [!NOTE]
  7. > Every company, brand, product, and person here is fictional; the only company is ACME.
  8. > Nothing places an order, charges a card, or changes a live listing: `checkout` renders
  9. > the cart for the host to complete, and every merchant write is staged until a person
  10. > approves it. Business rules, authorization, and compliance are the deployment's.
  11. ## Quick start: run the demos
  12. Python 3.11+ and Node 22. Clone, install, add a key, run a vertical:
  13. ```bash
  14. git clone https://github.com/anthropics/commerce-agents.git && cd commerce-agents
  15. python3 -m venv .venv && source .venv/bin/activate
  16. pip install -r requirements.txt # the seven packages and their pinned dependencies
  17. cp .env.example .env # add ANTHROPIC_API_KEY
  18. (cd examples && npm ci) # the eight web apps share one workspace
  19. python scripts/run_demo.py retail # API :8000 + storefront :3000
  20. ```
  21. `--merchant` starts the portal instead of the storefront and `--all` starts both. The
  22. verticals are `retail` (:3000, portal :3100), `travel` (:3001, :3101), `telecom` (:3002,
  23. :3102), and `entertainment` (:3003, :3103); each README lists prompts to try on both surfaces.
  24. ## Quick start: build your own
  25. The Claude Code plugin scaffolds an agent on these packages against your systems, or reviews
  26. one you have. With the repo cloned as above (the plugin reads it as the reference):
  27. ```bash
  28. claude plugin marketplace add anthropics/commerce-agents
  29. claude plugin install commerce-builder@claude-commerce-agents
  30. claude
  31. /scaffold-commerce-agent a shopping assistant for our store
  32. ```
  33. The command asks about your stack, plays the plan back, and builds the project; `/add-commerce-flow`
  34. and `/author-commerce-evals` continue from there, and `/review-commerce-agent` starts from an agent
  35. that already exists ([`plugins/commerce-builder/`](plugins/commerce-builder/)). Each command also
  36. runs when a request matches its description, so naming it is optional.
  37. ## The two agents
  38. The **shopping agent** searches, compares, plans, fills the cart, answers order and policy
  39. questions, and remembers what a customer tells it. Its five flows are the skills in
  40. [`shopping-agent/skills/`](shopping-agent/skills/); a deployment implements
  41. [`StorefrontBackend`](shopping-agent/core/shopping_agent/backend.py) over its catalog,
  42. cart, order, and policy systems.
  43. The **merchant agent** explains performance, maintains listings, acts on inventory and order
  44. alerts, prices and promotes, and drafts campaigns; every write is a staged change the host's
  45. approval surface applies. Its five flows are the skills in [`merchant-agent/skills/`](merchant-agent/skills/);
  46. a deployment implements [`MerchantBackend`](merchant-agent/core/merchant_agent/backend.py) over
  47. its analytics, catalog, inventory, pricing, and campaign systems.
  48. ## Layout
  49. | Directory | Contents | pip package, `import` name |
  50. |---|---|---|
  51. | [`commerce-common/`](commerce-common/) | What both roles share: config, fencing, memory, skills, grounding, presentation, executor frame, events | `commerce-common`, `commerce_common` |
  52. | [`shopping-agent/core/`](shopping-agent/core/) | Shopping types, `StorefrontBackend`, prompt, tool contracts, gates, executor | `shopping-agent-core`, `shopping_agent` |
  53. | [`shopping-agent/runtime-messages-api/`](shopping-agent/runtime-messages-api/) | `ShoppingAgent`, the turn loop on the Messages API | `shopping-agent-runtime`, `shopping_agent_runtime` |
  54. | [`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` |
  55. | [`shopping-agent/managed-agents/`](shopping-agent/managed-agents/) | Manifest and storefront MCP server for Managed Agents | — |
  56. | [`merchant-agent/core/`](merchant-agent/core/) | Merchant types, `MerchantBackend`, prompt, tool contracts, change guardrails, gates, executor | `merchant-agent-core`, `merchant_agent` |
  57. | [`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` |
  58. | [`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` |
  59. | [`merchant-agent/managed-agents/`](merchant-agent/managed-agents/) | Manifest, merchant MCP server, scheduled digest for Managed Agents | — |
  60. | [`examples/`](examples/) | Four verticals, shared host code (`demo_common/`), shared web code (`web-shared/`) | — |
  61. | [`plugins/commerce-builder/`](plugins/commerce-builder/) | The Claude Code plugin | — |
  62. | [`docs/`](docs/) | `safety.md` (enforced rules), `backends.md` (mapping your systems), `deployment.md` (other platforms) | — |
  63. | [`tests/`](tests/) | Cross-package suites; each package also has its own `tests/` | — |
  64. | [`scripts/`](scripts/) | `install.sh`, `run_demo.py`, `smoke_chat.py`, `screenshot_tour.py`, `check.py`, `deploy_managed_agent.sh`, `verify_all.py` | — |
  65. ## Three ways to run an agent
  66. **Messages API.** The reference loop; the examples are host applications around it:
  67. ```python
  68. from pathlib import Path
  69. from shopping_agent import ShoppingAgentConfig
  70. from shopping_agent_runtime import ShoppingAgent
  71. agent = ShoppingAgent(backend=your_backend, skills_dir=Path("shopping-agent/skills"),
  72. config=ShoppingAgentConfig(brand_name="Your Store"))
  73. async for event in agent.stream_turn(messages, session, state):
  74. ... # text_delta, tool_call, ui, cart_update (change_update on the merchant side), turn_complete
  75. await agent.update_memory(messages, session) # memory extraction; this path only
  76. ```
  77. The example hosts take the session id in an `X-Session-Id` header.
  78. **Agent SDK.** The same prompt, skills, and tools, with the SDK running the loop; the host
  79. prefetches grounding reads, and nothing runs after the turn:
  80. ```bash
  81. python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"
  82. python merchant-agent/runtime-agent-sdk/main.py # approves staged changes with y/N
  83. ```
  84. **Managed Agents.** A hosted agent over the same skills and contracts, calling your MCP server:
  85. ```bash
  86. scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent # or merchant-agent/...; --live deploys
  87. ```
  88. ## Safety
  89. Fencing, provenance gates, caps, memory validation, and the merchant approval gate run
  90. inside the tool call and hold on all three paths; grounding, the analysis budgets, and memory
  91. extraction are runtime features. [`docs/safety.md`](docs/safety.md) lists each rule with its
  92. module and paths, and what a deployment adds first; the examples have no authentication and
  93. the MCP servers bind to loopback.
  94. ## Verticals
  95. | Example | Storefront | Portal |
  96. |---|---|---|
  97. | [`examples/retail/`](examples/retail/) ACME | Search, comparison, plans, cart, checkout, memory over the built-in components | Digest, staged restocks and listing fixes, analysis delegate over a SQL view |
  98. | [`examples/travel/`](examples/travel/) ACME Travel | Date-bound inventory and a `present_itinerary` extension | Occupancy calendar and date-window rate moves |
  99. | [`examples/telecom/`](examples/telecom/) ACME Mobile | Account context, plan matrix, server-authored fee disclosures | Plan mix, price moves that state the lines affected, protected regulated fees |
  100. | [`examples/entertainment/`](examples/entertainment/) ACME Tickets | Timed holds, waitlists, transfers, venue map, all-in fee disclosures | Event pacing, hold releases that add real capacity, fee-preserving price moves |
  101. Each example's README has a `Try` section: the turns `scripts/smoke_chat.py` runs, and single
  102. prompts with what a good answer does.
  103. ## Verify
  104. ```bash
  105. ruff check . && ruff format --check . && pytest && python scripts/check.py
  106. python scripts/verify_all.py # the line above plus deploy dry runs and web builds
  107. python scripts/smoke_chat.py --vertical travel # one live conversation; needs a key
  108. ```
  109. `requirements-dev.txt` adds pytest and ruff. CI installs from it on two Python versions,
  110. builds the eight web apps, and checks that the package names stay unregistered on the
  111. public index (the pin files install them from their directories, never from the index). To confirm caching, read
  112. `cache_read_input_tokens` from `turn_complete`, or the line each model call logs on its
  113. runtime's logger: zero on a second turn means the prefix changed.
  114. ## Deploying elsewhere
  115. The runtimes take any `anthropic` client as `client=` and the SDK runtimes take the platform
  116. from the CLI environment; [`docs/deployment.md`](docs/deployment.md) covers GCP Vertex AI, AWS Bedrock, Microsoft Foundry, and gateways.
  117. ## MCP connectors
  118. None ship; both agents reach your systems through the backend interfaces. Where an official
  119. connector is the source of record, it is the integration target: analytics warehouses (Snowflake,
  120. BigQuery, Databricks, Amplitude), finance (Stripe, Square, PayPal, QuickBooks), delivery (Slack, Google Drive, Gmail).
  121. A commerce platform's own MCP server for catalog, cart, or checkout is called from a backend
  122. method server-side; on Managed Agents the manifest mounts it beside the role's server, and the
  123. provenance gates stay in front of every write.
  124. ## Making it yours
  125. - **Backend methods.** Each one calls your service server-side with the
  126. credential your host holds for the session; the model reads only the result. A flow whose
  127. steps have a fixed order enforces that order in the backend.
  128. - **Read the backend guide.** [`docs/backends.md`](docs/backends.md) walks through
  129. identity and credentials, ordered flows, checkout, products with options, and figures
  130. your platform cannot supply.
  131. - **The same interface covers other business shapes.** On a marketplace, seller is a search
  132. dimension and the merchant agent acts for the operator the session names. With account or
  133. contract pricing, the price quoted is the session account's. With no checkout of your
  134. own, turn the cart off or hand it to a quote, a purchase order, or a hosted checkout URL.
  135. - **Checkout hands off.** The checkout card links to your own checkout route, or to the
  136. platform's hosted checkout URL (one per seller on a marketplace). The backend returns the
  137. URL and the host renders it; the model never sees it.
  138. - **Start small.** A shopping pilot implements search and product details and stubs the
  139. rest; a stubbed method returns an unavailable result and changes no prompt bytes. A
  140. merchant pilot implements the eight read methods and has the writes refuse; digests and
  141. metrics then run with no write path.
  142. - **Switch off what you do not have.** A system the business lacks entirely (no cart on a
  143. referral surface, no order tracking) is an `enable_*` switch turned off, which removes its
  144. tools, prompt lines, and grounding rule on every path; park the flows that need it under
  145. `skills/_staged/`. The merchant config has the same switches for listing edits, inventory,
  146. pricing, and campaigns.
  147. - **Add your own.** A flow is a directory with a `SKILL.md` under either `skills/`. Domain
  148. UI is a `PresentationExtension` (the verticals ship seven). `brand_name`,
  149. `assistant_name`, and `brand_voice` on either config set the identity.
  150. ## License
  151. Copyright 2026 Anthropic PBC. Licensed under the [Apache License 2.0](./LICENSE).
  152. This is a reference implementation; it is not maintained and does not accept contributions.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.