# Claude Commerce Agents: A Reference Blueprint for Shopping and Merchant AI Agents

> Claude Commerce Agents is an open-source Python reference implementation from Anthropic that blueprints two Claude-powered agents: a customer-facing shopping agent and a back-office merchant agent. Four runnable verticals cover retail, travel, telecom, and entertainment, all sharing the same skills, tool contracts, and safety gates across three available runtimes.

**anthropics/commerce-agents** — Reference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.

- Repository: https://github.com/anthropics/commerce-agents
- Website: https://claude.com/solutions/commerce
- Stars: 3,100 · Forks: 600
- Language: Python
- License: Apache-2.0
- Published: 2026-09-16 · Updated: 2026-09-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/anthropics-commerce-agents

## What Claude Commerce Agents Is and Who It Is For

Claude Commerce Agents is a reference blueprint from Anthropic for building two types of AI agents in commerce applications: a shopping agent that a business embeds for customer interactions, and a merchant agent that back-office staff use to manage products, pricing, and campaigns. The README states that each agent is defined once (prompt, skills, tool contracts, and gates) and runs on the Messages API, the Claude Agent SDK, and Managed Agents.

The target audience is engineering teams at companies in retail, travel, telecom, or entertainment who want a tested, production-oriented starting point for deploying Claude-based agents rather than designing the prompt structure, tool contracts, and safety architecture from scratch. The blueprint is not a turnkey product; it provides a structure that a team adapts to their own catalog, cart, order, and policy systems by implementing the StorefrontBackend and MerchantBackend interfaces.

The README is explicit that all companies, brands, products, and people in the included examples are fictional (ACME), and that the checkout flow renders a cart for the host to complete rather than processing real payments. Every merchant write is staged until a person approves it.

## Two Agents, Three Runtimes, Eleven Directories

The repository is organized into two agent packages (shopping-agent and merchant-agent), a shared commerce-common package, an examples directory with four verticals, and supporting scripts and plugins. The README provides a layout table covering all eleven major directories with their contents and import names.

The shopping agent's five flows live in shopping-agent/skills/ and handle search, comparison, cart management, order status, and policy questions. A deployment implements the StorefrontBackend interface (defined in shopping-agent/core/shopping_agent/backend.py) over its own catalog, cart, order, and policy systems. The merchant agent's five flows live in merchant-agent/skills/ and cover performance analysis, listing maintenance, inventory and order alerts, pricing and promotion, and campaign drafts.

The three runtimes each run the same agent logic but differ in where the turn loop runs. The Messages API runtime puts the loop in the host application. The Agent SDK runtime delegates the loop to the SDK. Managed Agents runs the agent as a hosted service with the agent's tool calls going to an MCP server that the team deploys.

## Running the Demo Verticals

The four verticals (retail, travel, telecom, entertainment) are runnable out of the box after installing the repository's packages and building the example web apps. Python 3.11 or above and Node 22 are required.

```bash
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
(cd examples && npm ci)
python scripts/run_demo.py retail
```

After adding the ANTHROPIC_API_KEY to the .env file, running the last command starts both the API server on port 8000 and the storefront web app on port 3000. The --merchant flag starts the merchant portal on port 3100 instead, and --all starts both surfaces. Each vertical's README lists prompts to try.

To use the Messages API runtime directly in your own application:

```python
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):
    ...
await agent.update_memory(messages, session)
```

The Agent SDK console runs the shopping agent from the command line:

```bash
python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"
```

Deploying to Managed Agents uses a provided script:

```bash
scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent
```

## Safety Architecture: Fencing, Caps, and the Approval Gate

The README describes safety as running inside the tool call and holding across all three runtimes. The mechanisms listed are fencing, provenance gates, caps, memory validation, and the merchant approval gate. The docs/safety.md file, referenced in the README, lists the enforced rules in detail.

The merchant approval gate is the most operationally significant constraint: every write operation the merchant agent proposes is staged as a change and held until a person approves it. The merchant agent does not apply any change directly to inventory, pricing, or listings. This means a deployment needs an approval surface; the included Agent SDK console shows a y/N prompt for each staged change.

Fencing and provenance gates run at the tool call level, which means they apply whether the agent runs on the Messages API, the Agent SDK, or Managed Agents. Caps limit analysis budgets and are part of the runtime features. Memory extraction, which updates what the shopping agent remembers about a customer across sessions, is an explicit step in the Messages API path and is called after each turn with `await agent.update_memory(messages, session)`. The Agent SDK path does not run memory extraction after the turn; grounding prefetches and analysis budgets are runtime features in that path.

## What the Blueprint Does Not Include

The blueprint is a starting point, not a complete system. It does not include a catalog, a real cart system, an order management system, or a pricing engine. A team adopting it implements the StorefrontBackend interface over their own data sources. The README describes this mapping in docs/backends.md. The MerchantBackend interface in merchant-agent/core/merchant_agent/backend.py similarly must be implemented over real analytics, catalog, inventory, pricing, and campaign systems.

The examples use fictional ACME data. The scripts/smoke_chat.py and scripts/screenshot_tour.py scripts test the demo setup but are not integration tests against a real production system. The tests directory contains cross-package suites, but the blueprint does not include end-to-end tests against live commerce APIs.

Managed Agents deployment requires the Managed Agents service to be available for the team's account and region. The deploy script includes a --live flag that deploys rather than doing a dry run, and teams should review what the Managed Agents service entails before that step. Deployment considerations beyond Managed Agents are documented in docs/deployment.md.

The Claude Code plugin for scaffolding requires the repository to be cloned locally as a reference. The /scaffold-commerce-agent, /add-commerce-flow, /author-commerce-evals, and /review-commerce-agent commands then operate against that reference to generate code for the team's own stack. The /review-commerce-agent command also works as a starting point for reviewing an agent that already exists in the team's codebase.

## How This Compares to Building Agents from the Messages API Directly

Building a commerce agent from the Claude Messages API alone requires designing the skill structure, writing the system prompt, defining tool contracts, implementing the turn loop, adding safety checks, and deciding how memory is extracted and stored. The commerce-agents blueprint provides all of those pieces in a tested, opinionated form specific to commerce use cases.

LangChain and similar agent frameworks offer a different trade-off: they are provider-agnostic and provide tool integration and memory primitives, but they do not include commerce-specific patterns like the StorefrontBackend interface, the merchant approval gate, or the structured skill directories that this blueprint defines.

The blueprint's advantage over both alternatives is that it encodes design decisions that Anthropic has tested against commerce scenarios and documented in the safety and backends guides. The cost is that it is Claude-specific: all three runtimes use the Anthropic Messages API or the Claude Agent SDK, and the Managed Agents path requires Anthropic's hosted agent infrastructure.

## Conclusion

Claude Commerce Agents is the right starting point for engineering teams building e-commerce AI agents with Claude who want a tested architecture rather than building from the Messages API upward. The shopping agent and merchant agent patterns, with their pre-built skills, safety gates, and three runtime options, accelerate the design phase significantly. Teams that use a different LLM provider or need a framework-agnostic approach will find the blueprint less directly applicable. Before adopting it, verify that the Claude Agent SDK and Managed Agents service are available for your deployment region, and review docs/safety.md to ensure the built-in fencing and caps match your compliance requirements. The project is licensed under Apache 2.0 and the last push was on 2026-09-11.

## FAQ

### What is the difference between the shopping agent and the merchant agent?

The shopping agent is embedded in the customer-facing storefront and handles search, comparison, cart filling, and order and policy questions. The merchant agent is used by back-office staff to manage listings, analyze performance, and draft campaigns; every write it proposes is staged until a person approves it.

### Can commerce-agents run without the Managed Agents service?

Yes. The blueprint supports three runtimes independently. The Messages API runtime and the Agent SDK runtime both run locally without the Managed Agents service. Managed Agents is an optional third path for hosting the agent as a service on Anthropic's infrastructure.

### What safety mechanisms does the merchant agent use?

The merchant agent uses fencing, provenance gates, caps, and an approval gate that stages every write as a change until a person approves it. These mechanisms run inside the tool call and apply on all three runtimes. The full list of enforced rules is in docs/safety.md.

## Sources

- [anthropics/commerce-agents on GitHub](https://github.com/anthropics/commerce-agents)
- [Issues](https://github.com/anthropics/commerce-agents/issues)
- [License: Apache-2.0](https://github.com/anthropics/commerce-agents/blob/main/LICENSE)
- [Project website](https://claude.com/solutions/commerce)
- [README](https://github.com/anthropics/commerce-agents/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/anthropics-commerce-agents