AgentcardClient is the class every buy tool and listener shares. The class exchanges your company’s client credentials for an access token, renews that token a minute before it expires, and sends purchase turns, conversation reads and Vault link requests to Agentcard. Build one and keep it for the life of your process.
agent.ts
BuyTurn for the shopper user-42. Most apps never call buy themselves: buyTool calls it for the model. See Quickstart for the full wiring.
Create the client
TypeError for any other combination.
Properties
Methods
bearer
sandbox.
buy
BUY_TURN_TIMEOUT_MS. Name the shopper once, with external_user_id or user_id, when you use company credentials, and leave both out under a shopper’s own token.
The client sends a turn once, because a turn runs against live stores. The client sends again only after a 401, once, with a renewed token. After a timeout, unreachable or invalid_answer error, read the conversation with conversation before you send the turn again.
Pass stream with onProgress, onCatalog, onAck or any of them together to ask Agentcard to stream the turn. A stream that breaks after the turn started returns a BuyTurn with error_code set to turn_timeout, so the caller reads the conversation for what the turn left.
conversation
who with company credentials. The call waits up to 30 seconds.
order
order_id that order.placed carried. Pass who with company credentials. An order number two stores share throws order_id_ambiguous, with the stores in error.body.merchants; pass opts.merchant to say which. An order number Agentcard does not know throws order_not_found. See Read where an order is.
listCarts
threadId), a short label and when it was started (createdAt). Pass threadId to read one chat’s carts alone. A page holds up to 20 carts; pass nextCursor as cursor for the next page, until it reads null. See Bring back a saved cart.
getCart
listCarts named. Another shopper’s cart throws cart_not_found.
warmCart
resumeCart that follows answers sooner. The call answers at once.
resumeCart
cart_ended. A change that reads needs_input with reason replace_account_cart waits on the shopper’s yes; call again with replace: [{ key: change.key, holds: change.holds.token }] once they give it.
bringCart
threadId names: the cart moves there, never copies, and every store’s total is read again, as resumeCart reads it. Call it only when the shopper asks for a cart from another chat or picks one in your app. moved names the chat the cart came from, or reads null when it was already here. A cart whose payment is under way in another chat throws cart_paying, one that ended throws cart_ended, and one whose retail store, DoorDash or travel seller already has a cart of its own in this chat, such as a second Amazon cart, throws store_cart_here. See Pull a cart into this chat.
resumeCartAsText
send gets what the shopper saved at once, and what each store reads today once the resume answers. Answers the resume, which you pass to savedCartSettled for each cart.* event that follows.
setCartQuantity
version you read. A quantity of 0 takes the item out. The store reads the line’s total again at the next resume; a Shopify store’s line reads failed with edited_waits_for_store until the shopper adds the item again. A line at a retail store, at DoorDash, or for a booking or a trip throws line_not_editable: the shopper changes it in their chat. A cart that moved past that version throws cart_changed, with the cart as it stands in error.body.cart.
removeCartStore
version you read. A cart left with no store ends. A line at a retail store, at DoorDash, or for a booking or a trip throws line_not_editable.
setCartDelivery
gift_delivery_not_available until gift delivery reaches your company.
mintVaultLink
TypeError under a shopper’s token.
returnUrl is where the Vault page sends the shopper once their card is saved, such as your app’s own yourapp://agentcard-done. returnUrl must be one of the links your company registered. state comes back on that link unchanged, and a state without returnUrl throws a TypeError. See Checking out inside your app.
merchants
who, you read each merchant as a shopper of your app reads it before signing in anywhere, so you can check a merchant before anyone connects. kind is direct, catalog or all, direct by default and all with q. q matches part of a name or domain. limit is 1 to 100, 50 by default. Pass the last page’s next_cursor as cursor.
Each merchant’s wallets lists { wallet, status }, with wallet vault or link:
The Vault reads at every merchant. Link reads at a store whose
buys_through is browser, and for hotels, rental cars and flights booked through Agentcard. wallets is null from an older Agentcard.
sealLink
link_seal_needed. Only the sealed envelope leaves your server, and the call is POST /buy/v1/link-seals/{approval_id}. Pass who with company credentials. The answer is { status: 'sealed' }. The buy tool seals and posts for you; Pay with Stripe Link shows the steps over HTTP.
listen
delivered
message reached the chat of the shopper you call externalUserId, so that shopper’s next buy.turn hands it to your model. listen and agentcardWebhook({ agentcard }) call it once onMessage returns, so call it yourself only for a message you delivered another way. The client keeps a message once per eventId, at most 20 messages per shopper, in this process’s memory.
answered
message with a turn of its own in the chat threadId names, so the shopper never reads its text there. For a message about one purchase, delivered skips the message from then on, and no later turn tells the model its text. A message about the shopper alone, such as a saved card, still reaches the next turn in the shopper’s other chats. Leave out threadId for a tool built without one. buy.nextStep calls it.
unanswered
answered for a message your agent’s turn could not answer. Pass the threadId you passed to answered. After you post the message’s text, delivered keeps it again. turn.release() calls it.
keptMessages
threadId names, oldest first: each message about that chat’s purchase or about the shopper alone that reached the shopper’s chat, and that no history passed to turn.messages in that chat holds yet. Leave out threadId for a tool built without one: that tool gets the messages of the purchases made under no thread.
forgetMessages
threadId names. turn.messages calls it once the history it reads holds them. A message about the shopper alone stays kept for the shopper’s other chats until their own histories hold it.
Constants
BuyRequest
The body of onebuy call. Every field is optional.
BuyDeliveryAddress has the required fields street, city, state and zip, and the optional fields address2, phone, name, country and can_leave_at_door (boolean).
BuyTurn
One turn’s answer. Every field is present, and a field an older Agentcard does not send reads asnull.
BuyChoice has question (string or null), item (string or null, the item the choice is about), source and groups. source is menu_item for a restaurant item’s options, store_checkout for a store’s own size or colour question, and catalog_variant for a product’s sizes or colours in stock. Each group has name, required (boolean), min and max (max is null for no limit), and options. Each option has id (string or null, the option id the cart takes), label, and price_delta_cents (number or null, what choosing it adds to the price).
BuyNextAction is one of shipping_details, guest_details, store_login, add_card, confirm, verification_code, approve or bank_challenge, in the order a purchase asks for them. bank_challenge comes after the approval, when the shopper’s bank asks them to approve the payment too, and the turn’s bank_challenge field carries the details.
BuySearchStatus
Every store a turn searched.searchAt(search, 'gap.com') returns the same block with only that store, matched by its id, its domain or its name.
Each
BuyMerchantStatus has merchant (the store’s id or domain), merchant_name, status, results, confirmed, first_result_ms (number or null) and ms. status is one of searching, confirmed, recently_confirmed, confirmation_unavailable, no_results, timed_out, failed or unavailable; Showing each store as it is searched says what each one means. A store with a status this version does not know is left out.
merchantStatusLine(store, named) gives the line to show for one store, from merchants or from an onMerchantStatus update: still loading Walmart for an unavailable store the shopper named, and null for every other store. named is a store or a list of stores, each matched as searchAt matches it. searchStatusLines(search, named) gives every such line for the turn, in the order the searches started.
BuyCart
A cart as Agentcard answers it. Every amount is in the smallest unit ofcurrency.
BuyCartLine
BuyCatalog
The products the last search found.BuyCatalogItem
Show
store.domain as where the product is sold. The field reads null when Agentcard knows no website for the store, such as a restaurant, and an older API leaves it out.
BuyPick, BuyStores and BuyStorePick
BuyConversation
Where one conversation stands.BuyLatestReply has message_id, text, messages (string[]), catalog (BuyCatalog or null, the products the reply showed) and created_at (string or null).
BuyOrder has order_id (string or null), merchant, merchant_name, status, total_cents and placed_at (string or null). BuyOrder carries no merchant_of_record, who charged the shopper’s card: that field arrives on each order in raw.orders, and Send a dispute to the right place shows how to read it and what each of its fields says. For where one order is now, read it with order. BuyLastCheckout has at, merchant, merchant_name, status, code, message, order_id, decline_code, approval_url, approval_expires_at, placement_announced, approval_in_progress, add_card_url, add_card_expires_at and total_cents. All of its fields except at, merchant, merchant_name and status are null when absent.
Show a trip’s searches
When a shopper plans a trip, Agentcard asks where and when first, then searches flights, hotels and a rental car while the conversation goes on. Read the conversation and show each search as its results arrive:conversation() returns the trip as it stands at that read. While any lane’s status is queued or searching, read the conversation again every few seconds and render the lanes again, and stop once none is. Right after the reply that sets the place and the dates, lanes can still be empty while the searches start, so keep reading until it lists a lane, then apply that rule. A waiting lane runs no search on its own: flights wait for the city the shopper leaves from. Read the conversation again after each reply, since a reply can start a waiting lane, and a change to the place, the dates or the party starts a new set of searches.
BuyTrip has place, check_in, check_out, travelers, origin and lanes. The lanes come in the order a shopper reads them: flights first, since the flights set when the trip lands and leaves, then hotels, car, activities and payment, the check that the shopper’s card pays without stopping at checkout.
Each lane has status, done, checking, results, items and decision. Until done is true, more results can still arrive, so show checking beside the lane, such as still checking hotels…, and never present its results as the full list. Once the lane is done, its status says how it ended: confirmed, no_results, failed, timed_out or cancelled.
items holds up to 8 results, ordered by what the shopper said matters, such as the price or nonstop flights. Each result has product_id, title, price_cents, currency and fulfilled_by, the party the shopper books with, such as { "name": "Korean Air", "kind": "airline" }. Show fulfilled_by as one quiet line on the card, such as “via Korean Air”. decision says whether the shopper’s last preference re-ranked the results the lane held, searched again, or both, with the reasons.
A hotels lane carries fits_flight, which is false when the flight the shopper picked lands on another day than the stay those hotels were searched for. Show the mismatch only when fits_flight === false: null means no flight is picked yet, which is no mismatch. The payment lane carries ready.
Each of these can be null. A result whose fulfilled_by is null shows no seller line. A lane whose decision is null has had no preference stated, so show no decision.
BuyOrderStatus
Where one placed order is now, asorder reads it.
See Read where an order is for what each merchant answers.
BuyOrderShipment
One package of an order, as the carrier reports it. A value the carrier has not reported isnull.
BuyOrderShippingAddress
The address a placed order ships or delivers to, as it was sent at placement.VaultLink
Shopper
Who a call is for. Name the shopper exactly once with company credentials, and leave both fields out under a shopper’s own token.AgentcardApiError
The error every refusal and failed call throws.AgentcardApiError extends Error.
Through
buy.answer, five refusals still answer the shopper: they come back as needs_input with the reason in reply and the code in error_code. They are cart_changed, nothing_to_confirm, conversation_closed, a delivery address that changed since the cart was built (a code that starts with delivery_address), and turn_in_progress. Every other refusal throws an AgentcardApiError.
Error codes
Agentcard refuses a
conversation_id sent with the thread_id of another chat before it reads the message, so the other chat’s words never reach that purchase. The refusal comes back as a 409:
buyTool sends each purchase request once. Only a request that Agentcard refused with a 401 goes again, once, with a renewed token.