跳到主要内容
进阶

Commerce agents blueprint (Anthropic reference)

What you'll learn
  • Understand the two-agent split (shopping vs merchant) and why Anthropic did NOT use an intent router or domain subagents
  • Learn the staged-write guardrail: how no model tool call ever moves money or mutates the store — every write ends at a human-approved surface
  • See the three runtime paths (Messages API, Agent SDK, Managed Agents) and how the SAME core code plugs into all three
  • Steal three transferable patterns for any agent that touches a real business system: server-issued IDs, fenced third-party text, and prompt-vs-skill split

On September 2, 2026 Anthropic published anthropics/commerce-agents — an Apache 2.0 reference blueprint for building shopping and merchant agents on Claude. It ships two working agents, four vertical examples (retail, travel, telecom, entertainment), and — crucially — a set of guardrail patterns implemented in code, not in prompts. Anthropic states the repo is a reference implementation they will not maintain as a product and does not accept outside contributions.

The interesting thing is not that you can now build a shopping bot. The interesting thing is the shape: an unusually opinionated take on how an agent that touches real business systems should be structured. Everything below is transferable to any agent that has to write to a real backend — inventory, customer records, banking, ops tooling.

The split: two agents, not one​

Anthropic ships one shopping agent (customer-facing) and one merchant agent (staff-facing), each with its own backend interface (StorefrontBackend and MerchantBackend) and its own set of skills. They deliberately did not build:

  • an intent router that dispatches to sub-agents
  • per-domain subagents (a "cart agent" + "returns agent" + "search agent")
  • one monolithic agent that does both consumer and staff work

Instead: one unified agent per audience, in a standard agent loop, with skills and tools. Their guidance in the anatomy of effective commerce agents post: "anything the agent needs on most turns generally goes in the system prompt" — so for a shopping agent, catalog search lives in the prompt because it's on nearly every turn. "The rest goes in skills." Customer care, personalization, returns — skills.

This is a strong opinion. Intent routers and domain subagents are the default architecture in a lot of tutorials, and Anthropic is telling you: for a single audience with tightly coupled sessions, don't.

The load-bearing guardrail: staged writes​

Pro tip
  • The single most important line in the blueprint: 'No model tool call moves money or changes the business.' Every mutation goes through a server-controlled approval step. If you take one thing from the repo, take this.

The blueprint enforces safety in code, not prompts. The mechanism has three parts:

Guided walkthrough1 of 3
  1. The server maintains a per-session record of every product ID, SKU, campaign ID, and price ID it has handed the model. Writes and renders will ONLY accept IDs from that record. If the model hallucinates a SKU, the harness refuses — no prompt engineering required.

The blueprint also handles two other classic footguns:

  • Regulated content: for fees, disclosures, and price-shown-to-consumer, the model chooses which product to disclose; the words come from server-supplied approved copy. The model never writes disclosure text.
  • Third-party text sanitization: any user-generated content (reviews, seller notes, messages) is wrapped in "fenced text" markers before it reaches the model, so it can't smuggle instructions into the prompt.

Payments: explicitly out of scope​

The blueprint places no orders and charges no cards. Checkout is rendered for the host application to complete. In Anthropic's words, this "keeps payment handling, fraud rules and credentials outside the agent." Visa, Mastercard, and Accenture are named partners on the announcement, but the payment step lives in your existing checkout or an agentic payments provider — never in the model's tool surface.

This is another opinionated line: if it can lose money in one shot, the model doesn't touch it.

Three runtime paths, one core​

The repo splits every agent into a core package (types, backend interface, prompt, tool contracts) and separate runtime packages that adapt the core to different serving surfaces:

Messages API — the reference loop

from shopping_agent import ShoppingAgentConfig
from shopping_agent_runtime import ShoppingAgent

agent = ShoppingAgent(
backend=your_backend,
skills_dir=Path("shopping-agent/skills"),
config=ShoppingAgentConfig(brand_name="Your Store"),
)
async for event in agent.stream_turn(messages, session, state):
# yields: text_delta | tool_call | ui | cart_update | turn_complete
...
await agent.update_memory(messages, session)

Agent SDK — with a local console

python shopping-agent/runtime-agent-sdk/main.py \
--once "a two-person tent under $250"

python merchant-agent/runtime-agent-sdk/main.py
# prints staged changes and waits for y/n approval

Managed Agents (beta) — hosted

scripts/deploy_managed_agent.sh \
shopping-agent/managed-agents/shopping-agent

# The manifest declares tools + a storefront MCP server;
# Anthropic hosts the loop.

The same core/ code runs under all three, which is the actual portable pattern: keep the agent's contract (tools, prompt, backend interface) separate from the serving harness. If you swap Messages API for Managed Agents six months from now, only the runtime package changes.

Memory: not in context​

Long-term memory (preferences, past orders, service notes) is persisted in your existing databases, not in model context. Extraction happens asynchronously after the conversation ends — you don't pay latency to update memory on the hot path. On the next turn, the runtime hydrates relevant memory into the system prompt.

This is worth internalizing even if you're not building commerce: shoving conversation summaries into context on every turn is a common performance mistake. The blueprint's shape — write async, read on turn-start — is the cheaper one.

The four verticals (and why they differ)​

examples/ includes end-to-end demos for four verticals, each with a different structural wrinkle you can copy:

  • Retail — the base case. Standard catalog, cart, checkout.
  • Travel — date-bound inventory (a flight seat expires), itinerary presentation with multi-leg comparison.
  • Telecom — account context ("your current plan is X"), plan matrices, regulated fee disclosure.
  • Entertainment — timed holds on tickets, waitlists, venue seat maps.

If your product isn't commerce but has any of these traits (expiring inventory, regulated disclosure, timed holds), the matching vertical is worth reading before you design your own agent.

Get it running in an afternoon​

Clone, install, run one vertical

git clone https://github.com/anthropics/commerce-agents.git
cd commerce-agents

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # add ANTHROPIC_API_KEY

(cd examples && npm ci)

python scripts/run_demo.py retail
# API on :8000, storefront on :3000

The repo verifies with ruff check . && ruff format --check . && pytest && python scripts/check.py, and there's a python scripts/verify_all.py for the comprehensive pass.

Terms worth knowing​

按 Enter 或空格键翻转卡片。使用左右方向键在卡片之间切换。已显示术语。
1 / 5

Check yourself​

Check yourself

0/4
  1. Why does the blueprint stage every write instead of relying on prompt instructions like 'never place an order without confirming'?
  2. How does the merchant agent architecture differ from the common 'router + subagent' pattern many tutorials teach?
  3. Where does long-term customer memory live in the blueprint?
  4. The blueprint 'places no orders and charges no cards.' Why?

Sources & further reading​

Next​