commerce-ui-tools

プレゼンテーションツール

パスはリファレンスリポジトリ内のものです。commerce_common/ は commerce-common/commerce_common/、shopping_agent/ は shopping-agent/core/shopping_agent/、merchant_agent/ は merchant-agent/core/merchant_agent/ です。

契約

• コンポーネントはツールです。モデルの引数には、その判断が含まれます。つまり、どの ID をどの順番で使うか、それぞれの理由やメモ、比較対象です。サーバーは、このセッション中にレコードツールが返した記録から、すべての事実（タイトル、価格、画像、指標値、変更記録）を結合するため、フロントエンドがモデル作成の値を描画することはありません。
• コンポーネントごとに仕様が 1 つあります。commerce_common/presentation.py の PresentationComponent が、ツール名、ホストが描画する component 文字列、引数を検証する payload_model（各ロールの tools/presentation.py）、そして enrich フック（各ロールの enrichment.py。PRESENTATION_COMPONENTS に集約）を指定します。
• commerce_common/presentation.py の run_presentation が唯一のランナーです。検証、エンリッチ、ui イベントの送出を行います。モデルが読み取るのは、エグゼキューターの displayed_text とフックのメモです。エンリッチ済みのペイロードはホストにのみ渡されます。
• エンリッチフックは来歴のない ID を除外し、それらの名前を挙げたメモを追加します。残るものがなければ PresentationRefused を送出します。ゲート名が指定されている場合は保留中の呼び出しとして返され、それ以外の場合はエラーとして返されます。
• ショッピングでは ShoppingSessionState.seen_products、カート、または注文の読み取り結果から結合します。マーチャントでは MerchantSessionState.latest_snapshot、seen_series、seen_campaigns、seen_analyses、seen_listings、seen_changes から結合します。 enrich_change_preview は、通貨または曜日が変更記録と一致しないモデルのテキストも削除します。
• 構成ルール（どのコンポーネントでターンを終了するか、テキストに推論を含め、カードにデータを含めること）は静的なプロンプト素材です。各コンポーネントの使用タイミングを示す文は、そのツールの説明です（commerce-architecture のレイヤーテーブル）。

提案

• present_suggestions は、そのターンのチップを最大 4 つ載せる唯一のツールです。モデルは、ターンの最後のコンポーネントと同じラウンドで呼び出すか、ターンにコンポーネントがない場合はテキストの後に呼び出します。タップされたチップは、次のユーザーメッセージとして送信されます。組み込みか拡張機能かを問わず、チップを載せられるペイロードはほかにありません。
• commerce_common/fencing.py の sanitize_suggestion_chips は PresentSuggestionsPayload に適用されます。不可視文字と制御文字を除去し、空白をまとめ、空の項目を削除します。各項目は 80 文字以内、最大 4 項目です。サニタイズ後に残るチップがない場合、ペイロードは失敗します。
• present_suggestions を含む、問題のないプレゼンテーション呼び出しのラウンドはターンを終了します（commerce_common/turn.py の round_closes_turn、設定の close_on_presentation）。Messages API のループはそこで停止し、Agent SDK ランタイムも PostToolBatch フック（close_on_presentation_hook in commerce_common/agent_sdk.py）を通じて停止します。ホストによる承認が必要な場合、マーチャント向けプロンプトには、チップでは承認も適用も行われないことが記載されています。

ストリーミング

イベント一覧は commerce_common/streaming.py の docstring に記載されています。to_sse は各イベントをフレーム化し、ホストは認識できないタイプを無視します。ui にはエンリッチ済みコンポーネントが 1 つ含まれ、ui_partial には呼び出しのストリーミング中に同じ内容が含まれます。cart_update はカート書き込み後のカート全体を、change_update は変更後の変更記録を含みます。commerce_common/turn.py の outcome_events は、各 ui イベントに呼び出し ID を stream_id として付与し、その後に tool_result を続けます。その status は ok、error、blocked のいずれかです。プレゼンテーションツール以外のすべてのツールでは、最初の引数に status を指定できます（commerce_common/execution.py の with_status）。これは待っている人に伝える短い文言で、エグゼキューターは呼び出しの実行前に取り除き、ランタイムは tool_call イベントの label として出力します。ウェブレイヤーでは、これがアクティビティ行として表示されます。MCP サーバーは、この引数を含めずにツールを構築します。Agent SDK ランタイムは同じエグゼキューターを実行しますが、ターン後にペイロードをまとめて result.ui として返します。

段階的なレンダリング

enrich_partial フックを持つ仕様は、引数の受信に合わせてレンダリングされます。リクエストでは、そのツールを eager_input_streaming（commerce_common/prompt_assembly.py の with_eager_input）として指定し、オーケストレーターが parse_partial_json でバッファーを解析します（書き込み途中の文字列は、そのキーとともに除外されます）。その後、enrich_partial （commerce_common/presentation.py）を呼び出し、partial_signature が変化するたびに ui_partial を生成します（commerce_common/turn.py の StreamedRound.frame 。設定で eager_partial_frames を有効にすると、表示上の変化ごとに生成されます）。最終的な ui イベントには同じ stream_id が含まれ、それが置き換えられます。JSON ではないテキストとしてストリーミングされた入力は、エラー結果としてモデルに返され、ラウンドは続行されます （StreamedRound）。部分レンダリング用の フックは同期処理で、セッション状態の情報のみを結合します（shopping_agent/enrichment.py の partial_products、partial_comparison、partial_plan、 partial_guide、merchant_agent/enrichment.py の partial_metrics、partial_digest、partial_change_preview）。

組み込みコンポーネント

• ショッピング（shopping_agent/enrichment.py）：present_products、present_comparison、present_plan、present_guide、 present_order_status、checkout（カートをレンダリングします。請求は発生しません）、present_suggestions、および present_disclosure。 present_disclosure は enable_disclosures が有効な場合にのみ登録され、StorefrontBackend.get_disclosure からデータを取得します。
• マーチャント（merchant_agent/enrichment.py）：present_metrics、present_digest、present_change_preview、present_suggestions。

業界固有のコンポーネントを追加する

• PresentationExtension（commerce_common/presentation.py）を作成します。モデルが認識するツールの説明と input_schema、 同じ形式を検証する payload_model、component 名、および拡張フックを指定します。
• extra_presentation_tools として ShoppingAgent または MerchantAgent（examples/travel/api/main.py）に渡します。Agent SDK および MCP の経路では、ツールセットをサブクラス化するか、executor_class= を渡して、エグゼキューターが extensions として受け取れるようにします。build_tools は組み込みコンポーネントと名前が重複する場合に拒否し、拡張のバイト列はキャッシュされたツールリストに含まれます（commerce-prompt-caching）。
• リポジトリにある 7 つのコンポーネントは、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 です。それぞれの型とカードは各業界固有の領域に置かれており、コアパッケージには何も追加されません。