Anthropic published a reference architecture for AI shopping agents on August 31, 2026: commerce-agents, Apache-2.0, on GitHub. Buried in it is a small, concrete answer to a question every merchant building for AI agents eventually asks: what does the agent actually need to call? The repo’s abstract StorefrontBackend class spells it out method by method — and one of those methods is a direct rebuttal to how the leading commerce protocol currently handles policy questions.

Nine methods, one interface

commerce-agents ships a customer-facing shopping agent and a back-office merchant agent, each defined once and runnable on the Messages API, the Claude Agent SDK, or Managed Agents. A deployment wires the shopping agent to its own systems by implementing StorefrontBackend, an abstract Python class with nine required methods grouped into four jobs:

  • Catalog — search_products (query + filters, best matches first) and get_product_details (the full record, including every variant of a product family).
  • Cart — get_cart, add_to_cart, update_cart_item, remove_from_cart. These are the only writes, and each returns the whole cart so the model never has to track state.
  • Orders and policies — get_orders, get_order, and search_policies.
  • Fulfillment — get_fulfillment_options for up to twenty product ids at once.

The interface is deliberately minimal: a pilot can implement search and product details and stub everything else, and a stubbed method just returns “unavailable” without changing a prompt byte. But search_policies is not optional, and its shape is the interesting part.

A search method, not a snapshot field

search_policies(session, query) returns a list of Policy objects — each just a policy_id, a title, an optional free-text category, and content. The reference retail example implements it as full-text search over a merchant’s own help documents: whatever the customer asks, the backend searches for it and returns whatever matches. There is no fixed list of question types the merchant has to anticipate.

That is a meaningfully different shape from how the Universal Commerce Protocol — the protocol Shopify, Google and others are converging on for cart and checkout — handles the same question. UCP’s own policy.json schema (tag v2026-08-25, fetched directly) defines Policy as a type plus a description, where type is an open reverse-DNS string but the spec’s own well-known values are exactly two: dev.ucp.shopping.policy.return and dev.ucp.shopping.policy.warranty. It’s a snapshot a merchant pre-attaches to a cart or catalog response, not a query an agent can ask. A shipping question, a damage-claim question, or anything outside return-and-warranty has no structured channel in UCP as it stands today — the exact gap this site covered on September 2.

Anthropic’s reference agent, coming from the model side of the wire rather than the protocol-standards side, sidesteps that gap entirely by making policy lookup a search tool instead of a fixed vocabulary. It’s one repo, not a standard, and it says nothing about what Shopify or any UCP-conformant platform will ship next — but it is a second, independent signal that “policies” means “answer anything, on demand” to at least one major model vendor’s own design, not “here are two pre-filled fields.”

Checkout still stops at your door

Consistent with every other Anthropic commerce surface this site has tracked, nothing in the repo places an order or moves money. The checkout method renders the cart for the host application to complete — a link to the merchant’s own checkout, a hosted checkout URL, or one link per seller on a marketplace — and the repo’s own README states plainly that “nothing places an order, charges a card, or changes a live listing.” The merchant agent’s writes are staged pending human approval before touching a live price or listing.

What this means for your store

commerce-agents is explicitly a reference implementation over a fictional store — the README says it “is not maintained and does not accept contributions” — so nothing here is a product you install. But its interface is a real, dated signal of what a model vendor expects a commerce backend to expose. Two checks worth running against your own store:

  • Can a question about shipping, damage, or a non-standard return be answered from your site’s own content, not just a static returns page? A search_policies-shaped agent will look for an answer; if the only structured channel your store offers is a return/warranty snapshot, anything else falls back to whatever the agent can scrape.
  • Does your product data expose full variant records, not just a parent SKU? The get_product_details contract expects every purchasable variant — size, color, plan — returned together, each with its own price and stock.

FAQ

Is commerce-agents a live Claude product I can install?

No. It’s an open-source reference architecture over a fictional company (“ACME”); Anthropic states in the README that it is not maintained and does not accept contributions. Its value is as a documented shape for what a shopping agent’s backend needs to expose, not as software to deploy as-is.

Does Claude’s shopping agent complete purchases automatically?

No. The checkout method only renders the cart for a human, or the host application, to complete — the repo states directly that nothing in it “places an order, charges a card, or changes a live listing.” Every merchant-agent write is staged for human approval first.

How is this different from UCP’s policy handling?

UCP’s Policy schema is a fixed snapshot with exactly two well-known types — return and warranty — attached to a specific cart or catalog response. Anthropic’s search_policies method is a query: the agent asks a free-text question and the backend searches for an answer, with no fixed list of question types.

Sources

  • Anthropic, commerce-agents — README, shopping-agent/core/shopping_agent/backend.py, shopping-agent/core/shopping_agent/types.py (commit fd4d592, fetched directly via git clone, Apache-2.0)
  • Universal Commerce Protocol, policy.json (tag v2026-08-25, fetched directly)

An agent that expects to search your policies on demand, not read a pre-filled snapshot, is exactly the gap between “the store answers a spec” and “the store answers a shopper” — which is what AgentReady’s transaction audit checks for on your own store.