Claude Commerce Agents
Two commerce agents built on Claude: a shopping agent a business embeds in its app for
customers, and a merchant agent its staff use to run the back office. Each is defined
once (prompt, skills, tool contracts, gates) and runs on the Messages API, the Claude Agent
SDK, and Managed Agents; four runnable verticals show both over the same libraries.
[!NOTE]
Every company, brand, product, and person here is fictional; 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 are the deployment's.
Quick start: run the demos
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.
Quick start: build your own
The Claude Code plugin scaffolds an agent on these packages against your systems, or reviews
one you have. With the repo cloned as above (the plugin reads it 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 store
The 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 (plugins/commerce-builder/). Each command also
runs when a request matches its description, so naming it is optional.
The two agents
The shopping agent searches, compares, plans, fills the cart, answers order and policy
questions, and remembers what a customer tells it. Its five flows are the skills in
shopping-agent/skills/; a deployment implements
StorefrontBackend over its catalog,
cart, order, and policy systems.
The merchant agent explains performance, maintains listings, acts on inventory and order
alerts, prices and promotes, and drafts campaigns; every write is a staged change the host's
approval surface applies. Its five flows are the skills in merchant-agent/skills/;
a deployment implements MerchantBackend over
its analytics, catalog, inventory, pricing, and campaign systems.
Layout
| Directory |
Contents |
pip package, import name |
commerce-common/ |
What both roles share: config, fencing, memory, skills, grounding, presentation, executor frame, events |
commerce-common, commerce_common |
shopping-agent/core/ |
Shopping types, StorefrontBackend, prompt, tool contracts, gates, executor |
shopping-agent-core, shopping_agent |
shopping-agent/runtime-messages-api/ |
ShoppingAgent, the turn loop on the Messages API |
shopping-agent-runtime, shopping_agent_runtime |
shopping-agent/runtime-agent-sdk/ |
The shopping agent on the Agent SDK, with a console |
shopping-agent-sdk, shopping_agent_sdk |
shopping-agent/managed-agents/ |
Manifest and storefront MCP server for Managed Agents |
— |
merchant-agent/core/ |
Merchant types, MerchantBackend, prompt, tool contracts, change guardrails, gates, executor |
merchant-agent-core, merchant_agent |
merchant-agent/runtime-messages-api/ |
MerchantAgent and the analysis delegate on the Messages API |
merchant-agent-runtime, merchant_agent_runtime |
merchant-agent/runtime-agent-sdk/ |
The merchant agent on the Agent SDK, with an approving console |
merchant-agent-sdk, merchant_agent_sdk |
merchant-agent/managed-agents/ |
Manifest, merchant MCP server, scheduled digest for Managed Agents |
— |
examples/ |
Four verticals, shared host code (demo_common/), shared web code (web-shared/) |
— |
plugins/commerce-builder/ |
The Claude Code plugin |
— |
docs/ |
safety.md (enforced rules), backends.md (mapping your systems), deployment.md (other platforms) |
— |
tests/ |
Cross-package suites; each package also has its own tests/ |
— |
scripts/ |
install.sh, run_demo.py, smoke_chat.py, screenshot_tour.py, check.py, deploy_managed_agent.sh, verify_all.py |
— |
Three ways to run an agent
Messages API. The reference loop; the examples are host applications around it:
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):
... # text_delta, tool_call, ui, cart_update (change_update on the merchant side), turn_complete
await agent.update_memory(messages, session) # memory extraction; this path only
The example hosts take the session id in an X-Session-Id header.
Agent SDK. The same prompt, skills, and tools, with the SDK running the loop; the host
prefetches grounding reads, and nothing runs after the turn:
python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"
python merchant-agent/runtime-agent-sdk/main.py # approves staged changes with y/N
Managed Agents. A hosted agent over the same skills and contracts, calling your MCP server:
scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent # or merchant-agent/...; --live deploys
Safety
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. docs/safety.md lists each rule with its
module and paths, and what a deployment adds first; the examples have no authentication and
the MCP servers bind to loopback.
Verticals
| Example |
Storefront |
Portal |
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 |
examples/travel/ ACME Travel |
Date-bound inventory and a present_itinerary extension |
Occupancy calendar and date-window rate moves |
examples/telecom/ ACME Mobile |
Account context, plan matrix, server-authored fee disclosures |
Plan mix, price moves that state the lines affected, protected regulated fees |
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 |
Each example's README has a Try section: the turns scripts/smoke_chat.py runs, and single
prompts with what a good answer does.
Verify
ruff check . && ruff format --check . && pytest && python scripts/check.py
python scripts/verify_all.py # the line above plus deploy dry runs and web builds
python scripts/smoke_chat.py --vertical travel # one live conversation; needs a key
requirements-dev.txt adds pytest and ruff. CI installs from it on two Python versions,
builds the eight web apps, and checks that the package names stay unregistered on the
public index (the pin files install them from their directories, never from the index). To confirm caching, read
cache_read_input_tokens from turn_complete, or the line each model call logs on its
runtime's logger: zero on a second turn means the prefix changed.
Deploying elsewhere
The runtimes take any anthropic client as client= and the SDK runtimes take the platform
from the CLI environment; docs/deployment.md covers GCP Vertex AI, AWS Bedrock, Microsoft Foundry, and gateways.
MCP connectors
None ship; both agents reach your systems through the backend interfaces. Where an official
connector is the source of record, it is the integration target: analytics warehouses (Snowflake,
BigQuery, Databricks, Amplitude), finance (Stripe, Square, PayPal, QuickBooks), delivery (Slack, Google Drive, Gmail).
A commerce platform's own MCP server for catalog, cart, or checkout is called from a backend
method server-side; on Managed Agents the manifest mounts it beside the role's server, and the
provenance gates stay in front of every write.
Making it yours
- Backend methods. Each one calls your service server-side with the
credential your host holds for the session; the model reads only the result. A flow whose
steps have a fixed order enforces that order in the backend.
- Read the backend guide.
docs/backends.md walks through
identity and credentials, ordered flows, checkout, products with options, and figures
your platform cannot supply.
- The same interface covers other business shapes. On a marketplace, seller is a search
dimension and the merchant agent acts for the operator the session names. With account or
contract pricing, the price quoted is the session account's. With no checkout of your
own, turn the cart off or hand it to a quote, a purchase order, or a hosted checkout URL.
- Checkout hands off. The checkout card links to your own checkout route, or to the
platform's hosted checkout URL (one per seller on a marketplace). The backend returns the
URL and the host renders it; the model never sees it.
- Start small. A shopping pilot implements search and product details and stubs the
rest; a stubbed method returns an unavailable result and changes no prompt bytes. A
merchant pilot implements the eight read methods and has the writes refuse; digests and
metrics then run with no write path.
- Switch off what you do not have. A system the business lacks entirely (no cart on a
referral surface, no order tracking) is an
enable_* switch turned off, which removes its
tools, prompt lines, and grounding rule on every path; park the flows that need it under
skills/_staged/. The merchant config has the same switches for listing edits, inventory,
pricing, and campaigns.
- Add your own. A flow is a directory with a
SKILL.md under either skills/. Domain
UI is a PresentationExtension (the verticals ship seven). brand_name,
assistant_name, and brand_voice on either config set the identity.
License
Copyright 2026 Anthropic PBC. Licensed under the Apache License 2.0.
This is a reference implementation; it is not maintained and does not accept contributions.
这是 Anthropic 出品的参考蓝图，用于构建两类由 Claude 驱动的商业智能体：一种是商家嵌入自家应用供顾客使用的购物智能体，另一种是员工用来打理后台的商家智能体。它附带四个可运行的垂直行业示例（零售、旅游、电信、娱乐）。