Anthropic 官方电商 Agent 参考实现拆解：七个值得抄的架构设计

Anthropic 官方电商 Agent 参考实现拆解：七个值得抄的架构设计

Agent 定义一次，跑在三种运行时上；模型从头到尾没碰过真实系统。

Anthropic 放出了一个重量级的参考实现：commerce-agents。两个电商 Agent——面向顾客的导购 Agent（搜索、比价、行程规划、填购物车、答订单和政策问题、记住顾客说过的话）和面向员工的商家 Agent（经营分析、商品维护、库存和订单告警处理、定价促销、草拟营销活动）——覆盖零售、旅行、电信、娱乐四个行业，Apache 2.0 协议开源。

但这个仓库真正的价值不在电商本身。它是 Anthropic 对"企业级 Agent 该怎么架构"这个问题给出的官方答卷——每一个设计决策都值得做 Agent 工程的人抄作业。本文拆解其中七个。

本文提纲

  1. 全景：一个分层清晰的三明治
  2. 设计一：定义一次，三处运行——Agent 是资产，不是程序
  3. 设计二：Backend 防腐层——模型永远不碰你的系统
  4. 设计三：安全是代码，不是提示词
  5. 设计四：写操作一律暂存，人批了才生效
  6. 设计五：渐进式落地——从 stub 到全量
  7. 设计六：流程即技能，开关在配置
  8. 设计七：工程细节里的信号
  9. 上手与边界

全景：一个分层清晰的三明治

先看整体结构。两个 Agent 共享一个公共库，各自有角色核心，再往上挂三种运行时，往下通过 Backend 接口对接宿主系统：

MERMAID_BLOCK_0

commerce-common 装两个角色共享的一切：配置、fencing（护栏）、记忆、技能加载、grounding、呈现、事件流。角色核心层放各自的类型、Backend 接口、提示词、工具契约和安全门。三种运行时消费同一份定义。宿主系统只出现在最底层，且只被 Backend 的服务端实现触碰。

这个分层是后面所有设计的基础。

设计一：定义一次，三处运行——Agent 是资产，不是程序

同一个 Agent（提示词、技能、工具契约、安全门），不改一行地跑在三种运行时上：

  • Messages API：参考实现的手写回合循环，宿主应用围绕它构建
  • Agent SDK：SDK 接管循环，宿主预取 grounding 读取，回合结束即停
  • Managed Agents：托管服务，通过 manifest 和 MCP 服务器部署（一条脚本 deploy_managed_agent.sh 完成）

这背后是一个关键认知：Agent 的本体是"定义"（prompt + skills + contracts + gates）这个静态资产，运行时只是消费它的壳。换运行时不该改 Agent 的行为语义——尤其是安全语义（后面会讲怎么保证）。

对照我们写过的趋势：这和 Google Antigravity "一个 Agent harness、多个 surface" 是同一个思想在两个公司的表达。当 Agent 定义与运行时解耦，"部署在哪"就从架构问题降级成了运维选择。

设计二：Backend 防腐层——模型永远不碰你的系统

这是整个仓库我最推荐细读的部分。两个角色各定义一个 Backend 接口（StorefrontBackend / MerchantBackend），部署方实现它来对接自己的商品、购物车、订单、库存、定价系统。三条铁律：

模型只读结果。Backend 方法由宿主代码在服务端调用，凭据握在宿主手里，模型看到的只有方法返回值——API key 永远不进上下文。

顺序在后端强制。一个流程如果步骤有固定顺序（比如先锁库存再改价），这个顺序写死在 Backend 实现里，而不是靠提示词恳求模型"请按顺序执行"。

结构决定集成方式。官方 MCP 连接器（Snowflake、Stripe、Slack 这些）是"数据源的事实记录"，作为集成目标由 Backend 方法在服务端调用；电商平台自己的 MCP 服务器则在 Managed Agents 路径上挂载——但 provenance 门永远挡在每个写操作前面。

对比一下 microsoft/mcp 的路线会很有意思：那边让 Agent 直接调用 M365 工具（以用户身份、受用户权限约束），这边坚持"模型不直接碰系统、一切经过宿主代码"。两条路线没有对错——前者灵活、边界是身份；后者可控、边界是代码——但涉钱的系统，Anthropic 选了后者。

设计三：安全是代码，不是提示词

docs/safety.md 里每条规则都标注了执行的模块和路径。核心机制：fencing、来源门（provenance gates）、上限（caps）、记忆校验、商家审批门——全部在工具调用内部执行，且三种运行时全部生效。

注意"在工具调用内部"这个措辞。不是系统提示词里写"请不要越权"，是工具的实现代码里直接检查：这个写操作的来源可溯吗？超过上限了吗？记忆里写入的内容校验过了吗？不通过就拒绝执行。

这印证了 Spotify 那篇文章的教训，而且更彻底——凡是"违反就出事"的约束，必须放在代码层而不是提示词层。提示词管方向，Hook 和门管底线。这个仓库把底线划得清清楚楚，还保证换运行时底线不松动（因为门在工具里面，跟运行时无关）。

设计四：写操作一律暂存，人批了才生效

看一个具体的信任设计。商家 Agent 的每个写操作——改商品、调库存、动价格、发活动——都是 staged change：Agent 草拟变更，宿主的审批界面展示，人点了批准才真正生效。README 顶部那句说明写得直白：没有任何操作会下真实订单、刷真实的卡、改在线的商品；checkout 只是把购物车渲染出来交给宿主完成。

这套"暂存 + 审批"的粒度设计很讲究：Agent 可以自由地读、分析、草拟，但"落到真实世界"的最后一步永远留给人类。而 Agent SDK 的运行时甚至自带一个 y/N 的审批控制台，把这条链路做成了开箱即用的默认值，而不是留给部署方的作业。

设计五：渐进式落地——从 stub 到全量

企业落地 Agent 最怕的是"要么全上要么别上"。这个仓库给出了三种渐进姿势：

Stub 起步。导购 Agent 的试点可以只实现搜索和商品详情，其余方法全部 stub——stub 返回"暂不可用"的结果，一个提示词字节都不用改。

开关裁剪。业务上不存在的能力（没有购物车、没有订单追踪）是一个 enable_* 配置开关，关掉后对应的工具、提示词行、grounding 规则在三种路径上同时移除——不会出现"工具没了但提示词还在让模型调用"的错位。暂时用不上的流程放进 skills/_staged/ 目录封存。

商家侧最小集。商家 Agent 的试点只需实现八个读方法，写方法全部拒绝——此时摘要和指标已经能跑起来，零写路径风险。

"开关一关、三条路径同步移除"这个细节最能体现工程成熟度：配置驱动的不是功能开关，是整个 Agent 行为面的一致收缩。

设计六：流程即技能，开关在配置

五个导购流程就是 shopping-agent/skills/ 下的五个技能目录，五个商家流程同理。添加自己的流程 = 添加一个带 SKILL.md 的目录；行业特有的 UI 是一个 PresentationExtension（四个垂直示例共带了七个）；品牌身份（brand_name、assistant_name、brand_voice）是配置字段而非提示词硬编码。

这个设计与我们介绍过的 Nature Skills、Agent Skills 浪潮完全同构：流程知识从提示词里析出，变成可安装、可版本化、可单独演进的资产。连扩展你自己 Agent 的方式都是一个 Claude Code 插件（/scaffold-commerce-agent 交互式生成脚手架，/add-commerce-flow 加流程，/review-commerce-agent 评审现成 Agent）——用 Agent 造 Agent，闭环了。

设计七：工程细节里的信号

几个容易被略过但很说明问题的细节：

缓存正确性验证。文档教你怎么确认 prompt caching 真的生效：读 turn_complete 里的 cache_read_input_tokens，第二回合为零说明前缀变了——缓存没命中，该去查哪里改了 prompt。把"验证缓存命中"写进文档，说明他们真的在生产语义下校验过 token 成本。

包名防抢注。CI 会检查七个 pip 包名始终没被注册到公共索引——pin 文件从本地目录安装，防止有人抢注同名包搞供应链攻击。参考实现做到这个程度的安全意识，本身就是示范。

完整验证链。ruff + pytest + check.py + verify_all.py（含部署 dry-run 和 web 构建）+ smoke_chat.py（真实对话冒烟），CI 跑两个 Python 版本。四个行业的示例每个 README 都有"Try"清单：冒烟脚本跑的回合、单条提示词和"好答案应该做什么"。

上手与边界

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
cp .env.example .env   # 填 ANTHROPIC_API_KEY
(cd examples && npm ci)
python scripts/run_demo.py retail   # API :8000 + 店面 :3000

四个行业各自跑一个端口，--merchant 起商家门户。所有公司、品牌、人物都是虚构的 ACME——这是个刻意的设计：参考实现必须能在零真实副作用的前提下演示完整流程。

边界也要说清楚：README 明确这是 reference implementation——不维护、不接受贡献。它不是产品，是范本；抄它的架构，别指望它修 bug。示例无鉴权、MCP 服务器只绑 loopback，生产化的一切（业务规则、授权、合规）都留给部署方。

最后把这个仓库放回大图里。我们已经看过 Agent 基础设施各个零件的标准化进程：Spotify 的 shunt 证明路由要 Hook 强制不要提示词建议，OKF Agent Memory 把记忆变成可审计的 git 仓库，microsoft/mcp 把企业工具变成身份约束下的标准服务。commerce-agents 补上的是总装层：当这些零件拼成一个真实业务的完整 Agent 时，架构应该长什么样——定义与运行时分离，模型与系统之间隔一层宿主代码，安全长在工具里而不是提示词里，写操作永远留一道人工闸门。

七个设计未必都要抄，但每一个都值得在白纸上推演一遍：你的 Agent 架构里，这条约束放在哪一层？

作者: itech001
来源: 公众号：AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

本文首发于 AI人工智能时代，转载请注明出处。

posted @ 2026-09-06 21:15  iTech  阅读(26)  评论(0)    收藏  举报