commerce-merchant-operations

商家 Agent

路径位于参考仓库中：merchant_agent/ 对应 merchant-agent/core/merchant_agent/，merchant_agent_runtime/ 对应 merchant-agent/runtime-messages-api/merchant_agent_runtime/，merchant_agent_sdk/ 对应 merchant-agent/runtime-agent-sdk/merchant_agent_sdk/，commerce_common/ 对应 commerce-common/commerce_common/。

功能

商家 Agent 通过一个 MerchantBackend（merchant_agent/backend.py）与商家后台中的运营人员协作。 它的五个工作流是 merchant-agent/skills/ 中的技能：performance-insights、catalog-listings、inventory-operations、 pricing-promotions、marketing-campaigns。commerce_common/ 中的机制为共享机制；提示词、工具、限制和 执行器则是它专属的，并且每个工具结果都会封装在 MERCHANT_FENCE（merchant_agent/fencing.py）中返回。

变更暂存约定

1. 每项写入操作都是一个 stage_* 工具（stage_listing_update、stage_price_update、stage_inventory_action、stage_promotion、 stage_campaign）。每个工具都会返回暂存记录和说明，并发出 change_update 事件；当启用 stage_shows_preview（默认值，见 merchant_agent/config.py）时，还会通过运行器使用的 present_change_preview 发出 change_preview 卡片（MerchantToolExecutor，merchant_agent/executor.py）。MCP 服务会关闭此功能， 因为它的执行器事件不会传达给运营人员，所以托管 Agent 会调用 present_change_preview；该工具也可以再次展示较早的变更。 直到执行 apply_change 进行平台写入之前，实时状态都不会受到影响。
2. 暂存操作只接受本次会话中工具返回的商品和活动 ID，且内容编辑还需要先通过 get_listing 读取；apply_change 和 discard_change 只接受由暂存操作或 get_pending_changes 返回的变更 ID（merchant_agent/gates.py）。展示预览卡片不会标记任何变更已获批准。
3. check_guardrails 位于 merchant_agent/changes.py，会在暂存变更时运行（ChangeLedger.stage 或后端中的等效操作）， 并会在 check_apply_change（merchant_agent/gates.py）中再次运行，采用应用时生效的配置。 限制项包括 merchant_agent/config.py 中的 max_items_per_change、max_price_delta_pct、max_promotion_discount_pct、 max_restock_quantity、max_campaign_budget 和 max_listing_field_chars；默认值仅供演示。
4. 绝不可暂存 protected_fields 中的字段；price_bearing_fields 是价格上限检查读取的字段； listing_update_blocked_fields 中的字段不得通过自由格式的商品更新提交。定价字段使用其他名称的领域 （如每晚房价、月费、分级价格）应将字段追加到这些元组中，绝不可替换它们。
5. require_host_approval 默认为 True：只有当 ID 位于 MerchantSessionState.approved_change_ids 中时， apply_change 才会成功，而该列表只能由宿主代码写入。仓库中的三个批准入口分别是门户的 /changes/{change_id}/apply 路由 （examples/demo_common/merchant.py）、MerchantToolset.host_approve（merchant_agent_sdk/merchant_tools.py，由 merchant-agent/runtime-agent-sdk/main.py 针对每项变更提示批准），以及托管清单中 apply_change 上的 always_ask；在该清单中，MCP 服务的配置将 require_host_approval=False（其 default_config 已设置此项； 传入的配置也必须设置，否则每次应用都会被拦截）。在聊天中输入批准内容不会设置任何值。
6. require_host_approval 和 approval_surface 会渲染到静态提示词和拒绝消息中，因此这两项需按部署配置， 修改其中任意一项都需要重新部署（commerce-prompt-caching）。请在 approval_surface 中写明真实的批准入口。
7. 系统不支持的变更类型会引发 ChangeNotApplicable（merchant_agent/changes.py），并由执行器传递；该工具仍会注册。 已应用和已丢弃的变更仍可查询，作为审计记录保留；每条记录都会标记 MerchantSessionContext.operator 中的运营人员， 生产环境的宿主会根据身份验证信息确定该字段。

依据与后续跟进

• 对业绩的提问会强制调用 get_business_snapshot；变更请求包含应用短语且本会话中没有已暂存内容时，会强制调用 get_pending_changes（merchant_agent/grounding.py 中的 GROUNDING_RULES；merchant_agent/config.py 中的词库和标志只追加，不替换）。
• 如果某轮匹配了 change_requested，最后只返回普通文本，且没有尝试调用 stage_*，也没有以 present_suggestions 收尾，则会向用户发送一次 STAGING_FOLLOWTHROUGH_REMINDER（merchant_agent/gates.py；在 merchant_agent_runtime/orchestrator.py 和 merchant_agent_sdk/agent.py 中应用）；提取记忆时会排除提醒文本。
• present_metrics 会将每个选项与快照、查询到的系列、营销活动或已记录的分析结果关联，并附注说明被舍弃的其余选项（merchant_agent/enrichment.py 中的 resolve_metrics），因此卡片不会包含模型生成的数字。

分析委派程序

• enable_analysis（默认关闭）会注册 run_analysis，这是一个由 merchant_agent_runtime/analysis.py 中的 build_analysis_delegate 构建的 DelegateExtension。该委派程序的工具包括提交工具、进度工具、ANALYSIS_READ_TOOLS（merchant_agent/analysis.py），以及在后端实现 MerchantBackend.execute_analysis_query 时提供的查询工具（此时 analysis_sql_only 会关闭按系列读取）。它不包含任何暂存工具；其结果会记录在 seen_analyses 中，并以独立的指标卡呈现。
• check_analysis_sql 会在后端执行前拒绝除单条 SELECT 语句（且不含注释）以外的任何内容；只读角色和商家范围限制由后端负责；analysis_query_timeout_s 和 cap_analysis_table（max_analysis_rows、max_analysis_table_chars）会限制每次查询，analysis_timeout_s、max_analysis_iterations 和 max_delegate_calls_per_turn 会限制运行范围。
• analysis_use_code_execution 会挂载托管沙箱，且仅适用于 Anthropic API（包括托管于 Anthropic 的 Foundry 部署）；查询方法则适用于所有环境（docs/deployment.md）。在 Agent SDK 中，相同契约对应一个工具恰好为只读工具的子 Agent（merchant_agent_sdk/agent.py 中的 build_analysis_agent）。
• 定时摘要是同一 Agent 的一次无头运行（merchant-agent/managed-agents/scheduled-digest/run_morning_digest.py）。

记忆与组件

• 记忆以 merchant_id 为键（merchant_agent/executor.py 中的 memory_subject）；merchant_agent/memory.py 中的提取提示词会纳入运营者对经营情况的陈述，并排除来自商品列表、评价、买家消息或指标的任何信息，以及任何有关可识别客户的信息。写入过滤、保留、删除、清除和 enable_memory 均遵循共享规则（commerce-trust-safety）。
• 内置组件（merchant_agent/enrichment.py）包括 present_metrics、present_digest、present_change_preview 和 present_suggestions；在宿主批准提示词时会注明，没有任何选项按钮可批准或应用变更。垂直领域可通过扩展添加自己的组件（示例包括 present_occupancy_calendar、present_plan_mix、present_event_pacing）（commerce-ui-tools）。

市场平台

• 许多卖家的内容都会经过同一道围栏；不存在按卖家设置的标签，也不存在可以绕过围栏的卖家。在购物部署中，卖家是一个搜索维度（SearchFilters.attributes），组件会显示该维度；当平台条款与卖家条款不同时，search_policies 的结果会注明条款归属。
• 来源信息和上限均按会话设置，因此会话只能针对其自身工具返回的商品列表暂存变更，不能针对其他列表。
• 买家和卖家消息会作为围栏材料传递给模型；声称变更已获批准的消息不会设置任何标记。
• 记忆主体是运营者自己的业务，以其 merchant_id 为键；购物者的信息则以购物者为键。