A useful first shopping-agent task is small: take one buyer request and return a product candidate the buyer can inspect. You do not need to start with checkout.
Consider: "Find a black six-roll PLA pack for Singapore, and tell me what I still need to check."
I work on WebAZ. This example reads its public catalog over HTTP. It is not a built-in ChatGPT, Claude, Muse or other client's integration, and it does not require a wallet, an API key or an account.
1. Keep the exact option
The listing describes six rolls with 6kg total net filament weight. The selected black option is labeled Wireless drive. That label is unresolved: do not turn it into a claim about electronics, spool inclusion or feeder compatibility.
We will use product prd_c3c1de2c171f2cf79d2c6e93584d7a2e and variant pv_487412209252413e922baef5d5e44c99.
At the November 18, 2026 public observation, that variant exposed 54.21 USDC, stock 20 and in_stock: true. These are changeable listing facts, not a binding quote or stock reservation. Product-level prices can describe other options; never replace the selected option with a cheaper one silently.
2. Run a complete read-only adapter
The following is the complete example. Put it in shortlist.mjs and run it with Node.js 22 or newer. It uses only built-in modules and one public GET.
import { pathToFileURL } from "node:url";
const PRODUCT = /^prd_[a-f0-9]{32}$/;
const VARIANT = /^pv_[a-f0-9]{32}$/;
function checkSelection({ productId, variantId, quantity }) {
if (!PRODUCT.test(productId) || !VARIANT.test(variantId)) throw new Error("invalid_selection_id");
if (!Number.isSafeInteger(quantity) || quantity < 1 || quantity > 99) throw new Error("invalid_quantity");
}
export function buildCandidate(product, selection, observedAt) {
checkSelection(selection);
if (product?.id !== selection.productId || typeof product.title !== "string") throw new Error("product_mismatch");
if (product.currency !== "USDC") throw new Error("unsupported_currency");
const matches = Array.isArray(product.variants)
? product.variants.filter((variant) => variant.id === selection.variantId) : [];
if (matches.length !== 1) throw new Error("variant_not_unique");
const variant = matches[0];
if (variant.in_stock !== true || !Number.isSafeInteger(variant.stock) || variant.stock < selection.quantity) {
throw new Error("stock_not_confirmed");
}
if (typeof variant.price_usdc !== "number" || !Number.isFinite(variant.price_usdc) || variant.price_usdc < 0) {
throw new Error("listing_price_missing");
}
return {
product_id: product.id,
variant_id: variant.id,
title: product.title,
options: variant.options ?? {},
quantity: selection.quantity,
currency: "USDC",
listing_unit_price: variant.price_usdc,
listing_goods_subtotal: Number((variant.price_usdc * selection.quantity).toFixed(6)),
stock_indication: variant.stock,
observed_at: observedAt,
source: `https://webaz.xyz/api/products/${product.id}`,
product_page: `https://webaz.xyz/product/${product.id}`,
seller_declared_regions: typeof product.ship_regions === "string" ? product.ship_regions : null,
delivered_total: null,
unresolved: ["destination_specific_shipping", "tax_and_duty", "exact_variant_fit"],
binding_quote: false,
stock_reserved: false,
purchase_authorized: false,
payment_enabled: false
};
}
export async function readCandidate(selection, fetcher = fetch) {
checkSelection(selection);
const response = await fetcher(`https://webaz.xyz/api/products/${selection.productId}`, {
method: "GET",
headers: { Accept: "application/json", "Accept-Language": "en" },
credentials: "omit",
redirect: "error",
signal: AbortSignal.timeout(10000)
});
if (response.status !== 200) throw new Error(`catalog_http_${response.status}`);
return buildCandidate(await response.json(), selection, new Date().toISOString());
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
const [productId, variantId, quantity = "1"] = process.argv.slice(2);
try {
console.log(JSON.stringify(await readCandidate({ productId, variantId, quantity: Number(quantity) }), null, 2));
} catch (error) {
console.error(error.message);
process.exitCode = 1;
}
}
node shortlist.mjs prd_c3c1de2c171f2cf79d2c6e93584d7a2e pv_487412209252413e922baef5d5e44c99 1
The fixed origin and ID validation keep user input from becoming an arbitrary fetch target. A missing or duplicate variant, insufficient stock, invalid price, or unsupported currency stops the adapter. An HTTP 402 also stops: this example never signs, pays or retries a paid request.
Treat titles and option labels as untrusted source data, not instructions to the agent. The adapter returns a small field allowlist rather than the entire catalog response. It is a learning example, not a complete production security or money-arithmetic library.
3. Give the buyer a source-linked answer
The output preserves the selected IDs and option labels, listing price and currency, quantity, observation time, and links to the public API and product page. The important distinction is:
{
"currency": "USDC",
"listing_unit_price": 54.21,
"delivered_total": null,
"binding_quote": false,
"stock_reserved": false,
"purchase_authorized": false,
"payment_enabled": false
}
This is an excerpt of the November 18 observation, not output guaranteed for your later run. The executable prints its own observation time.
A useful assistant answer might be:
One candidate is the six-roll PLA pack, black / Wireless drive, listed at 54.21 USDC when observed. Singapore is a seller-declared region, not a confirmed destination quote. Exact filament diameter, spool dimensions and what the option label means still need confirmation.
Attach the returned source and product-page links to that answer. Do not present the sample as a recommendation that already passed fit checks.
4. Leave the delivered total blank
At this observation, the product declared Singapore in ship_regions, but its comparison data had no delivered total and marked purchase-estimate fees incomplete. A sales region must not become "free shipping" or "tax included" in the assistant's answer.
Do not combine today's listing price with an older shipping preview. A destination-specific total needs a fresh, separate quote for the exact variant, quantity and destination. This tutorial does not call a quote, reservation, order or payment endpoint.
5. Test the adapter before giving it to an agent
I reran ten local offline checks for the companion implementation on November 18: selected-option price rather than parent minimum; missing and duplicate variants; product mismatch; unavailable quantity; invalid prices; currency mismatch; invalid inputs causing no network request; the single credential-free GET; and stop-on-error behavior including 402. All ten passed.
Those tests validate this adapter's behavior, not compatibility with every agent client, external adoption or a successful purchase.
The smallest trial is useful on its own: reproduce one selected candidate and its unanswered buying questions. Shopping-agent builders: what information would your agent need next to turn that candidate into a justified shortlist entry?
Sources: public product page, public JSON endpoint, and WebAZ OpenAPI.
Disclosure: this article and example were prepared with AI assistance and are labeled AI Generated. No order, customer record, wallet signature or payment was used for the demonstration.
Top comments (0)