Send one call per message
Send the shopper’s words as they wrote them, one message per call. Two messages joined into one call read as one request, and the shopper gets one answer for both. A conversation is one purchase. Every answer names its conversation, and every message about the same purchase goes back to it. The answer’s reply, its products, its cart and any link it carries, such as the page where the shopper approves the payment, belong to the message you sent. Show them under that message, never under a later one.- SDK
- MCP
- API
Build the buy tool once for each shopper, and open a turn from it for each message with
buy.turn. A turn is the tool for one message: it has the same name, schema and methods, so give it to your model in place of the tool.chat.ts
history stands for the shopper’s earlier messages. turn.messages(history) is the history, then what Agentcard told the shopper that the history does not hold yet, then the message. The turn opens the moment the message arrives, while the model runs go one after another, so a second message never writes the first one’s exchange out of the history.Every call the model makes through the turn belongs to that message alone:turn.linksholds each link the turn’s calls handed over, in order. Send them with the reply, or passsendLinktobuy.turnto send each one the moment the tool hands it over.turn.resultsholds the whole answer of each call, and anonResultpassed tobuy.turnhears each one.- An
onProgresspassed tobuy.turnhears only that turn’s stages. turn.agentcardMessagesholds each message Agentcard posted into this shopper’s chat that the model has not read yet.
buy.turn falls back to the one the tool was built with. Pass the turn to every framework the way you pass buy: tools: [turn] for Anthropic, tools: { buy: turn } for the Vercel AI SDK, tools: [turn.openai] with turn.handle for OpenAI and OpenRouter chat, and toOpenRouterTool(turn, { tool, z }) for OpenRouter’s agent SDK.The turns share the shopper’s conversation, so a card the shopper already holds from an earlier turn is not sent again. A tool built for every message buys the same way, but it sends the same product links again each time Agentcard shows the same products.Keep one purchase per chat
A shopper who writes to your app in several chats, such as a private chat and a group, keeps a purchase in each. Send your own id for the chat on every call. Agentcard keeps one open purchase for each shopper and chat, so two chats never share a cart, a question or an approval.- SDK
- MCP
- API
Build one tool for each shopper and chat, with the chat’s id:Leave
chat.ts
threadId out for an app with one chat per shopper.Send a newer message anytime
A shopper who changes their mind while Agentcard is still answering gets the answer to their newest message. Send the new message as soon as it arrives, in the same conversation. Agentcard stops working on the older message and answers the newer one. Products the older message already found stay in the conversation, so a later “the second one” still picks from them. When the shopper sends three messages quickly, the newest one answers and the two before it both stop. A confirm, the call that pays for a cart, is never stopped. A message sent while a confirm runs waits for it.- SDK
- MCP
- API
turn.stopped reads true once a call of the turn was stopped by a newer message. Check it after each call: do not call your model again, show no error and save no history for that turn. The cards it already showed stay with the shopper.Let Agentcard answer shopping first
Send every shopper message to Agentcard before your own model, the AI that runs your chat, reads it. Agentcard answers four kinds of message itself: a request to buy or book, a pick of what it just showed (the second one, 1 and 3), an answer to its question (an address, a size, a code), and a yes to a total. A shopper who types Printer paper, one ream reads Agentcard’s list of printer paper with no call to your model.
Every other message comes back to you at once, with no search. thanks! came back in 0.28 seconds in a sandbox run. Hand it to your own model, which answers the shopper as it always did and can still shop through Agentcard.
- SDK
- MCP
- API
Call When Agentcard’s reply only asks the shopper something, the turn sends it through
turn.handled() once, and run your model only when it resolves false:chat.ts
onItem, after the cards and links, and handled() resolves true. An answer your model has to word, such as an order placed or a refusal, resolves false, and turn.messages(history) hands your model that answer beside the shopper’s message. An app that never calls handled() works as before: nothing reaches Agentcard until your model calls the tool.Show the reply as written
Most answers only ask the shopper something: which product, which size, which store, or a yes to a total. Agentcard’s reply already says that, so show it as written. A second call to your model that rewords it costs the shopper another wait and changes nothing. Every list in the reply reads as lines that start with• , so the shopper sees choices as a list. A pick that asks which bread the shopper wants arrives like this:
- SDK
- MCP
- API
Pass Any other answer, such as an approval sent, an order placed, or a refusal, leaves
replyAsWritten: true, to buyTool for every turn or to buy.turn for one. turn.replyAsWritten then holds Agentcard’s reply, with every link taken out, whenever the turn’s last answer only asks. Show it and end the turn without calling your model again:chat.ts
turn.replyAsWritten null, and your model words it. The reply leaves out the products and stores whose cards the shopper holds, so the shopper never reads a card twice. An answer whose next step is a link reads as that step’s fixed short line, such as approve the payment to place your order (up to $19.02), as Read the step lines lists.Pass textingStyle: true beside replyAsWritten: true to also lowercase the start of each sentence and the word “I”, and to drop markdown and spaced dashes. The bullets stay. Show bullets and texting style lists which lines count as a list.Show the answer as it arrives
A turn reaches the shopper as messages and links that interleave: a short line saying Agentcard is on it, the products a search found, then the words about them. Show each part below the one before it, in the order it arrives, and the shopper sees products long before the reply is finished.- SDK
- MCP
- API
Pass A
onItem to buy.turn, and the turn hands your app every part as one sequence, one item at a time:chat.ts
text item is Agentcard’s short line, or a message your model wrote through turn.messageStream() or turn.say(text). A link item is each link the tool hands over, with the fields sendLink would get. turn.items holds every item that went out, in order.- Pass
pace: trueto space messages like someone texting: each waits 300 ms plus 12 ms a character, at most 1.5 seconds, after the item before it. Time your model spent writing counts toward the pause, and links never wait.onTypinghearstruewhen a pause starts andfalsewhen its message goes out. - With
onItem, the turn sends nothing tosendLinkoronWorking. PassingonItembeside either to the same turn throws. - A step link, the
vault,approvalorstore_loginpage, waits until your model’s next message ends orturn.sayis called, then goes out right after that message. A held link also goes out when the turn’s next call starts, or after 20 seconds.
onItem, pass onMessage beside sendLink. toMessages(text) cuts text at its blank lines into one message per paragraph, and keeps a list or a code block whole. messageStream does the same for a reply your model streams: push each piece, then call end. Start a new stream for each model message.Check it in the sandbox
- As a test shopper, ask for “a stainless steel french press from target”, and send “actually make it a pour over kettle instead” before the first answer arrives.
- Check that the kettles answer the second message, and that the first shows nothing over the SDK and the API. Over MCP, the second call answers
busyuntil the first returns. - Send “thanks!” through the SDK’s
handled()or the API’shand_back: true. Check that it comes back to your own model. - Ask for a sandwich and pick one that has a choice of bread. Check that the question arrives with each bread on its own line that starts with
•. - Over the API, send the first chat’s
conversation_idwith another chat’sthread_id. Check that it is refused withthread_mismatch.