Anthropic has published an architecture guide for commerce agents and open-sourced a reference implementation, anthropics/commerce-agents, on GitHub. It covers shopping agents, merchant agents, and frameworks plus evaluation tooling for four scenarios: retail, travel, telecom, and ticketing. The piece is written by Ali Shazal and Matthew Koen.
The opening recommendation is almost counterintuitive in its simplicity: one model, one standard agent loop, long-tail capabilities pushed into skills, and tools that call directly into existing backend systems.
Skills over sub-agents
The document places "skills, not sub-agents" as the first item on its list of architectural principles. The reasoning: handoffs in a sub-agent architecture are lossy for state, and quality suffers as a result. Anthropic says that in its own comparisons, a single agent paired with skills consistently outperformed both alternatives — one catch-all prompt trying to do everything, and a setup split across multiple sub-agents.
For deciding what goes into the system prompt versus what goes into skills, the guide offers a frequency rule: instructions used by more than a third of requests belong in the system prompt, and everything else goes into skills. In a shopping context, product search comes up in nearly every session, so it stays in the prompt.
UI components are also treated as tools rather than having the model emit custom tags. The tag-emitting approach has a poor reliability track record in production, since there's no strong constraint on the format of tags a model outputs.
Cache hit rate decides the latency bill
The substance of the performance section is concentrated on caching. The document states that production cache hit rates can reach 90% to 99%, and that reading from cache costs only a tenth of processing new tokens. The approach is to split each request into three fixed-order segments: a global segment holding the system prompt and tool definitions, a session segment holding user context, and a volatile segment holding current state.
One pitfall is spelled out bluntly: placing a timestamp or the current page at the top of the system prompt invalidates the cache on every request. This mistake is common in e-commerce because developers tend to put the "current cart" right at the front. The document also gives a reference figure — e-commerce responses typically run 500 to 700 output tokens.
The model-selection methodology is to run the full evaluation suite across every candidate model and every inference tier, weighing quality metrics against the latency and cost budget together rather than judging them separately.
Security can't rest on prompting alone
The production deployment section takes a firm stance: a prompt is the starting point for safe behavior, but in e-commerce it cannot be the enforcement point. Actions like payments, refunds, and price changes must all go through server-side staging and approval. The mechanism the document describes is called ID-level access control — the harness records, for every session, each ID the server has actually handed to the model, and only IDs in that record can be written or accepted for rendering. Product IDs the model invents on its own are blocked outright.
Memory is likewise pushed outside the model: long-term memory is stored in Anthropic's own database as typed records — key, value, category, and source session — with a separate thread or process reading sessions asynchronously to add, remove, or update facts. That asynchronous extraction raised fact recall by 13%.
Evaluation drops simulated multi-turn conversations in favor of a snapshot approach: build a test state, append a single user message, and score the result. The suggested starting scale is 50 to 100 test cases per user flow, with positive and negative examples paired up, covering both context-dependent requests and requests that span multiple capabilities.
Anthropic says these agents are already running in production, with enterprise customers seeing larger order values. It did not disclose specific customer names.
Sources: Anthropic official blog, GitHub repository anthropics/commerce-agents, CocoLoop; figures on cache hit rates, the 13% recall improvement, and the 500-700 output token range are all drawn from this document.