amazon

name	amazon
description	Shop on Amazon and Amazon Fresh through your browser
compatibility	Designed for Vellum personal assistants
metadata	{"icon":"assets/icon.svg","emoji":"🛒","vellum":{"category":"commerce","display-name":"Amazon","includes":["vellum-browser-use"]}}

Use browser automation for all Amazon actions. All browser operations are executed through the assistant browser CLI, invoked via host_bash. Use helper scripts with host_bash to normalize extraction results and decide the next step.

Required tools

• host_bash for assistant browser CLI commands and deterministic helper scripts under scripts/.

Hard constraints

• Do not call assistant browser chrome relay.
• Do not use legacy relay-backed scripts.
• Always require explicit user confirmation before final order submission.

Step graph (state machine)

Step 1: Classify workflow state

Run this early in each turn when intent is unclear:

bun {baseDir}/scripts/amazon-intent.ts --request "<latest user request>" --checkout-reviewed <true|false> --has-cart-items <true|false>

Use the returned step to route to one of: search, variant_select, cart_review, checkout_review, fresh_slot, place_order.

Step 2: Product discovery (search)

1. Navigate to search results page:

assistant browser --session amazon navigate --url "https://www.amazon.com/s?k=<urlencoded query>"

2. Capture current state:

assistant browser --session amazon --json snapshot
assistant browser --session amazon --json extract --include-links

3. Parse candidates deterministically:

bun {baseDir}/scripts/amazon-parse-search.ts --query "<query>" --input-json '<json payload with extracted text/links>'

4. Present top options with title, price, ASIN (if present), Prime/Fresh hints.

Step 3: Product detail + variant resolution (variant_select)

1. Open product result.
2. Re-snapshot + re-extract.
3. Parse product details:

bun {baseDir}/scripts/amazon-parse-product.ts --input-json '<json payload with extracted text/links>'

4. If variation hints are present, resolve user choice before add-to-cart.

Step 4: Add to cart + verify (cart_review)

1. Click Add to Cart on product page.
2. Navigate to cart page and extract:

assistant browser --session amazon navigate --url "https://www.amazon.com/gp/cart/view.html"
assistant browser --session amazon --json snapshot
assistant browser --session amazon --json extract --include-links

3. Parse cart summary:

bun {baseDir}/scripts/amazon-parse-cart.ts --input-json '<json payload with extracted text>'

4. Show parsed line items and totals. Ask user to confirm cart contents.

Step 5: Fresh slot validation (fresh_slot)

For Amazon Fresh flows, explicitly verify slot selection in UI before checkout:

1. Navigate to Fresh delivery slot surface if needed.
2. Snapshot + extract delivery slot details.
3. Confirm selected slot text is visible before proceeding.

If slot cannot be verified after retries, stop and ask user to choose slot manually.

Step 6: Checkout sanity (checkout_review)

1. Navigate to checkout review page.
2. Snapshot, extract, and capture a full-page screenshot:

assistant browser --session amazon --json snapshot
assistant browser --session amazon --json extract
assistant browser --session amazon screenshot --full-page --output /tmp/amazon-checkout.jpg

3. Validate readiness:

bun {baseDir}/scripts/amazon-checkout-sanity.ts --cart-confirmed true --input-json '<json payload with extracted text>'

4. Report missing markers (shipping/payment/total/submit action) before any submission.

Step 7: Final submit gate (place_order)

Immediately before clicking final submit button:

1. Ask for explicit final confirmation in plain language.
2. If user confirms, click final submit action (Place your order, Buy now, or equivalent).
3. Take post-submit snapshot/screenshot and report confirmation details.

Retry and fallback policy

• Retry budget: 3 attempts per step that mutates page state.
• After each mutation, run a fresh assistant browser --session amazon --json snapshot before the next click/type.
• If a step fails 3 times, stop and ask user to complete that step manually, then resume.

Example helper payload shape

{
  "phase": "search",
  "context": { "checkoutReviewed": false, "hasCartItems": false },
  "extracted": {
    "text": "...",
    "links": ["https://www.amazon.com/dp/B08XGDN3TZ"]
  },
  "userIntent": "order aa batteries"
}

Safety rules

• Always show price/totals before confirmation.
• Never infer final consent from prior messages; ask again right before submission.
• If CAPTCHA or anti-bot challenge appears, ask user to solve it and continue after refresh.