Claude’s commerce agents ship as code, writes stay staged

Anthropic’s commerce agents come down to two Python interfaces. To use the shopping agent, a team writes a StorefrontBackend over its catalog, cart, order and policy systems. To use the merchant agent, it writes a MerchantBackend over analytics, catalog, inventory, pricing and campaigns. The rest of the commerce-agents repository on Github, as it stood under Apache 2.0 on September 10, is shared code. Each agent is defined once, with its prompt, skills, tool contracts and gates, and runs on the Messages API, the Claude Agent SDK and Managed Agents.

Anthropic’s write-up accompanying the code says enterprise customers such as Shopify and Priceline already run agents that let shoppers search in plain language, compare and buy. It describes the blueprint as the harnesses, patterns and guardrails an engineering team needs to get one running in days, and names Accenture, Mastercard and Visa as solutions and ecosystem partners. None of those customers appear in the code: every company, brand, product and person in it is fictional, and the only company is ACME.

One agent, three loops

The Messages API runtime is the reference loop, and the example apps are hosts built around it. A host creates a ShoppingAgent with its backend, a path to shopping-agent/skills and a config carrying the brand name, then iterates over stream_turn. That yields text_delta, tool_call, ui, cart_update (change_update on the merchant side) and turn_complete events. After the turn, update_memory runs memory extraction. The example hosts take the session id in an X-Session-Id header.

On the Agent SDK the prompt, skills and tools stay the same, but the SDK runs the loop. The host prefetches the grounding reads, and nothing runs after the turn, so memory extraction is available only on the Messages API path. Both roles ship a console here: python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250" runs a single turn, and the merchant console approves staged changes with a y/N prompt.

Managed Agents is the hosted option: an agent over the same skills and contracts that calls an MCP server you run. Each role ships a manifest and its own MCP server, and the merchant side also gets a scheduled digest. Deployment goes through scripts/deploy_managed_agent.sh, and the --live flag deploys.

The repo separates what holds everywhere from what depends on the runtime. Fencing, provenance gates, caps, memory validation and the merchant approval gate run inside the tool call, so they hold on all three paths. Grounding, the analysis budgets and memory extraction are runtime features. For use beyond Anthropic’s own API, the runtimes take any anthropic client as client=, the SDK runtimes take the platform from the CLI environment, and docs/deployment.md covers Google Cloud Vertex AI, AWS Bedrock, Microsoft Foundry and gateways.

What never goes live

The README states the boundary in one sentence: “Nothing places an order, charges a card, or changes a live listing.”

The shopping agent searches, compares, plans, fills the cart, answers order and policy questions, and remembers what a customer tells it. Those five flows are the skills in shopping-agent/skills/. Anthropic says the guardrails are designed to keep prices and products tied to actual catalog data and to avoid manipulative upsell patterns. Checkout is a hand-off: the checkout card links to the business’s own checkout route or to a platform’s hosted checkout URL, one per seller on a marketplace. The backend returns that URL and the host renders it. The model never sees it. Payment is left to the deployer, either through an existing checkout or an agentic payments provider.

The merchant agent explains performance, maintains listings, acts on inventory and order alerts, prices and promotes, and drafts campaigns. Anthropic’s example is the agent flagging an item that is about to sell out before a promotion. Every write is a staged change, and the host’s approval surface applies it only after a person approves. The merchant core also carries its own change guardrails, next to its prompt, tool contracts and gates.

Business rules, authorization and compliance are left to the deployment. The examples have no authentication, and the MCP servers bind to loopback. docs/safety.md lists each enforced rule with its module and paths, plus what a deployment adds first.

Wiring it to your systems

Each backend method calls your service server-side with the credential the host holds for that session, and the model reads only the result. When a flow’s steps have a fixed order, the backend enforces it. docs/backends.md covers identity and credentials, ordered flows, checkout, products with options, and figures your platform cannot supply.

The same interface fits other business shapes. On a marketplace, seller becomes a search dimension and the merchant agent acts for whichever operator the session names. With account or contract pricing, the quoted price is the session account’s. A business with no checkout of its own can turn the cart off or send it to a quote, a purchase order or a hosted checkout URL.

The suggested pilot is only a slice of the agent. 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, so digests and metrics run with no write path at all. A system the business doesn’t have at all, such as a cart on a referral surface or order tracking, is an enable_* switch turned off. That removes its tools, prompt lines and grounding rule on every path, and the flows that need it get parked under skills/_staged/. The merchant config has the same switches for listing edits, inventory, pricing and campaigns.

To confirm prompt caching works, read cache_read_input_tokens from turn_complete or from the line each model call logs on its runtime’s logger. A zero on a second turn means the prefix changed.

No MCP connectors ship. Both agents reach company systems only through the backend interfaces. Where an official connector is the source of record, it is the integration target: Snowflake, BigQuery, Databricks and Amplitude for analytics, Stripe, Square, PayPal and QuickBooks for finance, Slack, Google Drive and Gmail for delivery. 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.

A new flow is a directory with a SKILL.md under either agent’s skills/. Domain UI is a PresentationExtension, and the verticals ship seven of them. brand_name, assistant_name and brand_voice on either config set the agent’s identity.

Four ACME businesses

Each vertical runs a storefront and a merchant portal over the same packages:

• Retail (storefront :3000, portal :3100): search, comparison, plans, cart, checkout and memory over the built-in components; the portal has a digest, staged restocks and listing fixes, and an analysis delegate over a SQL view.
• Travel (:3001, :3101): date-bound inventory and a present_itinerary extension; an occupancy calendar and date-window rate moves.
• Telecom (:3002, :3102): account context, a plan matrix and server-authored fee disclosures; plan mix, price moves that state the lines affected, and protected regulated fees.
• Entertainment (:3003, :3103): timed holds, waitlists, transfers, a venue map and all-in fee disclosures; event pacing, hold releases that add real capacity, and fee-preserving price moves.

Running one takes Python 3.11+ and Node 22. After cloning, pip install -r requirements.txt installs the seven packages, npm ci in examples/ sets up the eight web apps in one workspace, and python scripts/run_demo.py retail starts the API on :8000 with the storefront on :3000. --merchant starts the portal instead and --all starts both. Each vertical’s README has a Try section with the turns scripts/smoke_chat.py runs, plus single prompts paired with what a good answer does.

The plugin and the checks

For teams building their own agent there is the commerce-builder Claude Code plugin, which reads the cloned repo as its reference. /scaffold-commerce-agent a shopping assistant for our store 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.

Verification is ruff check . && ruff format --check . && pytest && python scripts/check.py, and scripts/verify_all.py adds deploy dry runs and web builds. CI installs from requirements-dev.txt 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.

The code is copyright 2026 Anthropic PBC, and the README states its status in one line: “This is a reference implementation; it is not maintained and does not accept contributions.”