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

# Search from a shopper's picture

> Send the picture a shopper points at with their message, and Agentcard searches for the product it shows.

Send the picture your shopper shows with their message, and Agentcard searches for the product in it. A viewer who points their phone at a jacket on screen and says "where can I get that jacket" gets product cards for that jacket, not for every jacket.

## Send the picture with the words

Send the picture beside the shopper's words. Agentcard reads the two together and names the product the picture shows, then searches with the shopper's words and that name in place of "that": "where can I get the Patagonia Down Sweater Jacket". The cards, the reply and the conversation's history all read those words.

> [tab] SDK
>
> Pass the picture as `image` to `buy.turn`:
>
> ```ts agentcard.ts theme={null}
> const turn = buy.turn('where can I get that jacket', {
>   image: { url: 'https://frames.yourapp.com/show/s01e04/00-12-31.jpg' },
> });
> ```

> [tab] MCP
>
> The [`buy`](https://docs.agentcard.com/commerce-mcp/tools/buy) tool takes the shopper's words only and has no field for a picture. Have your agent describe the product in `ask`, such as "where can I get a Patagonia Down Sweater Jacket", or send the picture through the SDK or the API.

> [tab] API
>
> Add the picture to the call as `image`, beside the shopper's words in `ask`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "ask": "where can I get these",
>     "image": { "url": "https://m.media-amazon.com/images/I/81U2sRlmzNL._AC_UL320_.jpg" },
>     "external_user_id": "user-42"
>   }'
> ```
>
> The answer's `catalog` lists what Agentcard found, as for any search:
>
> ```json theme={null}
> {
>   "conversation_id": "conv_6e96e48a70fc65d1f895bf47",
>   "status": "needs_input",
>   "reply": "You can get them at Amazon. Here are the AA-only options: ...",
>   "catalog": {
>     "presented": true,
>     "items": [
>       {
>         "ref": "p_0a02f4ebb745",
>         "name": "Amazon Basics 20-Pack AA Alkaline Batteries, 1.5 Volt, 10-Year Leak-Free Shelf Life, for Everyday and Household Devices",
>         "priceCents": 999,
>         "currency": "usd",
>         "store": { "id": "amazon", "name": "Amazon", "domain": "amazon.com" },
>         ...
>       },
>       ...
>     ]
>   }
> }
> ```

[Show products and add the pick](https://docs.agentcard.com/opencommerce/guides/showing-products.md) covers how to show these cards and add the one the shopper picks.

## Send the picture as data

A picture your app holds in memory goes as base64 text, the picture's bytes written out as letters and digits, with its type. Agentcard takes `image/jpeg`, `image/png`, `image/webp` and `image/gif`, up to 3,000,000 bytes once decoded. A full-size phone photo can be larger, so scale the picture down before you send it. A picture sent by address needs an `https` address of at most 2,048 characters.

> [tab] SDK
>
> ```ts agentcard.ts theme={null}
> const turn = buy.turn('how much is this', {
>   image: { data: frame.toString('base64'), media_type: 'image/jpeg' },
> });
> ```

> [tab] MCP
>
> The `buy` tool takes no picture, as the first step says.

> [tab] API
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "ask": "how much is this",
>     "image": { "data": "/9j/4AAQSkZJRgABAQ...", "media_type": "image/jpeg" },
>     "external_user_id": "user-42"
>   }'
> ```

## Send a picture with no words

A shopper who only shows a picture still gets a search. Agentcard searches as if the shopper had written "find" and the product's name, and the answer has the same shape: a reply and the products found.

> [tab] SDK
>
> `buy.turn` needs the shopper's words, so give it a short ask with the picture:
>
> ```ts agentcard.ts theme={null}
> const turn = buy.turn('find this', {
>   image: { url: 'https://frames.yourapp.com/show/s01e04/00-12-31.jpg' },
> });
> ```
>
> An app that calls `client.buy` itself can send the picture with no `ask` at all:
>
> ```ts agentcard.ts theme={null}
> const turn = await client.buy({
>   image: { url: 'https://frames.yourapp.com/show/s01e04/00-12-31.jpg' },
>   external_user_id: 'user-42',
>   resume: true,
> });
> ```

> [tab] MCP
>
> The `buy` tool needs the shopper's words in `ask` and takes no picture. Ask the shopper what they are looking for.

> [tab] API
>
> Send `image` with no `ask`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "image": { "url": "https://m.media-amazon.com/images/I/81U2sRlmzNL._AC_UL320_.jpg" },
>     "external_user_id": "user-42"
>   }'
> ```

## Handle an unclear picture

Agentcard searches for a product only when it is sure what the picture shows. A picture of a crowded shelf, or of several products when the words do not say which, leaves the search on the shopper's words alone, so "where can I get that jacket" searches for jackets.

A picture with no words that Agentcard cannot read is refused:

```text theme={null}
400
{
  "error": "ask is required: Agentcard could not tell what the picture shows, so send the shopper's words with it",
  "code": "invalid_request",
  "hint": "POST /buy { \"ask\": \"where can I get that jacket\", \"image\": { \"url\": \"https://...\" } }"
}
```

Ask the shopper what they are looking for, and send their words on the next message.

## Send it only with a new request

Send the picture with the shopper's message that asks for something, and with nothing else. A pick of a card, a yes to a total and every later message go without it, so a shopper who taps a card never uploads the picture again. Agentcard reads the picture during the call and never keeps it.

> [tab] SDK
>
> `buy.turn` sends the picture with the turn's first request for products and with nothing else, so your code does nothing more.

> [tab] MCP
>
> The `buy` tool takes no picture, as the first step says.

> [tab] API
>
> Send `image` only with `ask`. A request that sends `image` with `confirm` is refused.

## Fix a refused picture

A picture Agentcard cannot take is refused with `400`, and the error names the field:

| Error | What to do |
| - | - |
| `image.url must be an https URL` | Send the picture from an `https` address, or as data. |
| `image takes exactly one of image.url or image.data` | Send the address or the data, not both. |
| `image.data is at most 3 MB decoded` | Scale the picture down and send it again. |
| `image.media_type must be one of image/jpeg, image/png, image/webp, image/gif` | Convert the picture to one of those types. |
| `image goes with an ask, never with confirm` | Send the picture with the shopper's message, and confirm without it. |
| `image.embedding: embeddings are not accepted yet; send image.url or image.data` | Send the picture itself instead of a list of numbers your app computed from it. |
| `ask is required: Agentcard could not tell what the picture shows, so send the shopper's words with it` | Send the picture again with the shopper's words. |

> [tab] SDK
>
> `buy.turn` checks the picture's address, its type and the size of its data before any call, so a picture those checks refuse throws a `TypeError` naming the field. `buy.turn('that', { image: { url: 'http://frames.yourapp.com/a.jpg' } })` throws:
>
> ```text theme={null}
> TypeError: Pass image.url as an https URL of at most 2048 characters.
> ```
>
> Send the picture from an `https` address instead:
>
> ```ts agentcard.ts theme={null}
> const turn = buy.turn('that', { image: { url: 'https://frames.yourapp.com/a.jpg' } });
> ```
>
> The SDK's size check takes up to 3,145,728 decoded bytes, while Agentcard takes 3,000,000. A picture between the two throws nothing in the SDK and is refused by Agentcard with `image.data is at most 3 MB decoded`, so handle that refusal as well as the `TypeError`.

> [tab] MCP
>
> The `buy` tool takes no picture, so there is nothing to refuse.

> [tab] API
>
> A picture sent from an `http` address answers:
>
> ```text theme={null}
> 400
> {
>   "error": "image.url must be an https URL",
>   "code": "invalid_request",
>   "hint": "POST /buy { \"ask\": \"order sushi from DoorDash to my place\" }"
> }
> ```
>
> Send the picture from an `https` address, or as data. Every refusal in the table has the same shape.


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