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.
中文简介正在准备中。当前显示原文说明。
查看安装方法安装前可以查看交给 AI 代理的指令内容。
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/.
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).
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.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.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.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.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.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.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.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).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.enable_analysis (default off) registers run_analysis, a DelegateExtension built by build_analysis_delegate in
merchant_agent_runtime/analysis.py. The delegate's tools are a submit tool, a progress tool, the ANALYSIS_READ_TOOLS
(merchant_agent/analysis.py), and a query tool when the backend implements MerchantBackend.execute_analysis_query
(analysis_sql_only then leaves the per-series reads off). It holds no staging tool; its result is recorded in
seen_analyses and rendered as its own metrics card.check_analysis_sql refuses 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_s and cap_analysis_table (max_analysis_rows,
max_analysis_table_chars) bound each query, and analysis_timeout_s, max_analysis_iterations, and
max_delegate_calls_per_turn bound the run.analysis_use_code_execution mounts 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_agent in merchant_agent_sdk/agent.py).merchant-agent/managed-agents/scheduled-digest/run_morning_digest.py).merchant_id (memory_subject in merchant_agent/executor.py); the extraction prompt in
merchant_agent/memory.py admits 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, and enable_memory are the shared rules (commerce-trust-safety).merchant_agent/enrichment.py) are present_metrics, present_digest, present_change_preview,
and present_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_pacing in the examples) as extensions (commerce-ui-tools).SearchFilters.attributes) that the components show, and
search_policies results state whose terms they are when platform and seller terms differ.merchant_id; a shopper's facts are keyed by the shopper.还没有评价。欢迎分享你的使用感受。
无需登录即可发表。欢迎分享使用感受、提问，或说明在哪些环境下无法运行。
还没有评论。来写第一条吧。
Creating and improving listing content, covering titles, descriptions, attribute completeness, categorization fixes, image callouts written as text, edits written from material the operator supplies, and content-quality audits and bulk fixes across many listings. Not needed for questions about how a listing is performing.
中文简介正在准备中。当前显示原文说明。
How the reference commerce agents of either role are structured, covering the loop, where each rule lives, skills, the backend interface, delegates, and model fields. Load when designing or reviewing the structure of a shopping or merchant agent.
中文简介正在准备中。当前显示原文说明。
Authoring and running behavioral evals for a shopping or merchant agent, covering the case shape, authoring rules, code graders and judges, the run pattern, and poisoned fixtures. Load when writing eval cases or rubrics or deciding how a suite runs.
中文简介正在准备中。当前显示原文说明。
The reference agents' cache-stable request assembly, covering the static system and per-request context split, the fixed tool list, the rolling conversation breakpoint, which config fields are prompt bytes, and verification. Load when writing or reviewing a commerce agent's prompt assembly, when cache reads are zero, or when a turn's latency or cost is the question.
中文简介正在准备中。当前显示原文说明。
The rules the reference agents enforce in code for third-party content, writes, grounding, identity, and memory, each with its module, plus two adversarial-eval rules. Load when handling untrusted tool results, guarding a write tool, or scoping what an agent remembers.
中文简介正在准备中。当前显示原文说明。
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.
中文简介正在准备中。当前显示原文说明。