Anthropic 开源电商智能体蓝图，用安全审批与单循环重塑人机协同

Anthropic 于 2026 年 9 月 1 日正式开源电商智能体参考项目 anthropics/commerce-agents，该仓库上线后迅速获得 2446 颗 GitHub 星标 [0]。表面看这只是一套包含导购前端与运营后台的演示 Demo，本质上它是面向企业生产环境的一整套受控智能体（Controlled Agents）工程标准 [0]。

长期以来，电商场景下的 AI 智能体饱受“幻觉乱改价”、“私自越权下单”以及“复杂路由调度频繁死锁”等问题困扰。Anthropic 官方给出的解法非常明确：彻底放弃脆弱的多层意图分类路由，改用单一确定性对话主循环，并引入暂存变更审批机制（Staged Writes），将所有不可逆的系统写操作锁进安全箱 [0]。

架构核心：双智能体设计与单循环执行层

这套蓝图预置了两个核心智能体，覆盖完整的电商人机交互闭环：一个是面向终端消费者的购物助手（Shopping Agent），另一个是面向企业内部员工的商家运营智能体（Merchant Agent）[0]。

购物助手的核心任务是引导发现、辅助决策并完成加购。它内置了 5 个核心技能（Skills）：

搜索发现（search-discovery）：把用户的自然语言需求提炼为目录检索词，呈现结构化商品推荐 [0, 2]。
购买研究（purchase-research）：针对候选商品展开参数比对与深度评测。
规划目标（planning-goals）：处理长周期或成套预算方案（例如搭配一套露营装备）。
记忆个性化（memory-personalization）：持久化保存用户的尺码、偏好与约束。
客户关怀（customer-care）：解答物流跟踪、售后退换政策。

在落地部署时，开发者仅需实现 StorefrontBackend 接口，即可将购物助手无缝对接企业既有的商品目录、购物车、订单与知识库系统 [0]。

商家智能体则专注于业务运营与决策支持，同样内置 5 大技能：

商品目录（catalog-listings）：维护 Sku 属性、上下架状态与详情描述。
库存操作（inventory-operations）：排查库存告警、调拨建议与缺货预警。
营销活动（marketing-campaigns）：起草营销方案、文案与活动细则。
业绩洞察（performance-insights）：解读销售异动、转化率波动与品类归因。
定价促销（pricing-promotions）：模拟降价折扣并评估毛利冲击 [0, 3]。

在底层架构上，官方蓝图做出了关键取舍：废除多 Agent 之间的动态分流器（Router/Classifier）与交接（Hand-off）机制 [4]。整套系统由一个模型实例拥有完整对话流，每轮交互中模型发起的多个工具调用会并行执行，最终统一汇入单一执行器（ShoppingToolExecutor 或 MerchantToolExecutor）[4]。即使底层工具遇到错误，执行器也绝不抛出未捕获异常，而是转化为格式化错误提示回传给模型；当调用轮次触达最大工具迭代上限（max_tool_iterations）时，系统会强制进入无工具的最终回答轮次，彻底杜绝死循环 [4]。

智能体的提示词、技能描述、工具契约与安全围栏只需定义一次，即可同时运行在 Messages API、Claude Agent SDK 以及托管智能体（Managed Agents）三种运行时环境上 [0]。

动手实操：本地多垂直场景与插件脚手架

该项目基于 Python 3.11+ 和 Node.js 22 构建，预置了零售（Retail）、旅游（Travel）、电信（Telecom）以及娱乐（Entertainment）四个垂直行业的完整前端与后台 [0]。

本地运行步骤如下：


# 1. 克隆代码仓库
git clone https://github.com/anthropics/commerce-agents.git
cd commerce-agents

# 2. 创建并激活 Python 虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 3. 安装后端依赖
pip install -r requirements.txt

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入有效 ANTHROPIC_API_KEY

# 5. 安装前端示例工作区依赖
(cd examples && npm ci)

# 6. 启动零售行业演示环境（包含后端 API 与双端前端）
python scripts/run_demo.py retail --all

执行上述命令后，系统将在本地唤起完整的交互网络：

后端 API 服务：http://localhost:8000
顾客端店面（Storefront）：http://localhost:3000
商家端门户（Merchant Portal）：http://localhost:3100

若需要体验其他垂直行业，只需替换启动参数：

旅游行业：python scripts/run_demo.py travel --all（对应端口 3001 与 3101）
电信行业：python scripts/run_demo.py telecom --all（对应端口 3002 与 3102）
娱乐行业：python scripts/run_demo.py entertainment --all（对应端口 3003 与 3103）

对于深度开发者，Anthropic 还提供了 Claude Code 插件工具链 commerce-builder [0]。开发者可以直接在终端通过插件脚手架生成专属业务智能体：


# 添加官方插件市场源
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：交互式确认技术栈并生成初始工程结构 [0]。
/add-commerce-flow：为智能体扩展自定义业务技能 [0]。
/author-commerce-evals：自动编写针对电商逻辑的评测用例集 [0]。
/review-commerce-agent：静态审查已有智能体的安全边界与工具契约 [0]。

安全防线：暂存审批与定价边界硬约束

电商智能体进入生产环节的最大阻碍在于业务风控。官方蓝图建立了两套严密的防御边界：前台无敏感扣款权与后台写操作强制暂存（Staged Change） [0, 4]。

在购物助手端，结账流程（Checkout）被严格限制为“仅在前端渲染购物车与预填单”，智能体无权直接发起支付扣款或调用底层支付网关，真实的资金划扣必须留在商家原生的收银台页面由用户显式确认 [0]。

在商家后台端，所有针对商品状态、库存、价格、促销活动的修改均遵循“暂存提案机制”：


+-------------------+      调用暂存工具       +-------------------+      人工核对并点击      +-------------------+
|  Merchant Agent   | ---------------------> |   Staged Changes  | ---------------------> | Production System |
| (生成调价/改写方案) |  (stage_listing_edit) |   (待审批变更池)    |   (真正写入生产库)     | (生效应用)         |
+-------------------+                        +-------------------+                        +-------------------+

模型每次执行写操作，仅仅是向暂存区提交一份带有变更前后对比（Diff）的结构化载荷。商家运营人员必须在 UI 界面上完成人工审批（Human-in-the-loop），变更才会真正落库应用 [0]。

在定价促销（pricing-promotions）技能中，安全守则被刻画得极为苛刻 [3]：

禁止模型自行计算毛利率：大语言模型在浮点数运算上极易出错。模型必须首先调用 get_pricing_context 工具获取当前商品的基准数据，包括成本价、当前毛利率（margin_pct）、调价幅度上限（max_price_delta_pct）以及最大促销折扣（max_promotion_discount_pct）[3]。后续评估时，所有毛利波动必须严格依赖工具回传的 margin_after_pct 与 margin_impact 字段，模型不得在大脑中“估算”数字 [3]。
超限请求显式拒绝并回弹安全区间：当用户下达的指令超过策略上限（例如要求打三折，但安全规则设定最大折扣为八折）时，智能体严禁暂存超限版本以观望测试，也严禁向用户声称超限方案已被允许 [3]。智能体必须明确告知当前触发了具体哪项安全阈值，并主动提议在允许范围内的最高折扣方案（如“系统最大允许 20% 折扣，已为您按八折生成建议”）[3]。

规则分层与实战避坑指南

为了让提示词工程在复杂系统下依然清晰可控，项目采用了三级规则分层设计 [4]：

工具描述层（Tool Description）：针对单次工具调用的入参填充规则，直接写在工具定义内（例如参数格式校验）[4]。
静态系统提示词层（Static System Prompt）：覆盖大部分会话轮次的全局规则，包括暂存契约、展示排版语法、工具执行顺序以及防御越权准则 [4]。
动态技能层（Dynamic Skills）：仅在处理特定多步业务流程时按需挂载的业务专有知识（如复杂的捆绑销售逻辑）[4]。

回顾电商智能体的发展历程，其架构模式经历了三代演进：

阶段	核心问题	留下的硬伤
第一代：提示词直连 API	单个模型单轮调用工具，缺少上下文状态保持	无法处理多轮对比与渐进收窄，容易把参数填错直接报错
第二代：动态路由多分流	依靠分类器把请求分发给不同 Agent 处理	上下文在切换时频繁丢失，路由死锁，调试与复现困难
第三代：单循环 + 暂存审批	单一上下文主干驱动工具调用，写操作全部暂存待审	对底层工具契约定义要求极高，存在人工审核等待周期的状态漂移

在将这套蓝图移植到自有业务时，需要规避以下四个高频踩坑点：

不要用模型的算力去折算金额与毛利：凡涉及 margin_pct、margin_before_pct、margin_after_pct 的业务，必须由后端工具精确计算后返回，智能体只负责转述 [3]。
货币单位必须原样保留：严格采用工具输出中的原始货币符号与格式，切勿让模型擅自进行汇率转换或格式本地化缩写。
检索词必须贴合商品目录体系：在 search-discovery 技能中，消费者常使用口语化描述（如“适合送长辈且看起来显大气的杯子”），智能体必须将其映射并提炼为目录检索词汇（如“中式陶瓷茶具礼盒”），而非直接将原句塞入搜索引擎 [2]。
推荐候选展示数量保持克制：在向顾客展示商品卡片时，调用 present_products 一次推荐 3 至 6 个匹配项即可；在进入对比阶段（present_comparison）时，候选数量应收窄至 2 至 4 个，并针对用户的约束（预算、尺寸、材质）逐项展开差异对比，避免信息过载 [2]。

综合判断与落地挑战

这套电商智能体蓝图并非又一次炫技式的全自动黑盒尝试，而是将 AI 牢牢框定在建议与辅助边界内的工程化落地样板。部分开发者常误以为引入智能体就意味着让模型全面接管店铺运营，甚至自动下发调价。Anthropic 的官方实践表明，真正的企业级智能体系统，其核心竞争力在于完备的工具防错拦截与严密的权限降级设计，而非无休止地赋予模型系统写权限。

然而，该架构在落地实际生产环境时仍面临一个尚未完全解决的挑战：人工审批延迟导致的数据状态漂移（State Drift）。在实时变动的电商大促场景中，智能体基于下午 2 点的库存与销售速率生成了降价暂存方案；若运营人员直到下午 5 点才完成人工点击审批，此时底层供需关系与竞品价格可能已经发生剧烈变化。如何在审批落库的一瞬间，对已暂存方案进行轻量级的高性能二次条件校验（Optimistic Concurrency Check），仍需各业务系统结合自身的分布式事务框架自行探索与补全。