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.基于 Claude 构建的两个商务智能体：一个是企业嵌入其应用中供客户使用的购物智能体，另一个是供员工运行后台业务的商家智能体。每个智能体只需定义一次（包含提示词、技能、工具契约、门控机制），即可运行在 Messages API、Claude Agent SDK 和托管智能体（Managed Agents）上；四个可运行的垂直领域示例展示了它们如何基于相同的库运行。
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.此处提到的所有公司、品牌、产品和个人均为虚构；唯一真实的公司是 ACME。任何操作都不会实际下单、扣款或更改实时列表：结账功能仅为宿主应用渲染购物车以供完成流程，且所有商家的写入操作均处于暂存状态，直至获得人工批准。业务规则、授权和合规性均由部署方自行负责。
Python 3.11+ and Node 22. Clone, install, add a key, run a vertical:需要 Python 3.11+ 和 Node 22。克隆代码、安装依赖、添加密钥，然后运行垂直领域示例：
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.--merchant 参数将启动门户而非店面，--all 参数则同时启动两者。垂直领域包括：零售（端口 :3000，门户 :3100）、旅游（端口 :3001，:3101）、电信（端口 :3002，:3102）和娱乐（端口 :3003，:3103）；每个 README 文件中都列出了可在两个界面上尝试的提示词。
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 Code 插件可以基于这些包在你的系统上搭建智能体，或对你现有的智能体进行审查。在如上克隆代码库后（插件将其作为参考）：
claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude
/scaffold-commerce-agent a shopping assistant for our storeThe 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.该命令会询问你的技术栈、回放计划并构建项目；/add-commerce-flow 和 /author-commerce-evals 可在此基础上继续操作，/review-commerce-agent 则从现有的智能体（位于 plugins/commerce-builder/）开始。每个命令在请求匹配其描述时也会自动运行，因此无需手动命名。
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.购物智能体负责搜索、比价、规划、填充购物车、回答订单和政策问题，并能记住客户提供的信息。它的五个流程即 shopping-agent/skills/ 中的技能；部署时，StorefrontBackend 会在其目录、购物车、订单和政策系统之上实现。
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.商家智能体负责解释业务表现、维护列表、处理库存和订单警报、定价与促销，以及起草营销活动；所有写入操作均为暂存变更，需由宿主应用的批准界面进行应用。它的五个流程即 merchant-agent/skills/ 中的技能；部署时，MerchantBackend 会在其分析、目录、库存、定价和营销系统之上实现。
| 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 |
— |
Messages API. The reference loop; the examples are host applications around it:Messages API：参考循环；示例是围绕它构建的宿主应用：
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 onlyThe example hosts take the session id in an X-Session-Id header.示例宿主应用通过 X-Session-Id 标头获取会话 ID。
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:Agent SDK：使用相同的提示词、技能和工具，由 SDK 运行循环；宿主应用预取基础数据，且在回合结束后不执行任何操作：
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/NManaged Agents. A hosted agent over the same skills and contracts, calling your MCP server:托管智能体（Managed Agents）：在相同的技能和契约之上运行的托管智能体，调用你的 MCP 服务器：
scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent # or merchant-agent/...; --live deploysFencing, 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.围栏防护、来源门控、上限控制、内存验证以及商家批准门控都在工具调用内部运行，并贯穿所有三条路径；基础数据、分析预算和内存提取是运行时功能。docs/safety.md 列出了每条规则及其所属模块和路径，以及部署时应优先添加的内容；示例中不包含身份验证，且 MCP 服务器绑定到回环地址。
| 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.每个示例的 README 都有一个“尝试”部分：包含：scripts/smoke_chat.py 运行的回合脚本，以及针对良好回答的单条提示词示例。
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 keyrequirements-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.requirements-dev.txt 添加了 pytest 和 ruff。CI 会在两个 Python 版本上安装这些依赖，构建八个 Web 应用，并检查包名是否未在公共索引中注册（锁定文件从各自目录安装它们，而非从索引安装）。要确认缓存情况，请读取 turn_complete 中的 cache_read_input_tokens，或查看每个模型调用在其运行时日志记录器中打印的行：第二个回合为零表示前缀已更改。
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.运行时支持将任何 Anthropic 客户端作为 client= 传入，SDK 运行时则从 CLI 环境获取平台信息；docs/deployment.md 涵盖了 GCP Vertex AI、AWS Bedrock、Microsoft Foundry 和网关的部署。
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.不提供内置连接器；两个智能体均通过后端接口连接到你的系统。当官方连接器作为记录源时，它就是集成目标：分析仓库（Snowflake、BigQuery、Databricks、Amplitude）、金融（Stripe、Square、PayPal、QuickBooks）、交付（Slack、Google Drive、Gmail）。商务平台自身的目录、购物车或结账 MCP 服务器通过后端方法在服务端调用；在托管智能体中，清单将其挂载在角色服务器旁边，且来源门控始终位于每次写入操作之前。
- 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.
docs/backends.mdwalks through identity and credentials, ordered flows, checkout, products with options, and figures your platform cannot supply.阅读后端指南。docs/backends.md 详细介绍了身份验证与凭据、有序流程、结账、带选项的产品，以及你的平台可能无法提供的内容。 - 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.相同的接口涵盖了其他业务形态。在市场上，卖家是一个搜索维度，商家智能体代表会话中指定的运营者行事。对于账户或合同定价，报价为会话账户的价格。如果没有自己的结账系统，可以关闭购物车功能，或将其移交给报价单、采购订单或托管结账 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.结账移交：结账卡片链接到你自己的结账路由，或平台的托管结账 URL（市场上每个卖家一个）。后端返回 URL，宿主进行渲染；模型不会接触到该 URL。
- 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.从小处着手：购物试点实现搜索和产品详情，其余部分设为存根（stub）；存根方法返回不可用的结果，且不更改任何提示词字节。商家试点实现八个读取方法，写入操作则拒绝；这样可以在没有写入路径的情况下运行摘要和指标。
- 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_*switch turned off, which removes its tools, prompt lines, and grounding rule on every path; park the flows that need it underskills/_staged/. The merchant config has the same switches for listing edits, inventory, pricing, and campaigns.关闭不需要的功能：如果业务完全缺乏某个系统（如引用页面没有购物车、没有订单跟踪），可以通过关闭 enable_* 开关来移除其工具、提示词行和路径上的基础数据规则；将需要该功能的流程存放在 skills/_staged/ 下。商家配置中也有针对列表编辑、库存、定价和营销活动的类似开关。 - Add your own. A flow is a directory with a
SKILL.mdunder eitherskills/. Domain UI is aPresentationExtension(the verticals ship seven).brand_name,assistant_name, andbrand_voiceon either config set the identity.添加你自己的功能：流程是一个包含 SKILL.md 的目录，位于 skills/ 下。领域 UI 是一个 PresentationExtension（示例提供了七个）。在任一配置中设置 brand_name、assistant_name 和 brand_voice 即可确定身份。
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.版权所有 2026 Anthropic PBC。采用 Apache License 2.0 授权。这是一个参考实现；它不进行维护，也不接受贡献。
