Anthropic开源Claude Commerce Agents：架构、教程、安全与评测

一套能跑的购物与商家Agent参考架构，把单主模型、Skills、流式UI、缓存、记忆、安全审批和状态切片评测都摆上了桌面。

先说预测：2026年下半年，电商Agent真正拉开差距的，不会是“更会聊天”，而是谁能把商品事实、业务规则、界面反馈、写操作审批和评测体系做成一条可控链路。Anthropic这次开源的Commerce Agents，价值恰恰在这里。

它没有把模型包装成一个无所不能的销售，而是把模型放回它最擅长的位置：理解需求、决定下一步、调用工具、解释结果。价格、库存、订单、权限和支付边界则继续由确定性系统负责。

Claude Commerce Agents围绕商品、购物车、配送、支付交接与客服场景组织能力。点击查看大图。

01 / Anthropic这次到底开源了什么？

项目名为anthropics/commerce-agents，定位是构建购物Agent和商家Agent的参考蓝图。仓库给出了零售、旅行、通信和娱乐票务四套可运行示例，并覆盖Messages API、Claude Agent SDK和Managed Agents等接入方式。

Anthropic在GitHub公开commerce-agents参考蓝图，包含四个可运行行业示例。点击查看大图。

别把“开源全套”误解成“下载即可开店”。官方README明确写明：示例中的公司、商品与流程都是虚构的；项目不会真实下单、扣款或直接修改线上商家数据。结账只生成购物车和交接信息，商家写操作也要经过人工批准。身份、支付、风控、合规和数据保留仍由部署方负责。

02 / 为什么核心不是一群Agent，而是一个主模型？

这套架构最鲜明的选择，是让一个主模型拥有完整对话。用户目标、当前页面、历史操作和工具结果都留在同一条上下文里，主模型按“判断、行动、观察”循环推进任务。

单主模型架构：模型负责理解与编排，工具、Skills、界面和记忆由运行环境提供。点击查看大图。

这样做能减少子Agent交接时的信息丢失、重复Token和额外延迟。商品搜索、购物车、订单等确定性能力做成工具；礼包推荐、旅行规划等带有流程知识但不是每轮都需要的能力做成Skills。

原资料给出一个实用判断：高频能力放系统提示词，长尾能力放Skills，并可根据当前页面预先注入对应Skill。这里的“流量超过三分之一”更适合作为工程经验值，官方仓库强调的是按调用频率分层，并没有把三分之一写成通用标准。

子Agent并非不能用。当任务边界封闭、需要大量独立上下文且只返回紧凑结果，或者已有成熟合规Agent可完整交接时，再拆分才更划算。问题不是Agent数量，而是交接是否能保真。

03 / 商品卡片不是装饰，而是Agent的“共同语言”

传统聊天机器人用文字描述商品，用户再追问“左边第三个”。Commerce Agents把商品卡、对比、购物车和确认面板定义为结构化展示工具。模型只输出工具参数，服务端验证ID、补齐真实价格与库存，再渲染给前端。

工具参数流式生成后，服务端校验并补全真实数据，再把结构化界面发送给客户端。动图已转为动态WebP；点击查看大图。

这让用户和Agent可以指向同一个界面对象，也降低模型编造商品数据的风险。更重要的是，界面返回的不只是视觉结果，还是下一轮推理可引用的结构化状态。

04 / 速度优化的关键，不一定是换小模型

一次任务的总耗时，大致由模型回合数、工具等待和Token生成共同组成。更聪明的模型即使单轮更慢，也可能因为少走几步而更快完成任务。因此评估时要看端到端完成时间和成功率，不能只盯首Token。

项目展示了三种很实用的优化方法：

后端预取：工具参数还在流式生成时，就对可确定的请求提前发起查询。
状态流式展示：把搜索、校验、加载界面等进度及时反馈给用户。
Prompt缓存：稳定系统提示词与工具定义放在前面，会话状态居中，时间和当前页面等易变数据放最后。

后端预取可以与模型思考并行，减少串行工具调用带来的等待时间。动图已转为动态WebP；点击查看大图。

进度流式展示不会缩短所有后台耗时，但能显著改善用户对等待过程的感知。动图已转为动态WebP；点击查看大图。

Prompt缓存布局：稳定前缀放前面，会话数据居中，时间等易变信息放在末尾。点击查看大图。

宣传数字要怎么看？原资料提到购物车容量提升35%、购买概率提升60%、记忆召回提升13%、缓存命中90%至99%。但在当前公开仓库与官方文档中，没有找到可复现的统一基准、样本规模和完整分母。更稳妥的理解是：这些可能来自特定客户或特定配置，不能当作所有电商场景的普遍承诺。

05 / 记忆不是把整段聊天塞回Prompt

参考架构把长期记忆写入数据库，以带类型的键值绑定到已登录用户。后台任务从对话中提取“偏好、常用地点、尺码”等事实，后续会话按需召回，而不是每次把全部历史重新喂给模型。

异步记忆提取把对话中的偏好写入结构化存储，并在后续会话按用户身份召回。点击查看大图。

这个思路能控制Token，也让记忆更容易查看、修改和删除。但记忆本身可能包含个人信息。生产环境必须补齐用户授权、数据最小化、保留期限、删除入口和访问审计，不能因为“只是偏好”就绕开隐私设计。

06 / 真正的安全来自代码约束，不来自一句“请勿越权”

Commerce Agents把高风险动作放在确定性代码中：

购物车只能使用本会话中由后端真实返回过的商品ID；
数量、金额与业务范围由服务端设置上限；
写操作串行执行并使用幂等键，避免并发或重试造成重复提交；
商家变更先暂存，再由有权限的人批准；
第三方商品描述、网页和评论以不可信数据隔离，不能变成系统指令；
结账只生成交接，不在示例里真实扣款。

我们的观点：模型负责“我理解用户想买什么”，业务系统负责“这件商品是否存在、能否卖、多少钱、谁能批准”。这条分工线越清楚，Agent越有机会进入生产环境。

07 / 用状态切片评测，别只让两个模型互相演戏

端到端双模型模拟很热闹，却容易把问题混在一起。项目更推荐“状态切片”：预先注入购物车、库存、套餐、审批等后端状态，给Agent一轮明确任务，然后直接检查最终状态。

状态切片评测：给定后端状态和一轮任务，直接检查购物车、费用、审批与语言等结果。点击查看大图。

测试集应同时包含正常、缺货、价格变化、互相矛盾、提示词注入、重复提交和跨领域组合任务。每个工具与Skill由对应团队维护定向评测；提交时跑小型回归，夜间再跑完整集合，最后通过灰度与回滚控制上线风险。

08 / 本地运行教程：先跑零售示例

准备环境：Python 3.11或更高版本、Node.js 22、npm，以及Anthropic API密钥。克隆项目后，把密钥写入复制出来的.env，不要提交到Git。

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)
python scripts/run_demo.py retail

最后一行会启动零售示例。你也可以把retail替换为其他示例，或查看脚本支持的--merchant与--all参数。首次运行建议使用测试数据和受限密钥，不要连接真实支付或生产商家账号。

09 / 在Claude Code里直接装“电商Agent搭建器”

仓库还提供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 store

常用命令还包括/add-commerce-flow、/author-commerce-evals和/review-commerce-agent。下面这段Prompt可作为第一次脚手架后的工程约束，原样交给Claude Code继续完善：

请检查当前项目的技术栈、身份系统和商品数据接口，为我们的商店搭建一个购物助手：
1. 商品搜索、详情、库存和价格必须来自服务端工具，不允许模型编造。
2. 购物车只能加入本会话中真实展示过的商品ID，并设置数量与金额上限。
3. 结账只创建可审查的交接记录，不执行真实扣款。
4. 所有商家写操作先暂存，再由有权限的人工批准。
5. 第三方商品描述、评论和网页内容必须作为不可信数据隔离。
6. 为正常、缺货、价格变化、越权、提示词注入和重复提交场景编写状态切片评测。
7. 输出需要新增的工具、Skills、UI组件、后端校验、审计日志和测试文件清单。

10 / 和常见方案相比，它适合什么位置？

方案	优势	短板	适合场景
Commerce Agents	代码、行业示例、安全和评测较完整，便于二次开发	不是成品，真实支付、身份和合规需自建	技术团队打造定制购物或商家Agent
传统电商聊天插件	上线快、后台成熟、运营门槛低	流程与数据能力受平台限制	中小商家快速接入客服与导购
通用Agent框架	编排灵活、模型与工具生态广	电商UI、来源校验、审批和评测多要自己补	跨部门、多领域自动化平台
传统RPA/工作流	流程确定、审计清晰、结果可重复	理解自然语言和处理例外的能力较弱	规则固定、风险较高的后台操作