电商 Agent 解剖学：Anthropic 如何设计可上线的交易型 Agent

Anthropic 在 2026 年 9 月 2 日发布了工程指南 The anatomy of effective commerce agents，作者 Matthew Koen 与 Ali Shazal。过去一年，他们与零售、电商平台、旅行、娱乐和电信行业的团队一起，把 commerce agent 送上了生产环境——企业客户看到了更大的购物车和更高效的卖家运营。而这些上线的 agent 共享一个"简单到不像架构"的架构：

Claude 跑在标准 Agent Loop 里，配一组 Skills、一组工具，以及一套足够强的 Eval。

这篇文章就是这套架构的解剖报告：Part 1 讲架构（只决定一次），Part 2 讲时延与成本，Part 3 讲生产化——记忆、安全、Eval，以及如何在大组织里协作。配套参考实现 anthropics/commerce-agents 包含购物与商户两个 agent，覆盖零售、旅行、电信、票务四个垂直。同一天 Anthropic 还发了产品侧公告《Building commerce agents with Claude》，而这篇是工程侧的操作手册——可执行性更强。

几天前我从源码角度拆过这个仓库（见 《Claude Commerce Agents 源码解析》），今天换个角度：从官方设计指南出发，把"为什么这么设计"讲清楚。

一、架构：一次决定，长期受益

1.1 什么是 Commerce Agent

定义朴素：一个简化线上目录中买与卖的 agent。面向消费者的那类负责搜索、比较、替代和拼装订单——可能是零售购物车、旅行行程、手机套餐变更，或一场演出扣住的座位；面向商家那类回答销售问题、跑促销活动、管理库存与定价。

核心架构是"一个模型跑标准 Agent Loop"：推理目标、探索上下文、通过工具行动、通过 Skills 学习流程、必要时提问澄清、观察结果直到目标完成。没有前置的意图路由器，没有后面的领域子代理群。

1.2 Skills, not Subagents：为什么不做子代理

Commerce agent 要覆盖大量类目和意图，最诱人的做法是每个领域一个子代理。Anthropic 的结论是：实践上这是次优解。原因有三：

1. 电商对话是跨多意图多轮的紧耦合会话，需要大量共享上下文。子代理架构里，购物车、用户偏好、对话历史都握在 orchestrator 手里，每一次交接都是有损状态操作——交接本身还要多花几倍 token 和几秒时延。
2. 领域很少能干净切分。一个退货流程同时需要订单历史、当前购物车和商品目录。子代理方案要么在每个域复制访问权限，要么任务做到一半交接出去。
3. 模型在变聪明。每一代模型都能处理更长上下文、更多 Skills 和工具——今天的"放不下的东西"明天就放得下，placement 规则随代际松动。

Skills 提供了按领域的模块化与上下文控制，但没有交接税：技能指令按需载入进主 Agent，而主 Agent 本来就持有完整历史。作者给出的数据是：

在多次企业部署对比中，单 Agent + Skills 在质量上稳定优于「一个 Prompt 打天下」和「子代理群」两种设计，且单任务成本与时延通常更低。

那子代理什么时候用？两个例外，判断标准是对话的所有权：

• 作为工具被调用：窄而自包含的任务，值得拥有自己的上下文窗口。典型是深度研究子代理——搜索、读文档、写代码、遍历数据模型、撞死胡同，所有这些发生在子代理内部，只把一份紧凑答案返回 orchestrator。
• 整体交接（hand-off）：领域已经有自己的专用 Agent。比如药房或金融服务体验跑着一个带自己合规面的专用 Agent，正确做法是让它接管任务，用自己的 loop 直接和用户工作到任务完成。

两种模式的差别一句话：hand-off 让领域 Agent 成为用户的对端；delegation 让 orchestrator 保留主导，领域 Agent 在一个 turn 内被弹进弹出、每次交换都在降质。

1.3 System Prompt 还是 Skill：按频率划分

放指令的第一个问题是频率：加载一个 Skill 要花一个模型 turn，所以大多数 turn 都用得到的东西应该进系统 Prompt。

经验起点（作者给的锚点）：约 1/3 以上流量相关的指令进系统 Prompt，其余进 Skills——无论这个相关性是上线前预判的，还是上线后在 evals 里观察到的。如果某个 Skill 可以从已有信号预测（比如用户从哪个页面进来），建议由 harness 在第一次模型调用前注入，省掉加载 turn。

关键指令永远在系统 Prompt：安全与法律规则、品牌约束，以及关键用户事实（比如过敏信息）。

在参考实现里，购物 agent 把 grounding、购物车与结账语义、呈现规则和商品搜索放进 Prompt——因为几乎每个会话都会碰到搜索；五个 Skill 覆盖长尾：search-discovery、purchase-research、planning-goals、customer-care、memory-personalization。商户 agent 同样切分：performance-insights、catalog-listings、inventory-operations、pricing-promotions、marketing-campaigns，每个运营域一个。

1.4 工具工程：调用已有系统，结果就是上下文

Anthropic 的通用工具设计指南之外，电商场景里最重要的两点：

第一，Agent 工具必须构建在核心系统之上，而不是重实现它们。 一家电商公司已经有了搜索与排序、购物车、偏好档案、库存、促销引擎、销售分析——这些系统编码了多年调优的逻辑，看着模型永远看不到的信号。工具的边界就是"系统逻辑结束、模型判断开始"的地方：调用 search_products 时结果应该已经排好序，模型的工作是决定哪些结果服务用户目标、展示几个、怎么呈现。

第二，工具结果就是上下文。 只返回模型推理需要的字段，其余全部丢弃——每行搜索结果都带图片 URL 是最常见的"罪魁"。在工具内部重塑原始响应，必要时补上"下一步"提示。错误场景尤其重要：给模型指令而不是错误码。比如"查询可用性时请带上商品 ID"，而不是一个干巴巴的 403。

1.5 UI 组件也是工具

Commerce agent 的大多数响应不是散文，而是 UI 组件——商品轮播、旅行行程、座位图、图表。这意味着 agent 要输出的是 schema 而不是文本。

团队常从"让模型输出自定义标签、客户端解析"起步，但界面一旦长大就会崩：

• 模型对自定义 markup 的训练远不如对工具调用的训练，嵌套组件一多可靠性就掉；
• 标签定义住在系统 Prompt 里，每个新组件都膨胀上下文，每次修改都可能回归 Prompt 其他部分；
• 历史对话存成只有你自己的 parser 能读的格式，重载历史要么客户端解析原始消息，要么维护一份非原生格式的副本。

经受住考验的模式：每个 UI 组件一个工具。模型调用 present_products、present_itinerary、present_plan_comparison，带 typed 参数；服务端校验并 enrich，发事件；客户端渲染。组件作为工具调用已经以原生格式躺在 messages 数组里，重载旧对话无需重新解析。

两个细节值得记：

• 流式粒度的取舍：工具调用的每个顶层参数会在服务端缓冲校验，所以即使开了流式，presentation 工具的子组件也是分批到达。要 token 级流式就设 eager_input_streaming: true——代价是失去服务端 schema 保证。Eval 显示 Sonnet 级以上 schema 违反非常罕见，包一层 retry 兜底即可。
• 参数要反映渲染布局。当顾客说"第一家酒店"或"左边第三个"，agent 能答上来的前提是：布局就在 messages 数组里——在最后一次 presentation 调用的参数里。所以参数要按 UI 的结构组织成有序的行和轮播，而不是一个客户端再重排的扁平列表。

二、时延与成本：攻两头，靠缓存

电商场景里时延重要，消费侧最不宽容。但 Anthropic 的观察值得先摆出来：

在 agentic 界面上，稳定驱动留存、参与度和购物车大小的，是结果质量——答案是否相关、任务是否真的完成——而不是边际时延收益。

所以策略是攻两个战线：用工程手段压缩端到端时延，同时降低感知时延——因为看着 agent 干活，读起来像进度。

2.1 三个杠杆：更少轮次、更快工具、更快 token

任务完成时延 = 各模型轮次的"末 token 时间 + 工具处理时间"之和。三个杠杆有时互相竞争，要最小化的是总和而不是单项：

几个反直觉的判断：

• 上下文前置能白赚轮次：用户从商品页打开助手，这段对话大概率就是关于这个商品的，从上下文里回答不花额外轮次。
• 更快模型常常是更聪明的那个：智能模型规划工具调用更高效，总轮次更少，往往抵消更慢的 token 速度。经验阈值：查询偏复杂、或生产环境显示每任务超过约 5 轮，就值得换更聪明的模型。
• 工具边界别变成"拼接缺失后端逻辑"的地方：一个可用性检查工具如果在自己的代码里拼目录查询、多店库存、履约截止、替代规则，它已经过载了领域知识。发现自己在工具里写这种逻辑时，正确的修法是一个能回答这个问题的后端 endpoint。
• 工具派发要贪心：工具参数像 token 一样流式产出，harness 可以在参数完成的那一刻就执行——多秒级的间隙能降到几百毫秒。Claude Agent SDK 默认这么做；让模型先发最慢的调用收益最大。

2.2 感知时延：让等待看起来像进展

两招，都不碰模型：

1. 组件边生成边渲染。一次 commerce 响应通常 500–700 个输出 token，不流式就是五秒以上的 spinner。把 presentation 工具的每个参数流式发给客户端，页面渐进渲染。
2. 展示工作进度。Agent 收集上下文时，每步渲染一行进度——“正在寻找滨水酒店…"。这行文字可以从工具参数（搜索 query）构建，也可以加一个 user_facing_message 参数让模型自己写。

原文有个精彩的对比：两个面板跑同一个 agent、同样的工具和 Prompt，只有 harness 不同——总耗时几乎一样，但用户看到东西的时间完全不同。

2.3 Prompt Caching：三段式前缀缓存

缓存是最大的成本削减项，而电商流量天生适合：面向消费者的应用量大，用默认的 5 分钟过期就能做到极高的缓存水平。作者给的数字：

• 缓存输入读的价格是新鲜的 1/10；缓存写有约 1.25x 溢价，但第二次使用就回本；
• 最好的部署跑在 90–99% 缓存命中率，这是应该从一开始就按它设计的区间；
• 约 100k token 时缓存读快 1.5–2x，且随 token 数近似线性扩展。

缓存是前缀式的：请求从第一个与之前请求不同的字节开始失效，所以重要的不只是上下文里有什么，还有顺序。把请求想成三段，按变化频率排：

1. Global 全局段：大部分系统 Prompt 和工具定义，跨会话完全一致。这是最热的缓存，规模上去后基本不过期。保持逐字节一致，段尾放一个缓存断点。
2. Session 会话段：用户级上下文和对话历史，跨会话不同、会话内稳定，排在全局段之后。
3. Volatile 易变段：会话内也会变的东西——当前时间、当前页面。放在请求最后（新用户轮里的 tagged block，或支持中途系统消息的模型上以 system-role 消息追加）。

最常见的错误：把时间戳或当前页面放在系统 Prompt 顶部——这会静默破坏每一次请求的缓存。

两个实现细节：Skills 要作为工具结果加载，而不是追加进系统 Prompt，这样技能体会落在会话前缀里、跟着前缀一起被缓存；断点要每轮前移——请求允许的断点数有限，把最新的断点移到每轮用户消息末尾，每一轮都能从缓存读到累积历史（包括搜索响应这类长工具结果）。

2.4 选模型：让 Eval 扫描说话

模型尺寸与 effort 设置是同一个权衡——智能 vs 时延与成本——都应该按测量决定：

1. 定指标与底线：业务运行所依赖的质量指标（任务完成率、答案相关性、grounded 准确率）、不能低于的 eval 分数、以及 p50/p99 时延与成本预算。
2. 扫描：把整套 eval 跑遍每一个候选模型与 effort。起点建议：商户 agent 从 Opus 起步（任务偏分析），消费 agent 从 Sonnet 起步（时延权重更大）；有生产流量就按真实 query 分布加权。让数字决定——有时 Opus 5 在驱动购物车的任务上的提升值回差价，有时不值。
3. 细读结果，两个经常让团队意外的点：其一，Prompt 是给某个模型调过音的，一次扫描里其他模型可能因为没有为它写指令而被低估——小模型通常需要大模型自己就能推断的指令，大模型会字面执行小模型一直忽略的指令，淘汰任何模型前先对它的失败 case 做几轮迭代；其二，更聪明的配置有时在 p90/p99 上赢时延——token 虽慢，但规划更好、复杂请求轮次更少。

最后按每完成任务的成本衡量，而不是每次调用：一个更便宜但需要更多轮次、或更容易失败的模型并不便宜。结果接近时，选智能——质量驱动采纳与留存，也为未来六个月的模型进步留出空间。

三、生产化：记忆、安全与 Eval

3.1 记忆：住在你的系统里

长期记忆的定义朴素：让 agent 从上一次对话停下的地方继续，而不是从零开始。三月提过坚果过敏的购物者六月不该重复一遍；每周一查同样三个 campaign 的商户不该每次点名。这是一个要自己构建的系统，三部分：怎么存、怎么写、怎么读。

存储：记忆属于你的系统，不属于模型。 扁平 Markdown 档案只在规模小、且 agent 是唯一读者时可行；生产环境的务实替代就是你已在运营的数据库。一条事实是一个小型 typed record：key（shoe_size、default_store、preferred_report_cadence）、短 value、category、来源会话。有些 key 提前定好人人都有，其余由 extractor 发现。数据库保持可查询，能让你在特定属性上构建确定性行为，也能 join 已有的用户数据。

商户侧有个容易踩的坑：按人而不是按账号记。商户登录常被多位运营共享，每个 operator 要有自己的 profile，读取要尊重权限——店长的 agent 不该想起区域经理说过的某条事实。

电商的记忆装的是个人数据，往往还是最受监管的那类。四件事必须在工程上落实：决定愿意持有哪些记忆类型（用写入路径上的 validator 强制，而不是只写进 Prompt）；给用户查看、更正、删除的途径（接入账号删除与数据请求流程）；设保留期；把记忆做成按部署开关，让无法承担合规义务的区域可以关掉。

写入：异步。 每轮末尾（或长会话里每几轮），一个独立线程/进程里的 agent 读对话，创建、更新、删除事实。它不给对话加时延，且在 Anthropic 内部 commerce memory eval 上取得了 13% 更高的事实召回率。明显替代方案——让 agent 调一个保存工具——是错的：每次保存都是用户可见轮次里的一次工具调用；store 不在上下文时还得先读一次来更新去重；还让 agent 每轮多一个决策，在 evals 里表现为漏记。分离 extractor 还能精确 prompt：只读用户与助手的文本、从不读工具结果——商品描述或评论不能变成关于用户的事实。

读取：三层。 固定小集事实每轮进上下文（默认门店、履约偏好、运营的门店与角色）；与当前请求相关的事实按轮预取（用预加载 Skill 的同一批信号：搜鞋就拉尺码与品牌偏好）；其余全部躲在一个查询工具后面。记忆是 per-user 上下文，全部放在 Session 段（全局断点之下）——顺带呼应 2.3 的缓存布局。

3.2 安全：执行点在 Harness，不在 Prompt

这部分是全篇最硬核的一节，也最能解释"参考实现"四个字的分量：

Prompt 是安全行为的起点，但在商业场景里不能是安全的执行点——失败是财务性的、常常不可逆，而一条 Prompt 规则距离一次注入或一个坏样本只有一步之遥。

每条规则都在代码里执行（消费侧与商户侧双份），且只定义一次、所有运行时共享。

第一，模型只 stage，人或政策来 apply。 没有任何模型工具调用能动钱或改业务：下单、支付、退款、改价、活动上线，全部终结在 harness 控制的 action 上。消费侧是结构性的——checkout 工具只渲染带下单按钮的购物车，后端接口根本没有 charge 方法。商户侧每个写工具产出一个带服务端生成 ID 的 staged change，apply_change 只对通过真实界面批准的 ID 成功：portal 里的按钮、CLI 里的确认、或平台自己的工具审批。Guardrail 在 apply 时按当前限额重查，而不是 stage 时的限额。无论什么界面，形态一致：模型最危险的动作也只是提案，审批走业务已有的 maker-checker 流程。

第二，写与渲染只认服务端签发过的 ID。 Harness 按会话记录服务端发给模型的每一个 ID，这份记录是任何写或渲染接受的唯一 key。购物车只收本会话服务器返回过的 product ID；商户工具只收 agent 实际读过的 listing/campaign ID。其他任何途径来的 ID——幻觉出来的、用户粘贴的、种在评论里的——在后端看到之前就被拒。UI 同理：presentation 工具只收 ID，服务器自己填充记录，卡片只渲染服务器自己填过的记录。费用、披露这类受监管内容，模型只决定"披露哪个产品”，服务器从批准文案里逐字提供；同样的费用字段也在商户侧受保护列表上——柜台两侧都不能改一个字，evals 逐字节校验渲染字符串。

第三，封顶规则要扛得住反复请求。 大多数交易面限制单人购买数量（票务分配、促销定价、风控），而 agent 会重试、换措辞、并行——人类点按钮永远不会这么干。所以封顶在写入后的结果状态上执行：“再加两个"第二次来就超限、直接拒绝；同一会话的购物车写串行化，单轮并行调用不能组合超限。商户变更同样检查价格变动、折扣深度、补货量、活动预算，外加一张受保护字段清单。规则可以推广成一句话：对结果状态执行每个限额，按会话串行化所有写。

第四，第三方内容一律 sanitize。 电商上下文里大部分文字不是你的人写的——卖家、评论者、竞争对手。所以每个后端读取都是不可信输入，过一个 sanitizer：剥控制字符与双向字符、移除模仿 fence 标记的内容、解除模仿对话轮次或工具调用的文本、限制大小，最后包进带固定标签的 fence。Prompt 承担合约的另一半：fenced text 是报告对象，不是行动依据——一条敌意 listing 冒充不了系统，也填不满上下文。

3.3 Eval：给非确定系统上确定性

从一次小 Prompt 改动到一个新工具，都可能以难以预测的方式改变 agent 行为——而且出问题的往往不是你 ship 的那个改动。Eval 就是在部署前把它找出来的办法。电商场景的四个要点：

评快照，不评对话。 模型 API 无状态，agent 输出是（系统 Prompt、工具、消息数组）的函数——意味着任何可达状态都能直接构造。所以一条 eval case = 构造测试状态 + 追加测试用户消息 + 让 agent 从这里跑。然后评结果：最终状态与渲染响应（含最后一次写操作的参数）。大多数情况下不评路径——那样的用例脆弱且限制性强。simulated-user eval（第二个模型扮用户、judge 评整段对话）是差的度量工具：两个非确定系统交互，样本要更大、单次更贵、更难判、失败难归因。它的正确用途是发现覆盖缺口、做整体 vibe check，然后把每个 case 写成快照。

测恶劣条件，不是干净开局。 一个 case 应该编码失败的前提条件，而不只是任务。如果一个行为只在忙碌的第一轮多次工具调用之后、或会话早期出现矛盾之后才浮现，那么从干净状态开局的 case 在每个配置上都通过，提供不了任何数据。大多数套件都太重干净状态——确保你的 case 里有一部分从长、乱、矛盾的 history 开局。

五类 case，每个正例配反例。 缺反例是套件最常见的缺口：每个"应该服务"配一个"应该拒绝”，每个"直接做"配一个"应该先问"。五类：

与一线专家共建，用真实事故喂料。 找最先看到失败的人——Product、Legal、Merchant Ops、Customer Care、Category Management——一起设计 case。真实失败是最好的 eval，每个用户流 50–100 条起步。生产 transcript 是新 case 的富矿（尤其棘手的那些）；coding agent 擅长生成额外 case 和对抗变体。参考仓库自带一个 Claude Code 插件和按这套方法写的 eval-authoring skill。

3.4 大组织：怎么不让彼此踩脚

电商企业里，agent 由许多工程团队共建：搜索、结账、定价、营销技术、客服、目录平台，各自拥有 agent 依赖的系统、各按自己的节奏发布、各自想加改一个工具、一个 Skill、一条 Prompt 规则。和一个服务不同，agent 没有严格的模块边界保护彼此——定价团队的改动和结账共享同一个上下文窗口。

诱惑的修法是把系统拆成一堆子代理、一个业务单元一个——第一节已经论证了为什么不要。取而代之的是三条去风险流程：

• Ownership follows the systems：每个 Skill 和工具有一个 owner 团队——定价拥有促销工具和定价 Skill，客服拥有订单/退货工具和客服 Skill；共享 Prompt 有一个平台级 owner 管公共部分、领域 owner 管各自段落。
• 改动带着它的 case 一起 ship：贡献 Skill 的团队同时贡献 case（含反例和对邻接 Skill 的边界 case）。全量套件每 PR 跑太慢太贵，所以从它构建 CI set：最高流量请求的核心集 + 全部安全 case，再加上改动触及的部分——改 Skill 跑它自己的和邻居的边界 case，改工具跑所有调用它的 case，改共享 Prompt 跑全量（因为什么都读系统 Prompt）。通过门槛设为多次试验的通过率，加上缓存命中率与每轮成本；全量套件 nightly 和每次 release 前跑。
• Agent 也要进 release calendar：它是一个部署单元，坏改动一次到达所有用户。Prompt/Skill 改动先 roll 到 canary 人群；留一个不发版就能关掉某个 Skill 的开关；高峰期前 freeze agent，和其他系统一样。

四、展望：架构会活得比模型久

文章的结尾值得完整转述一遍（意译）：

这篇文章的大部分内容与模型无关。工具调用的是你已在运行的系统，Skills 编码的是你已在遵循的流程，Eval 是你的产品需求文档写成的测试，harness 执行的是你对任何客户端都会执行的政策。模型会继续进步，当更好的模型发布时，这套架构只需一次配置变更和一轮 eval 扫描——其余一切照常工作。

还有两层更远的判断：这套架构会活过聊天面板——同一个 agent 可以走语音，可以在用户开口前主动对票价下降行动，对已有 evals 和工具的团队，这些只是 presentation-layer 项目；再往后，你的 storefront 的一部分流量会来自替用户购物的 agents——约束你自己 agent 的同一套 provenance、staging、approval 规则，正是你安全地向那些 agents 开放工具的规则。

五、总结：六条可复用判断标准

如果只从这篇指南里带走一套东西，我建议是这六条（作者归纳，非原文编号）：

1. 架构默认单 Agent + Skills。子代理只留给自包含窄任务（作为工具），或已有专用 Agent 的领域（整体交接）。判断标准是对话的所有权。
2. Prompt 与 Skill 按频率划分：约 1/3 流量相关的进 Prompt；安全、品牌、用户事实永远在 Prompt；可预测的 Skill 由 harness 预注入。
3. 工具调用已有系统，结果即上下文：别在工具里重写业务逻辑；只回模型推理需要的字段；错误给指令不给错误码。
4. UI 组件就是工具：typed 参数 + 服务端校验 enrich；参数反映渲染布局；eager_input_streaming 换 token 级流式。
5. 时延攻两头，成本靠前缀：三杠杆最小化总和；感知时延靠渐进渲染与进度行；缓存按 Global/Session/Volatile 三段排布，命中率 90–99% 是设计起点；按每完成任务算成本。
6. 记忆、安全、Eval 各有归宿：记忆住进数据库、异步写入；安全执行在 harness，模型只提案；Eval 用快照、配反例、脏状态开局，与 SME 共建。

对照源码再看这六条，会更有意思：commerce-common 的 fencing、memory、presentation 模块，商户侧的 staged change 状态机，购物侧的 provenance gate——指南里的每一条原则，都能在 anthropics/commerce-agents 的代码里找到对应落点。方法论的归宿永远是代码。

× 爱折腾的工程师

真诚赞赏，手留余香

2元 5元 10元 50元 100元 任意金额

2元

使用微信扫描二维码完成支付

• ← Previous Post
• Next Post →