Anthropic has published a reference implementation for commerce agents under an Apache 2.0 licence. The release, hosted at anthropics/commerce-agents, provides code for a shopping agent and a merchant agent across retail, travel, telecom and entertainment sectors.
Documentation accompanies the code in two forms: a product announcement and an engineering deep-dive titled A guide to the anatomy of effective commerce agents.
Deployment and compatibility
The repository runs locally on Python 3.11+ and Node 22. It requires an ANTHROPIC_API_KEY but accepts any anthropic client. Consequently, the code deploys on the Claude API, Amazon Bedrock, Microsoft Foundry or Google Cloud Vertex AI.
The two agents
The shopping agent operates within a merchant’s own application. It searches the catalog, manages multi-item requests, compares options, builds the cart and answers order or returns questions during the same conversation. Its five skills are search-discovery, purchase-research, planning-goals, customer-care and memory-personalization. A deployment implements a StorefrontBackend over the catalog, cart, order and policy systems.
The merchant agent supports store staff by answering sales performance questions, issuing inventory alerts and generating pricing recommendations or campaign drafts. Its skills are performance-insights, catalog-listings, inventory-operations, pricing-promotions and marketing-campaigns, operating over a MerchantBackend.
Both agents run via three methods: the Messages API, the Claude Agent SDK and Claude Managed Agents (beta). These options use a single definition for prompts, skills, tool contracts and gates. A Claude Code plugin, commerce-builder, scaffolds a new agent using /scaffold-commerce-agent or reviews an existing one with /review-commerce-agent.
Skills, not subagents
The architectural claim is the most transferable part. Anthropic argues against an intent router and against one subagent per domain. A commerce session is one tightly coupled conversation, and every handoff loses state. The orchestrator holds the cart, preferences and history, while each handoff costs several times the tokens and adds seconds of latency. Domains also overlap; a returns flow needs order history, while the cart and catalog are required simultaneously.
Agent skills provide the same modularity without that tax because skill instructions load into the agent that already holds the history. Across several enterprise deployments, Anthropic reports a single agent with skills beat both the one-big-prompt design and the subagent design on quality, often at lower cost and latency. Subagents still earn a place for narrow, self-contained work such as deep research.
The prompt-versus-skill split is decided by frequency. Roughly a third or more of traffic goes in the system prompt, while the rest enters skills. Safety rules, brand constraints and key user facts always go in the prompt.
UI components are tools
Most commerce responses are components, not prose. Rather than prompting the model to emit custom tags, the blueprint makes each component a tool—present_products, present_itinerary, present_plan_comparison—with typed arguments the server validates before the client renders. Because those calls sit in the messages array natively, reloading history needs no custom parser, and the agent can resolve “the first hotel” from the last presentation call. For token-level streaming, eager_input_streaming: true skips server-side buffering and its schema guarantee.
Explainer: the five decisions, interactive
Latency, caching and memory
A rendered response runs 500–700 output tokens, which without streaming is five seconds of spinner. Anthropic separates end-to-end latency from perceived latency, streaming components as they form and rendering plain-language progress lines. Eager tool dispatch—executing each call as its arguments finish streaming, the Agent SDK default—reportedly cuts multi-second gaps to a few hundred milliseconds.
Prompt caching is the main cost lever. Requests are ordered global → session → volatile, since caching is prefix-based and a timestamp at the top of the system prompt breaks the cache on every request. Cached reads cost a tenth of fresh tokens, cache writes carry a ~1.25x premium, and the best deployments run at 90–99% hit rates. Memory extraction runs asynchronously in a separate process; Anthropic measured 13% higher fact recall than an in-turn save tool.
Key Takeaways
- Apache 2.0 blueprint with shopping and merchant agents, four verticals, and a Claude Code plugin.
- One agent loop plus skills outperformed subagent and single-prompt designs in Anthropic’s deployments.
- UI components ship as typed tools, so history stays native and layout is resolvable.
- Prompt caching targets 90–99% hit rates; volatile data belongs last, never first.
- Money, writes and IDs are gated in code—the model proposes, the harness applies.
What it means
Developers can now implement multi-step shopping flows without writing the underlying scaffolding. The shift from subagents to a single agent with skills reduces token usage and latency while keeping context intact. For users, this means more responsive interfaces that remember previous actions without needing to restate them.
