commerce-merchant-operations
The reference merchant agent, covering its flows, staged changes and host approval, metrics grounding, the analysis delegate, store memory, components, and marketplace rules. Load when building or reviewing an agent for the operators of a store, property, subscriber base, or venue.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-04
- Stars
- ★ 3.5k
- Forks
- 714
01 前言 Front Matter
- name
- commerce-merchant-operations
- description
- The reference merchant agent, covering its flows, staged changes and host approval, metrics grounding, the analysis delegate, store memory, components, and marketplace rules. Load when building or reviewing an agent for the operators of a store, property, subscriber base, or venue.
03 SKILL.md 正文
Merchant agent
Paths are in the reference repo: merchant_agent/ is merchant-agent/core/merchant_agent/, merchant_agent_runtime/
is merchant-agent/runtime-messages-api/merchant_agent_runtime/, merchant_agent_sdk/ is
merchant-agent/runtime-agent-sdk/merchant_agent_sdk/, commerce_common/ is commerce-common/commerce_common/.
What it does
The merchant agent works with an operator inside their back office over one MerchantBackend (merchant_agent/backend.py).
Its five flows are the skills in merchant-agent/skills/: performance-insights, catalog-listings, inventory-operations,
pricing-promotions, marketing-campaigns. The mechanisms in commerce_common/ are shared; the prompt, tools, gates, and
executor are its own, and every tool result comes back inside MERCHANT_FENCE (merchant_agent/fencing.py).
The staged-change contract
- Every write is a
stage_*tool (stage_listing_update,stage_price_update,stage_inventory_action,stage_promotion,stage_campaign). Each returns the staged record and a note, emits achange_updateevent, and, withstage_shows_previewon (the default,merchant_agent/config.py), emits thechange_previewcard through the runnerpresent_change_previewuses (MerchantToolExecutor,merchant_agent/executor.py). The MCP server turns it off because its executor events do not reach the operator, so the hosted agent callspresent_change_preview; that tool also shows an earlier change again. Live state is untouched untilapply_change, which performs the platform write. - Staging accepts only listing and campaign ids that tools returned this session, and a content edit also needs a
get_listingread;apply_changeanddiscard_changeaccept only change ids that staging orget_pending_changesreturned (merchant_agent/gates.py). Showing the preview card marks nothing approved. check_guardrailsinmerchant_agent/changes.pyruns when a change is staged (ChangeLedger.stage, or your backend's equivalent) and again incheck_apply_change(merchant_agent/gates.py) under the config in force at apply time. The limits aremax_items_per_change,max_price_delta_pct,max_promotion_discount_pct,max_restock_quantity,max_campaign_budget, andmax_listing_field_charsinmerchant_agent/config.py; the defaults are demonstration values.protected_fieldscan never be staged,price_bearing_fieldsare the fields the price cap reads, andlisting_update_blocked_fieldsmay not ride a free-form listing update. A domain that prices under another name (a nightly rate, a monthly fee, a tier price) appends to these tuples and never replaces them.require_host_approvaldefaults toTrue:apply_changesucceeds only for an id inMerchantSessionState.approved_change_ids, which only host code writes. The three surfaces in the repo are the portal's/changes/{change_id}/applyroute (examples/demo_common/merchant.py),MerchantToolset.host_approve(merchant_agent_sdk/merchant_tools.py, prompted per change bymerchant-agent/runtime-agent-sdk/main.py), andalways_askonapply_changein the hosted manifest; there the MCP server's config setsrequire_host_approval=False(itsdefault_configdoes; a config you pass must too, or every apply is held). An approval typed into the chat sets nothing.require_host_approvalandapproval_surfacerender into the static prompt and into refusals, so they are set per deployment and a change to either is a redeploy (commerce-prompt-caching). Name the real surface inapproval_surface.- A change kind a system does not support raises
ChangeNotApplicable(merchant_agent/changes.py) and the executor relays it; the tool stays registered. Applied and discarded changes stay queryable as the audit trail, each stamped with the operator fromMerchantSessionContext.operator, which a production host derives from its authentication.
Grounding and follow-through
- A performance question forces
get_business_snapshot, and a change request carrying an apply phrase with nothing staged this session forcesget_pending_changes(GROUNDING_RULESinmerchant_agent/grounding.py; lexicons and flags inmerchant_agent/config.py, appended to and never replaced). - A turn that matched
change_requestedand ended on bare text, with nostage_*attempt and nopresent_suggestionsclose, getsSTAGING_FOLLOWTHROUGH_REMINDERonce, as a user message (merchant_agent/gates.py; applied inmerchant_agent_runtime/orchestrator.pyandmerchant_agent_sdk/agent.py); the reminder text is excluded from memory extraction. present_metricsjoins each pick from the snapshot, a queried series, a campaign, or a recorded analysis and drops the rest with a note (resolve_metricsinmerchant_agent/enrichment.py), so a card never carries a model-authored figure.
The analysis delegate
enable_analysis(default off) registersrun_analysis, aDelegateExtensionbuilt bybuild_analysis_delegateinmerchant_agent_runtime/analysis.py. The delegate's tools are a submit tool, a progress tool, theANALYSIS_READ_TOOLS(merchant_agent/analysis.py), and a query tool when the backend implementsMerchantBackend.execute_analysis_query(analysis_sql_onlythen leaves the per-series reads off). It holds no staging tool; its result is recorded inseen_analysesand rendered as its own metrics card.check_analysis_sqlrefuses anything other than one SELECT without comments before the backend runs it; the backend owns the read-only role and merchant scoping;analysis_query_timeout_sandcap_analysis_table(max_analysis_rows,max_analysis_table_chars) bound each query, andanalysis_timeout_s,max_analysis_iterations, andmax_delegate_calls_per_turnbound the run.analysis_use_code_executionmounts the hosted sandbox and works on the Anthropic API only (including a Foundry deployment hosted on Anthropic); the query method works everywhere (docs/deployment.md). On the Agent SDK the same contract is a subagent whose tools are exactly the read tools (build_analysis_agentinmerchant_agent_sdk/agent.py).- A scheduled digest is one headless turn of the same agent (
merchant-agent/managed-agents/scheduled-digest/run_morning_digest.py).
Memory and components
- Memory is keyed by
merchant_id(memory_subjectinmerchant_agent/executor.py); the extraction prompt inmerchant_agent/memory.pyadmits what the operator stated about running the operation and excludes anything from listings, reviews, buyer messages, or metrics and anything about an identifiable customer. The write filter, retention, delete, purge, andenable_memoryare the shared rules (commerce-trust-safety). - The built-in components (
merchant_agent/enrichment.py) arepresent_metrics,present_digest,present_change_preview, andpresent_suggestions; under host approval the prompt says no chip approves or applies. A vertical adds its own (present_occupancy_calendar,present_plan_mix,present_event_pacingin the examples) as extensions (commerce-ui-tools).
Marketplaces
- Many sellers' content goes through the one fence; there is no per-seller label and no seller whose text escapes it.
In a shopping deployment the seller is a search dimension (
SearchFilters.attributes) that the components show, andsearch_policiesresults state whose terms they are when platform and seller terms differ. - Provenance and caps are per session, so a session can stage against the listings its own tools returned and no others.
- Buyer and seller messages reach the model as fenced material; a message that says a change is approved sets no mark.
- The memory subject is the operator's own business, keyed by its
merchant_id; a shopper's facts are keyed by the shopper.
04 同仓库更多 Skills
search-discovery
Turning a described need (several constraints, a gift, a choice between candidates already in view, a search that came back empty or sold out) into a shortlist and a pick. Not needed when one search for the thing the customer named answers the request, or when the customer wants to learn what matters in a category first (purchase-research).
purchase-research
Teaching a customer how to choose before any candidates appear, when they ask what matters in a category, how two approaches to it differ, or where to begin. Not needed once the customer has named the thing they want, however considered the purchase (that is search work), nor for outfitting a space or an event (planning-goals).
planning-goals
Planning a coordinated set of items toward a goal, an event, a trip, or a project, where the request only comes together as several purchases with a structure between them, and later changes to a plan you have presented. Not needed when the customer wants a single item, however carefully chosen.
memory-personalization
Requests about what is remembered, however short, from an ask to remember one thing to asks to say what is on file, correct it, or forget it; a bare save or an answer from the profile alone does not cover these. Also applying what the store already knows, recalling an older fact (a past recipient, a size, a recurring order) when it would change the pick, and deciding what should outlast the session. Not needed when the request carries no personal context to apply or keep.
customer-care
Help after a purchase or booking, covering the status of an order or delivery whether or not the customer names it, returns, refunds, exchanges, and cancellations, an item that arrived damaged, incomplete, or late, and questions about the store's terms or a membership. Not needed for finding, comparing, or choosing something new.
commerce-ui-tools
The reference presentation-tool contract, covering server-side enrichment, suggestion chips, the event stream, progressive rendering, both roles' built-in components, and adding a vertical component. Load when building or reviewing how a commerce agent's output reaches a frontend.