linkfox-amazon-alexa-for-shopping

Amazon Alexa ショッピングアシスタント

このスキルは、Amazon のストアフロントにある Alexa ショッピングアシスタントを操作します。自然言語で質問すると、回答、厳選された商品リスト（ASIN とリンク付き）、および Alexa が続けて回答できるフォローアップ質問の一覧が返されます。各呼び出しで指定できるプロンプトは 1 つだけです。複数ターンの会話では、エージェントが以前のコンテキストを要約し、新しい質問と連結して新たに呼び出す必要があります。

基本概念

1. 呼び出しごとに 1 ターン：prompts は配列ですが、要素は 1 つしか指定できません。各 API 呼び出しでは Alexa に質問を 1 つだけ送信し、回答が 1 つ返されます。複数の要素を渡さないでください。
2. 呼び出しをまたいでコンテキストは保持されません：呼び出しごとに、新しい Alexa セッションが開始されます。フォローアップ質問をするには、エージェントが以前の回答（主なおすすめ商品、ASIN、関連するコンテキスト）を要約し、新しい呼び出しの prompts[0] として新しい質問に連結する必要があります。
3. 任意のページコンテキスト（url）：会話を特定のページ（カテゴリページ、検索結果ページ、商品詳細ページ）に基づいて行いたい場合にのみ、Amazon のページ URL を渡してください。https://www.amazon.com/ のようなマーケットプレイスのトップページ URL は渡さないでください。有用なコンテキストは追加されません。基準となる特定のページがない場合は、url を省略してください。
4. 2 種類の出力形式：
   • markdown（デフォルト）— 質問、Alexa の回答、おすすめ商品のグループ、フォローアップ質問を含む、読みやすい 1 つの Markdown レポートです。
   • json — data の下に構造化された配列を返します。各項目には prompt、content、products（グループ化されたおすすめ商品）、followUpQuestions、screenshot が含まれます。

resultsNum は Alexa が実際に回答した会話ターン数です。0 の場合、入力に対して利用可能な回答はありませんでした。

パラメーター

パラメーター	型	必須	説明	デフォルト
prompts	string[]	はい	会話プロンプトです。1 回の呼び出しで指定できるのは要素 1 つだけです。フォローアップ質問をするには、コンテキストの要約と新しい質問を prompts[0] として指定し、新たに呼び出してください。	-
format	string	いいえ	応答形式です。markdown は読みやすいレポートを返し、json は構造化された配列を返します。	markdown
url	string	いいえ	会話の基準となる特定の Amazon ページ URL（カテゴリ、検索結果、商品詳細）です。特定のページがない場合は省略してください。https://www.amazon.com/ のようなトップページ URL は渡さないでください。	-

応答フィールド

フィールド	型	説明
stdout	string	format=markdown の場合の Markdown レポートです。各ターンの質問、Alexa の回答、おすすめ商品のグループ、フォローアップ質問が含まれます
data	array	format=json の場合の構造化されたターンです。各項目には prompt、content、products[]、followUpQuestions[]、screenshot が含まれます
resultsNum	integer	回答されたターン数（0 = Alexa が応答しなかった）
code / errcode	string / integer	成功時は 200、200 以外はビジネスエラーを示します
msg / errmsg	string	成功時は ok、それ以外はエラーの説明です
costTime	integer	API のレイテンシ（ミリ秒）
costToken	integer	消費されたトークン数（成功時のみ課金）
taskId	string	トレース用の上流タスク識別子
type	string	レンダリングのヒントです。Markdown の場合は stdoutWorkbenches、JSON の場合は json です

構造化された data[*] の形式（format=json）

Field	Type	Description
prompt	string	このターンで送信された質問または追加質問
content	string	Alexa による自然言語での回答
products[].title	string	グループのタイトル（例：「おすすめ商品」「ランニングに最適」）
products[].items[].asin	string	商品の ASIN
products[].items[].title	string	商品名
products[].items[].url	string	商品詳細ページの URL
products[].items[].cover	string	商品のカバー画像の URL
products[].items[].price	string	現在の価格（通貨を含む）
products[].items[].originalPrice	string	表示価格／取り消し線付き価格
products[].items[].score	string	星評価
products[].items[].ratingsCount	string	レビュー件数
products[].items[].describe	string	商品の簡単な説明
followUpQuestions	string[]	Alexa が次の会話のために提示する質問
screenshot	string	このターンのスクリーンショット URL

API の使用方法

このスキルは LinkFox ツールゲートウェイを呼び出します。呼び出し規約、リクエスト／レスポンスの形式、エラーコード、curl の例については references/api.md を参照してください。コマンドラインから直接テストするには、scripts/amazon_alexa_search.py も実行できます。

クエリの作成方法

1. ユーザーの意図を prompts[0] の先頭に記述します — マーケットプレイスの手がかり（「on Amazon US」）、用途、必須条件（予算、主要機能など）を含めてください。Alexa は質問の冒頭を重視します。
2. 1 回の呼び出しにつき質問は 1 つです — prompts が受け付ける要素は 1 つだけです。複数の要素を渡さないでください。
3. 追加質問では要約して再度質問します — ユーザーが会話の継続を希望する場合、エージェントは次の手順を実行する必要があります。（a）前回の Alexa の回答の要点（回答のハイライト、おすすめの ASIN、関連するコンテキスト）を要約する。（b）その要約に新しい質問をつなげる。（c）新しい API 呼び出しで prompts[0] として送信する。Alexa は以前の呼び出しの内容を記憶していません。
4. 特定のページがある場合に限り url を指定します — そのページをもとにユーザーが検討している場合は、カテゴリ、検索結果、または商品詳細ページの URL を渡してください。一般的な質問では url を省略してください。https://www.amazon.com/ のようなトップページだけの URL は渡さないでください。
5. 目的に応じて format を選択します — ユーザーに整った回答を表示するには markdown が最適です。後続のコードで ASIN、価格、追加質問をプログラムから抽出する必要がある場合は、json が適しています。

使用例

1. 1 回のやり取りで完結する買い物の質問

{
  "prompts": ["best wireless earbuds for running on Amazon US under $100"]
}

2. 追加質問（エージェントが前回のコンテキストを要約して再度質問）

1 回目の呼び出し：

{
  "prompts": ["best electric kettle on Amazon US"]
}

2 回目の呼び出し（エージェントが前回の回答を要約し、追加質問を付け加える）：

{
  "prompts": ["Previously Alexa recommended: 1) Cosori Electric Kettle (B07T1KY5TZ, $35.99, 4.7★), 2) Mueller Ultra Kettle (B09KC7D3HR, $29.97, 4.5★). Now compare these two on noise level and boil time."]
}

3. カテゴリページをもとにした質問

{
  "prompts": ["What are the most popular picks on this page?"],
  "url": "https://www.amazon.com/s?k=electric+kettle"
}

4. 後続の抽出に使う構造化出力

{
  "prompts": ["best gift ideas for a 10-year-old who likes science"],
  "format": "json"
}

表示ルール

1. format=markdown の場合は Markdown をそのまま表示します — stdout はターン見出し、商品カード、追加質問を含む構造化済みの内容です。その構造を保ってください。
2. おすすめの ASIN を提示します — ユーザーが商品ページに移動できるよう、title、price、score／ratingsCount、商品 URL を表示してください。
3. Alexa が返した追加質問を表示します — ユーザーがさらに調べるために選べるプロンプトとして利用できます。ユーザーが質問を選んだら、現在の回答を要約し、選択された追加質問を prompts[0] として新しい呼び出しに使用してください。
4. データ分析用のサンドボックスに転送しないでください — 回答本文は会話形式であり、おすすめ商品はネストされたグループになっています。SQL のような集計に適した、フラットな表形式のデータセットではありません。
5. 結果が空の場合はその旨を伝えます — resultsNum が 0 または data が空の場合は、Alexa から利用可能な回答が得られなかったことを伝え、質問の言い換え、または url を指定することを提案してください。
6. 情報の鮮度を示します — 結果は呼び出し時点での Alexa のリアルタイム回答を反映しています。ユーザーが時期について尋ねた場合は、その旨を伝えてください。
7. ビジネスエラーに対応します — code／errcode が 200 以外の場合は、msg／errmsg の内容を伝え、簡潔なプロンプトで再試行することを提案してください。

重要な制限事項

• Alexa による応答であり、決定論的ではありません：同じプロンプトでも、呼び出しごとに異なる回答が返る場合があります。Alexa の応答は、時間帯、トラフィック、コンテキストによって変わります。
• 呼び出しをまたいだ記憶はありません：ツールを呼び出すたびに新しい Alexa セッションが開始されます。エージェントは以前のコンテキストを要約し、新しい質問に含める必要があります。
• 1 回の呼び出しにつきプロンプトは 1 つです：prompts が受け付ける要素は 1 つだけです。追加の質問をする場合、エージェントはコンテキストと新しい質問を 1 つの prompts[0] に要約して、新たに呼び出す必要があります。
• マーケットプレイスの対象範囲：Amazon のストアフロントにおける Alexa の利用体験（主に amazon.com）を対象としています。米国外のマーケットプレイスで利用できるかどうかは、Alexa の展開状況によって異なります。
• 出力の構成：主な価値は、会話形式の回答と厳選された少数の商品です。検索結果ページ（SERP）全体から商品を抽出する代わりにはなりません。

ユーザーの表現とシナリオのクイックリファレンス

適用対象 — Amazon での自然言語による会話形式のショッピング：

ユーザーの発言	シナリオ
"用 Alexa 帮我推荐...", "亚马逊 Alexa 问下..."	Alexa への直接的な質疑応答
"在亚马逊上聊聊给我推荐 ...", "对话式选品"	会話形式の商品探索
"顺便再追问一下 / 接着问 ..."	追加質問（エージェントが以前の結果を要約し、新しい呼び出しで再度質問します）
"在这个页面 / 这个分类下推荐...", "基于这个页面再问一下"	ページを基点とした会話（url を使用します）
"best XX for YY under $Z on Amazon"	目的、条件、予算に関する質疑応答
"对比 Alexa 给的前两个推荐"	Alexa の回答に含まれる上位 2 件のおすすめを比較
"Alexa 还能继续问什么 / 给我一些追问思路"	追加質問の候補を提示

適用対象外 — 別のスキルに振り分けるのが適切です：

• キーワードに対する、順位やスポンサーフラグなどを含む SERP 全体の取得（ストアフロント検索シミュレーションスキルを使用します）。
• 過去の検索語句に関する分析や検索ボリュームの推移（ABA データエクスプローラーを使用します）。
• 既知の ASIN に関する詳細な商品情報、A+ コンテンツ、箇条書き（Amazon 商品詳細スキルを使用します）。
• レビュー単位のセンチメント分析（Amazon レビュースキルを使用します）。
• 画像を使った類似商品の検索（画像検索スキルを使用します）。
• 商品のフラットなリストに対する集計統計（ここでは構造化テーブルを利用できません）。

適用範囲の判断：ユーザーが会話を求めている場合（「Amazon に質問して、おすすめを聞き、その後も質問を続ける」）、このスキルが適用されます。検索結果の生データ行、構造化分析、または特定の ASIN のデータを求めている場合は、代わりに該当する専門スキルに振り分けてください。

フィードバック：

次のいずれかに該当する場合は、Feedback API を通じてフィードバックを自動検出し、報告してください：

1. このスキルで説明されている機能または目的が、実際の動作と一致しない場合
2. スキルの結果がユーザーの意図と一致しない場合
3. ユーザーがこのスキルに対する不満または称賛を示した場合
4. 改善できると思われることがある場合

references/api.md に記載されているとおりに Feedback API を呼び出してください。ユーザーの作業の流れを妨げないでください。

大きなレスポンスの処理

エージェントのコンテキストがあふれないよう、レスポンスをディスクに保存し、必要なフィールドだけを抽出します。

python scripts/response_io.py run --script scripts/amazon_alexa_search.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

--out-dir は、Git の作業ツリーの外（Unix では /tmp/...、Windows では %TEMP%/... など）に指定してください。保存されたレスポンスには、PII、価格、認証に関わる機密データが含まれている可能性があります。コミットしないでください。ファイルは自動削除されないため、タスクが終わったら削除してください。

run はレスポンス全体をファイルに書き込み、スキーマのプレビューとファイルパスのみを出力します。read は特定のフィールドを抽出し、スライスには --limit/--offset、出力形式には --format json|jsonl|csv|table を指定できます。

このパターンを優先する場合 — レスポンスの特性に応じて判断してください。たとえば、次のような場合です。

• レコードあたりのフィールド数が多い、または不要なフィールドがある
• バッチ／ページネーションされた結果（1 回の呼び出しで複数の項目を返す）
• 長文のフィールド（説明、レビュー、HTML、時系列データ）
• すぐに使うのではなく、後続の手順でも出力を再利用する

小規模で一度だけ使うレスポンスの場合は、メインスクリプトを直接呼び出しても問題ありません。

⚠️ プレビューは省略されたスキーマとサンプルであり、データ全体ではありません。フィールド単位で判断する場合は、必ず保存されたファイルを read で読み取ってください。

---

高品質でプロフェッショナルな越境 EC スキルをさらに利用するには、LinkFox Skills を設定してください。