What the release actually is
On September 2, 2026, Anthropic published `anthropics/commerce-agents` on GitHub under Apache 2.0. It is a reference implementation of two agents on Claude: a shopping agent a business embeds in its own app for customers, and a merchant agent its staff use in the back office. The repository ships the prompts, skill definitions, tool contracts, safety gates, an eval authoring pattern, runnable demo storefronts, and a Claude Code plugin. It is explicitly a blueprint, not a maintained product, and it accepts no contributions.
The whole repo exists in a fictional world. Every company, brand, and person is invented, the only company being ACME, and nothing in the demos places a real order or charges a card. The point is to show a working shape of the harness, so an engineering team can take the same prompt, skills, and contracts and point them at their own systems.
The shopping agent, and what it does for a customer
The shopping agent is the customer-facing half. It lives inside the merchant's storefront and handles natural-language requests: search, compare, plan a multi-item purchase, fill a cart, answer order and policy questions, and remember what a customer told it in a previous visit.
Its five flows are shipped as skills in shopping-agent/skills/: search and discovery, purchase research, planning and goals, customer care, and memory personalization. When a shopper says "I need a tent, a sleeping bag, and a stove for a weekend trip with two kids," the agent moves through these flows without being routed to subagents. Anthropic's engineering guidance is explicit about why: cart state, customer preferences, order history, and product data are so tightly coupled that splitting a commerce conversation across subagents loses context while multiplying tokens and latency. One agent owns the conversation in a single reasoning/action/observation loop.
The product cards, comparison grids, and cart panels are not generated HTML. They are typed tool calls the server validates and fills with real records, which is why the agent can reference "the third one on the left" and have it resolve to an actual product id. Preference memory is extracted by a small model in a separate pass, keeping the main conversation cheap.
Checkout is a deliberate handoff. The checkout tool renders the cart, and the backend returns the checkout URL directly to the host, so the model never sees the URL and cannot touch it. One deployment implements StorefrontBackend, a 14-method interface over its own catalog, cart, order, and policy systems.
The merchant agent, and how it keeps humans in the loop
The merchant agent is the staff-facing half. It explains performance, maintains listings, acts on inventory and order alerts, proposes pricing and promotions, and drafts campaigns. Its five flows are performance insights, catalog listings, inventory operations, pricing promotions, and marketing campaigns.
Every state-changing write is staged. A price move, restock, campaign, or listing edit is proposed as a change, then a human applies or discards it. The repo ships an approving console for the SDK path (the runtime asks the operator with a y/N prompt), and guardrails run both when a change is staged and again when it is applied: items per change, promotion discount cap, price move limits, restock size, campaign budget, protected fields. This is the pattern to notice. Anthropic chose to make every write an explicit human approval step with a transaction log, which is exactly the discipline most agentic commerce demos skip.
The merchant agent also has an analysis delegate. On the Messages API path, a brief and read-only tools go to an analysis pass that returns a single schema-validated result: a SQL query (a single SELECT, no comments), capped in rows and characters, with a wall-clock budget. A merchant team can ask it to slice an inventory view without giving a model write access to anything.
How to run the demos
The quick start is clone, install, add a key, run a vertical. Python 3.11+ and Node 22 are the only prereqs.
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
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 merchant portal instead of the storefront; --all starts both. Four verticals ship as runnable examples, each with its own web apps over a FastAPI service:
Vertical | Storefront | Portal |
|---|---|---|
Retail | Cart, comparison, memory, staged restocks | Digest, listing fixes, analysis delegate over a SQL view |
Travel | Date-bound inventory, itineraries | Occupancy calendar, date-window price moves |
Telecom | Plan matrix, server-authored fee disclosures | Plan mix, regulated fee protection |
Entertainment | Timed holds, waitlists, venue map, all-in fees | Event pacing, fee-preserving price moves |
scripts/smoke_chat.py --vertical travel runs one live conversation against the example, so you can test a flow with real model calls. The repo verifies itself with ruff check . && ruff format --check . && pytest && python scripts/check.py, plus a verify_all.py that adds deploy dry runs and web builds.
There are three ways to run either agent against your own systems:
- Messages API (the reference loop). Host application code drives the turn loop and receives
text_delta,tool_call,ui, andcart_updateevents. - Claude Agent SDK (the Claude Code-style loop). One example invocation:
python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250". The merchant version prints pending changes and waits for approval. - Managed Agents (hosted agent).
scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent --livedeploys a manifest and MCP server for the shop's catalog.
Platform is a config choice, not a rewrite. The runtimes take any anthropic client via client=, so a Vertex, Bedrock, Foundry, or in-house gateway client drops in the same place. Default models are Claude Sonnet 5 for the shopping agent, Claude Opus 5 for the merchant agent, and Haiku 4.5 for memory extraction.
How to build your own
The integration point is the backend interface, not a plugin. A deployment implements StorefrontBackend over its own catalog, cart, order, and policy systems; the model reads only what those methods return. The repo's docs walk through the mapping decisions.
The agent can also be assembled through a Claude Code plugin that ships separately (the commerce-builder plugin):
claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude
/scaffold-commerce-agent a shopping assistant for our storeThe scaffold command asks about the stack, plays a plan back, and builds a project. Once running, four commands come in sequence: /scaffold-commerce-agent for the initial project, /add-commerce-flow for a new flow as a SKILL.md under the skills directory, /author-commerce-evals to generate an eval suite, and /review-commerce-agent to audit an existing agent against the contract.
The recommended pilot path is deliberately small. A shopping pilot implements just search and product details, stubbing the rest. A merchant pilot implements the eight read methods and refuses every write, then runs digests with no write path. Missing systems are switched off with an enable_* switch rather than left dangling.
The repo's eval skill shows the test shape, and the build step is genuinely usable by an e-commerce team. A case has priority (critical/high/medium/low), difficulty, tags, state (seen products, cart, memory, staged changes), turns (the customer's or operator's messages), and an expected block with fields such as calls_tool, never_calls, first_tool, ui_components, cart_contains, cart_item_count, memory_contains, and staged_change_kinds. A runner executes cases against a fresh agent with a live backend; scorers grade each expected field; rubric cases go to a judge at temperature 0. CI can replay stored outcomes with no API access, and a baseline keyed by case and scorer catches regressions without a new transcript. The repo ships no harness: the suite is yours, on your catalog.
What it deliberately will not do
The safety design is worth reading as a set of intentional refusals:
- Never takes money. Checkout renders the cart and hands off. Payment, identity, and liability stay with the merchant.
- Never writes from the model's reasoning. The merchant agent stages a change; a defined approver applies it.
- Never invents a record. Cart writes accept only product ids from the session's catalog reads. Prices, stock, and checkout URLs come from the backend. Disclosure text and fee disclosures are server-authored.
- Never trusts third-party content. Customer reviews, chat, and page texts are fence-wrapped and sanitized, and unverified content is clearly marked.
- Never lies upward. Where your catalog cannot produce a figure, the backend returns
Nonewith a note, not a zero. - Never changes facts mid-answer. Prompt and tool definitions stay static on every turn; the fenced per-request data sits after the cache breakpoint, so caching holds and the rule set stays fixed.
Also deliberate: the repo is a reference implementation, and Anthropic says it is not maintained and accepts no contributions.
What this means for AI shopping visibility
A few observations for anyone whose work is SEO, GEO, or AI-search visibility, without pretending this blueprint is the whole market. The broader framework for shaping how AI answers represent your site is in our GEO framework guide; this section is about what this release adds on top of it.
It formalizes the merchant-owned lane. Until now, agentic commerce was mostly framed as a choice between building on someone else's platform or giving up the shopper relationship. This release is the clearest publicly available technical answer to a third option: keep the agent, the catalog, and the data in the store. As a positioning choice, Anthropic has provided the pattern for it. That does not change what works on the external platforms (ChatGPT, Gemini, and their shopping protocols still retrieve and cite web pages; entity consistency, mention quality, and authority still drive who gets included). It adds the different mechanics of a storefront agent.
The record is the participating unit. Whatever system the visibility measurement measures, what this blueprint makes unambiguous is that the agent's answer is assembled from method results, not from a page model or from search-engine index text. Your catalog data is not alternative metadata. It is the recall set the agent sees. Catalog hygiene, then, is not a data-engineering issue that happens to affect marketing. It is the marketing surface.
The page is not obsolete, but its role shifted. Outside a storefront agent, pages are the citation layer and the explanation that survives a skeptical shopper who leaves the conversation. Inside one, pages supply the schema source, the entity facts, and the human floor. Content teams who assume this release is too low-level to matter will be surprised by the sequencing: the product page and the product record now carry separate requirements.
What the blueprint does not answer
Some of the numbers deserve skepticism. The reported results (cart size up 30 to 35 percent, purchase completion roughly 60 percent higher) come from one retailer's data, relayed to Reuters by an Anthropic product lead. There is no payment protocol, no identity layer, and no consumer attribution layer. The four verticals are demos with no real orders. The blueprint is a pattern, not a market forecast. The external shopping platforms are alive and competing, and the merchant-owned style it formalizes may take years to become common.
Auspia take
If you are an e-commerce growth team with a Claude API key, the fastest useful thing you can do with this release is run one demo. python scripts/run_demo.py retail gives you the reference shape of a shopping conversation in a safe, fictional world, and scripts/smoke_chat.py --vertical travel gets you one live turn. The second thing is reading the backend guide next to your own schema, to see how your families and variants would map. Both are weekend-sized tasks, and the mapping conclusions themselves are salvageable. The parts that do not apply to your catalog are the parts you know in advance. The parts that do apply are exactly the parts you want to find before the agent does.
Author: Eva Laurent, Ecommerce Search Strategist for 10,000+ Product Pages. Eva writes about product discovery, category content, and AI-driven shopping visibility.
