one sec, checking target for la croix.
React with a đ
A reaction is the best acknowledgement. It names nothing the shopper said, so it never reads a request back wrong, and the chat holds only real answers. Give each message at most one đ. React at once to a message that starts a search. Messages that Agentcard answers fast need none when they arrive: a pick of a product or a store the shopper saw, an address or other details, an answer to a question such asyes, 2 or a code, a step toward checkout such as ok lets checkout, and an acknowledgement such as its ok. When one of those has no answer after 1 second, such as a slow yes or a confirm still placing the order, put the đ on it then.
- SDK
- MCP
- API
Pass The turn follows the rules above for you. When the đ went out, your model reads
onReaction to buy.turn, and show the emoji as a reaction on the shopperâs message:chat.ts
shopper_already_told_looking: true in that turnâs answers, and the toolâs description tells it not to acknowledge the request again, so the reply opens with the answer or the question, not on it. An onReaction that throws costs only the reaction, and the model then reads false. With onItem on the turn, the đ still goes to onReaction and never joins the turnâs items.Send a short text instead
For SMS, or any chat that shows no reactions, send the shopper one short line instead. On a streamed search, Agentcard writes the line from the shopperâs message and the last few messages before it. After a search for office chairs,can you show me yellow ones reads looking now for yellow ergonomic office chairs under $250.
The line goes out before the products, and only while the shopper has read nothing else of the answer, because a line after a card or a message says nothing. A pick, a confirm, an address, other details the shopper was asked for, and an answer such as yes get no line from Agentcard.
- SDK
- MCP
- API
Pass
onWorking and no onReaction, or set ack: 'text':chat.ts
ack takes 'reaction', 'text', or 'none'. Left out, the tool reacts when the tool or the turn has an onReaction, and sends text through onWorking otherwise. With both callbacks, the shopper gets the đ and never the text too. With ack: 'reaction', Agentcardâs line never reaches the shopper as text, not even through onText.The tool also covers the messages Agentcard writes no line for. When a turn has shown the shopper nothing for ackDelayMs, 1 second by default, it sends one fixed line through onWorking. A turn sends one line at most, and the call waits for onWorking, so the shopper reads the line before any link.A turn your model runs gets no line from Agentcard: the toolâs description tells your model to write one short line itself before it calls the tool on a new request. Pass
ack: (ask) => text to write your own text from the shopperâs words, where an empty answer sends none.Drop your modelâs opening line
When your model writeson it, looking for a dryer under $20 before it calls Agentcard, and the shopper already read Agentcardâs line, the shopper would read two. Show only one of them.
- SDK
- MCP
- API
The turn does this for you. It keeps the modelâs opening line in the modelâs own history and never sends it. A line counts as an opening line when it is one line of at most 90 characters, says the turn is working, asks nothing, and claims no result such as a price or a cart. A first message that asks a question, answers, or says what a search found goes out. When your app failed to send the fixed line, the modelâs line goes out in its place.
End the turn when your model fails
If your model fails before it writes anything, the shopper should not readone moment or see a đ after your error message.
- SDK
- MCP
- API
Call
turn.end() in the catch or finally of the run:chat.ts
turn.end() cancels the line the turn holds and the acknowledgement of every call still running. A call still running keeps answering, so its text, products and links reach the shopper after your error message. A second call of turn.end() does nothing, so a finally is safe too.Acknowledge before your model runs
Your model takes several seconds to call Agentcard after the shopperâs message arrives. Acknowledge the message the moment it arrives, before your model runs, and the shopper sees the đ at once.- SDK
- MCP
- API
buy.turn does this the moment it opens. Outside a turn, call buy.instantReaction(message), or buy.instantAck(message) in text mode, the moment the message arrives:chat.ts
hi, a message that carries the shopperâs own details, or a short reply right after a question. A reply that opens a new request, such as find me black running shoes, or that runs past four words is still a search. When either returns an acknowledgement, neither the tool nor Agentcard sends one for that turn. Pass ack: 'none' to the tool when you acknowledge yourself.Show a long wait
A search often takes 10 to 40 seconds. Send no second text line, however long it runs: a second line at any wait short enough to help would land on most searches. Show the stage as a status line or a typing indicator instead.- SDK
- MCP
- API
Pass The tool then asks Agentcard to stream each call. Pass
onProgress:chat.ts
stream: false to wait for each whole answer instead.Check it in the sandbox
The sandbox is Agentcardâs test mode, which charges nothing.- As a test shopper, ask for âtwo packs of AA batteries from Amazonâ. Check that the shopper sees a đ or a short line before any product, and that the reply opens with the answer.
- Send âthe first oneâ after a product list. Check that no reaction or line appears at once.
- In text mode, ask for
la croix from target. Check that one line likeone sec, checking target for la croixarrives before the products, over the SDKâsonWorkingor the APIâsackevent. - Over the SDK, make your model throw before it writes anything, and call
turn.end()in thecatch. Wait 3 seconds. Check that the shopper reads your error and noone momentafter it.