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.
インストール方法を見るインストールする前に、エージェントに与えられる指示の中身を確認できます。
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/.
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.PresentationRefused, which comes back as a held call when it names a gate and as an error otherwise.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.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.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.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.
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).
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_agent/enrichment.py): present_metrics, present_digest, present_change_preview, present_suggestions.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.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).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.まだレビューはありません。使ってみた感想をお寄せください。
概要と使いどころ
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 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.
日本語の概要は準備中です。原文の説明を表示しています。
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.
日本語の概要は準備中です。原文の説明を表示しています。