commerce-agents README

The project's README from github.com/anthropics/commerce-agents. As one markdown file: README.md.

Claude Commerce Agents

Two commerce agents built on Claude: a shopping agent a business embeds in its app for customers, and a merchant agent its staff use to run the back office. Each is defined once (prompt, skills, tool contracts, gates) and runs on the Messages API, the Claude Agent SDK, and Managed Agents; four runnable verticals show both over the same libraries.

[!NOTE] Every company, brand, product, and person here is fictional; the only company is ACME. Nothing places an order, charges a card, or changes a live listing: checkout renders the cart for the host to complete, and every merchant write is staged until a person approves it. Business rules, authorization, and compliance are the deployment's.

Quick start: run the demos

Python 3.11+ and Node 22. Clone, install, add a key, run a 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       # the seven packages and their pinned dependencies
cp .env.example .env                  # add ANTHROPIC_API_KEY
(cd examples && npm ci)               # the eight web apps share one workspace
python scripts/run_demo.py retail     # API :8000 + storefront :3000

--merchant starts the portal instead of the storefront and --all starts both. The verticals are retail (:3000, portal :3100), travel (:3001, :3101), telecom (:3002, :3102), and entertainment (:3003, :3103); each README lists prompts to try on both surfaces.

Quick start: build your own

The 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):

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

The command asks about your stack, plays the plan back, and builds the project; /add-commerce-flow and /author-commerce-evals continue from there, and /review-commerce-agent starts from an agent that already exists (plugins/commerce-builder/). Each command also runs when a request matches its description, so naming it is optional.

The two agents

The shopping agent searches, compares, plans, fills the cart, answers order and policy questions, and remembers what a customer tells it. Its five flows are the skills in shopping-agent/skills/; a deployment implements StorefrontBackend over its catalog, cart, order, and policy systems.

The merchant agent explains performance, maintains listings, acts on inventory and order alerts, prices and promotes, and drafts campaigns; every write is a staged change the host's approval surface applies. Its five flows are the skills in merchant-agent/skills/; a deployment implements MerchantBackend over its analytics, catalog, inventory, pricing, and campaign systems.

Layout

Directory Contents pip package, import name
commerce-common/ What both roles share: config, fencing, memory, skills, grounding, presentation, executor frame, events commerce-common, commerce_common
shopping-agent/core/ Shopping types, StorefrontBackend, prompt, tool contracts, gates, executor shopping-agent-core, shopping_agent
shopping-agent/runtime-messages-api/ ShoppingAgent, the turn loop on the Messages API shopping-agent-runtime, shopping_agent_runtime
shopping-agent/runtime-agent-sdk/ The shopping agent on the Agent SDK, with a console shopping-agent-sdk, shopping_agent_sdk
shopping-agent/managed-agents/ Manifest and storefront MCP server for Managed Agents —
merchant-agent/core/ Merchant types, MerchantBackend, prompt, tool contracts, change guardrails, gates, executor merchant-agent-core, merchant_agent
merchant-agent/runtime-messages-api/ MerchantAgent and the analysis delegate on the Messages API merchant-agent-runtime, merchant_agent_runtime
merchant-agent/runtime-agent-sdk/ The merchant agent on the Agent SDK, with an approving console merchant-agent-sdk, merchant_agent_sdk
merchant-agent/managed-agents/ Manifest, merchant MCP server, scheduled digest for Managed Agents —
examples/ Four verticals, shared host code (demo_common/), shared web code (web-shared/) —
plugins/commerce-builder/ The Claude Code plugin —
docs/ safety.md (enforced rules), backends.md (mapping your systems), deployment.md (other platforms) —
tests/ Cross-package suites; each package also has its own tests/ —
scripts/ install.sh, run_demo.py, smoke_chat.py, screenshot_tour.py, check.py, deploy_managed_agent.sh, verify_all.py —

Three ways to run an agent

Messages API. The reference loop; the examples are host applications around it:

from pathlib import Path

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):
    ...   # text_delta, tool_call, ui, cart_update (change_update on the merchant side), turn_complete
await agent.update_memory(messages, session)   # memory extraction; this path only

The example hosts take the session id in an X-Session-Id header.

Agent SDK. The same prompt, skills, and tools, with the SDK running the loop; the host prefetches grounding reads, and nothing runs after the turn:

python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"
python merchant-agent/runtime-agent-sdk/main.py          # approves staged changes with y/N

Managed Agents. A hosted agent over the same skills and contracts, calling your MCP server:

scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent   # or merchant-agent/...; --live deploys

Safety

Fencing, provenance gates, caps, memory validation, and the merchant approval gate run inside the tool call and hold on all three paths; grounding, the analysis budgets, and memory extraction are runtime features. docs/safety.md lists each rule with its module and paths, and what a deployment adds first; the examples have no authentication and the MCP servers bind to loopback.

Verticals

Example Storefront Portal
examples/retail/ ACME Search, comparison, plans, cart, checkout, memory over the built-in components Digest, staged restocks and listing fixes, analysis delegate over a SQL view
examples/travel/ ACME Travel Date-bound inventory and a present_itinerary extension Occupancy calendar and date-window rate moves
examples/telecom/ ACME Mobile Account context, plan matrix, server-authored fee disclosures Plan mix, price moves that state the lines affected, protected regulated fees
examples/entertainment/ ACME Tickets Timed holds, waitlists, transfers, venue map, all-in fee disclosures Event pacing, hold releases that add real capacity, fee-preserving price moves

Each example's README has a Try section: the turns scripts/smoke_chat.py runs, and single prompts with what a good answer does.

Verify

ruff check . && ruff format --check . && pytest && python scripts/check.py
python scripts/verify_all.py                        # the line above plus deploy dry runs and web builds
python scripts/smoke_chat.py --vertical travel      # one live conversation; needs a key

requirements-dev.txt adds pytest and ruff. CI installs from it on two Python versions, builds the eight web apps, and checks that the package names stay unregistered on the public index (the pin files install them from their directories, never from the index). To confirm caching, read cache_read_input_tokens from turn_complete, or the line each model call logs on its runtime's logger: zero on a second turn means the prefix changed.

Deploying elsewhere

The runtimes take any anthropic client as client= and the SDK runtimes take the platform from the CLI environment; docs/deployment.md covers GCP Vertex AI, AWS Bedrock, Microsoft Foundry, and gateways.

MCP connectors

None 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.

Making it yours

License

Copyright 2026 Anthropic PBC. Licensed under the Apache License 2.0. This is a reference implementation; it is not maintained and does not accept contributions.

commerce-agents (anthropics/commerce-agents)

Searching Database…

3.3K ·GitHub
Commerce-agents
Что это?Референсный образец от Anthropic для создания двух видов торговых агентов на Claude: шопинг-агента, который бизнес встраивает в своё приложение для покупателей, и мерчант-агента для сотрудников, ведущих бэк-офис. В комплекте четыре запускаемых примера вертикалей (retail, travel, telecom, entertainment).
Это готовый продукт или заготовка, которую я адаптирую под свои системы?Это референсная реализация, а не продукт: шопинг- и мерчант-агенты определены один раз (промпт, навыки, контракты инструментов, проверки) и могут работать на Messages API, Claude Agent SDK или Managed Agents, а четыре вертикали — это демо-хосты, которые вы адаптируете под свой бэкенд.
Как запустить демо?Склонируйте репозиторий, установите зависимости, добавьте API-ключ и запустите выбранную вертикаль; --merchant запускает портал для сотрудников, --all — и портал, и витрину. Есть также плагин для Claude Code, который создаёт каркас нового агента под ваш стек.
Что нужно установить перед тем, как пробовать?Python 3.11+ и Node 22 для запуска демо плюс API-ключ Anthropic для вызовов модели. Плагину Claude Code дополнительно нужен сам Claude Code.
Демо реально оформляет заказы или списывает с карт?Нет. Все бренды и компании в примерах вымышлены, checkout лишь отрисовывает корзину, которую хост должен завершить, а каждая запись со стороны мерчанта ставится в очередь до одобрения человеком. Репозиторий также явно заброшен и не принимает контрибуции.
Для кого это?Для разработчиков в бизнесе сферы торговли, путешествий, телекома или развлечений, которые хотят подключить шопинг- или мерчант-агента к собственным системам витрины, заказов, склада и ценообразования, а не писать логику агента с нуля.
Можно ли запустить демо на своей машине независимо от ОС?Да, это обычный код на Python/Node без требований к конкретной ОС; примеры вертикалей работают как локальные веб-серверы (витрина и портал на отдельных портах), к которым вы обращаетесь через браузер.
Каковы три способа реального запуска агента?На «сыром» Messages API (референсный цикл ходов), на Claude Agent SDK (те же промпт/навыки/инструменты, но цикл ведёт SDK) или как Managed Agent (хостинговый агент, вызывающий ваш собственный MCP-сервер).
Что плагин Claude Code добавляет сверх примеров кода?Он создаёт каркас совершенно нового торгового агента под ваши системы (или разбирает существующий), расспрашивая о вашем стеке и собирая проект; продолжают работу последующие команды вроде /add-commerce-flow и /author-commerce-evals.
Чем шопинг-агент отличается от мерчант-агента?Шопинг-агент обращён к покупателям: он ищет, сравнивает, наполняет корзину и отвечает на вопросы о заказах и правилах. Мерчант-агент — для сотрудников: он объясняет показатели, ведёт карточки товаров и действует с инвентарём, ценами и кампаниями, причём каждая запись ставится на ожидание одобрения человеком.
Есть ли в комплекте готовые интеграции с платформами вроде Stripe или Snowflake?Коннекторов в репозитории нет; оба агента выходят на реальные системы только через бэкенд-интерфейсы, которые реализуете вы, хотя README перечисляет целевые платформы вроде Snowflake, Stripe и Slack как точки интеграции.
What are similar projects?ruflo, turnstone, open-multi-agent, qwen-code, headroom, wigolo, SuperClaude_Framework, openpencil
Which topics is it in?ecommerce, agent-framework, ci, model-context-protocol, anthropic, sdk, multi-agent, mcp-server, claude, ai-agent, framework, claude-code
Creator
anthropics
Size
1.5 MB
Stars
3.3K
Updated
CommitAug 31
Age
1mo
Commits · 90 Days