Skip to main content
A first search can take Agentcard most of a minute. While it works, the shopper sees a 👀 on their own message, the way a friend reacts to a text before answering it. In a chat that shows no reactions, the shopper reads a short text instead, such as 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 as yes, 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.
Pass onReaction to buy.turn, and show the emoji as a reaction on the shopper’s message:
chat.ts
The turn follows the rules above for you. When the 👀 went out, your model reads 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.
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 writes on 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.
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 read one moment or see a 👀 after your error message.
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.
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
Both return null for a message that starts no search, such as a confirmation, a short answer, a step toward paying, a pick of something the shopper saw, a code, small talk like 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.
Pass onProgress:
chat.ts
The tool then asks Agentcard to stream each call. Pass stream: false to wait for each whole answer instead.

Check it in the sandbox

The sandbox is Agentcard’s test mode, which charges nothing.
  1. 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.
  2. Send “the first one” after a product list. Check that no reaction or line appears at once.
  3. In text mode, ask for la croix from target. Check that one line like one sec, checking target for la croix arrives before the products, over the SDK’s onWorking or the API’s ack event.
  4. Over the SDK, make your model throw before it writes anything, and call turn.end() in the catch. Wait 3 seconds. Check that the shopper reads your error and no one moment after it.