SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslinkfox-amazon-alexa-search

linkfox-amazon-alexa-search

Marketing & growth

View repository

Updated 10-16 00:00

About this skill

Amazon Alexa Shopping Assistant

This skill drives Amazon's storefront Alexa shopping assistant: pose a natural-language question and get an answer, a curated product list (with ASINs and links), and a set of follow-up questions Alexa is willing to continue with. Each call supports only one prompt. For multi-turn conversations, the agent must summarize prior context and concatenate it with the new question in a fresh call.

Core Concepts

  1. Single-turn per call: prompts is an array but only supports 1 element. Each API call sends exactly one question to Alexa and returns one answer. Do not pass multiple elements.
  2. Cross-call context is not preserved: every call starts a brand-new Alexa session. To ask follow-up questions, the agent must summarize the previous answer (key recommendations, ASINs, relevant context) and concatenate it with the new question as prompts[0] in a new call.
  3. Optional page context (url): pass an Amazon page URL only when you want the conversation anchored to a specific page (a category page, search results page, or product detail page). Do not pass a plain marketplace homepage URL like https://www.amazon.com/ — it adds no useful context. Omit url entirely when there is no specific page to anchor on.
  4. Two output formats:
    • markdown (default) — a single readable Markdown report containing the question, Alexa's answer, recommended product groups, and follow-up questions.
    • json — a structured array under data, where each entry carries prompt, content, products (grouped recommendations), followUpQuestions, and screenshot.

resultsNum is the number of conversation turns Alexa actually answered; if 0, Alexa did not produce a usable reply for the input.

Parameters

Parameter Type Required Description Default
prompts string[] Yes Conversation prompts. Only 1 element is allowed per call. To ask follow-up questions, make a new call with context summary + new question as prompts[0]. -
format string No Response format: markdown returns a readable report; json returns a structured array. markdown
url string No Specific Amazon page URL (category, search results, or product detail) to anchor the conversation. Skip when there is no specific page; do not pass a plain homepage URL such as https://www.amazon.com/. -

Response Fields

Field Type Description
stdout string Markdown report when format=markdown: per-turn question, Alexa answer, recommended product groups, follow-up questions
data array Structured turns when format=json. Each item has prompt, content, products[], followUpQuestions[], screenshot
resultsNum integer Number of answered turns (0 = Alexa did not respond)
code / errcode string / integer 200 on success; non-200 indicates a business error
msg / errmsg string ok on success; otherwise an error description
costTime integer API latency in milliseconds
costToken integer Tokens consumed (only billed on success)
taskId string Upstream task identifier for tracing
type string Render hint: stdoutWorkbenches for markdown, json for json

Structured data[*] shape (format=json)

Field Type Description
prompt string The question or follow-up sent for this turn
content string Alexa's natural-language answer
products[].title string Group title (e.g. "Top picks", "Best for running")
products[].items[].asin string Product ASIN
products[].items[].title string Product title
products[].items[].url string Product detail page URL
products[].items[].cover string Product cover image URL
products[].items[].price string Current price string (with currency)
products[].items[].originalPrice string List price / strikethrough price
products[].items[].score string Star rating
products[].items[].ratingsCount string Review count
products[].items[].describe string Short product blurb
followUpQuestions string[] Questions Alexa offers to continue with
screenshot string Screenshot URL for this turn

How to call

  • API endpoint：POST /amazon/alexaSearch(For complete parameters/response/error codes, see references/api.md）
  • Python script：python scripts/amazon_alexa_search.py '<JSON 参数>' [--inline]
  • Cost constraints: This tool consumes compute; by default, the same parameter combination in the same session is called only once, and the script has a 24h local cache. On failure or empty results, do not automatically switch keywords, turn pages, or change the zip code to probe continuously; if continued retrieval is needed, first explain to the user that additional consumption will be incurred.

Output strategy (default script behavior)：

  • Alwayswrite the complete response to <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-alexa-search-<timestamp>.json（<cwd> is the working directory when the script is executed, which in Claude Code is the current project directory;<session> is taken from the environment variable SESSION_ID, automatically aggregated according to the user task;writing to /tmp is prohibited, and if the current directory is not writable, report an error)
  • Response body ≤ 8 KB: after writing to disk, print the complete JSON to stdout
  • Response body > 8 KB: after writing to disk, stdout outputs only a summary (top-level fields, common counts such as total/costToken, the length of the largest list field + the first 3 samples)
  • add --inline to force full printing to stdout (also written to disk)

Data reading suggestions: first look at the summary to determine whether it is sufficient; when specific fields are needed, prefer to use jqorConvertFrom-Json to extract on demand from the saved json file, avoiding bringing the entire JSON into the context.

Resolve authentication and compute issues

When the following abnormal situations occur, use references/onboarding.md to guide problem resolution:

Abnormal situations

  • API Key not configured: the environment variable is not configured LINKFOX_AGENT_API_KEY, and LINKFOXAGENT_API_KEY。
  • Response 401 or 402 status code
  • Response indicates insufficient compute or balance: the message contains "insufficient compute balance/insufficient billing/insufficient balance/quota exceeded/insufficient balance/package expired/recharge required/please recharge", or content with a similar meaning.

How to Build Queries

  1. Front-load the user's intent in prompts[0] — include marketplace cue ("on Amazon US"), use case, and any hard constraints (budget, key feature). Alexa weights the opening question heavily.
  2. One question per call — prompts only accepts 1 element. Do not pass multiple elements.
  3. For follow-ups, summarize and re-ask — when the user wants to continue the conversation, the agent must: (a) summarize the key points from the previous Alexa response (answer highlights, recommended ASINs, relevant context); (b) concatenate the summary with the new question; (c) send as prompts[0] in a new API call. Alexa has no memory of prior calls.
  4. Anchor with url only when there's a specific page — pass a category, search results, or product detail URL when the user is reasoning over that page. Skip url for general questions; do not pass a plain homepage like https://www.amazon.com/.
  5. Pick format deliberately — markdown is best for showing the user a polished answer; json is better when downstream code needs to extract ASINs, prices, or follow-up questions programmatically.

Usage Examples

1. Single-turn shopping question

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

2. Follow-up question (agent summarizes prior context and re-asks)

First call:

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

Second call (agent summarizes the previous answer and appends the follow-up):

{
  "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. Question anchored to a category page

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

4. Structured output for downstream extraction

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

Display Rules

  1. Render the Markdown directly when format=markdown: stdout is already structured with turn headings, product cards, and follow-up questions — preserve that structure.
  2. Surface the recommended ASINs so the user can click through; show title, price, score/ratingsCount, and the product URL.
  3. Show the follow-up questions Alexa returned — they are usable prompts the user can pick to continue digging. When the user picks one, summarize the current answer and use the selected follow-up as prompts[0] in a new call.
  4. Don't reroute to a data-analysis sandbox: the answer body is conversational and the recommended products are nested groups, not a flat tabular dataset suitable for SQL-like aggregation.
  5. Flag empty results: if resultsNum is 0 or data is empty, tell the user Alexa did not produce a usable reply and suggest rephrasing or anchoring with a url.
  6. Indicate freshness: results reflect Alexa's live answer at call time; mention this when the user asks about timing.
  7. Handle business errors: if code / errcode is not 200, surface msg / errmsg and suggest retrying with simpler prompts.

Important Limitations

  • Alexa-driven, not deterministic: same prompts can yield different answers across calls — Alexa's response varies with time, traffic, and context.
  • No cross-call memory: each tool call is a fresh Alexa session; the agent must summarize prior context and embed it in the new question.
  • One prompt per call: prompts only accepts 1 element. For follow-ups, the agent must summarize context + new question into a single prompts[0] and make a new call.
  • Marketplace coverage: anchored on Amazon's storefront Alexa experience (primarily amazon.com); availability on non-US marketplaces depends on Alexa rollout.
  • Output mix: primary value is the conversational answer plus a curated handful of products; this is not a substitute for SERP-wide product extraction.

User Expression & Scenario Quick Reference

Applicable — natural-language conversational shopping on Amazon:

User Says Scenario
"Use Alexa to recommend for me...", "Ask Amazon Alexa..." Direct Alexa Q&A
"Chat on Amazon and recommend to me ...", "conversational product selection" Conversational discovery
"By the way, follow up again / then ask ..." Follow-up (agent summarizes prior result and re-asks in new call)
"Recommend on this page / under this category...", "ask again based on this page" Page-anchored conversation (use url)
"best XX for YY under $Z on Amazon" Goal + constraint + budget Q&A
"Compare the first two recommendations given by Alexa" Compare within Alexa's reply
"What else can Alexa continue to answer / give me some follow-up ideas" Surface follow-up questions

Not applicable — better routed elsewhere:

  • Pulling the full SERP for a keyword with positions, sponsored flags, etc. (use the storefront search-simulation skill).
  • Historical search-term analytics or volume trends (use the ABA data explorer).
  • Detailed product detail / A+ / bullets for a known ASIN (use the Amazon product detail skill).
  • Review-level sentiment analysis (use the Amazon reviews skill).
  • Image-based similar product discovery (use the image search skill).
  • Aggregated statistics over a flat product list (no structured table here).

Boundary judgment: when the user wants a conversation — "ask Amazon, get a recommendation, then keep asking" — this skill applies. If they want raw search-result rows, structured analytics, or a specific ASIN's data, route to the matching specialized skill instead.

Compute consumption rules

Billed according to dynamic rules: compute consumed = dialogue turns × 12.6.

Important: the service of this skill is calculated dynamically by a multiplier and may consume a large amount of compute at once. The user must be reminded, and the user decides whether to continue.

Feedback:

Auto-detect and report feedback via the Feedback API when any of the following apply:

  1. The functionality or purpose described in this skill does not match actual behavior
  2. The skill's results do not match the user's intent
  3. The user expresses dissatisfaction or praise about this skill
  4. Anything you believe could be improved

Call the feedback API as specified in references/api.md. Do not interrupt the user's flow.

For more high-quality, professional cross-border e-commerce skills, set LinkFox Skills.