Skip to main content
buyTool(options) returns the buy tool for one shopper. The model calls it with the shopper’s words, and Agentcard finds the products, builds the cart and places the order once the shopper approves. Each framework reads its own fields from the same object, so you pick no adapter.
agent.ts
textShopper stands for your own code. The model calls buy, shows the shopper the cart, and confirms the cart only after the shopper says yes. Build the tool once per shopper and keep it. In a chat app, open a turn from it for each message.

Create the tool

Name your company’s AgentcardClient and the shopper, or pass one shopper’s own access token. The function throws a TypeError when you pass both agentcard and accessToken, or neither.

Options

sendLink, onResult, onReaction and onWorking hear every call the tool makes, whichever shopper message the call answers. To keep the links and answers of one message apart from those of another message, pass them to buy.turn instead. A throw from sendLink on a product link leaves that product’s linkSent false, and the call goes on. A throw from onResult costs only that call to it. A throw from onText leaves shopper_already_read_reply false, so your model words the answer. onProducts also hears the search itself: asOf says when the search ran, and merchantName which store answered. Like sendLink, onProducts hears every call, so pass it to buy.turn to hear one turn’s products alone. A throw costs only the call to it. With onProgress, or with earlyCards and sendLink, the tool asks Agentcard to stream the call. Pass stream: false to wait for each whole answer.

Acknowledgements

Left out, ack reacts through onReaction when the tool or the turn has one, and sends text through onWorking otherwise. 'text' sends text even with an onReaction. 'none' and false send nothing. A function writes the instant reply from the shopper’s words, and an empty answer sends none. A streamed search that buy.turn sends straight gets one line that Agentcard writes while it searches, such as one sec, checking target for la croix. The line reaches onWorking, or onText with no onWorking, before the cards, and only while the shopper has read nothing else of the turn. When the line has not come after twice ackDelayMs and the call has not answered, the tool sends one moment once through onWorking, and a line of Agentcard’s that comes later is dropped. A search with stream: false gets the tool’s own template instead, once Agentcard has not answered within ackDelayMs. A pick, a confirm or another answer that has shown the shopper nothing for ackDelayMs gets one fixed line through onWorking: got it, one moment for a pick, on it, one moment for a confirm, and one moment for anything else. A code gets none. The acknowledging guide shows both modes.

Keep a purchase per chat

Build one tool per shopper and chat when your agent talks to a shopper in more than one place at once, such as several group chats, and name the chat with threadId:
Agentcard keeps an open purchase for each chat. A cart, a question or an approval link from one chat never shows up in another, and the shopper keeps one Vault card, one store sign-in and one address book across all of them. A tool built without threadId continues the shopper’s one purchase from every chat. Each message about a chat’s purchase carries that chat as threadId, so post it into that chat. A message about the shopper alone, such as a saved card, carries threadId: null, and each chat’s tool can take its next step from it. A chat’s tool reads only its own chat’s messages and the shopper’s own, and a tool built without threadId reads the purchases opened under no thread and the shopper’s own, never a chat’s. Take the next step for a message about the shopper alone in the chat that sent the link the message ends: the card link for a saved card, or the store’s sign-in link for a store sign-in. That chat’s purchase is the one waiting, and actionLinkOutcome(link, message) says whether a message ends a link. Post the message’s own text where only the shopper reads it, such as their own chat with your agent, so a group never sees their card. When the message ends links in several chats, or in none, take no step: the shopper carries on in each chat with their next message. DoorDash keeps one cart per account. While one chat’s DoorDash cart waits, Agentcard refuses a change or a checkout of that cart from another chat and leaves the cart as it was. The agent in the other chat gets this answer from its cart call, POST /buy/v1/merchants/doordash/cart/items, captured from a local run, and tells the shopper what the cart holds:
The shopper finishes or clears that order in its own chat first. A chat keeps its hold on the cart until its order is placed or cleared, or until 24 hours pass without activity in it, the window in which resume continues a purchase. When another chat is still changing the same cart after 40 seconds, the same cart call changes nothing and answers with a 409, also captured from a local run:
When Agentcard cannot read the DoorDash cart to tell which chat holds it, the same cart call changes nothing and answers with a 503:

Members of the tool

run, execute and handle each return JSON.stringify(buy.forModel(result)). handle rejects a call with input outside the schema before anything reaches Agentcard. A call that fails rejects with a message that names no link, and error.cause keeps the original error for your logs. answer throws the AgentcardApiError itself. Call instantAck or instantReaction the moment a message arrives, before your model runs. When either returns a reply, the tool sends none of its own for that turn, and the model reads shopper_already_told_looking: true.

Frameworks

Pass buy as it is. toOpenRouterTool(buy, { tool, z }) takes your own tool from @openrouter/agent and z from zod, so the package installs no dependencies. toOpenRouterTool accepts the tool or a turn. toAnthropicTool(buy) is deprecated and returns buy itself.

The model’s input

The model sends five fields and nothing else. The schema marks all five required and sets additionalProperties to false. parseBuyToolInput accepts an object or its JSON text. The function trims product_id and store_id, reads an empty string as null, and throws a TypeError when both are set. Your own code may leave product_id and store_id out.

BuyToolResult

buy.answer returns the whole answer for your code.

Status

Waits

A call that lands while Agentcard is still placing the order pauses once for 12 seconds and reads the conversation. A call that finds the order already placed reads it at once. A request that takes Agentcard more than 110 seconds comes back before its cart is ready, so the tool reads the conversation every 5 seconds for up to a minute and returns the cart once Agentcard finishes. Pass wait to replace the timer between reads. Each link has a kind. The fields below belong to the kinds named in the second column. Show storeDomain as where the product comes from, never the host of url, which can be a tracking link. The tool sends up to eight product links and eight store links per answer. The Sending each link guide shows how to render each kind.

BuyToolProduct

productAction(merchant) returns reserve for reservations, book for flights, hotels, cars, tickets, classes and events, and buy for every other merchant. From 0.18.15 a product whose action is book or reserve gets a card through sendLink though it has no url, as a flight does.

BuyToolStore

Rank the products yourself

Pass candidates: true to get the products behind the cards, so your app can rank them again against what it knows, such as a camera frame or the shopper’s past orders, with no second search:
The answer then carries found_total, such as 23, and up to 16 candidates. Every product and candidate carries rank and why:
Show text to the shopper as it is, or read code to rank. A code this version does not list can appear later, so treat an unknown code as a reason without weight. A pick, a confirm and a restaurant menu carry none of these fields. Your model never reads them: forModel leaves them out, so the model talks about the cards as before.

What the model reads

buy.forModel(result) returns BuyToolModelView, the answer with every link taken out. An address with a path or a scheme is removed, and a bare one, such as walmart.com, reads as the site’s name. BuyToolModelCart has store, items, fees, fee_lines, tip, total, total_is_estimate, total_leaves_out and max_charge. Each item has product_id, name, qty, price, line_total, options and variant. Prices are text such as \$13.31. While total_is_estimate is true, total_leaves_out names what the store adds at checkout, such as tax and shipping or delivery, which the store adds at checkout, and leaves out a part a fee line already holds. A cart the shopper picks up never names shipping or delivery there. Once the store prices the cart, total_leaves_out is null. Show grand_totals when the shopper buys from more than one store. Each entry has amount, the sum as text, amount_cents, the sum in the currency’s smallest unit, currency, is_estimate, leaves_out and stores, the number of carts it adds. Each store’s total already holds its tip, fees and tax, so the sum counts each once. Carts in two currencies give two entries, and they are never added together. is_estimate is true when any store’s total is an estimate, and leaves_out then says what those stores add at checkout.

Standalone helpers

The package root exports the functions the tool uses, for a loop that reads results itself. The instantAck options work as follows: previous is the reply you sent last, so the next one comes from another template. nextAction is the last answer’s next_action. asked is the last message the shopper read. stores holds the names of the stores the last answer listed.
ack.ts
The first call returns a reply that names the request, and the second returns null because yes starts no search.

Show bullets and texting style

replyAsWritten(result), turn.replyAsWritten and each message onText hears show every list as lines that start with • . That covers lines marked - , * , • , 1. or 1) , and two or more short lines in a row after a line that ends in : or ?. A short line has at most 60 characters and 8 words, and does not end in ., !, ?, : or ;. The lead-in line stays as written, and so do prose, a single line, and a line indented under a bullet. In a streamed message, choices that open the message count as a list when the message before it ended in : or ?. A numbered list keeps its numbers where the shopper can answer with one, such as number 3. In replyAsWritten, that is a list whose items name the answer’s products or stores. In a message onText hears, every numbered list keeps its numbers, because the cards it names sit before it.
bullets.ts
textingStyle(text) writes the text the way a chat does, with the bullets kept. It writes the first word of each sentence and the word “I” in lowercase, takes out markdown headings, bold, and a lone - or * marker, and turns spaced dashes into commas. A capital inside a sentence stays, and so does an all-caps word such as USB, a capital after an abbreviation such as St., and the first word of a list line, which is usually a name.
texting.ts
Pass textingStyle: true to buyTool or buy.turn to get turn.replyAsWritten and each onText message in that style. replyAsWritten(result, { textingStyle: true }) does the same for one answer. The tool’s description also tells your model to write the options it lists, such as sizes, breads or times, one per line, each starting with • , in the same paragraph as the question.

Leave out the lists the cards show

replyAsWritten(result) and turn.replyAsWritten drop the products and stores the reply lists again when their cards went out, so the shopper never reads a card twice. withoutCardList(reply, cards) does the same for any reply. A card is the product or store name, or the name with its price, such as { name: 'Mini Soaps Gift Box', price: '$58.00' }. The function drops:
  • each list line that names a card, with or without a marker, up to the question on the line;
  • a list written on one line, item by item, such as 1) a mug ($19.00); 2) a soap box ($58.00);
  • the line that leads into a list whose items all went, such as here are a few:;
  • a sentence that points at a number the list gave, such as #2 ships fastest, and a sentence that goes on to more of the list, such as other 6-packs are ....
An item for a product no card shows stays, with its lead-in. A reply may recommend one or two products in words, and those sentences stay.
cards.ts
The candle has no card, so its item stays. When nothing of the reply is left, replyAsWritten is null and your model words the answer.

List a choice one per line

When the reply asks the shopper to choose, such as a sandwich’s bread or a shirt’s size, the answer carries choice with every value. replyAsWritten(result) and turn.replyAsWritten list the values one per line under the question, each starting with • and followed by its extra price when it has one, even when Agentcard’s reply names them inside a sentence.
choice.ts
choiceLines(result.choice) returns the lines alone. A choice of more than one group leads each group’s lines with its name, such as Size:. When the text already lists a value on its own line, that line stays, a priced value that leaves its price out gets it at the end of its line, and the values no line holds follow the last value of their group. A bracket that holds only the values, such as (Size: 3 oz, 4.375 oz), goes, because the list replaces it. A reply that asks nothing gets the list at its end. A message that onText hears works the same way. When the messages the shopper read do not list every value one per line with its price, the tool sends one more message with the lines. If that message fails to send, the model words the answer.

Read the step lines

When the answer’s next step is a link the shopper holds, replyAsWritten(result) returns the step’s fixed short line, and stepAsWritten(result) returns it alone. The link follows the line. After the shopper’s own words put the cart together, a line about the cart comes first as its own message, such as 1 Chicken Pesto Caprese from Mendocino Farms, $17.89, then a blank line, then the ask. When the shopper has carts at several stores, the card they add pays for all of them, so the line names each store’s cart on its own line, starting with • :
The cart line comes before an add_card or a store_login ask, and never before approve, a confirm, or a go-ahead the tool carried. When the total changed after the go-ahead, the ask opens with the new total, such as it's $17.89 with fees and tax now. approve the payment to place your order (up to $19.02), or it's about $17.89 now. for an estimate. When one approval pays every seller, the answer carries basket, and the approve line names each seller with its total and the card hold, then asks once for the approval’s total and hold. A store that charges its final amount holds the card above its total, and the shopper pays only the final amount:
A seller the approval leaves out reads not in this approval, and the approval charges nothing there. Agentcard’s reply says why the seller was left out, such as a cart that changed after the shopper’s yes, and what the shopper does next. A seller paid exactly its total shows no hold. stepAsWritten returns null when the link did not go out, when the shopper already read Agentcard’s ask through onText, when a card or approval step has no cart or basket to place, and when the answer also showed products.

Carry the go-ahead

After the shopper picks something, and then saves a card or signs in to the store, the next step goes straight to the approval link. The shopper does not say yes again. The approval link is their consent, because it names the most they can be charged and the order goes in only once they approve it there. The tool carries the go-ahead in two cases, and buy.nextStep confirms the cart by its hash:
  • The shopper said yes to the cart in the chat, and that confirm stopped for the card or the sign-in. yes_carried is set.
  • The shopper picked what is in the cart, such as a product, a tap on its card, or a request to buy it, and answered only the checkout’s questions since, such as an address, a phone number, or a name. yes_carried is set with picked: true, and said_yes_to_cents is the total the chat last showed.
The cart must hold the same items at the same store. A total that moved because the store priced its fees and tax in keeps the go-ahead, and total_changed reads true. Any other shopper message, a cart that changed, and a declined approval take the go-ahead back. confirm_sent reads true on the call that sent the confirm.