AllWorkin / Articles / 2026.09.03

Claude官方购物agent:Claude Commerce Agents拆解这5条

Claude Commerce Agents 把导购循环钉死了。一个模型占会话,Skills 扛长尾,卡片走 tool 调用,扣款和改价不交给模型。仓库里购物和商家两套 Agent,三条运行路径共用同一套闸。

2026.09.03约 13 分钟#Agent#Claude#Skills#Prompt

用户指着商品卡说「就要左边那件红的」。这一句在店员耳朵里很清楚,在 Agent 里要成立,屏幕上那一排卡必须还在上下文里,而且顺序和渲染出来的一样。

2026 年 9 月 2 日,Anthropic 发了工程长文 The Anatomy of Effective Commerce Agents,同一天把参考实现开源成 Claude Commerce Agents。购物 Agent 和商家 Agent 共用一套循环,一个模型占住整段会话,长尾能力用 Skills 加载,工具去调你已经在跑的搜索、购物车、库存,评测拍快照,不必再演一整段对话。

官方另一篇发布说明写,零售商在 Claude 上跑购物 Agent,购物车最多大 35%,成交意愿高 60%。这是企业客户口径,不是公开榜单,别拿去当评测分。

仓库 README 第一句就写死,演示里谁都不下单、不刷卡、不改线上货架。checkout 只渲染购物车给宿主去收尾,商家侧每次写入都先暂存,等人点头。

五条先放这儿,可以先存。

Claude Commerce Agents五条

一、左边那件红的这一轮怎么转

官方发布说明里有一句现成的任务:「我要帐篷、睡袋和炉子,周末带两个孩子露营。」零售 Demo 就是奔着这种多件请求去的。

循环本身并不新。模型看目标,探上下文,调工具,按需加载 Skill,缺日期或人数就问一句,看结果,直到组好一套。前面没有意图路由器,后面也没有按品类拆开的一排领域 Agent。之前写过《AI Agent 12步全路线图Context、Tools & MCP、Loops、Graphs、Harness、Evals》,那篇讲零件,这篇落到购物会话里。

search-discovery 这份 SKILL.md 把动作写死了。默认先搜,预算、尺码、送给谁,没给就先出短名单,只有「住宿却没日期」这种搜都搜不了的才把缺口补上。一次请求里点名的每样东西各搜一次,同一轮并行。展示 3 到 6 个,推荐的放 present_products 第一个,理由只写用户自己提过的那条约束。

用户回「左边那件」时,上一轮 present_products 的参数必须按真实排版写成有序的行和轮播。参数已经在 messages 数组里,模型才能把「左边」「第三个」映射回 product_id。前端自己重排一张平面列表,指代就对不上。

子 Agent 在这里帮不上忙。购物车、偏好、整段历史都在主会话里,交接一次就要再塞一遍,官方把它叫丢状态的操作,还要多付几倍 token 和好几秒延迟。退货还要同时碰到订单、当前购物车、商品目录,领域切不干净。

子 Agent 仍有位置。深度研究这类会读文档、跑代码、走进死胡同的活,适合自带窗口,只把压缩后的答案交回来。药房或金融这种已经有独立合规面的 Agent,正确动作是交接会话所有权,让它直接跟用户把活干完,而不是每一轮弹进弹出。

二、Skills扛长尾别拆成子Agent

长文里写得很硬,企业部署里对照下来,Skills 不当子 Agent 这一套,质量和时延都压过「一个提示词包打天下」和「按领域拆子 Agent」。

系统提示还是 Skill,看频率。加载一份 Skill 要多一轮模型调用,大多数回合都要用的东西进系统提示。官方给的起点是,三分之一以上流量会碰到的,进系统提示,其余进 Skills。安全、法律、品牌约束、过敏这类关键事实,永远进系统提示。商品搜索几乎每段会话都碰,也放提示词里。

从哪个商品页或活动看板进来的,Harness 在第一次模型调用前就把对应 Skill 注进去,不必再花一轮去加载。

对照仓库,购物侧五个目录和博客一字不差,search-discovery、purchase-research、planning-goals、customer-care、memory-personalization。商家侧五个也是,performance-insights、catalog-listings、inventory-operations、pricing-promotions、marketing-campaigns。提示词里只放索引,正文等 load_skill 才进来。

工具不要重写你已经调了多年的排序、购物车、库存。search_products 交回来的结果应该已经排好序,模型只决定给谁看、看几个、怎么呈现。工具结果就是上下文,每行搜索再挂一遍图片 URL,是最常见的浪费。报错也别丢一个 403,附一句「查库存时带上商品 ID」,模型才知道下一轮怎么改。

三、卡片不是一段Markdown

大多数电商回复是商品轮播、行程、座位图、图表。团队常先让模型吐自定义标签,客户端再解析。表面长大之后会垮。模型对你的标记没有对 tool 调用那么熟,嵌套一深就不保证形状;标签定义堆在系统提示里,每加一种组件都膨胀窗口;历史还要用你自己的解析器才能读回来。

撑得住的做法是 UI 组件做成 tool。模型调用 present_products、present_itinerary、present_plan_comparison,带类型参数。服务端校验、补全,再发事件,客户端渲染。调用已经在 messages 数组里,重载旧对话不用再解析一遍。

仓库里 present_products 的契约很窄。picks 最多 12 个,每项只要 product_id 和一句不超过 140 字的理由,价格、标题、图由 UI 按 ID 去填。present_comparison 只管 2 到 4 个决选。测试里塞两个从未出现过的 ghost-1、ghost-2,展示会被拒。

代价在流式粒度。工具调用的顶层参数要在服务端攒完再校验,子组件会分步到达。官方给的开关是 eager_input_streaming: true,跳过缓冲,也跳过服务端那层 schema 保证。参考运行时对展示类 tool 套了 with_eager_input。评测里 Sonnet 及以上很少破 schema,仍要包一层重试。

时延在电商里刺耳,但官方写得很直,留存、互动、购物车大小,跟的是结果好不好、任务有没有做完,不是再抠几十毫秒。端到端和体感一起压,别拿智能换速度。

完成时延是各轮「最后一个 token 的时间加工具处理」的和,杠杆是更少轮、更快的工具、更快的 token,最小化的是这个和。从商品页打开助手,就把这一页数据放进会话。生产里一段任务超过大约五轮,更快的模型常常是更聪明的那个,因为它少绕路。独立工具同一轮并行,结果放进一条用户消息。工具参数像 token 一样往外流,Harness 可以参数一齐就派发,官方说能把好几秒的空档压到几百毫秒,Claude Agent SDK 默认就这么做,提示词里让模型先吐最慢的那次调用。

体感时延是屏幕开始动的时间。一条电商回复大约 500 到 700 个输出 token,不流式就是五秒以上转圈。展示 tool 的参数边流边画。搜集上下文时,用工具参数拼一句人话进度,比如「在找水边的酒店」,也可以加一个面向用户的短句参数。官方配过两张对照,同一套 Agent、同一套工具和提示词,只换 Harness,总时长差不多,用户看见东西的时间差一截。

四、缓存三段和安全闸

提示缓存是成本上最划算的一块。缓存读取大约是新写入的十分之一,写入大约 1.25 倍,第二次命中就回本。面向用户的量大,默认五分钟过期也能打到很高命中。官方见过最好的电商部署按 90% 到 99% 命中来设计。大约 10 万 token 时,缓存读取还大约快 1.5 到 2 倍。

缓存按前缀走,请求读到第一个不一样的字节就停。前缀按变不变排,全局段是系统提示和工具定义,跨会话字节级相同,最热,末尾打一个断点;会话段是这个用户的上下文和对话历史;易变段是当前时间和当前页,放到请求最末尾。最常见的打穿方式,是把时间戳或当前页塞进系统提示开头。

Skill 正文当成工具结果加载,落在对话前缀里一起缓存,不要追加到系统提示。每个用户回合把最新断点往前滚,搜索这种长工具结果下一轮才能从缓存读。

记忆要活过会话。三月提过坚果过敏,六月不该再问一遍。存在你自己的库里,不要存在模型里。扁平 Markdown 档案只够很小的画像。一条事实是带键、短值、类别、来源会话的小记录。商家侧按人键,不要按账号键,店长不该召回区经提过的事实。

记忆写入走异步。每轮或每隔几轮,另一条线程读对话、增删改事实,不往用户回合里加时延。官方内部记忆评测里,这样召回高 13%。让主 Agent 再调一次「保存」工具是错的,一次保存往往还要先读再去重,等于多一轮,还会跟别的决策抢注意力。抽取器只读用户和助手的文本,不读工具结果,商品描述才不会变成用户画像。读取分三层,每轮都在窗口里的固定事实,比如默认店和履约偏好;按当前请求预取,搜鞋就带尺码和品牌;其余放查找工具后面。记忆属于会话段,放在全局缓存断点之下。

安全从提示词开始,但不能停在提示词。扣款、退款、改价、上架活动,模型最危险的动作是提出,批准走你业务里已经有的先做后审。消费侧结构上就没有扣款方法,结账 tool 只渲染购物车加一颗下单按钮。商家侧每次写入产出带服务端 ID 的暂存,apply_change 只接受已经在门户按钮、CLI 确认或 Managed Agents 审批提示里通过的 ID,应用时按当时限额再查一遍。

写入和渲染只接受本会话里服务端发过的 ID。幻觉出来的、用户粘贴的、评论里种下的,后端见不到。展示 tool 也走 ID,卡片上的商品、订单、变更由服务器自己填。分析用的子 Agent 可以读数,不得往可写 ID 集合里加东西。费用和披露文案由服务器从核准稿取出,评测按字节比对。

限购按写入后的行状态执行,同一会话的购物车写入串行,避免一轮里并行两次「再加两件」叠穿。第三方内容,列表、评论、政策、卖家留言、已存记忆,进模型前都消毒、加上固定标签的围栏、限长。提示词另一半约定,围栏里的文字只用来报告,不拿来执行。

评测拍快照,不拍整段对话。API 无状态,任何会话状态都可以直接拼出来。构造测试状态,接上测试用户消息,让 Agent 跑,打分看终态和渲染,包括最后一次写入的参数。不要给路径打分,那组用例又脆又限制发挥。用第二个模型扮演用户再让裁判打整段分,取样大、贵、难归因,适合找覆盖空洞,找到了再写成快照。

一部分用例要从又长又乱、前后矛盾的历史起步。每个该拒绝的,配一个该执行的;每个该问一句的,配一个该直接做的。核心请求、指着屏幕的指代、安全注入(用户自己写的,和种在商品名、评论、网页片段里的),以及「打八五折库存够不够」这种一次跨两个能力的请求,都要两边一起打分。每个用户流程 50 到 100 条是官方给的起点。仓库插件里有现成的 /author-commerce-evals 命令。

大组织里,搜索、结账、定价、营销、客服、目录各有自己的节奏,都想改 tool、Skill 或提示词。Agent 没有严格模块边界保护别人,定价改的那一行和结账共享同一扇窗口。所有权跟着系统走,定价拥有促销工具和定价 Skill,客服拥有订单退货和客服 Skill,共享提示词有平台负责人和领域负责人。一次改动带着自己的用例走 CI,全量套件太慢也太贵,日常跑最高流量加全部安全用例,再加被改到的邻居边界。提示词改了跑全套。按几次试验的通过率、缓存命中、每轮成本设门禁,夜间和发版前跑全量。Agent 进发布日历,先金丝雀,单个 Skill 能关,高峰前冻结。

五、官方仓库能抄什么

仓库全名 Claude Commerce Agents,路径 anthropics/commerce-agents,Apache-2.0,Python。2026 年 9 月 1 日建仓,截至 9 月 3 日是千星量级、一百多个 fork。同一套提示词、Skills、工具契约,走三条路径,Messages API、Claude Agent SDK、Managed Agents(测试版)。四个可跑的垂直行业是零售、旅行、电信、票务,公司名全是虚构的 ACME。

README 要求 Python 3.11 和 Node 22。克隆、建虚拟环境、pip install -r requirements.txt,.env 里填 ANTHROPIC_API_KEY,examples 目录 npm ci,接着跑下面这条。

python scripts/run_demo.py retail

零售店面默认 3000 端口,商家门户 3100,--merchant 只开门户,--all 两个都开。SDK 控制台也可以单次跑,购物侧例子是 python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"。

Claude Code 插件从参考仓搭你自己的系统,命令如下。

claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents

对话里可以敲 /scaffold-commerce-agent、/add-commerce-flow、/author-commerce-evals、/review-commerce-agent。没有 API Key 也可以先读 docs/safety.md,里面把围栏、来源门、限购、记忆校验、商家审批,对到具体模块。

试点不必一次接完全部后端。购物侧先实现搜索和商品详情,其余方法返回不可用,占位实现不改提示词字节。商家侧先实现八个读方法,写入一律拒绝,日报和指标也能跑。StorefrontBackend 没有下单或扣款方法,结账跳转 URL 在模型调用之后由宿主渲染,模型看不见。

Cursor、Claude Code、Codex 上自己搭导购或商家助手,先把这五条对进仓库,再加模型。模型换代是改配置加评测扫描,闸和工具契约不用重写。只想在商品页挂一个问答框,先把搜索和详情接上就够。想把改价和上架交给模型,先把 apply_change 接到你现有的审批流上。


参考链接

AI工具实战派

觉得有用?每周的新笔记先发公众号。

每周的实战笔记先发在这里。扫码关注,新文章第一时间推给你。

关注 / 加入社群 →