checking Gap, and change the line when the store answers: two shirts at Gap, nothing at 1-800-Flowers, Sephora too slow to wait for. The shopper sees work happening before the first product arrives.
Store statuses are not on for every company yet. Until they reach yours, your app hears no store update and the answer carries no
search, so code written from this guide shows no store line and needs no change when they turn on.Show each store as it changes
Agentcard sends a store’s status each time it changes:searching when Agentcard starts on the store, then the status it ends with. An update carries these fields:
Match each line to its store by
merchant, and replace the line on each update. A store can change more than once in an answer, and a store searched twice reads searching again.
- SDK
- MCP
- API
Pass The fields are
onMerchantStatus to the buy tool:chat.ts
conversationId, searchId, merchant, merchantName, status, results, confirmed, firstResultMs and ms.Read each status
A
timed_out, failed or unavailable store says nothing about whether the store carries the product. Tell the shopper so in your own words, and never as “none at Sephora”.
A shopper who asked for a candle at Walmart while Agentcard could not reach Walmart reads still loading Walmart beside the products from the stores that did answer. A store the shopper did not name gets no line: it drops out, and the other stores fill the answer.
- SDK
- MCP
- API
Pass the stores the shopper named to For the whole answer at once,
merchantStatusLine, and show the line it gives:chat.ts
searchStatusLines(result.search ?? null, shopper.namedStores) gives every line. An app on an SDK version before 0.18.8 leaves an unavailable store out and never hears its update.Read every store at the end
The answer’ssearch holds every store the search asked, in the order their searches started, with the same fields. final is true once no store is still being searched. While it reads false, show a note such as “still checking a store or two”. search is null for an answer that searched no store, such as a reply about the cart.
- SDK
- MCP
- API
chat.ts
searchAt, which matches the store by its id, its domain, or its name:store-line.ts
Check it in the sandbox
Once store statuses are on for your company, try them in the sandbox, Agentcard’s test mode, which charges nothing:- Ask for “a men’s linen shirt” as a test shopper, over the SDK or the API with
?stream=1. - Check that a line appears for each store,
searchingfirst. - Check that each store’s line changes as it answers, and that the answer’s
searchlists the same stores withfinal: true.