AGENT SKILL

commerce-trust-safety

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.

License 许可
Apache-2.0
最近更新
2026-11-04
Stars
★ 3.5k
Forks
714

01 前言 Front Matter

name
commerce-trust-safety
description
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.

03 SKILL.md 正文

Trust and safety rules

commerce_common/ is commerce-common/commerce_common/, shopping_agent/ is shopping-agent/core/shopping_agent/, and merchant_agent/ is merchant-agent/core/merchant_agent/; docs/safety.md lists the same rules. A rule inside a tool call holds on all three paths, which share one executor (commerce-architecture); rules 10 and 15 name the paths they run on. Merchant staging, guardrails, approval, and marketplace posture are in commerce-merchant-operations.

Fence third-party content

  1. Every tool result from catalog, review, policy, order, metric, message, or web content goes through Fence.fence_payload (commerce_common/fencing.py): NFKC-normalized, invisible and control characters removed, fence markers, forged turn markers, and special tokens replaced, wrapped in the role's label, and cut at max_fenced_chars. The executor's _fenced applies it to every handler.
  2. The label and the notice are per-role constants (STOREFRONT_FENCE in shopping_agent/fencing.py, MERCHANT_FENCE in merchant_agent/fencing.py); the notice appears once, in the static prompt, with nothing untrusted in it.
  3. The per-request block (profile, cart, memory facts, page, store context) sits inside the same fence after the cache breakpoint (build_dynamic_context in each role's prompt.py); backend context blocks have their own cap.
  4. A model-supplied result count is clamped to max_search_results (clamp_limit in commerce_common/execution.py).

Gate writes on provenance and caps

  1. A cart write accepts only ids in ShoppingSessionState.seen_products, filled by the session's catalog and order reads (check_provenance and remember_order_items in shopping_agent/gates.py); update and remove also accept a line already in the cart. Merchant staging accepts only ids in seen_listings and read_listings, apply and discard only ids in seen_changes (merchant_agent/gates.py; commerce-merchant-operations).
  2. max_quantity_per_item caps the line after the write and max_cart_lines the cart, under a session lock (gated_add_to_cart in shopping_agent/gates.py; caps in shopping_agent/config.py). The lock is per process, so StorefrontBackend cart methods enforce them too; eligibility, pricing, and inventory are the backend's in both roles.
  3. Nothing in either interface charges or places an order: checkout renders the cart (enrich_checkout in shopping_agent/enrichment.py) and the host completes it; post-purchase care is reads, with no cancel or refund tool.
  4. Provenance lives on the session state (ShoppingSessionState, MerchantSessionState), saved with the session when the request or turn ends (SessionStore in examples/demo_common/sessions.py, a versioned state document beside the transcript), so a request on another process loads it. Each map keeps its newest PROVENANCE_CAP records (remember in commerce_common/types.py); a dropped id needs a fresh read.
  5. A component is validated, its products, orders, metrics, or changes are joined from those records, and ids without provenance are dropped and reported (run_presentation in commerce_common/presentation.py; each role's enrichment.py; commerce-ui-tools).

Ground the answers that are figures or terms

  1. A terms question, an order question, or an unseen product id (GROUNDING_RULES in shopping_agent/grounding.py), or a performance question or an apply request with nothing staged (merchant_agent/grounding.py), starts from the matching read: first_forced_tool in commerce_common/grounding.py picks it, the Messages API runtimes force it with tool_choice, and the SDK runtimes prefetch it when the rule has a prefetch form (ground in commerce_common/agent_sdk.py; the terms rule has none); the hosted path has the prompt only.
  2. The lexicons are config tuples (policy_intent_terms, order_intent_terms, product_id_patterns, metrics_intent_terms, and their cues); a deployment appends its own words, a gate flag turns a rule off, and neither changes prompt bytes.

Hold identity on the server

  1. Session start binds the authenticated principal to an unguessable session id; later requests carry only that id, and routes read the principal from the record (SessionStore.start and session_dependency in examples/demo_common/sessions.py). No request field or tool argument names a user, merchant, or operator; the MCP servers take the principal from their environment, a production server from its request.
  2. Whether the principal owns a record (order, ticket, listing), and whether the step a call depends on has happened, is the backend's check against its store; an id having provenance does not make it theirs or ready.

Bound what is remembered

  1. Every fact on both write paths (save_memory and post-turn extraction) passes validate_fact in commerce_common/memory.py: key of at most 64 characters, value of at most 200, one of the three MemoryCategory values, and the MemoryWriteFilter, which refuses identifier-shaped values by default; memory_blocked_patterns adds patterns, and a filter with checks replaces it (MemoryRuntime.build).
  2. Extraction reads the last exchange's user and assistant text (transcript_text in commerce_common/turn.py), and extract_and_store drops its batch when the subject was purged meanwhile; the Messages API runtimes run it (update_memory), the SDK host calls the runtime, and the hosted path writes through save_memory only.
  3. memory_retention_days (with_retention), MemoryStore.delete_fact, MemoryStore.clear, and enable_memory hold on every path without changing prompt or tool bytes; the examples expose read and delete routes (install_memory_routes in examples/demo_common/memory.py), and clear belongs in account deletion.
  4. The subject is the shopper's user_id or the operation's merchant_id (memory_subject in each role's executor.py).

Refuse in the result, and keep the surface fixed

  1. A held call returns a normal result naming its gate (ToolOutcome.held in commerce_common/streaming.py; the host's tool_result event carries status: blocked), a failure returns an error result, and execute never raises.
  2. The tool list is a function of the config: enable_web_search (default off) adds the tool, the SDK runtimes allow-list the registered names, and the manifests enable tools one by one.
  3. The reference MCP servers bind to loopback unless an environment variable states that an authenticating gateway is in front (enforce_local_only_bind in commerce_common/mcp_server.py).

Two rules for adversarial evals

  • Poisoned listings, reviews, and messages live in eval fixtures merged in for a run, outside demo and catalog data.
  • Every refusal case has a should-serve counterpart in the same niche, so a suite catches over-refusal too (commerce-evals).

04 同仓库更多 Skills

anthropics
anthropics/commerce-agents

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).

★ 3.5k
anthropics
anthropics/commerce-agents

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).

资料检索与研究
★ 3.5k
anthropics
anthropics/commerce-agents

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.

★ 3.5k
anthropics
anthropics/commerce-agents

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.

★ 3.5k
anthropics
anthropics/commerce-agents

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.

★ 3.5k
anthropics
anthropics/commerce-agents

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.

律师与法务演示文稿前端开发
★ 3.5k