commerce-architecture

商务 Agent 架构

路径位于参考仓库中：commerce_common/ 对应 commerce-common/commerce_common/，shopping_agent/ 对应 shopping-agent/core/shopping_agent/，merchant_agent/ 对应 merchant-agent/core/merchant_agent/，运行时分别位于 shopping-agent/runtime-messages-api/shopping_agent_runtime/ 和 merchant-agent/runtime-messages-api/merchant_agent_runtime/。

一个循环

• 一个模型负责整个对话。一轮由 ShoppingAgent.stream_turn 或 MerchantAgent.stream_turn 执行（各运行时的 orchestrator.py）：模型读取缓存的提示词，调用工具（同一轮的调用会并发运行），最后返回文本并调用展示工具。没有路由器、分类器或交接。
• 所有路径上的每次调用都会经过角色执行器（shopping_agent/executor.py 中的 ShoppingToolExecutor、 merchant_agent/executor.py 中的 MerchantToolExecutor），并由 commerce_common/execution.py 中的 BaseToolExecutor 执行。 Messages API 运行时、Agent SDK 工具集和 MCP 服务调用相同的 execute，该方法不会抛出异常； 达到 commerce_common/config.py 中的 max_tool_iterations 轮后，运行时会强制执行一轮不含工具的调用。

规则所在之处

适用规则	所在位置	参考
填写某次调用的参数时	该工具的描述	每个角色的 tools/registry.py 中的 build_tools
大多数轮次：购物车和结账、分阶段写入约定、展示语法、工具顺序、信任规则	静态提示词	每个角色的 prompt.py 中的 build_static_system
少数需要多步流程的请求	按需加载的技能	shopping-agent/skills/、merchant-agent/skills/

核心流程在大多数对话中都需要遵循的规则，会下移一层。本表是分层方式的唯一说明。

技能

• 技能是包含 SKILL.md 的目录：文件先是 frontmatter 中的 name 和 description，然后是正文（由 commerce_common/skills.py 中的 parse_skill_md 解析）。description 描述请求类别，不包含示例话语。
• 静态提示词仅包含索引（SkillRegistry.index_block，按名称排序），而 load_skill 会返回 一份正文（由 commerce_common/execution.py 中的 _load_skill 加载）。在 Agent SDK 中，ensure_project_skills 会将 相同目录链接到 .claude/skills/，而 SKILL_TOOL_ADAPTER 会将模型指向 SDK 的 Skill 工具 （commerce_common/agent_sdk.py）；托管清单会在 agent.yaml 的 skills[] 中列出这些目录。

后端接口

每个部署都会为每个角色实现一个抽象类；除此之外，没有其他内容会访问其系统。

• StorefrontBackend（shopping_agent/backend.py）：11 个抽象方法，包括商品目录（2 个）、购物车（4 个）、偏好设置（1 个）、订单（2 个）、政策（1 个）和履约（1 个）；get_account_context、get_disclosure 和 checkout_handoff 有默认实现。没有任何方法会下单或转移资金；checkout_handoff 会指明付款发生的位置（托管结账 URL，或每个卖家对应一个 URL），并由主机呈现。
• MerchantBackend（merchant_agent/backend.py）：16 个抽象方法，包括读取（8 个：业绩 3 个、商品目录 2 个、库存和订单健康状况 2 个、定价 1 个）以及变更生命周期（8 个：五个 stage_*、get_pending_changes、apply_change、discard_change）；execute_analysis_query、get_analysis_schema、get_merchant_context 有默认实现。
• 按尺码、颜色或等级销售的商品或 listing 是一个包含 options 的系列记录，其变体各自是包含 option_values 和 variant_of 的记录；购物车以及价格或补货写入操作使用变体的 id，而门控检查针对系列执行。docs/backends.md 说明了常见商品目录模型的映射，以及平台无法提供某项数据时应返回什么。
• 后端负责执行资格、定价、库存和数量规则；门控检查来源和上限（commerce-trust-safety）。后端返回的所有内容都会在模型读取前经过隔离处理。
• 尚未接入的系统对应一个会失败的方法（merchant 方法会从 merchant_agent/changes.py 抛出 ChangeNotApplicable）；工具仍会注册，因此提示词字节不会改变。业务完全没有的系统则不会存在：角色配置中的 enable_* 开关会关闭该系统，从而移除其工具（absent_tools()）、提示词行以及三个路径上的依据规则，并且执行器会拒绝调用这些名称；依赖该系统的技能会放在 skills/_staged/ 下，随后字节会为该部署固定。NotOffered（shopping_agent/backend.py）是更具体的信号：系统已启用，但商店不服务某一件商品或某个卖家。
• ShoppingAgent / MerchantAgent 上的 executor_class=、SDK 工具集以及 MCP 服务的 build_server 都接受角色执行器的子类，以便部署自定义 domain_error 映射或结果措辞。

委派

第二次模型调用采用一种形式：DelegateExtension（commerce_common/delegation.py）。它接收简述和 DelegationContext 中的句柄，不会接收对话或执行器；它会返回一个经 result_model 验证的结果；它不能写入内容、呈现内容或调用其他委派；commerce_common/execution.py 中的 _run_delegate 会将每轮调用次数限制为 max_delegate_calls_per_turn。MerchantAgent 接受 extra_delegates，其内置实例为 run_analysis（commerce-merchant-operations）。ShoppingAgent 不注册任何委派。

模型字段

model 运行轮次循环，memory_model 运行轮后提取（commerce_common/config.py 中的 BaseAgentConfig）；analysis_model 运行委派，设为 None 表示使用 model（merchant_agent/config.py 中的 MerchantAgentConfig）。SDK 运行时会将 config.model 复制到选项中；清单会设置 model:。请通过自己的评测选择这些值。

请勿

• 按请求改变 tools[] 或静态提示词（commerce-prompt-caching）。
• 将适用于大多数轮次的规则放进技能，或将只适用于一种工具的规则放进提示词。
• 仅在提示词文本中执行上限或权限限制；这些限制应由执行器或后端负责。
• 让模型编写价格、数据或条款；组件由服务器记录组合而成（commerce-ui-tools）。
• 将领域工具添加到核心包；垂直领域应通过 PresentationExtension 添加 UI，其余内容保留在自己的代码中。