{"slug": "commerce-agents-reference-blueprint-for-building-shopping-and-merchant-agents", "title": "Commerce Agents: Reference blueprint for building shopping and merchant agents", "summary": "Anthropic released a reference blueprint, \"Commerce Agents,\" for building shopping and merchant agents on its Claude platform, featuring two fictional agents (a shopping agent for customers and a merchant agent for staff) that run on the Messages API, Claude Agent SDK, and Managed Agents. The open-source repository includes four runnable verticals (retail, travel, telecom, entertainment) and a Claude Code plugin to scaffold agents, with all merchant writes staged for human approval and no real orders or charges placed.", "body_md": "Two commerce agents built on Claude: a **shopping agent** a business embeds in its app for\ncustomers, and a **merchant agent** its staff use to run the back office. Each is defined\nonce (prompt, skills, tool contracts, gates) and runs on the Messages API, the Claude Agent\nSDK, and Managed Agents; four runnable verticals show both over the same libraries.\n\nNote\n\nEvery company, brand, product, and person here is fictional; the only company is ACME.\nNothing places an order, charges a card, or changes a live listing: `checkout`\n\nrenders\nthe cart for the host to complete, and every merchant write is staged until a person\napproves it. Business rules, authorization, and compliance are the deployment's.\n\nPython 3.11+ and Node 22. Clone, install, add a key, run a vertical:\n\n```\ngit clone https://github.com/anthropics/commerce-agents.git && cd commerce-agents\npython3 -m venv .venv && source .venv/bin/activate\npip install -r requirements.txt       # the seven packages and their pinned dependencies\ncp .env.example .env                  # add ANTHROPIC_API_KEY\n(cd examples && npm ci)               # the eight web apps share one workspace\npython scripts/run_demo.py retail     # API :8000 + storefront :3000\n```\n\n`--merchant`\n\nstarts the portal instead of the storefront and `--all`\n\nstarts both. The\nverticals are `retail`\n\n(:3000, portal :3100), `travel`\n\n(:3001, :3101), `telecom`\n\n(:3002,\n:3102), and `entertainment`\n\n(:3003, :3103); each README lists prompts to try on both surfaces.\n\nThe Claude Code plugin scaffolds an agent on these packages against your systems, or reviews one you have. With the repo cloned as above (the plugin reads it as the reference):\n\n```\nclaude plugin marketplace add anthropics/commerce-agents\nclaude plugin install commerce-builder@claude-commerce-agents\nclaude\n/scaffold-commerce-agent a shopping assistant for our store\n```\n\nThe command asks about your stack, plays the plan back, and builds the project; `/add-commerce-flow`\n\nand `/author-commerce-evals`\n\ncontinue from there, and `/review-commerce-agent`\n\nstarts from an agent\nthat already exists ([ plugins/commerce-builder/](/anthropics/commerce-agents/blob/main/plugins/commerce-builder)). Each command also\nruns when a request matches its description, so naming it is optional.\n\nThe **shopping agent** searches, compares, plans, fills the cart, answers order and policy\nquestions, and remembers what a customer tells it. Its five flows are the skills in\n[ shopping-agent/skills/](/anthropics/commerce-agents/blob/main/shopping-agent/skills); a deployment implements\n\n[over its catalog, cart, order, and policy systems.](/anthropics/commerce-agents/blob/main/shopping-agent/core/shopping_agent/backend.py)\n\n`StorefrontBackend`\n\nThe **merchant agent** explains performance, maintains listings, acts on inventory and order\nalerts, prices and promotes, and drafts campaigns; every write is a staged change the host's\napproval surface applies. Its five flows are the skills in [ merchant-agent/skills/](/anthropics/commerce-agents/blob/main/merchant-agent/skills);\na deployment implements\n\n[over its analytics, catalog, inventory, pricing, and campaign systems.](/anthropics/commerce-agents/blob/main/merchant-agent/core/merchant_agent/backend.py)\n\n`MerchantBackend`\n\n| Directory | Contents | pip package, `import` name |\n|---|---|---|\n`commerce-common/` |\n\n`commerce-common`\n\n, `commerce_common`\n\n`shopping-agent/core/`\n\n`StorefrontBackend`\n\n, prompt, tool contracts, gates, executor`shopping-agent-core`\n\n, `shopping_agent`\n\n`shopping-agent/runtime-messages-api/`\n\n`ShoppingAgent`\n\n, the turn loop on the Messages API`shopping-agent-runtime`\n\n, `shopping_agent_runtime`\n\n`shopping-agent/runtime-agent-sdk/`\n\n`shopping-agent-sdk`\n\n, `shopping_agent_sdk`\n\n`shopping-agent/managed-agents/`\n\n`merchant-agent/core/`\n\n`MerchantBackend`\n\n, prompt, tool contracts, change guardrails, gates, executor`merchant-agent-core`\n\n, `merchant_agent`\n\n`merchant-agent/runtime-messages-api/`\n\n`MerchantAgent`\n\nand the analysis delegate on the Messages API`merchant-agent-runtime`\n\n, `merchant_agent_runtime`\n\n`merchant-agent/runtime-agent-sdk/`\n\n`merchant-agent-sdk`\n\n, `merchant_agent_sdk`\n\n`merchant-agent/managed-agents/`\n\n`examples/`\n\n`demo_common/`\n\n), shared web code (`web-shared/`\n\n)`plugins/commerce-builder/`\n\n`docs/`\n\n`safety.md`\n\n(enforced rules), `backends.md`\n\n(mapping your systems), `deployment.md`\n\n(other platforms)`tests/`\n\n`tests/`\n\n`scripts/`\n\n`install.sh`\n\n, `run_demo.py`\n\n, `smoke_chat.py`\n\n, `screenshot_tour.py`\n\n, `check.py`\n\n, `deploy_managed_agent.sh`\n\n, `verify_all.py`\n\n**Messages API.** The reference loop; the examples are host applications around it:\n\n``` python\nfrom pathlib import Path\n\nfrom shopping_agent import ShoppingAgentConfig\nfrom shopping_agent_runtime import ShoppingAgent\n\nagent = ShoppingAgent(backend=your_backend, skills_dir=Path(\"shopping-agent/skills\"),\n                      config=ShoppingAgentConfig(brand_name=\"Your Store\"))\nasync for event in agent.stream_turn(messages, session, state):\n    ...   # text_delta, tool_call, ui, cart_update (change_update on the merchant side), turn_complete\nawait agent.update_memory(messages, session)   # memory extraction; this path only\n```\n\nThe example hosts take the session id in an `X-Session-Id`\n\nheader.\n\n**Agent SDK.** The same prompt, skills, and tools, with the SDK running the loop; the host\nprefetches grounding reads, and nothing runs after the turn:\n\n```\npython shopping-agent/runtime-agent-sdk/main.py --once \"a two-person tent under $250\"\npython merchant-agent/runtime-agent-sdk/main.py          # approves staged changes with y/N\n```\n\n**Managed Agents.** A hosted agent over the same skills and contracts, calling your MCP server:\n\n```\nscripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent   # or merchant-agent/...; --live deploys\n```\n\nFencing, provenance gates, caps, memory validation, and the merchant approval gate run\ninside the tool call and hold on all three paths; grounding, the analysis budgets, and memory\nextraction are runtime features. [ docs/safety.md](/anthropics/commerce-agents/blob/main/docs/safety.md) lists each rule with its\nmodule and paths, and what a deployment adds first; the examples have no authentication and\nthe MCP servers bind to loopback.\n\n| Example | Storefront | Portal |\n|---|---|---|\n`examples/retail/` |\n\n[ACME Travel](/anthropics/commerce-agents/blob/main/examples/travel)`examples/travel/`\n\n`present_itinerary`\n\nextension[ACME Mobile](/anthropics/commerce-agents/blob/main/examples/telecom)`examples/telecom/`\n\n[ACME Tickets](/anthropics/commerce-agents/blob/main/examples/entertainment)`examples/entertainment/`\n\nEach example's README has a `Try`\n\nsection: the turns `scripts/smoke_chat.py`\n\nruns, and single\nprompts with what a good answer does.\n\n```\nruff check . && ruff format --check . && pytest && python scripts/check.py\npython scripts/verify_all.py                        # the line above plus deploy dry runs and web builds\npython scripts/smoke_chat.py --vertical travel      # one live conversation; needs a key\n```\n\n`requirements-dev.txt`\n\nadds pytest and ruff. CI installs from it on two Python versions,\nbuilds the eight web apps, and checks that the package names stay unregistered on the\npublic index (the pin files install them from their directories, never from the index). To confirm caching, read\n`cache_read_input_tokens`\n\nfrom `turn_complete`\n\n, or the line each model call logs on its\nruntime's logger: zero on a second turn means the prefix changed.\n\nThe runtimes take any `anthropic`\n\nclient as `client=`\n\nand the SDK runtimes take the platform\nfrom the CLI environment; [ docs/deployment.md](/anthropics/commerce-agents/blob/main/docs/deployment.md) covers GCP Vertex AI, AWS Bedrock, Microsoft Foundry, and gateways.\n\nNone ship; both agents reach your systems through the backend interfaces. Where an official connector is the source of record, it is the integration target: analytics warehouses (Snowflake, BigQuery, Databricks, Amplitude), finance (Stripe, Square, PayPal, QuickBooks), delivery (Slack, Google Drive, Gmail). A commerce platform's own MCP server for catalog, cart, or checkout is called from a backend method server-side; on Managed Agents the manifest mounts it beside the role's server, and the provenance gates stay in front of every write.\n\n**Backend methods.** Each one calls your service server-side with the credential your host holds for the session; the model reads only the result. A flow whose steps have a fixed order enforces that order in the backend.**Read the backend guide.** walks through identity and credentials, ordered flows, checkout, products with options, and figures your platform cannot supply.`docs/backends.md`\n\n**The same interface covers other business shapes.** On a marketplace, seller is a search dimension and the merchant agent acts for the operator the session names. With account or contract pricing, the price quoted is the session account's. With no checkout of your own, turn the cart off or hand it to a quote, a purchase order, or a hosted checkout URL.**Checkout hands off.** 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.**Start small.** A shopping pilot implements search and product details and stubs the rest; a stubbed method returns an unavailable result and changes no prompt bytes. A merchant pilot implements the eight read methods and has the writes refuse; digests and metrics then run with no write path.**Switch off what you do not have.** A system the business lacks entirely (no cart on a referral surface, no order tracking) is an`enable_*`\n\nswitch turned off, which removes its tools, prompt lines, and grounding rule on every path; park the flows that need it under`skills/_staged/`\n\n. The merchant config has the same switches for listing edits, inventory, pricing, and campaigns.**Add your own.** A flow is a directory with a`SKILL.md`\n\nunder either`skills/`\n\n. Domain UI is a`PresentationExtension`\n\n(the verticals ship seven).`brand_name`\n\n,`assistant_name`\n\n, and`brand_voice`\n\non either config set the identity.\n\nCopyright 2026 Anthropic PBC. Licensed under the [Apache License 2.0](/anthropics/commerce-agents/blob/main/LICENSE).\nThis is a reference implementation; it is not maintained and does not accept contributions.", "url": "https://wpnews.pro/news/commerce-agents-reference-blueprint-for-building-shopping-and-merchant-agents", "canonical_source": "https://github.com/anthropics/commerce-agents", "published_at": "2026-09-02 19:56:29+00:00", "updated_at": "2026-09-02 20:22:55.583536+00:00", "lang": "en", "topics": ["ai-agents", "ai-products", "developer-tools"], "entities": ["Anthropic", "Claude", "Messages API", "Claude Agent SDK", "Managed Agents", "Claude Code", "ACME"], "alternates": {"html": "https://wpnews.pro/news/commerce-agents-reference-blueprint-for-building-shopping-and-merchant-agents", "markdown": "https://wpnews.pro/news/commerce-agents-reference-blueprint-for-building-shopping-and-merchant-agents.md", "text": "https://wpnews.pro/news/commerce-agents-reference-blueprint-for-building-shopping-and-merchant-agents.txt", "jsonld": "https://wpnews.pro/news/commerce-agents-reference-blueprint-for-building-shopping-and-merchant-agents.jsonld"}}