Read the products
Send the shopper’s words, such as “two packs of AA batteries from amazon”. When Agentcard searched, the answer lists the products it found, at most eight.- SDK
- MCP
- API
Pass The model never reads a link. It reads
sendLink to buy.turn. Agentcard hands it one product link for each product a search finds, and the turn waits for your callback before the model answers:chat.ts
product_links_sent, the number of cards the shopper holds, and writes one short line beside the cards instead of listing the products again. A shopper who asks for links hears that the links are there.A sendLink that throws on a product link counts that product as not sent, and the call goes on. The model reads link_sent: false on that product. A throw on a card or approval link makes the call throw too.Show each product
Show the picture, the name, the price and a button. Show the store’s website as where the product comes from, never the host of the product’s page link, because that link can pass through a tracking page before the store. When a product has more than one photo, show the others as thumbnails that swap the main picture. Word the button for what taking the product does: Reserve for a restaurant table, Book for a flight, room, class or ticket, and Buy for anything else. Write each price in the product’s own currency. An amount of1331 in the smallest unit of the currency reads \$13.31 in USD, CA\$13.31 in CAD and ¥1,331 in JPY. A product whose price depends on a choice the shopper still makes, such as a size, shows as “from $9.99”.
- SDK
- MCP
- API
A
product link carries these fields:The SDK writes
price in the product’s own currency for you. A price in a currency Agentcard does not name shows with no symbol.Show a flight
A flight has no page at a store, so its page link is null. The airline, the route and the times are in its name, and the API also carries aflight object with each leg’s airports and times. Show it as a card with no link to open, and send its id back when the shopper picks it.
Add the one the shopper picks
When the shopper taps a card, send their words and the product’s id. Agentcard adds exactly that product from the list it showed, and runs no new search. The shopper’s words still count: “two of the 20-pack” sets the quantity to two. A shopper who picks by typing, such as “the second one”, needs no id at all. Send their words, and Agentcard reads which product they mean from the list it showed.- SDK
- MCP
- API
Each product in the model’s view carries a The model reads the
product_id. When the shopper picks a product by its name, its place in the list or a tap on its card, the model passes that product_id. A Buy button that sends the shopper’s words is enough:product_id beside that name in its last result, so keep every tool result in the model’s history, as a tool runner does. Without the history, the model no longer holds the ids on the shopper’s next message.Your own code can pick too. A card’s button can call buy.answer with the link’s productId:cart-button.ts
result.pick holds the product’s product_id and in_cart, whether the cart now holds it. The model reads the same pick.Handle a product that is gone
Agentcard keeps a search’s products for 15 minutes, and a newer search in the same conversation replaces them. A pick of a product Agentcard no longer keeps adds nothing.- SDK
- MCP
- API
The answer reads The model then searches again with the shopper’s words.
needs_input with error_code: pick_not_found, and the model reads this line:Handle a pick not yet added
A pick can leave the cart without the product, and the reply says why. At a store where Agentcard fills in the store’s own checkout page, that page often needs the delivery address before it takes the product. Show the reply to the shopper and send their answer as the next message. The product goes into the cart once the store has what it needs, so ask for no payment until a later answer carries the cart.- SDK
- MCP
- API
result.pick.in_cart reads false. The model tells the shopper what Agentcard said, and it asks for no card and no yes for an older cart.Check it in the sandbox
The sandbox, Agentcard’s test mode, searches real stores and stops before payment, so it places no order and charges nothing. Sandbox credentials run every call there.- Send “two packs of AA batteries from amazon” as a test shopper, such as
docs-test-1. - Check that products arrive, each with a name, a price and a picture.
- Pick one. Check that the cart holds that product and that Agentcard ran no new search.
- Wait more than 15 minutes, pick a product from the old search, and check that nothing is added and Agentcard searches again.