anthropics/commerce-agents: The Checkout URL Never Reaches the Model
Anthropic's commerce blueprint puts its safety guarantees in the shape of its interfaces instead of in its prompts, then declares itself unmaintained in the same file that explains it.
The last line of the README is the strangest thing about the repository.
This is a reference implementation; it is not maintained and does not accept contributions.
Anthropic created anthropics/commerce-agents on September 1, announced it on September 2 with quotes from Visa, Mastercard, Shopify and Intuit, and watched it climb the trending boards on September 3. It has roughly 1,500 stars, no releases, no tags, and a note saying nobody is coming to fix it.
That combination tells you how to read the thing. This is not a dependency. It is a specification of where the boundaries go, published as runnable code so you cannot argue with it, and the interesting content is what the interfaces refuse to do.
Instructions versus missing methods
Most agent safety in 2026 ships as text. You write "never issue a refund without confirmation" into a system prompt, you add a rule to a policy file, and you hope the model treats your sentence as more binding than the eleven thousand tokens of user input sitting underneath it.
commerce-agents takes the other approach almost everywhere. The guarantees are structural, and the clearest one is checkout.
From the README's "Making it yours" section, describing how a deployment wires up its own payment flow:
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.
The engineering deep dive by Matthew Koen and Ali Shazal states the general rule and then the specific mechanism: "No model tool call moves money or changes the business," and "the backend interface the agent calls has no charge method at all."
Read that second clause again. The agent cannot charge a card, and the reason is not that it was told not to. There is no function. A prompt injection that convinces Claude to place an order finds nothing to call, and a jailbreak that extracts the checkout URL finds that the URL was never in the context window to extract.
I have written the prompt-instruction version of this control more than once and it works until it does not. Deleting the method works on the worst day too.
What "staged" actually means
The merchant agent is the half that scares people, because it edits catalogs, moves inventory, changes prices and launches campaigns. Every one of those writes is staged.
The mechanism lives in docs/safety.md. With require_host_approval on, which is the default, apply_change succeeds only for IDs the host has marked approved, and the mark has to come from the operator portal's approve route or the SDK toolset's host_approve. Then the sentence that carries the whole design:
A preview card approves nothing; an approval typed in chat sets nothing.
The model can render something that looks exactly like an approval. It can produce a message saying the user said yes. Neither one moves the flag, because the flag lives outside the conversation. Guardrails also get re-checked at apply time against current limits rather than the limits in force when the change was staged, which closes the window where a price ceiling changes between proposal and execution.
Koen and Shazal compress it into a clause I expect to steal: the model's most dangerous action is to propose.
The rest of the architecture, briefly
Two agents. A shopping agent a business embeds in its own app for customers, and a merchant agent its staff use for the back office. Each is defined once as a prompt plus skills plus tool contracts plus gates, then runs three ways: the Messages API, the Claude Agent SDK, and Managed Agents.
Five skills each. Shopping covers search and discovery, purchase research, planning and goals, customer care, and memory and personalization. Merchant covers performance insights, catalog listings, inventory operations, pricing and promotions, and marketing campaigns. Anthropic's stated preference is skills ahead of subagents: "In our comparisons across several enterprise deployments, a single agent with skills consistently has outperformed both the one-prompt-for-everything design and the subagent design on quality, and often at a lower cost and latency per task." The carve-out matters, though, because the repo itself uses it. Subagents earn their place on narrow, self-contained work that benefits from its own context window, which is exactly how the merchant agent's analysis path is built on the Agent SDK. Their placement heuristic is a decent rule of thumb for any agent, not only commerce ones. Anything relevant to a third or more of your traffic goes in the system prompt. The rest goes in skills.
Four verticals ship runnable over the same libraries: retail on port 3000 with its merchant portal on 3100, travel on 3001, telecom on 3002, entertainment on 3003. Eight web apps in total, every company in them fictional.
No MCP connectors ship at all. The README is blunt about it: "None ship; both agents reach your systems through the backend interfaces." Among the named integration targets are Snowflake, BigQuery, Databricks and Amplitude for analytics, Stripe, Square, PayPal and QuickBooks for finance, and Slack, Google Drive and Gmail for delivery.
Putting this into practice
The fastest path in is not reading the source. Clone the repo so the Claude Code plugin can read it as its reference, then let the plugin scaffold against your own systems:
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
Four commands come with it: /scaffold-commerce-agent, /add-commerce-flow, /author-commerce-evals, /review-commerce-agent. The README notes that each also fires when a request matches its description, so naming it is optional.
If you want to run the examples, prerequisites are Python 3.11 or newer and Node 22, then pip install -r requirements.txt and (cd examples && npm ci). Start with retail and open both sides, the storefront on 3000 and the merchant portal on 3100, so you can watch a staged write appear in the approval surface.
Here is the move that transfers even if you never touch commerce. Take the one operation in your agent that you cannot undo, whatever it is, and check whether the model can call it. Not whether the model has been told not to. Whether the method exists on the interface you handed it. If it does, split it: one call that produces a proposal with an ID, one out-of-band surface that marks that ID approved, one apply step that re-checks limits at apply time. That is the entire pattern, and you can build it this afternoon in any framework.
Then read docs/safety.md, specifically the section called "What a deployment owns." Nine items sit on your side of the line: auth, credentials, rate limits, business rules, payment, memory treated as personal data, log hygiene, the approval surface itself, and guardrail values. That last one is a single sentence you should put in your own docs: the defaults in the two config.py modules are demonstration values.
Where it breaks
The approval story is not uniform across the three runtimes, and the repo says so rather than hiding it. On Managed Agents, the MCP server's config sets require_host_approval=False, and the platform's own always_ask prompt on apply_change becomes the approval instead. So the structural gate that impressed me on the Messages API path becomes a platform prompt on the hosted path, and Managed Agents carries a beta label in the announcement post. If you pick that runtime, you inherit a different control with different failure modes, and you should know which one you are relying on before you ship.
The examples have no authentication. The README's own words: "the examples have no authentication and the MCP servers bind to loopback." The safety doc is more direct: "The examples accept any caller; the servers accept any connection that reaches them." Loopback binding lifts as soon as an environment variable is set, and the safety doc describes that variable as one that states an authenticating gateway is in front of the server, not as anything that confirms one is.
Logging deserves a look before you turn the verbosity up. At DEBUG, request and response bodies get logged, and a request body carries every injected fact plus the whole cart. The safety doc says a DEBUG log therefore needs the retention and access controls of the memory store, which is the kind of sentence that usually shows up in a postmortem instead of a README.
The vendor numbers in the announcement should not survive into your internal deck. Anthropic writes that retailers "have seen carts up to 35% larger and shoppers 60% more likely to complete a purchase" with no methodology, no sample size, and no named customer. The Accenture quote carries an "85% are now open to collaboration with an AI agent" figure attributed to "our latest research" with no citation. Two vendor speed claims, fifteen minutes at Wix and under an hour at Fetch, are quotes rather than measurements. None of that is dishonest. None of it is evidence either.
Small thing worth knowing before you copy metadata: GitHub's own repo description lists the verticals as "retail, commerce, telecom, and entertainment." The second one should be travel. The README, the directory listing and both blog posts all name travel, and the announcement post calls the fourth one "ticketing" where the repo directory says entertainment.
And the maintenance note is real. No releases, no tags, one push, no contributions accepted. Whatever you take from this repository, you are forking a snapshot, and the bugs are yours from the moment you clone it.
Read it as a spec
I would not build a commerce product on this code. I would hand docs/safety.md to anyone on my team who is putting an agent anywhere near a system of record, because it is the clearest short statement I have read of where a model's authority should stop.
The blueprint's best idea is not a feature. It is the discovery that the safest agent design is mostly a list of functions you decided not to write. Go look at the interface your own agent calls and count how many of them you did.
Sources: anthropics/commerce-agents on GitHub (README and docs/safety.md, Apache-2.0, repo created 2026-09-01, read cache-busted 2026-09-03); Anthropic, "Building commerce agents with Claude", 2 September 2026; Matthew Koen and Ali Shazal, "A guide to the anatomy of effective commerce agents", 2 September 2026. Star count (1,491 at read) via ungh.cc cross-checked against shields.io.