> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Acknowledge the shopper while Agentcard works

> Tell the shopper you are on it while Agentcard works, with a 👀 on their message or a short text.

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.

> [tab] SDK
>
> Pass `onReaction` to `buy.turn`, and show the emoji as a reaction on the shopper's message:
>
> ```ts chat.ts theme={null}
> const turn = buy.turn(message, {
>   onReaction: (emoji) => reactToShopperMessage(shopper.id, emoji), // your code; emoji is always '👀'
> });
> ```
>
> 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.

> [tab] MCP
>
> The MCP server sends no reaction. Put the 👀 on the shopper's message yourself before your model calls `buy`, and tell your model in its instructions that the shopper already knows you are looking.

> [tab] API
>
> The API sends no reaction. Put the 👀 on the shopper's message yourself the moment you send a message that starts a search, and send `"ack": false` so Agentcard writes no text line for it:
>
> ```bash theme={null}
> curl -N "https://api.agentcard.sh/buy?stream=1" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "thread_id": "dm-user-42", "resume": true, "external_user_id": "user-42", "ask": "la croix from target", "ack": false }'
> ```

## 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.

> [tab] SDK
>
> Pass `onWorking` and no `onReaction`, or set `ack: 'text'`:
>
> ```ts chat.ts theme={null}
> const buy = buyTool({
>   agentcard,
>   externalUserId: shopper.id,
>   ack: 'text',
>   onWorking: (text) => textShopper(shopper.id, text), // your code
> });
> ```
>
> `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.
>
> | The shopper's message | The text |
> | - | - |
> | A streamed search | The line Agentcard writes, such as `one sec, checking target for la croix`. |
> | The same search, when Agentcard's line has not come after twice `ackDelayMs` | `one moment`, and Agentcard's line is dropped if it comes later. |
> | A search with `stream: false` | A template of the tool's, such as `on it, looking for usb-c cables under $20`. |
> | A slow pick of a product, a store, or a place in a list such as `the first one` | `got it, one moment` |
> | A slow confirm | `on it, one moment` |
> | Any other slow answer, such as `yes` or an address | `one moment` |
> | A code | No text. |
>
> 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.

> [tab] MCP
>
> The MCP server writes no line. Have your model write one short line itself, such as `on it, looking for la croix at target`, before it calls `buy` on a new request.

> [tab] API
>
> Ask for a streamed answer with `?stream=1`. The line arrives as an `ack` event, usually within a second:
>
> ```text theme={null}
> event: ack
> data: {"text":"give me a sec, finding a men's linen shirt","conversation_id":"conv_143abb3d7b6735f1dabab870"}
> ```
>
> Show `text` as a message. A call without `?stream=1` gets no line, because your app would read it after the answer. Send `"ack": false` when your app already told the shopper. For a pick, a confirm or an answer that takes more than a second, send your own short line, such as `one moment`.

## 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.

> [tab] SDK
>
> 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.

> [tab] MCP
>
> The MCP server sends no line of its own, so your model's line is the only one. There is nothing to drop.

> [tab] API
>
> When the stream sent an `ack` event, skip your model's opening line, or send `"ack": false` and keep your model's line instead.

## 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.

> [tab] SDK
>
> Call `turn.end()` in the `catch` or `finally` of the run:
>
> ```ts chat.ts theme={null}
> const turn = buy.turn(message, { onItem: (item) => deliver(shopper.id, item) }); // your code
> try {
>   await runModel(shopper.id, turn); // your code
> } catch (error) {
>   turn.end(); // no `one moment` and no 👀 after your error message
>   await showError(shopper.id, error); // your code
> }
> ```
>
> `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.

> [tab] MCP
>
> The MCP server sends nothing on its own, so there is nothing to cancel.

> [tab] API
>
> Stop showing the stream's events once your app shows its error.

## 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.

> [tab] SDK
>
> `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:
>
> ```ts chat.ts theme={null}
> const reaction = buy.instantReaction(message); // '👀' or null
> if (reaction) await reactToShopperMessage(shopper.id, reaction);
> // In text mode instead:
> const ack = buy.instantAck(message);
> if (ack) await textShopper(shopper.id, ack);
> ```
>
> 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.

> [tab] MCP
>
> React to the message yourself before your model runs. The MCP server has no helper that tells a search from a short answer.

> [tab] API
>
> React to the message yourself before you call `POST /buy`, and send `"ack": false`. The API has no helper that tells a search from a short answer.

## 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.

> [tab] SDK
>
> Pass `onProgress`:
>
> ```ts chat.ts theme={null}
> const turn = buy.turn(message, {
>   onProgress: ({ stage }) => showStatus(shopper.id, stage), // 'searching', 'building_cart', 'checking_out' or 'working'
> });
> ```
>
> The tool then asks Agentcard to stream each call. Pass `stream: false` to wait for each whole answer instead.

> [tab] MCP
>
> Each `buy` call answers within about 45 seconds. When its result has `turn_continues: true`, Agentcard is still working: tell the shopper you're on it, and read [`get_conversation`](https://docs.agentcard.com/commerce-mcp/tools/get_conversation) or [`get_updates`](https://docs.agentcard.com/commerce-mcp/tools/get_updates) later.

> [tab] API
>
> A streamed answer sends `status` events while Agentcard works. Show `text` as a passing line:
>
> ```text theme={null}
> event: status
> data: {"conversation_id":"conv_143abb3d7b6735f1dabab870","step":"searching","text":"Searching stores…"}
> ```

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.