Claude Commerce Agents 提供的功能
Claude Commerce Agents 是基于 Claude 构建的两个商务型 AI 代理的参考实现。企业可以在面向客户的应用中嵌入购物代理，员工则可使用商家代理处理后台工作流。
每个代理都通过提示词、技能、工具契约和安全门控进行一次性定义。同一套定义可以通过 Messages API、Claude Agent SDK 或 Managed Agents 运行。四个可运行的垂直行业示例展示了该架构在零售、旅游、电信和娱乐领域的应用。
代码仓库中的所有公司、产品、品牌和人物均为虚构。示例不会下单、扣款或更新线上商品信息。结账流程会移交给宿主应用，商家侧的写入操作也会保持在暂存状态，直到获得人工批准。
了解两种代理角色
购物代理
购物代理支持面向客户的任务，例如搜索和比较商品、规划采购、填充购物车、回答订单及政策相关问题，以及记住客户提供的信息。
它的五个流程位于 shopping-agent/skills/ 下。要将该代理用于真实系统，你的部署需要基于相关的商品目录、购物车、订单和政策服务实现 StorefrontBackend。
商家代理
商家代理可帮助员工了解业务表现、维护商品信息、响应库存和订单警报、调整价格与促销活动，以及起草营销活动。它的五个流程位于 merchant-agent/skills/ 下。
部署时通过实现 MerchantBackend，将其连接到分析、商品目录、库存、定价和营销活动系统。所有写入操作都会先暂存，而不会立即应用；宿主应用必须展示并批准拟议的变更。
核心架构与功能
- 共享基础：
commerce-common/包含两种角色共用的配置、边界防护、记忆、技能处理、事实依据约束、呈现、事件和执行器框架。 - 多种运行时：同一套提示词、技能和工具契约可与 Messages API、Agent SDK 和 Managed Agents 配合使用。
- 后端抽象：代理工具调用后端接口，使你的服务器能够保管凭据并协调对业务系统的访问。
- 暂存商家变更：商家侧写入操作必须通过宿主应用的审批界面获得批准。
- 可配置功能：可以禁用不支持的功能，从而移除相应的工具、提示词内容和事实依据约束规则。
- 可扩展呈现：可以通过
PresentationExtension添加特定领域的界面。 - 可运行示例：八个 Web 应用为四个垂直行业分别提供店面和商家门户。
前提条件
安装 Python 3.11 或更高版本和 Node.js 22。你还需要一个 Anthropic API 密钥才能运行实时模型交互。
安装代码仓库
克隆项目、创建 Python 虚拟环境、安装锁定版本的 Python 依赖项、创建环境文件，并安装共享的 JavaScript 工作区：
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
(cd examples && npm ci)打开 .env 并添加你的 ANTHROPIC_API_KEY。运行 Python 脚本时，请保持虚拟环境处于激活状态。
运行第一个演示
使用以下命令启动零售店面及其 API：
python scripts/run_demo.py retail零售 API 在端口 8000 上运行，店面则在端口 3000 上运行。要启动商家门户而非店面，请添加 --merchant：
python scripts/run_demo.py retail --merchant使用 --all 同时启动两个界面：
python scripts/run_demo.py retail --all可用的垂直行业及其 Web 端口如下：
- 零售：店面
3000，商家门户3100。 - 旅游：店面
3001，商家门户3101。 - 电信：店面
3002，商家门户3102。 - 娱乐：店面
3003，商家门户3103。
每个示例目录都包含 README，其中提供建议使用的提示词，并说明高质量响应应包含哪些内容。
探索垂直行业示例
零售
ACME 零售示例展示了商品搜索、比较、规划、购物车、结账移交和记忆功能。其商家门户包括绩效摘要、暂存补货、商品信息修正，以及基于 SQL 视图的分析委托器。
旅游
ACME Travel 增加了限定日期的库存和 present_itinerary 扩展。商家侧包括入住率日历和按日期范围调整费率的功能。
电信
ACME Mobile 展示了账户上下文、套餐矩阵和由服务器生成的费用披露信息。商家工作流涵盖套餐组合和价格变更，同时保护受监管费用。
娱乐
ACME Tickets 包括限时锁定、候补名单、转让、场馆地图和全包费用披露。其商家工具涵盖活动销售节奏、可释放容量的锁定解除操作，以及保留费用的价格变更。
使用 Messages API 运行时
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):
...
await agent.update_memory(messages, session)事件流可以包含 text_delta、tool_call、ui、cart_update 和 turn_complete。在商家侧，暂存写入以 change_update 事件表示。
通过 update_memory 提取记忆是此运行时路径独有的功能。示例宿主通过 X-Session-Id 请求标头接收会话标识符。
使用 Agent SDK 运行时
Agent SDK 使用相同的提示词、技能和工具运行，同时负责管理代理循环。宿主会预取事实依据读取结果，并且轮次结束后不会再运行任何任务。
从控制台运行一次购物请求：
python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"使用以下命令启动商家控制台：
python merchant-agent/runtime-agent-sdk/main.py商家控制台在应用暂存变更前会请求 y/N 批准。
通过 Managed Agents 部署
Managed Agents 在使用相同技能和契约的同时托管代理。代理通过调用你的 MCP 服务器访问系统。使用以下命令执行部署试运行：
scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent对于商家角色，请使用 merchant-agent/managed-agents/ 下的对应路径。只有确实要执行线上部署时，才添加 --live。
搭建自己的商务代理
随附的 Claude Code 插件可以针对你的技术栈创建项目，也可以审查现有代理。在本地克隆代码仓库后，注册并安装该插件：
claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude在 Claude Code 中，请求搭建购物助手：
/scaffold-commerce-agent a shopping assistant for our store该命令会询问你的技术栈、展示实施计划并构建项目。使用 /add-commerce-flow 和 /author-commerce-evals 继续开发。如果从已有代理开始，请使用 /review-commerce-agent。
将代理连接到你的系统
该代码仓库不提供 MCP 连接器。两个代理都通过后端接口访问业务系统。每个后端方法都应使用宿主为当前会话持有的凭据，在服务器端调用你的服务。模型只会收到方法的返回结果。
- 选择角色：为面向客户的购物场景实现
StorefrontBackend，或为员工操作实现MerchantBackend。 - 映射读取操作：将商品目录、政策、分析、库存、定价或其他受支持的读取操作连接到你的权威数据源系统。
- 确保流程顺序：如果某个工作流必须遵循固定顺序，请在后端强制执行该顺序，而不要依赖模型。
- 控制写入：在宿主审批界面授权之前，始终将商家变更保持在暂存状态。
- 移交结账：从后端返回结账 URL，并让宿主负责渲染。模型绝不能看到该 URL。
后端可以在服务器端调用商务平台或官方连接器。项目提到的潜在集成目标包括分析数据仓库、财务系统和配送工具。写入操作前应始终保留来源验证门控，包括通过 Managed Agents 使用 MCP 服务器时。
自定义功能与身份
从满足需要的最小功能范围开始。购物试点可以实现搜索和商品详情，并让存根方法返回不可用结果。商家试点可以实现八个读取方法并拒绝写入，使摘要和指标功能可以正常工作，同时不开放写入路径。
如果企业不具备某项功能，请关闭对应的 enable_* 设置。这样会在所有运行时路径中移除相关工具、提示词内容和事实依据约束规则。依赖不可用功能的流程可以放在 skills/_staged/ 下。
要创建自定义流程，请在相应的 skills/ 目录下添加一个包含 SKILL.md 的目录。使用 PresentationExtension 创建特定领域的 UI。通过 brand_name、assistant_name 和 brand_voice 设置，可以自定义任一代理的身份。
安全与部署责任
项目在所有三种运行时路径的工具调用中实施边界防护、来源验证门控、上限限制、记忆验证和商家审批。事实依据约束、分析预算和记忆提取属于运行时级功能。
这些控制措施不能替代特定于部署环境的安全机制。示例不提供身份验证，其 MCP 服务器也仅绑定到回环地址。你的生产环境宿主仍需负责身份识别、授权、业务规则、合规、凭据处理和审批策略。连接真实系统之前，请查阅安全指南。
验证实现
如果需要测试和代码检查工具，请安装开发依赖项：
pip install -r requirements-dev.txt运行格式检查、代码检查、测试和代码仓库检查：
ruff check . && ruff format --check . && pytest && python scripts/check.py运行完整验证工作流，包括部署试运行和 Web 构建：
python scripts/verify_all.py要测试一次实时对话，请提供 API 密钥并运行：
python scripts/smoke_chat.py --vertical travel进阶技巧
- 检查缓存行为：从
turn_complete事件或运行时模型调用日志中读取cache_read_input_tokens。如果第二轮的值为零，表明提示词前缀发生了变化。 - 支持多商家平台：将卖家视为一个搜索维度，并将商家代理的作用域限定为会话所标识的运营方。
- 遵循账户定价：当定价取决于账户或合同时，返回适用于当前会话账户的价格。
- 调整结账方式：如果结账流程不由你控制，请禁用购物车，或将工作流移交至报价、采购订单或托管结账页面。
- 使用平台专用客户端：这些运行时通过
client=接受anthropic客户端，而 SDK 运行时则从 CLI 环境中读取平台配置。 - 查看部署选项：该代码仓库在部署指南中介绍了 GCP Vertex AI、AWS Bedrock、Microsoft Foundry 和网关部署。
- 研究后端映射：后端指南涵盖身份、凭据、结账、顺序流程、商品选项和不可用数据等内容。
总结
Claude Commerce Agents 提供了一套实用架构，可基于共享的提示词、技能、契约和安全控制构建面向客户的购物助手，以及设有审批门控的商家工具。首先选择一个可运行的垂直行业示例，然后选择适合你平台的运行时，实现相应的后端接口，禁用不支持的功能，并在连接生产数据或启用写入操作前验证完整系统。
该代码仓库采用 Apache License 2.0 许可。它是一个参考实现，不再维护，也不接受贡献。