如何接入自家系统commerce-agents的StorefrontBackend实现六步指南身份、结算与SKU变体【免费下载链接】commerce-agentsReference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.项目地址: https://gitcode.com/gh_mirrors/co/commerce-agentscommerce-agents 是一个用 Claude 构建购物 Agent 与商户 Agent 的开源参考蓝图内置零售、电信、旅行、娱乐四个可运行示例。想把自家电商系统接进来核心只需实现一个接口——StorefrontBackend它定义了 12 个方法把你自己的商品目录、购物车、用户档案、订单与政策系统映射给 Agent全程不需要模型接触任何凭证。本文按官方文档梳理的六步带你完成身份绑定、结算交接与 SKU 变体映射这三件最关键的事。git clone https://gitcode.com/gh_mirrors/co/commerce-agents先认识 StorefrontBackend唯一的集成接口StorefrontBackend是接入方唯一需要实现的类backend.py。它的设计原则非常清晰每个方法都以session开头方法代表该会话里的顾客行事服务端调用你平台自己的 API模型只看到结果永远看不到 token返回的数据全部进入围栏所有返回值经过 fencing 处理后交给模型避免提示注入购物车方法是唯一的写操作下单、扣款都不在仓库范围内checkout只负责渲染购物车。方法作用可选search_products/get_product_details商品搜索与详情含变体必填get_cart/add_to_cart/update_cart_item/remove_from_cart购物车读写唯一写路径必填get_preferences每轮对话前读取顾客档案必填get_orders/get_order/search_policies订单与帮助政策检索必填get_fulfillment_options配送、自提、运费选项必填checkout_handoff/get_account_context/get_disclosure结算交接 URL、账户上下文、披露框可选有默认实现完整字段定义见 types.py方法契约的权威说明就在每个方法的 docstring 里。第一步把身份绑定到会话凭证与身份同行身份处理的黄金法则是**会话开始时绑定身份**docs/backends.md由宿主认证调用者你的宿主应用负责登录解析出 principal购物 Agent 是顾客 id商户 Agent 是商户 id 操作员用它开启会话。此后每个 backend 方法都从session对象里读身份——没有任何路由或工具参数携带 user id凭证放在身份旁边永远不经过模型按顾客的 token 可挂在会话上下文子类上或存在宿主登录时填充的存储里backend 按顾客 id 读取服务级凭证则直接在 backend 构造函数注入把游客也当作 principal标记会话为 guest需要账户的读操作订单历史、地址抛异常由你的 executor 子类转成请先登录的提示游客登录后开启新会话。示例宿主用data/users.json里的演示 profile id 模拟真实登录storefront.py。 若托管在 Managed Agents 平台上平台按 MCP server 在 vault 中保存一个凭证你的 MCP server 从已认证请求中推导顾客身份。第二步保持多步流程的先后顺序先验身份→再查资格→后提交先占座→再确认这类流程顺序必须由你的 backend 强制流程状态存在 backend 内按 session 键控依赖的步骤未完成时抛自定义异常类而不是普通错误在 executor 子类中通过domain_error映射该异常让工具结果说清缺哪一步而不是系统故障模型就能告诉顾客该先做什么平台去重的写操作用会话 id 购物车行哈希派生幂等键顾客在对话外完成步骤支付页、验证码时由宿主向会话排一个 app 事件下一轮对话即可读到。娱乐示例的票务引擎就是这样强制占座限额、过期与归属的。第三步结算交接的三种选择URL 永不经过模型checkout工具到此为止——它只渲染购物车卡片仓库内没有任何代码下单或收款。卡片如何走完由你三选一backends.md你的情况卡片行为你要实现什么结算就是自家 App 的一个路由链接到该路由什么都不用做默认行为平台托管结算购物车 API 无法服务端收款打开平台托管结算 URLcheckout_handoff返回该购物车的 URL市场平台、各卖家分别结算每个卖家一个链接checkout_handoff按卖家返回多条关键点executor 是在模型调用之后才把checkout_handoff的返回值放进卡片 payload 的所以结算 URL 永远不会作为工具参数、也永远不会到达模型checkout_handoff。支付完成后记得排 app 事件让下一轮对话知道结果。第四步SKU 变体映射——family / variant / plain 三种形状这是接入中最容易踩坑的一步。一条商品记录只能是三种形状之一Product 类型形状识别特征Agent 的行为Plain 单品无options搜索直接返回购物车/改价/补货都用它的 idFamily 家族有options如 size: twin/queen/king搜索返回它详情里列出变体加购等写操作必须用变体 idVariant 变体有option_valuesvariant_of家族 id出现在家族详情里自带 id、价格、库存id 可像普通商品 id 一样用于加购常见目录模型怎么映射backends.md你的目录familyvariantplain父/子记录父不可购买父记录id、内容、变化属性作 options每条子记录独立商品每行都是可购 SKU兄弟共享 group key合成一个group key 加前缀作 id每行无组的行产品壳永远带变体价格库存只在变体上产品壳每个变体单变体产品按变体 id 提供几个必须记住的规则家族自身数字前台价格是最低有库存变体的起售价任一变体有货则家族视为有货标题、描述、图片描述家族变体可覆盖任何继承字段变体数量有上限详情里所有变体合在一个围栏结果内默认max_fenced_chars12,000 字符约容纳 60 个紧凑变体行。更大的矩阵按主选项拆家族8 色 × 14 码的鞋 → 8 个 14 码家族缺货add_to_cart遇到有记录但不可买的变体抛Unavailable且消息只写 id哪个没了、哪些兄弟有货executor 原样转达、不写入Unavailable不是变体的东西按请求算价的酒店夜价、座位、差异不止选项值的票档含独立分区与费用、多卖家同品不同价——这些都应保持为独立记录。零售示例里的加重毯就是标准 family 写法AR-1008 按重量给出 12/15/20 lb 三个变体各自独立定价catalog.json。第五步把商户侧写操作落到 family 上如果同时接商户 Agent写操作要区分家族 id与变体 idbackends.md写操作命名对象对 family id 的行为改价 / 补货变体executor 拦截指向具体变体 id暂停 / 恢复二者皆可整体下架或恢复全部变体促销二者皆可展开为每个变体一条各计一次内容编辑二者皆可编辑共享内容变体共享家族内容字段时后端应拒绝变体上的这些字段另外如果你的领域用别的字段承载价格夜价、票价记得加进商户配置的price_bearing_fields否则价格上限校验不会生效。第六步平台给不出的数字一律返回 None最后一条纪律绝不返回占位零。缺流量、转化率、客单价就返回None并在 note 里说明缺了什么指标序列返回空序列加原因商户上下文可用limitations列表声明整店级缺口如仅 90 天订单历史。零售商户示例就声明了两条 limitations订单历史仅 90 天、邮件渠道不上报收入backends.md。在示例中验证你的实现写完后对着零售示例逐条比对它是一份完整的内存版实现参考实现mock_retail.py含加权关键词搜索、同义词表、按会话购物车目录与变体数据catalog.json含床垫按尺寸、枕套按尺寸×颜色的 family 案例用户档案、订单、政策users.json、orders.json、policies.json电信示例展示了带分期金额的变体娱乐示例展示了固定顺序流程。按照这六步走完——身份绑定到会话、流程顺序自守、结算三选一、变体映射合规、写操作落 family、缺失值返回 None——你的自家系统就完成了与 commerce-agents 的接入模型侧无需任何额外适配。【免费下载链接】commerce-agentsReference blueprint for building shopping and merchant agents with Claude. Examples in retail, commerce, telecom, and entertainment included.项目地址: https://gitcode.com/gh_mirrors/co/commerce-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考