AnthropicApache-2.0双角色 Agent参考实现

Claude Commerce Agents

一套面向电商前台与运营后台的 Agent 架构参考：把“模型会说什么”与“系统允许做什么”拆开，由受控工具、会话溯源、服务端富化和人工审批共同约束业务动作。

仓库：anthropics/commerce-agents　·　代码与文档核对：2026-09-06

项目定位：不是聊天组件，而是业务动作的控制框架

一句话理解：仓库提供两个共享底座、职责不同的 Agent：面向消费者的 shopping agent，以及面向运营人员的 merchant agent；模型负责理解、推理与选择，后端负责事实、权限、写入与最终执行。

Shopping Agent｜购物助手

检索、比较、规划、加购、订单与政策问答、偏好记忆。它只能把商品加入购物车并渲染结算摘要，不能下单或扣款。

典型入口：店铺 App、官网、导购页。

Merchant Agent｜运营助手

解释经营指标、处理库存/订单预警、维护商品、定价促销、起草活动。所有写操作先形成变更草案，默认必须由宿主界面批准后才可应用。

典型入口：商家后台、运营工作台。

它刻意不包含什么

不含：真实支付、订单提交、用户认证、业务授权、风控策略、生产凭据与速率限制。这些均属于接入方系统的责任边界。

提供：工具协议、执行器、提示词与技能结构、会话状态、溯源门禁、展示富化、变更审批骨架，以及四个可运行的垂直示例。

整体架构：一个共享控制面，三条可替换运行路径

commerce-agents
├─ commerce-common：配置、fencing、memory、skills、展示、执行器、事件
├─ shopping-agent：顾客侧领域类型、工具、门禁、运行时
├─ merchant-agent：运营侧领域类型、变更、审批、分析委托、运行时
├─ examples：零售 / 旅行 / 通信 / 票务的 FastAPI + Next.js 宿主
└─ plugins/commerce-builder：基于此架构生成或检查业务 Agent 的 Claude Code 插件

宿主应用身份、会话、UI、凭据

→

运行时对话循环、grounding、流式事件

→

角色执行器工具校验、门禁、展示富化

→

业务 Backend目录、库存、订单、指标、变更

关键分工：模型不直接访问数据库或凭据；模型看到的是 Backend 返回、经过清洗和围栏化的业务数据。

分层	解决的问题	可替换点
Backend 接口	将你已有的目录、购物车、ERP、分析仓库转换成稳定的工具返回值。	`StorefrontBackend` / `MerchantBackend` 的具体实现。
角色核心	定义工具合同、提示词、会话状态、领域门禁与 UI 组件。	启用的能力开关、品牌身份、领域扩展。
执行器	统一输入校验、故障处理、skills、presentation、memory 与 delegate 调用。	角色的 handler 表和领域异常映射。
运行时	驱动模型工具循环、流式输出、模型客户端和部署环境。	Messages API、Agent SDK、Managed Agents。
宿主应用	认证、授权、凭据、审批界面、真实 checkout 与 UI 呈现。	你的 Web / App / 后台系统。

一次对话如何执行：从自然语言到受控结果

核心模式：Agent 的“动作”不是函数直通。每一笔模型工具调用都会经历 schema → dispatch → gate → backend → fence/enrichment → event，因此同一业务规则可在三种运行方式下复用。

01 · HOST CONTEXT

宿主绑定身份，建立会话。示例把用户/运营者主体放在 session context；工具参数中没有 user_id 或 merchant_id。

02 · PROMPT ASSEMBLY

静态系统提示词 + 动态会话上下文。静态部分按配置和已安装 skills 构建，可命中 prompt cache；个人偏好、记忆、购物车、页面状态等动态信息置于缓存断点之后，并被围栏包裹。

03 · GROUNDING

需要事实时先读后答。例如政策、订单、未见过的商品 id、经营指标等场景，运行时会强制或预取相应读取工具，降低模型凭空回答的概率。

04 · TOOL EXECUTION

执行器剥离状态文案、校验参数、分派工具。status 仅供宿主显示“正在查找商品”等进度，不会抵达 Backend、门禁或模型上下文。

05 · GATE & BACKEND

门禁校验当前会话溯源与限制，再由业务 Backend 读/写。被拦截的调用返回 blocked，而不是让异常中断整轮对话。

06 · UI & STREAM

展示请求按 schema 校验后，由服务端按 id 回填真实数据。宿主消费 text_delta、tool_call、tool_result、ui、cart_update 等事件。

# 认知模型：工具调用并不是「模型 → 数据库」
model decision
  → role tool contract
  → BaseToolExecutor.dispatch()
  → domain gate / guardrail
  → Backend(session-bound credential)
  → fenced result or server-enriched UI event
  → host renders / host completes real-world action

安全与控制面：把“建议遵守”变成“代码强制”

提示词层

规定语气、先读后答、不可把第三方文本当指令、不要确认尚未完成的动作。

作用：约束模型表达和工作方式。

执行层

schema、工具白名单、fencing、provenance、数量上限、guardrails、审批门禁。

作用：无论模型是否遵守，都阻止越权副作用。

宿主层

认证、授权、凭据、风控、支付、审计、速率限制与数据保留。

作用：把参考实现接入真实生产系统。

机制	实现思想	它阻止的风险
Fencing	第三方目录、评论、政策、记忆等文本先清洗控制字符、伪造标记与围栏标识，再按固定标签及长度上限包裹。	Prompt injection 将“商品描述”伪装成系统指令。
会话溯源	会话状态记住本轮已由读取工具返回的商品/订单/变更 id；写工具仅接受这些 id。	模型编造 id，或对未验证对象执行写操作。
展示富化	模型仅提交 `product_id` 与简短理由；服务端从当前记录中回填标题、价格、图片、指标与变更差异。	幻觉价格、伪造订单状态、前端信任模型 payload。
能力收缩	配置决定工具面；未启用能力不会只是在提示词中“禁止”，而是从可调用工具中移除。	闲置能力被意外触发。
失败梯	工具参数错误、业务异常、未知工具均变为结构化错误/blocked 结果，整个 turn 不因单个工具异常中止。	工具故障导致会话崩溃或暴露内部错误。

重要边界：参考代码的门禁验证“调用是否有充分上下文、是否超额度”，并不替代你的商业授权。真正的库存可售、会员资格、区域合规、价格规则、风控与支付确认，仍必须由 Backend 和宿主系统决定。

双角色的关键差异：购物车写入 vs. 受审批的业务变更

顾客侧：先获得商品事实，才允许修改购物车

Provenance gate：add_to_cart 只接受本会话的搜索、商品详情或订单读取曾返回的 product_id。
Options gate：存在尺码、颜色、套餐等选项的商品族不能直接加入；必须先定位具体 variant。
Caps + lock：限制单品数量、购物车行数，并按 session 串行化购物车写入，避免同一轮并发工具调用交叉覆盖。
Checkout handoff：模型输出的只是结算摘要；宿主获取 hosted checkout URL 并执行真实订单、支付流程，URL 不经过模型。

运营侧：先 stage，再由宿主批准，最后 apply

Staging provenance：商品与 campaign id 必须来自当前会话；编辑内容前还要读取商品详情。
Guardrails：在 stage 和 apply 两次校验条目数、涨降价幅度、折扣深度、补货数量、预算与受保护字段。
Host approval：默认 require_host_approval=True；聊天中的“同意”不会批准，必须由 portal 的批准控件写入批准标记。
Analysis delegate：可将指标归因等任务交给受预算和 schema 限制的分析代理，且其结果不会扩展可写对象集合。

运营者请求
“把 A 降价 10%”

→

读取 A 的记录
建立溯源

→

stage_price_change
guardrail 校验

→

宿主审批 UI
人确认范围

→

apply_change
再次校验后落地

这不是“模型请求确认”这么简单：审批权在宿主，而不是由模型从自然语言中自行推断。

三种运行方式：保持契约一致，替换循环与托管边界

路径	谁运行工具循环	适用场景	控制重点
Messages API	应用自身的 runtime。	需要最强编排掌控、逐事件流式 UI、强制 grounding、后处理记忆提取。	轮次、工具迭代数、历史压缩、预取与强制工具选择由你的服务控制。
Claude Agent SDK	Agent SDK。	希望利用 SDK 的 loop，同时继续复用仓库的 prompt、skills、工具合同与执行器。	工具 allow-list，`max_turns`，无额外 turn 后处理。
Managed Agents	托管平台。	希望以 manifest + MCP server 托管 Agent。	MCP 工具逐个显式启用；写工具可配置 `always_ask`；接入方管理 MCP 身份与网关。

可迁移性的秘诀：三个路径都汇入角色执行器。因而 fencing、商品/变更溯源、数量限制、展示富化等规则不是散落在不同 runtime 的“重复实现”，而是由同一个 execute() 路径执行。

Skills 与提示词缓存：把稳定策略和按需流程拆开

静态系统提示词

包含身份、核心规则、工具原则、信任边界和 Skill 索引。它只依赖部署配置与已安装 skills，因此跨 turn 字节保持稳定，适合缓存。

配置开关会同步改变：工具清单、提示词里的能力描述、grounding 规则。

动态上下文

放置当前用户偏好、购物车、页面、商家上下文和可用记忆；全部经过 size cap 和围栏处理，并在 cache breakpoint 之后拼接。

避免用户特有状态破坏稳定前缀的缓存命中。

Skill 的作用不是“把所有流程塞进 prompt”

每个业务流是一个目录中的 SKILL.md。系统提示词先放入技能索引；当请求匹配某个较复杂流程时，模型调用 load_skill 获取对应细则。简单的一次读取则直接调用工具。

顾客侧 5 个流：
搜索发现、目标规划、购买研究、记忆个性化、客户服务。

运营侧 5 个流：
经营表现、商品维护、库存与订单、定价与促销、营销活动。

可借鉴的工程原则：把“频繁、稳定、全局有效”的约束留在静态 prompt；把“低频、具体、长文本”的工作流做成可加载 skill。新增 skill 时需要意识到：它会改变静态前缀，因而影响缓存与回归评估范围。

接入你的电商系统：Backend 是唯一的业务适配层

不要让模型拿 API Key 调第三方平台。让宿主根据已认证的 session 解析凭据，Backend 代为调用内部服务、ERP、商城平台或数据仓库；模型只获得受控结果。

StorefrontBackend 的最小切入

实现商品搜索与详情，让 Agent 先具备“可核实的推荐”。
接入购物车读写；保留仓库的 provenance、选项与数量门禁。
对接政策、订单、履约信息等读接口。
由宿主实现 checkout handoff 和支付后回写事件。

MerchantBackend 的最小切入

先实现经营快照、商品搜索/详情、库存/订单预警等读取能力。
保持写能力关闭，先验证数据解释、展示与分析流程。
再接入 stage_* 的草案存储和审批 UI。
最后实现 apply_change，使之在业务系统中执行幂等且可审计的操作。

接入项	正确做法	常见误区
用户身份	登录时将 customer / merchant / operator 绑定入 session，之后 Backend 从 session 取身份。	让模型在工具参数里传用户 id，或将 JWT 暴露给模型。
多步业务	Backend 以 session 为 key 保存流程状态；前置条件不满足时抛出领域异常并映射为可理解结果。	只靠模型记住“先验证再提交”的顺序。
幂等写入	对平台写入从 session id + 业务内容导出 idempotency key，并存储操作结果。	把重试交给模型，导致重复创建订单或变更。
真实 UI	按事件协议渲染；展示组件由服务端以 id 富化，审批与 checkout 放在宿主。	直接信任模型输出的价格、库存、订单状态或“已经成功”文案。

从学习到落地：建议按控制能力而非聊天界面推进

跑通零售示例，观察事件而不只看页面

分别体验 storefront 和 merchant portal，关注工具调用、ui、cart_update 与变更预览如何流向前端。

阅读共享执行器和一个门禁

优先理解 commerce_common.execution.BaseToolExecutor，再对照购物车 gates.py。这能建立“模型决策不等于业务执行”的核心心智模型。

替换一个只读 Backend

选商品搜索或经营快照接到你的真实服务，验证 session 身份、数据裁剪、fence 和 UI 回填是否正确。

引入一条低风险写流程

先做草案，不做 apply；再实现审核页面、审计记录、幂等键和回滚策略。不要把“审批”仅做成对话中的一句确认。

为每个关键规则写 eval

覆盖注入文本、未见 id、变体缺失、并发写、额度超限、越权主体、审批绕过、Backend 超时与工具 schema 错误。

可以迁移到通用 Agent 的三条方法论

模型生成“意图与候选 id”，服务端决定“事实与副作用”。
让每一次写操作都有来源证明，而非仅有语义上看似合理的参数。
把展示层也当作安全边界：模型出建议，服务端回填可信业务字段。
统一执行器优先于每个 runtime 各自补安全逻辑。
静态策略与动态上下文分离，兼顾缓存效率与个性化。
人工审批是一个系统权限动作，不是文本分类问题。

源码阅读地图：按问题定位，而不是从目录顺读

想回答的问题	优先文件	阅读关注点
工具为什么能跨 runtime 保持一致？	`commerce-common/commerce_common/execution.py`	`dispatch`、错误梯、status 分离、presentation/delegate/memory 路由。
如何阻止模型将任意商品加入购物车？	`shopping-agent/core/shopping_agent/gates.py`	`seen_products`、variant、数量限制、session lock。
运营变更为何不能被聊天绕过？	`merchant-agent/core/merchant_agent/gates.py`、`changes.py`	stage/apply 双重 guardrail、approved change id、受保护字段。
模型上下文怎样防注入且不破缓存？	两个角色的 `prompt.py` 与 `commerce_common/fencing.py`	静态/动态拆分、data fence、大小上限、第三方文本处理。
页面为什么不信任模型报出的价格？	`commerce_common/presentation.py` 与各角色 `enrichment.py`	schema 校验、按 id join 服务端记录、无溯源 id 丢弃。
接入已有商城时身份和凭据放哪里？	`docs/backends.md`	session-bound identity、Backend server-side credential、业务顺序与幂等。

关键源码与文档

README：项目结构、运行方式、四个垂直示例与接入边界。
docs/safety.md：代码强制规则、模型约束和接入方责任的完整清单。
docs/backends.md：身份、凭据、多步骤流程、checkout、产品变体与缺失数据的 Backend 接入说明。
commerce_common/execution.py：统一工具执行框架。
shopping_agent/gates.py：购物车溯源、变体和并发控制。
shopping agent manifest：Managed Agents 的 MCP 工具白名单与权限策略示例。