Anthropic open-sources Claude Commerce Agents blueprints

• Anthropic open-sourced a reference implementation for commerce agents, which ClaudeDevs' announcement describes as blueprints for shopping and merchant workflows, under an Apache 2.0 license.
• Both roles reuse prompts, skills, tool contracts, and gates across the Messages API, Claude Agent SDK, and Managed Agents, according to ClaudeDevs' repository post.
• The architecture takes an unusually firm position on orchestration: ClaudeDevs' architecture post says a single agent with skills beat both one giant prompt and subagent designs in Anthropic's enterprise comparisons.
• Anthropic says retailers running Claude shopping agents have seen carts up to 35% larger and shoppers 60% more likely to complete a purchase, per ClaudeDevs' retail metrics post.

The repository README includes runnable retail, travel, telecom, and entertainment surfaces, plus a Claude Code plugin that can scaffold against an existing backend. The accompanying engineering guide makes UI components into typed tool calls and puts checkout and merchant writes behind host-controlled approval paths.

The package separates customer conversations from back-office operations, while sharing its core libraries across four vertical demos.

• Shopping agent: searches and compares a catalog, plans multi-item purchases, fills carts, answers order and policy questions, and stores customer details.
• Merchant agent: analyzes performance, maintains listings, handles inventory and order alerts, proposes pricing or promotions, and drafts campaigns.
• Verticals: retail, travel, telecom, and entertainment. Each has a storefront and a merchant portal, including domain-specific capabilities such as itineraries, regulated fee disclosures, timed ticket holds, and waitlists.

The README makes the boundary explicit: all brands and data are fictional, checkout only renders a cart for the host to complete, and merchant changes remain staged until a person approves them.

Anthropic's central design choice is one model in an agent loop, with skills for the long tail rather than an intent router or a subagent per domain.

The architecture guide argues that cart state, preferences, and conversation history make subagent handoffs state-lossy and costly. It reserves subagents for self-contained work such as deep research, or for a domain agent that fully takes over the conversation.

The reference implementation divides its skills as follows:

• Shopping: search-discovery, purchase-research, planning-goals, customer-care, memory-personalization.
• Merchant: performance-insights, catalog-listings, inventory-operations, pricing-promotions, marketing-campaigns.

The guide's rule of thumb puts instructions relevant to roughly a third or more of traffic in the system prompt, because loading a skill costs a model turn. Safety, legal and brand rules, plus facts such as allergies, stay in the prompt regardless of frequency.

The useful engineering artifact is the boundary between the model and existing commerce systems. The shopping deployment implements StorefrontBackend over catalog, cart, order, and policy systems; the merchant deployment implements MerchantBackend over analytics, catalog, inventory, pricing, and campaign systems.

• Backend methods call services server-side with host-held credentials. The model receives only the result.
• Checkout returns a host route or hosted-checkout URL, which the host renders. The model never sees the URL.
• Merchant writes become staged changes, applied only through the host's approval surface.
• Fencing, provenance gates, caps, memory validation, and the merchant approval gate run inside tool calls across all three runtimes, as documented in the safety rules.

No connectors ship in the repository. The backend guide instead places catalog, cart, checkout, warehouse, finance, or commerce-platform integrations behind those backend interfaces; Managed Agents can mount MCP servers alongside the role server while retaining provenance gates ahead of writes.

The companion guide treats task latency as the sum of time-to-last-token across turns plus tool-processing time. Its three levers are fewer turns, faster tools, and faster tokens.

The specific cost guidance is unusually concrete:

• Cached input reads cost one-tenth of fresh reads; cache writes cost about 1.25x, so a reused prefix pays for itself on its second use.
• Anthropic says its strongest commerce deployments reach 90% to 99% cache-hit rates using the default five-minute expiration.
• A prefix should be ordered as global, then session, then volatile context. A timestamp or current page at the beginning of a prompt breaks reuse on every request.
• Skills load as tool results rather than system-prompt text, letting their bodies fall into the cacheable conversation prefix.

The guide also models product carousels, itineraries, and comparison views as tools with typed arguments. Server-side validation buffers each top-level argument, while eager_input_streaming trades that validation for token-level streaming.

The repository's builder plugin installs as commerce-builder@claude-commerce-agents. Its /scaffold-commerce-agent command asks about a stack, replays a plan, and generates a project against the reference packages.

The remaining commands are:

• /add-commerce-flow
• /author-commerce-evals
• /review-commerce-agent

The quick-start path requires Python 3.11+, Node 22, and an Anthropic API key. python scripts/run_demo.py retail starts the retail API on port 8000 and storefront on 3000; --merchant selects its portal, and the other storefronts start on ports 3001 through 3003. The repo's verification routine runs Ruff, pytest, package checks, deployment dry runs, and web builds.