Linkfox Amazon Alexa Search

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

Response Fields

Structured data[*] shape (format=json)

调用方式

• API 端点：POST /amazon/alexaSearch（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/amazon_alexa_search.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-alexa-search-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后把完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 加 --inline 强制全量打印到 stdout（同样落盘）

读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq或ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应401或402状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

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"
}