项目详情

Claude Commerce Agents

Anthropic 官方蓝图：购物 Agent 与商户 Agent 该怎么建——一天 2.1k stars 的教科书

GitHub 地址 方案页 Apache-2.0 2.1k Stars / 发布首日 官方声明：不维护、不接受贡献

更新于 2026-09-06

← 返回汇总
项目速览

一句话定位

商务 Agent 的官方施工图纸

Anthropic 出品的参考蓝图：两个对称的商务 Agent——给顾客用的购物 Agent（搜索/比价/加购/答疑）与给员工用的商户 Agent（经营分析/listing 维护/定价/营销草稿）。每个只定义一次（prompt、skills、工具契约、门控），可跑在 Messages API、Claude Agent SDK、Managed Agents 三条路径上；四个垂直行业示例证明抽象层可复用。真正的价值是教科书级安全设计：一切写入先暂存待审批、checkout 只出卡片由宿主完成、模型永远看不到支付 URL。适合要给电商平台加 Agent 能力的团队抄作业。

项目速览

核心数据

2.1k
Stars（发布首日）
2
对称 Agent（购物/商户）
4
垂直行业示例
3
运行路径
363
Forks（首日）
1
Commit（发布快照）
10
pip 包分层的仓库
2026-09-01
创建日期

数据来源：GitHub API，采集于 2026-09-06。Apache-2.0；Python 3.11+ 与 Node 22 双栈；8 个 web 应用共享 workspace；4 open issues。

怎么读这个仓库

「不维护、不接受贡献」是姿态不是缺陷

  • 蓝图（blueprint）定位：License 区明确写「reference implementation; not maintained and does not accept contributions」——它是给行业抄的标准答案，不是要养的产品
  • 一天 2.1k stars 的含义：Anthropic 官方定义「商务 Agent 最佳实践」的权威背书——读它的结构比用它的代码更重要
  • 配套生态指向产品：方案页挂在 claude.com/solutions/commerce，Managed Agents 路径通向 Anthropic 托管服务——蓝图是入口，商业产品在门后
  • 所有公司品牌人物均为虚构（README 红字声明）：唯一的真公司是 ACME 示例——法律边界清晰
仓库分层（10 个 pip 包）
层内容
commerce-common两角色共享：配置/围栏/记忆/skills/grounding/执行框架/事件
*-core ×2类型、Backend 接口、prompt、工具契约、门控、执行器
*-runtime ×2Messages API turn loop / Agent SDK 两条运行路径
*-managed-agents ×2托管形态的 manifest + MCP server
examples/四垂直示例 + 共享宿主/web 代码
双 Agent 设计

镜面对称：对客的与对内的

🛍 Shopping Agent（对客） 商家嵌入自己的 App 给顾客用 五条 Flow 即 skills：搜索 / 比价 / 规划 / 购物车 / 订单与政策问答 StorefrontBackend 接口（部署方实现） catalog · cart · order · policy 系统 记忆：跨会话记住顾客说的偏好（经校验后写入） checkout 只渲染购物车卡片 → 交给宿主的 checkout 完成 🏪 Merchant Agent（对内） 员工在后台用它经营 五条 Flow：业绩解释 / listing 维护 / 库存告警 / 定价 / 营销草稿 MerchantBackend 接口（部署方实现） analytics · catalog · inventory · pricing · campaign 系统 每次写操作 = staged change，人工在审批面点击后才生效 同一套 commerce-common 库 · 同样可跑三条路径 · 镜像式职责分离
安全模型

教科书级：模型永远不碰真正的「写」

  • Staged writes：商户 Agent 的一切写操作都是「暂存变更」，宿主的审批面点确认才落库——Agent 没有直接写路径
  • Checkout 交接：购物 Agent 的 checkout 只渲染购物车卡片；结账 URL 由 backend 返回、宿主渲染，模型从头到尾看不到它——无从泄露、无从伪造
  • Fencing 围栏：prompt 注入防护内建于工具调用层，三条运行路径行为一致
  • Provenance gates：Managed Agents 上每个写操作前都有来源门
  • Caps 与预算：分析任务带预算上限；内存写入先过校验
  • docs/safety.md：每条安全规则列出模块、代码路径、部署方应补的第一步——透明到行
诚实的边界声明

README 红字：示例无认证、MCP 只绑 loopback；business rules、authorization、compliance 全部归部署方。蓝图给你安全骨架，合规外皮自己长。

渐接入策略（对集成者极友好）
  • 购物试点：只实现 search + 商品详情，其余 stub——stub 返回 unavailable 且不改一个字节的 prompt
  • 商户试点：实现 8 个读方法、写方法一律拒绝——digest 和指标照常跑
  • 没有的功能用 enable_* 开关整体摘除（连 prompt 行和 grounding 规则一起摘）
三条运行路径

一次定义，三处运行

路径谁跑循环适合
Messages API参考 turn loop 自己跑（async 事件流：text_delta/tool_call/ui/cart_update/turn_complete）想完全掌控循环的团队——examples 就是围绕它做的宿主应用
Claude Agent SDKSDK 跑循环，宿主预取 grounding、turn 后无代码执行快速落地；商户版自带 y/N 审批台
Managed AgentsAnthropic 托管；Agent 经 MCP 调你的服务器不想运维运行时；manifest 挂载角色 MCP + 定时 digest
python scripts/run_demo.py retail          # API :8000 + 店面 :3000
python shopping-agent/runtime-agent-sdk/main.py --once "250 刀以内的双人帐篷"
scripts/deploy_managed_agent.sh shopping-agent/managed-agents/...   # --live 真部署
垂直示例

四个行业，一套抽象

垂直店面演示门户演示
Retail 零售搜索/比价/规划/购物车/记忆摘要、暂存补货、SQL 分析委托
Travel 旅行日期库存 + 行程卡片扩展入住率日历、日期窗口调价
Telecom 电信账户上下文、资费矩阵、监管费用披露套餐组合、标注影响线路的调价、受保护监管费
Entertainment 票务限时锁座、候补、转让、场馆图、含费披露票量节奏、释放锁座即真实加库存、保费调价
  • 行业特有逻辑在扩展层：七个 PresentationExtension 示例（如 travel 的 present_itinerary）证明 UI 域可插拔
  • 监管敏感设计：电信的「说明影响线路数的调价」「受保护监管费不可动」，票务的「全含费披露」——合规被做成了组件
  • 每个示例 README 带 Try 清单：smoke_chat.py 可回放的对话轮次 + 单条 prompt 的好答案标准——评测即文档
  • 市场/账期/无结算台等变体都有映射说明（卖家成搜索维度、购物车可关、结账可转报价/PO/托管 URL）
工程与工具链

蓝图也带着完整的工程纪律

  • 测试矩阵：ruff lint/format + pytest + check.py；verify_all.py 加部署演练与 web 构建；CI 双 Python 版本
  • 包名保护：CI 持续检查 10 个包名未在公共 PyPI 被抢注（pin 文件只从本地目录安装）——防供应链投毒的细节
  • 缓存可观测：从 turn_complete 读 cache_read_input_tokens 验证前缀缓存命中，第二 turn 为零说明前缀变了
  • commerce-builder 插件：Claude Code marketplace 安装，/scaffold-commerce-agent 问答式脚手架、/add-commerce-flow、/author-commerce-evals、/review-commerce-agent 审查已有 Agent
部署面

运行时接受任意 anthropic client；SDK 路径吃 CLI 环境的平台配置。docs/deployment.md 覆盖 GCP Vertex AI、AWS Bedrock、Microsoft Foundry 与各类网关。

MCP 连接器策略

不内置任何 MCP。后端方法在服务端以宿主持有的凭据调你的系统，模型只见结果；官方连接器（Snowflake/Stripe/Gmail…）是集成目标而非捆绑件；provenance gates 永远在写操作之前。

风险与局限

冷静看

潜力评估

打分

维度评分依据
设计质量
对称双 Agent + 分层包 + 三路径，官方水准的结构美
安全设计
staged writes/审批门/checkout 交接/safety.md 透明到行
可复用性
四垂直 + 渐接入策略 + enable_* 开关 + scaffold 插件
持续维护
官方声明不维护不接受贡献——快照定位
行业影响
首日 2.1k stars，正在定义「商务 Agent 该长什么样」

综合 8/10。把它当「付费教材」读：Anthropic 用一个仓库回答了「可落地的商务 Agent 该有什么骨架、哪些安全边界、怎么渐进接入」。代码是快照，知识是资产。

最终裁决

适合谁，不适合谁

精读 + 抄作业
  • 电商平台要加购物助手或商户后台 Agent——先抄结构再接系统
  • 研究「Agent 怎么安全地碰交易」——staged writes 与 checkout 交接是范本
  • 用 commerce-builder 插件给自己的栈快速 scaffold 一个原型
  • 想学 Anthropic 官方 Agent 分层与门控设计的所有开发者
别指望
  • 开箱即用的产品（无认证、虚构数据、需自接全部后端）
  • 持续更新与社区支持（官方明说不维护）
  • 非 Claude 模型路线（三条路径全绑 Anthropic 生态）
上一个
OpenWiki
下一个
NoSignups
在线体验

商户审批台模拟器

体验 Merchant Agent 的安全内核：Agent 提出暂存变更（调价/补货/营销），你在审批台逐条批准或驳回——降价超帽会被自动拦截。这正是「模型永不直接写」的 staged writes 模型。

进入 Playground →
1 / 13
← → 翻页 · 汇总 · Playground