Build and Run Shopping and Merchant Agents with Claude Commerce Agents

What Claude Commerce Agents provides

Claude Commerce Agents is a reference implementation of two commerce-focused AI agents built on Claude. A business can embed the shopping agent in a customer-facing application, while staff can use the merchant agent to operate back-office workflows.

Each agent is defined once through its prompt, skills, tool contracts, and safety gates. The same definitions can run through the Messages API, the Claude Agent SDK, or Managed Agents. Four runnable verticals demonstrate the architecture across retail, travel, telecom, and entertainment.

All companies, products, brands, and people in the repository are fictional. The examples do not place orders, charge cards, or update live listings. Checkout is handed to the host, and merchant writes remain staged until a person approves them.

Understand the two agent roles

The shopping agent

The shopping agent supports customer-facing tasks such as searching and comparing products, planning purchases, filling a cart, answering order and policy questions, and remembering information supplied by the customer.

Its five flows live under shopping-agent/skills/. To use the agent with real systems, your deployment implements StorefrontBackend over the relevant catalog, cart, order, and policy services.

The merchant agent

The merchant agent helps staff understand performance, maintain listings, respond to inventory and order alerts, adjust prices and promotions, and draft campaigns. Its five flows are under merchant-agent/skills/.

A deployment connects it to analytics, catalog, inventory, pricing, and campaign systems by implementing MerchantBackend. Every write is staged rather than applied immediately; the host application must present and approve the proposed change.

Key architecture and features

• Shared foundations: commerce-common/ contains configuration, fencing, memory, skill handling, grounding, presentation, events, and the executor frame used by both roles.
• Multiple runtimes: the same prompts, skills, and tool contracts work with the Messages API, Agent SDK, and Managed Agents.
• Backend abstraction: agent tools call backend interfaces, allowing your server to retain credentials and mediate access to business systems.
• Staged merchant changes: merchant writes require approval through the host application's approval surface.
• Configurable capabilities: unsupported features can be disabled so their tools, prompt lines, and grounding rules are removed.
• Extensible presentation: domain-specific interfaces can be added through a PresentationExtension.
• Runnable examples: eight web applications provide a storefront and merchant portal for each of four verticals.

Prerequisites

Install Python 3.11 or newer and Node.js 22. You also need an Anthropic API key to run live model interactions.

Install the repository

Clone the project, create a Python virtual environment, install the pinned Python dependencies, create an environment file, and install the shared JavaScript workspace:

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)

Open .env and add your ANTHROPIC_API_KEY. Keep the virtual environment active while running the Python scripts.

Run your first demo

Start the retail storefront and its API with:

python scripts/run_demo.py retail

The retail API runs on port 8000, and the storefront runs on port 3000. To start the merchant portal instead of the storefront, add --merchant:

python scripts/run_demo.py retail --merchant

Use --all to start both surfaces:

python scripts/run_demo.py retail --all

The available verticals and web ports are:

• Retail: storefront 3000, merchant portal 3100.
• Travel: storefront 3001, merchant portal 3101.
• Telecom: storefront 3002, merchant portal 3102.
• Entertainment: storefront 3003, merchant portal 3103.

Each example directory has a README with suggested prompts and a description of what a good response should contain.

Explore the example verticals

Retail

The ACME retail example demonstrates product search, comparisons, planning, carts, checkout handoff, and memory. Its merchant portal includes performance digests, staged restocks, listing fixes, and an analysis delegate over a SQL view.

Travel

ACME Travel adds date-bound inventory and a present_itinerary extension. The merchant side includes an occupancy calendar and date-window rate changes.

Telecom

ACME Mobile demonstrates account context, a plan matrix, and server-authored fee disclosures. Merchant workflows cover plan mix and price changes while protecting regulated fees.

Entertainment

ACME Tickets includes timed holds, waitlists, transfers, venue maps, and all-in fee disclosures. Its merchant tools cover event pacing, capacity-producing hold releases, and fee-preserving price changes.

Use the Messages API runtime

The Messages API implementation is the reference turn loop. Create a configuration, provide your backend implementation, point the runtime at the shopping skills, and stream the events generated during a turn:

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 event stream can include text_delta, tool_call, ui, cart_update, and turn_complete. On the merchant side, staged writes are represented by change_update events.

Memory extraction through update_memory is specific to this runtime path. The example hosts receive the session identifier through the X-Session-Id request header.

Use the Agent SDK runtime

The Agent SDK runs the same prompts, skills, and tools while managing the agent loop. The host prefetches grounding reads, and no work runs after the turn.

Run a single shopping request from the console:

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

Start the merchant console with:

python merchant-agent/runtime-agent-sdk/main.py

The merchant console asks for y/N approval before applying staged changes.

Deploy through Managed Agents

Managed Agents hosts the agent while using the same skills and contracts. The agent calls your MCP server for system access. Run a deployment dry run with:

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

Use the equivalent path under merchant-agent/managed-agents/ for the merchant role. Add --live only when you intend to perform a live deployment.

Scaffold your own commerce agent

The included Claude Code plugin can create a project against your stack or review an existing agent. With the repository cloned locally, register and install the plugin:

claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude

Inside Claude Code, request a shopping assistant scaffold:

/scaffold-commerce-agent a shopping assistant for our store

The command asks about your technology stack, presents its plan, and builds the project. Continue development with /add-commerce-flow and /author-commerce-evals. Use /review-commerce-agent when starting from an agent that already exists.

Connect the agents to your systems

The repository does not ship MCP connectors. Instead, both agents reach business systems through backend interfaces. Each backend method should call your service on the server side using credentials held by the host for the current session. The model receives only the method result.

1. Select the role: implement StorefrontBackend for customer shopping or MerchantBackend for staff operations.
2. Map read operations: connect catalog, policies, analytics, inventory, pricing, or other supported reads to your source-of-record systems.
3. Preserve ordered flows: if a workflow must follow a fixed sequence, enforce that sequence in the backend rather than relying on the model.
4. Control writes: keep merchant changes staged until the host approval surface authorizes them.
5. Hand off checkout: return your checkout URL from the backend and let the host render it. The model should never see the URL.

The backend can call commerce platforms or official connectors server-side. Potential integration targets mentioned by the project include analytics warehouses, finance systems, and delivery tools. Provenance gates should remain in front of writes, including when MCP servers are used with Managed Agents.

Customize capabilities and identity

Start with the smallest useful surface. A shopping pilot can implement search and product details while returning unavailable results from stubbed methods. A merchant pilot can implement the eight read methods and refuse writes, allowing digests and metrics to work without exposing a write path.

If the business lacks a capability, turn off the corresponding enable_* setting. This removes the associated tools, prompt content, and grounding rule on every runtime path. Flows that depend on an unavailable capability can be placed under skills/_staged/.

Create a custom flow by adding a directory containing SKILL.md under the appropriate skills/ directory. Use PresentationExtension for domain-specific UI. The settings brand_name, assistant_name, and brand_voice customize either agent's identity.

Safety and deployment responsibilities

The project enforces fencing, provenance gates, caps, memory validation, and merchant approvals inside tool calls across all three runtime paths. Grounding, analysis budgets, and memory extraction are runtime-level features.

These controls do not replace deployment-specific security. The examples have no authentication, and their MCP servers bind only to loopback. Your production host remains responsible for identity, authorization, business rules, compliance, credential handling, and approval policies. Review the safety guide before connecting real systems.

Verify the implementation

Install the development requirements if you need the test and lint tools:

pip install -r requirements-dev.txt

Run formatting checks, linting, tests, and repository checks:

ruff check . && ruff format --check . && pytest && python scripts/check.py

Run the full verification workflow, including deployment dry runs and web builds:

python scripts/verify_all.py

To exercise one live conversation, provide an API key and run:

python scripts/smoke_chat.py --vertical travel

Advanced tips

• Inspect cache behavior: read cache_read_input_tokens from the turn_complete event or from runtime model-call logs. A zero value on the second turn indicates that the prompt prefix changed.
• Support marketplaces: treat the seller as a search dimension and scope the merchant agent to the operator identified by the session.
• Respect account pricing: when pricing depends on an account or contract, return the price applicable to the session's account.
• Adapt checkout: if you do not own checkout, disable the cart or hand the workflow to a quote, purchase order, or hosted checkout page.
• Use platform-specific clients: the runtimes accept an anthropic client through client=, while SDK runtimes read their platform configuration from the CLI environment.
• Review deployment options: the repository documents GCP Vertex AI, AWS Bedrock, Microsoft Foundry, and gateway deployments in the deployment guide.
• Study backend mapping: identity, credentials, checkout, ordered flows, product options, and unavailable figures are covered in the backend guide.

Conclusion

Claude Commerce Agents provides a practical architecture for building customer-facing shopping assistants and approval-gated merchant tools from shared prompts, skills, contracts, and safety controls. Begin with a runnable vertical, choose the runtime that fits your platform, implement the appropriate backend interface, disable unsupported capabilities, and verify the complete system before connecting production data or write operations.

The repository is licensed under Apache License 2.0. It is a reference implementation, is not maintained, and does not accept contributions.