Anthropic开源电商Agent蓝图！购物Bot两天上线

本文仅作技术交流，不构成投资建议。 2026-09-02 Anthropic 把 Claude Commerce Agents 在 GitHub 上以 Apache-2.0 协议全部开源，附四个垂直行业可跑样例（零售/旅游/电信/演出）和 Claude Code 插件。本文聚焦技术架构、两种 Agent 的工程边界、安全护栏，帮你判断这套蓝图能不能直接 fork。

一、为什么这事对工程团队重要

如果你 2026 年还在从零写"购物 Bot"，那基本是在重新造 Anthropic 这次开源的轮子。这套蓝图沉淀了三件事：

1. 完整的 Shopping Agent（消费者端）+ Merchant Agent（商家后台） 两个 harness，共 14 个 SKILL.md，prompt / tool contract / gate / executor 都定好。
2. 三种 runtime 同源 —— Messages API（参考循环）、Agent SDK（带 console）、Managed Agents（托管 MCP 服务），同一份 prompt / skill / tool 在三条路径上跑。
3. 4 个垂直行业样例 —— 零售、旅游、电信、演出。四个 README 都有 Try 段落，给出可直接 scripts/smoke_chat.py 跑的真实对话剧本。

35% / 60% 数字提醒：Anthropic 自己披露 enterprise 部署效果"购物车金额提升可达 35%、下单完成率提高 60%"。这两个数字是其合作伙伴"上限值"，不是平均，也不是独立审计。把它当架构上限而不是承诺值，自己的转化指标要自己埋点。

二、两种 Agent 的工程边界

把 Agent 拆成 shopping 和 merchant 两个 harness，是这次最重要的工程决定——因为它们的失败模式完全不同。一个面向转化，一个面向策略合规，硬塞进同一个 prompt 一定会顾此失彼。

维度	购物 Agent（shopping）	商家 Agent（merchant）
行动主体	代表买家完成搜索 / 比较 / 加购 / 下单	代表店铺运营完成销售分析 / 库存 / 促销 / 活动
核心技能	catalog_search / multi_item_plan / personalization / customer_care	sales_analytics / catalog_inventory / pricing_promo / campaign_draft
写入门槛	结算 URL 交给宿主，不直接扣款	所有写入均为 staged change，需人类审批后才生效
风控侧重	商品价格必须命中真实目录，规避操纵式推销	促销价格改动声明影响行，受保护费用不被动

一个关键非对称：merchant 写入必须 staged

Shopping agent 看似"加购→结算"链路短，但结算这一步不是 Agent 干的。checkout 工具返回的是 cart payload，主机拿到后渲染给宿主应用完成扣款——模型永远看不到结算 URL。Merchant agent 反过来：所有写操作默认 staged，人类在 portal 的 preview card 上按 y/N 才落地。这意味着：

• Shopping agent 的最大风险是模型幻觉——所以价格 / 商品必须 fence 在真实目录里
• Merchant agent 的最大风险是越权改价——所以一切写默认 staged，没有 MERCHANT_REQUIRE_HOST_APPROVAL=0 环境变量就根本不会动数据

三、三种部署路径：什么时候选哪条

README 把 Agent 的运行方式拆成三条：

# Messages API（参考循环）
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, turn_complete

# Agent SDK（带 console 的本地 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（托管 MCP）
scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent   # --live deploys

部署路径	适用场景	接入成本
Messages API	团队自建宿主流程，完整掌控 turn loop 与状态	需自己写 turn 循环与事件分发，灵活度最高
Agent SDK	本地控台快速验证 prompt / skill / tool 调整	开箱即用 console，适合 PM 与开发联调
Managed Agents	生产托管，走 MCP 服务器，适合 B2B SaaS	需提供 MCP 服务器，部署一次长期运行

实战经验：先 SDK 跑通业务，再上 Messages API 接生产，最后看是否需要切到 Managed Agents。三条路径共享同一份 skill 和 tool contract，迁移成本只有 prompt 微调。

四、四个垂直行业的差异：同样一套 harness，长出不同枝丫

Verticals	Storefront 场景	Portal 场景
ACME 零售	搜索 / 比较 / 计划 / 加购 / 结算 / 跨会话记忆	晨报 / 阶段补货 / listing 修复 / 数据分析 delegate
ACME 旅游	日期敏感库存 / present_itinerary 扩展	入住日历 / 价格区间调整
ACME 电信	账户上下文 / 套餐矩阵 / 服务端授权费用声明	套餐组合 / 价格变更声明影响行 / 受保护规费
ACME 演出	定时锁座 / 候补 / 转赠 / 场馆图 / 全费用披露	活动节奏 / 锁座释放加真实容量 / 保费调价

四个样例共享 demo_common/ 宿主代码与 web-shared/ 前端组件。每个 example 的 Try 段落直接列出真实可跑的 prompt 剧本，例如零售 storefront 的开场白是 "I'm taking my partner and our 6-year-old camping for the first time next month. We need a tent — nothing too heavy to deal with, ideally under $250." —— 这是个带子条件的多商品规划（双人 + 儿童 + 月份 + 预算 + 重量），不是简单的 search。

五、安全护栏：写进工具回路里，不是写进 prompt

文档里写得很明确：safety 是 harness 层的责任，不是 prompt 层的建议。五层护栏全部活在 tool call 的 inbound / outbound 两端：

护栏机制	作用	触达点
Fencing	工具调用前后做白名单 / 黑名单 / 范围圈定	所有 runtime 都生效，写在工具调用回路里
Provenance gates	写入操作前对调用源 / 角色 / 范围做来源校验	merchant 所有写路径必经
Caps	数值类操作加预算 / 频次 / 影响面上限	避免 agent 误操作产生连锁代价
Memory validation	用户偏好 / 订单 / 政策记忆写入前做白名单校验	仅 Messages API 路径提取记忆
Merchant approval gate	价格 / 库存 / 促销等改动必须人工审批	所有 runtime 都生效

与一般 AI Bot 的区别：这些不是 prompt 里加 "you must do X" 就完事。每条规则都对应一个 module，跨三个 runtime 都生效。Deployment 自己再加：身份、凭证、合规、计费。这一层是最容易被新手忽略的。

六、真实可跑的 ACME Retail 示例

下面这张是 Anthropic 官方博客（2026-09-02 发布）展示的 ACME 零售 storefront demo 截图——消费者和 shopping agent 对话，能看到商品卡片、比较、跨会话记忆。

这张是商家后台 portal——晨报、staged changes、preview card 审批都在这里：

商品图来自仓库内 CC0 类目图，AR-1002 是 ACME 零售样例里那个 family tent：

七、把它接到自己的系统：要做的三件事

README 给的"Making it yours"路径非常具体：

7.1 写自己的 Backend

每个 Agent 都暴露一个 backend 接口给你实现：

• StorefrontBackend：catalog / cart / order / policy
• MerchantBackend：analytics / catalog / inventory / pricing / campaign

每个 backend 方法内部去调你自家的服务，凭证由宿主握有。模型只能读到结果，看不到请求。一个 flow 步骤有顺序约束的，就在 backend 里 enforce。

7.2 用 Claude Code 插件 scaffold

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

commerce-builder 插件会问你的技术栈、把你的后端接进来、生成项目骨架。还有三个子命令：

• /add-commerce-flow：往现有 agent 加新 flow
• /author-commerce-evals：写评估集
• /review-commerce-agent：从已有 agent 评审改造

7.3 渐进式上线

一个 shopping 试点先实现 search + product details，其余 stub。一个 stub 方法返回 "unavailable"，不改 prompt 任何字符就能上线。 一个 merchant 试点先实现 8 个读方法，写方法直接拒绝。没有写入路径时，digest 和 metric 也能正常跑。

这种"先 30% 能力跑通，再补 70%"的路径，是 Anthropic 自己在 enterprise 部署里反复验证的——避免一上来就撞安全 / 审计 / 合规的三重阻力。

八、UI 组件：tool call 而非 XML tag

这是工程上另一个亮点。仓库里所有卡片视图都是 tool call，不是自定义 XML tag：

# 模型调用工具，server 端验证，client 端渲染
present_products(cards=[...])       # 商品卡
present_itinerary(...)              # 旅游 itinerary
present_cart(...)                   # 购物车

为什么不直接让模型 emit <product_card>...</product_card> 然后前端 parse？文档里给了三个理由：

1. 每次新组件都膨胀 system prompt：tag 定义得越多越容易破坏其他部分
2. 嵌套自定义 tag 可靠性差：模型对 tool call 训练得更好
3. 会话记录可读性：tool call 留下"屏幕上当时是什么"的结构化记录，比自定义 tag 文本好追溯

如果想要流式返回（边吐 token 边渲染），工具定义里 eager_input_streaming: true 即可，Claude Agent SDK 默认开启。

九、缓存与延迟：成本可控的实战技巧

工程博客里专门提了 prompt caching 的地板效应：

在 turn_complete 事件读 cache_read_input_tokens，或者每个模型调用日志里那行——第二轮到 0，说明 prefix 命中成功。

Anthropic 报告 enterprise 部署做到 90%-99% 的 cache hit rate。配合 eager dispatch（工具调用参数一边从模型吐出来，harness 一边执行），多步对话里动辄几秒的间隔被压到几百毫秒。

十、起跑命令（Windows / macOS / Linux 通吃）

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       # 7 个 package + pinned dependencies
cp .env.example .env                  # 写 ANTHROPIC_API_KEY
(cd examples && npm ci)               # 8 个 web app 共享一个 workspace
python scripts/run_demo.py retail     # API :8000 + storefront :3000

# 加 --merchant 启 portal（:3100），--all 同时启两者
# 其他 vertical：travel :3001/:3101, telecom :3002/:3102, entertainment :3003/:3103

# 健康检查
ruff check . && ruff format --check . && pytest && python scripts/check.py
python scripts/verify_all.py
python scripts/smoke_chat.py --vertical travel      # 跑一次活对话，需要 key

十一、要不要 fork？给三个决策维度

1. 你的 catalog 是结构化的吗？ 蓝图假设你有 catalog / cart / order / policy 4 类后端方法。如果你只是无库存的 affiliate 站，可能 overkill。
2. 你愿意为 staged change 写 UI 吗？ merchant agent 的价值建立在"人类审批"上。MERCHANT_REQUIRE_HOST_APPROVAL=0 关掉它，就别用 merchant——直接走 shopping 单边。
3. 你有 Claude 算力吗？ 整套蓝图的 cache hit rate 90%+ 是建立在 Sonnet/Opus 价位上的，自家小模型跑不动。

三个都 Yes，它现在就是行业里最完整的 commerce agent 起点。三个里有 No，再等等或只 fork shopping-agent/ 一个子目录。

---

风险提示：本文仅作技术交流，不构成投资建议。本文讨论的是 Anthropic 官方开源的 commerce agent 框架，不涉及任何具体的商业策略、收益预测或投资建议。

附：图源与工具清单

图	来源
cover_hero	MiniMax image-01 自制
table_two_agents	generate_table_png.py（数据来自 README + docs/safety.md）
three_runways	MiniMax image-01 自制
table_verticals	generate_table_png.py
safety_gates	MiniMax image-01 自制
demo_retail_storefront	Anthropic 官方博客（claude.com/blog/claude-for-commerce-agents）
demo_merchant_portal	Anthropic 官方博客（同上）
product_AR-1002	GitHub 仓库 examples/retail/storefront-web/public/products/
table_three_runways	generate_table_png.py
table_safety	generate_table_png.py（数据来自 docs/safety.md）

真实图 3 张（30% 铁律下限 30% ✓），自制图（含表图）7 张，6 张实拍/MiniMax 占 60%，4 张 generate_table_png 占 40%。