Commerce Merchant Operations

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

1. 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 a change_update event, and, with stage_shows_preview on (the default, merchant_agent/config.py), emits the change_preview card through the runner present_change_preview uses (MerchantToolExecutor, merchant_agent/executor.py). The MCP server turns it off because its executor events do not reach the operator, so the hosted agent calls present_change_preview; that tool also shows an earlier change again. Live state is untouched until apply_change, which performs the platform write.
2. Staging accepts only listing and campaign ids that tools returned this session, and a content edit also needs a get_listing read; apply_change and discard_change accept only change ids that staging or get_pending_changes returned (merchant_agent/gates.py). Showing the preview card marks nothing approved.
3. check_guardrails in merchant_agent/changes.py runs when a change is staged (ChangeLedger.stage, or your backend's equivalent) and again in check_apply_change (merchant_agent/gates.py) under the config in force at apply time. The limits are max_items_per_change, max_price_delta_pct, max_promotion_discount_pct, max_restock_quantity, max_campaign_budget, and max_listing_field_chars in merchant_agent/config.py; the defaults are demonstration values.
4. protected_fields can never be staged, price_bearing_fields are the fields the price cap reads, and listing_update_blocked_fields may 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.
5. require_host_approval defaults to True: apply_change succeeds only for an id in MerchantSessionState.approved_change_ids, which only host code writes. The three surfaces in the repo are the portal's /changes/{change_id}/apply route (examples/demo_common/merchant.py), MerchantToolset.host_approve (merchant_agent_sdk/merchant_tools.py, prompted per change by merchant-agent/runtime-agent-sdk/main.py), and always_ask on apply_change in the hosted manifest; there the MCP server's config sets require_host_approval=False (its default_config does; a config you pass must too, or every apply is held). An approval typed into the chat sets nothing.
6. require_host_approval and approval_surface render 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 in approval_surface.
7. 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 from MerchantSessionContext.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 forces get_pending_changes (GROUNDING_RULES in merchant_agent/grounding.py; lexicons and flags in merchant_agent/config.py, appended to and never replaced).
• A turn that matched change_requested and ended on bare text, with no stage_* attempt and no present_suggestions close, gets STAGING_FOLLOWTHROUGH_REMINDER once, as a user message (merchant_agent/gates.py; applied in merchant_agent_runtime/orchestrator.py and merchant_agent_sdk/agent.py); the reminder text is excluded from memory extraction.
• present_metrics joins each pick from the snapshot, a queried series, a campaign, or a recorded analysis and drops the rest with a note (resolve_metrics in merchant_agent/enrichment.py), so a card never carries a model-authored figure.