anthropics/commerce-agents: a reference blueprint for shopping and merchant agents on Claude
Reference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.
At a glance
- What is it?
- The repository defines two agents once and runs them on three runtimes, with every merchant write staged for human approval. It is a blueprint to copy, not a product to deploy, and it keeps business rules and compliance with the host.
- Who is it for?
- Adopt it if you are building a commerce agent on Claude and want a working reference for tool contracts, gates and staged writes before you wire in your own catalog and order systems; the four verticals give you something to run on day one. Do not adopt it expecting a production storefront: the README states that every company and product is fictional and that nothing places an order, charges a card or changes a live listing.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 5 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 16, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the blueprint actually gives you, and who it is for
Most "agentic commerce" material describes an outcome. This repository ships the parts: two agent roles, each defined once as a prompt, a set of skills, tool contracts and gates, then executed on the Messages API, the Claude Agent SDK and Managed Agents. The shopping agent is the one a business embeds for customers; it searches, compares, plans, fills the cart, answers order and policy questions and remembers what a customer tells it. The merchant agent is the back-office counterpart for staff: it explains performance, maintains listings, acts on inventory and order alerts, prices and promotes, and drafts campaigns.
The audience is an engineering team that has already decided to put an agent in front of a catalog and now needs to know what the seams look like. The repository answers that with two Python base classes. A deployment implements StorefrontBackend over its catalog, cart, order and policy systems, or MerchantBackend over its analytics, catalog, inventory, pricing and campaign systems. Everything above that line is provided. Everything below it is yours.
The README is blunt about the boundary. Every company, brand, product and person in the repository is fictional, and 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 belong to the deployment.
How the two agents are wired: one definition, three runtimes
The design choice worth noticing is that the agent is not the runtime. The prompt, skills, tool contracts and gates live in the core packages, and the runtimes are interchangeable shells around them. That is why the same skills directory can drive a FastAPI host, an SDK console and a hosted Managed Agent without a second definition.
The shared layer sits in commerce-common: config, fencing, memory, skills, grounding, presentation, the executor frame and events. The shopping and merchant cores add their own types, backend interface, prompt, tool contracts, gates and executor. On top of that, the Messages API runtime provides ShoppingAgent and its turn loop; the Agent SDK runtime runs the same prompt, skills and tools with the SDK driving the loop; and the Managed Agents path is a manifest plus an MCP server.
There is a real behavioural difference between the paths, and the README states it rather than hiding it. Fencing, provenance gates, caps, memory validation and the merchant approval gate run inside the tool call and hold on all three paths. Grounding, the analysis budgets and memory extraction are runtime features. So a team that moves from the Messages API to the Agent SDK should expect grounding reads to be prefetched by the host, and should not expect anything to run after the turn. Memory extraction is likewise tied to the Messages API path, where the example calls update_memory explicitly.
The event stream is the integration surface. A turn emits text_delta, tool_call, ui, cart_update (change_update on the merchant side) and turn_complete, and the example hosts identify a session through an X-Session-Id header. If you are building a UI, that event list is effectively your contract.
Running the demos: clone, install, pick a vertical
The quickest way to see whether the shape fits is to run one of the four verticals. The README asks for Python 3.11+ and Node 22, and the install is a virtualenv plus a pinned requirements file. Python packages are installed editable from their directories, and the requirements file notes that the seven repository packages are unregistered on the package index, so the install only works from a clone.
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 :3000After that command you should have an API on port 8000 and a storefront on port 3000. The other verticals follow the same pattern: travel on 3001 with a portal on 3101, telecom on 3002 and 3102, entertainment on 3003 and 3103. Passing --merchant starts the portal instead of the storefront, and --all starts both. Each vertical's README lists prompts to try on each surface, which is the fastest way to see the difference between the customer-facing flows and the staged merchant writes.
To build your own rather than run the demos, the Claude Code plugin scaffolds an agent against your systems. It reads the cloned repository 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 storeThe 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. Each command also runs when a request matches its description, so naming it is optional.
The approval gate is the design decision, and it costs you a surface
Staging every merchant write is the most consequential choice in the repository, and it is a trade-off rather than a feature list. The merchant agent can price, promote, edit a listing and draft a campaign, but the change does not take effect until the host's approval surface applies it. The SDK console demonstrates this directly, prompting y/N before a staged change goes through. The safety documentation places the approval gate inside the tool call, alongside fencing, provenance gates, caps and memory validation, which is why it holds on all three runtimes rather than only in the reference host.
The cost is that you cannot ship the merchant agent without building an approval UI and deciding who is allowed to press the button. The README does not document a rollback path for an approved change, and it does not describe an audit trail beyond the staged change itself; that work belongs to the host. Teams expecting an autonomous back-office operator will find the opposite here, deliberately.
The same caution applies to the shopping side. checkout renders the cart for the host to complete, so the payment, tax and fulfillment logic is outside the repository. If your interest is in the transaction itself rather than the conversation that precedes it, the demos will not answer your questions about settlement, and the README does not claim they do.
Where the four verticals stop being a demo
The verticals cover retail, travel, telecom and entertainment over shared host code in examples/demo_common and shared web code in examples/web-shared. Because they run the same libraries over different backends, they are a useful check on whether the StorefrontBackend and MerchantBackend interfaces are general enough for your domain. A travel catalog and a telecom catalog do not model inventory the same way, and seeing both implemented against one interface is more informative than reading the interface alone.
What the verticals do not provide is any of the operational machinery. There is no authentication story beyond the X-Session-Id header the example hosts use to identify a session, and the README places authorization with the deployment. There is no persistence layer described for memory beyond the extraction call. The docs directory points at backends.md for mapping your systems and deployment.md for other platforms, which is where a serious evaluation should go next.
A practical way to use the verticals: pick the one furthest from your own domain, run it, and read its backend implementation. If the interface still reads cleanly against a business you do not run, it will probably hold for yours.
The alternative: build the loop yourself on the Messages API
The obvious alternative is to skip the blueprint and write the agent loop directly against the Anthropic Python SDK, using the Messages API and your own tool definitions. The difference in approach is where the guardrails live. Here, fencing, provenance gates, caps, memory validation and the approval gate are implemented inside the tool call in shared code, and the same code runs whether the loop is yours, the Agent SDK's or a hosted Managed Agent. In a hand-rolled loop you write those checks yourself, once per runtime, and they drift the moment you add a second surface.
That difference cuts both ways. A hand-rolled loop has no opinions about your catalog, your approval UI or your event schema, and it does not ask you to implement a backend interface or to keep seven packages pinned in editable mode. For a narrow agent that answers order-status questions and nothing else, the blueprint is more structure than the task needs. The repository is aimed at teams that expect to run both a customer-facing and a staff-facing agent over the same systems, which is exactly the case where duplicated guardrail code becomes expensive.
If you already run agents on the Claude Agent SDK, the migration cost is lower than it looks: the Agent SDK runtime here runs the same prompt, skills and tools, with the host prefetching grounding reads and nothing running after the turn.
Licence and the upgrade cost you are signing up for
The repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. The practical implication for a team copying the blueprint into a product is that you can, provided you keep the licence and notice files; this is not legal advice, and the LICENSE file is the authority.
The upgrade cost is the pinned dependency set. requirements.txt pins the seven repository packages as editable local installs and pins every third-party package to the versions the release was tested against. The file states that the seven names are unregistered on the package index and that each pyproject pins its sibling dependencies to a version no index carries, so there is no index-based install path. Moving a pin means editing requirements.txt and the pyproject that declares the range, then running the verify line in the README. That is a deliberate reproducibility choice, and it means you own the dependency graph rather than inheriting one from PyPI.
Given the last push was on 2026-09-11, the repository is current, but there are no releases retrieved, so there is no versioned artefact to track. Plan to follow the main branch and re-run the verification after you move a pin.
Editorial conclusion
Adopt it if you are building a commerce agent on Claude and want a working reference for tool contracts, gates and staged writes before you wire in your own catalog and order systems; the four verticals give you something to run on day one. Do not adopt it expecting a production storefront: the README states that every company and product is fictional and that nothing places an order, charges a card or changes a live listing. Verify first that your team can implement StorefrontBackend or MerchantBackend over your real systems, since that is the boundary where this repository stops and your deployment begins.
Frequently asked questions
What is anthropics/commerce-agents?
It is a reference blueprint for building two commerce agents on Claude: a shopping agent a business embeds for customers, and a merchant agent staff use for the back office. Each is defined once as a prompt, skills, tool contracts and gates, and runs on the Messages API, the Claude Agent SDK and Managed Agents.
How do I install and run the commerce-agents demos?
You need Python 3.11+ and Node 22. Clone the repository, create a virtualenv, run pip install -r requirements.txt, copy .env.example to .env and add ANTHROPIC_API_KEY, run npm ci inside examples, then run python scripts/run_demo.py retail to start the API on port 8000 and the storefront on port 3000.
Does the merchant agent change live listings on its own?
No. Every merchant write is a staged change that the host's approval surface applies, and the approval gate runs inside the tool call on all three runtimes. The SDK console demonstrates this by asking y/N before a staged change goes through.
Can I install the commerce-agents packages from PyPI?
No. The requirements file states that the seven repository packages are unregistered on the package index and that each pyproject pins its sibling dependencies to a version no index carries, so they are installed editable from their directories in a clone.
Community notes