commerce-ui-tools

Name: commerce-ui-tools
Author: anthropics/commerce-agents

$npx mdskill add anthropics/commerce-agents/commerce-ui-tools

Paths are in the reference repo: `commerce_common/` is `commerce-common/commerce_common/`, `shopping_agent/` is `shopping-agent/core/shopping_agent/`, `merchant_agent/` is `merchant-agent/core/merchant_agent/`.

SKILL.md

.github/skills/commerce-ui-toolsView on GitHub ↗

---
name: commerce-ui-tools
description: 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.
---

# Presentation tools

Paths are in the reference repo: `commerce_common/` is `commerce-common/commerce_common/`, `shopping_agent/` is
`shopping-agent/core/shopping_agent/`, `merchant_agent/` is `merchant-agent/core/merchant_agent/`.

## The contract

- A component is a tool. The model's arguments carry its judgment: which ids, in what order, the reason or the
note for each, what to compare on. The server joins every fact (title, price, image, metric value, change
record) from records tools returned this session, so the frontend never renders a model-authored value.
- One spec per component: `PresentationComponent` in `commerce_common/presentation.py` names the tool, the
`component` string the host renders, the `payload_model` that validates the arguments (each role's
`tools/presentation.py`), and the `enrich` hook (each role's `enrichment.py`, collected in `PRESENTATION_COMPONENTS`).
- `run_presentation` in `commerce_common/presentation.py` is the one runner: validate, enrich, emit the `ui` event.
The model reads the executor's `displayed_text` plus the hook's notes; the enriched payload goes to the host only.
- An enrich hook drops ids without provenance and appends a note naming them; with nothing left it raises
`PresentationRefused`, which comes back as a held call when it names a gate and as an error otherwise.
- Shopping joins from `ShoppingSessionState.seen_products`, the cart, or an order read; merchant joins from
`MerchantSessionState.latest_snapshot`, `seen_series`, `seen_campaigns`, `seen_analyses`, `seen_listings`, and `seen_changes`.
`enrich_change_preview` also removes model text whose currency or weekday disagrees with the change record.
- Composition rules (which component ends a turn, text carries the reasoning, cards carry the data) are static
prompt material; each component's when-to-use line is its tool description (commerce-architecture's layer table).

## Suggestions

- `present_suggestions` is the one tool that carries the turn's chips, up to four; the model calls it in the same
round as the turn's last component, or after its text when the turn has none, and a tapped chip is sent as the next
user message. No other payload, built-in or extension, carries chips.
- `sanitize_suggestion_chips` in `commerce_common/fencing.py` runs on `PresentSuggestionsPayload`: invisible and control
characters out, whitespace collapsed, empties dropped, 80 characters each, four at most. The payload fails when no
chip survives sanitizing.
- A round of clean presentation calls that includes `present_suggestions` ends the turn (`round_closes_turn` in
`commerce_common/turn.py`, `close_on_presentation` in the config): the Messages API loop stops there, and the Agent
SDK runtimes stop through a `PostToolBatch` hook (`close_on_presentation_hook` in `commerce_common/agent_sdk.py`).
Under host approval the merchant prompt says no chip approves or applies.

## Streaming

The event list is the docstring of `commerce_common/streaming.py`; `to_sse` frames each event and a host ignores
types it does not know. `ui` carries one enriched component, `ui_partial` the same while its call still streams,
`cart_update` the whole cart after a cart write, and `change_update` a change record after it moved. `outcome_events`
in `commerce_common/turn.py` stamps each `ui` event with its call id as `stream_id` and follows it with the
`tool_result`, whose `status` is `ok`, `error`, or `blocked`. Every tool that is not a presentation tool may take a
`status` argument first (`with_status` in `commerce_common/execution.py`): a few words for the person waiting, which
the executor drops before the call runs and the runtime emits as the `tool_call` event's `label`; the web layer shows
it as the activity line. The MCP servers build their tools without it. The Agent SDK runtimes run the same executor but return the payloads together in `result.ui`
after the turn.

## Progressive rendering

A spec with an `enrich_partial` hook is rendered while its arguments arrive: the request marks its tool
`eager_input_streaming` (`with_eager_input` in `commerce_common/prompt_assembly.py`), the orchestrator parses the
buffer with `parse_partial_json` (a string still being written is left out with its key), calls `enrich_partial`
(`commerce_common/presentation.py`), and yields `ui_partial` whenever `partial_signature` changes (`StreamedRound.frame`
in `commerce_common/turn.py`; every visible change with `eager_partial_frames` on the config); the final `ui` event
carries the same `stream_id` and replaces it. Input that streams as text that is not JSON comes back to the model as
an error result and the round goes on (`StreamedRound`). Partial
hooks are synchronous and join from session state only (`partial_products`, `partial_comparison`, `partial_plan`,
`partial_guide` in `shopping_agent/enrichment.py`; `partial_metrics`, `partial_digest`, `partial_change_preview` in
`merchant_agent/enrichment.py`).

## Built-in components

- Shopping (`shopping_agent/enrichment.py`): `present_products`, `present_comparison`, `present_plan`, `present_guide`,
`present_order_status`, `checkout` (renders the cart; charges nothing), `present_suggestions`, and `present_disclosure`,
registered only with `enable_disclosures` and filled from `StorefrontBackend.get_disclosure`.
- Merchant (`merchant_agent/enrichment.py`): `present_metrics`, `present_digest`, `present_change_preview`, `present_suggestions`.

## Adding a vertical component

- Build a `PresentationExtension` (`commerce_common/presentation.py`): the tool description and `input_schema` the
model sees, the `payload_model` that validates the same shape, the `component` name, and the enrich hook.
- Pass it as `extra_presentation_tools` to `ShoppingAgent` or `MerchantAgent` (`examples/travel/api/main.py`); on
the Agent SDK and MCP paths, subclass the toolset or pass `executor_class=` so the executor receives it as
`extensions`. `build_tools` rejects a name that collides with a built-in,
and the extension's bytes join the cached tool list (commerce-prompt-caching).
- The seven in the repo: `examples/travel/api/itinerary.py`, `examples/travel/api/occupancy.py`,
`examples/telecom/api/plan_matrix.py`, `examples/telecom/api/plan_mix.py`, `examples/entertainment/api/venue_map.py`,
`examples/entertainment/api/hold_view.py`, `examples/entertainment/api/event_pacing.py`. Each keeps its types and
its card in the vertical; nothing is added to a core package.

More from anthropics/commerce-agents

Skill	Description
catalog-listings	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.
commerce-architecture	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.
commerce-evals	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.
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.
commerce-prompt-caching	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.
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.
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.
inventory-operations	Stock, capacity, and availability monitoring, acting on low-stock and slow-mover alerts, triaging order exceptions such as delays, return spikes, and complaints, and the operator's daily briefing; any start-of-day or what-needs-attention rundown is this flow, presented as a digest. Not needed for performance questions with no operational action attached.
marketing-campaigns	Drafting campaigns and ads as staged drafts, from acquisition and seasonal pushes to lifecycle sends such as win-backs, pre-arrival messages, and presale or last-call notices, choosing audiences and placements by intent, allocating budget across campaigns, and reviewing campaign results with their attribution caveats. Not needed for listing copy (catalog-listings) or overall performance questions (performance-insights).
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.