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

# Give your model Agentcard's instructions

> Start your model's system prompt with the instructions Agentcard writes for it, so it describes what Agentcard buys in Agentcard's words and hands every shopping request to the buy tool.

Start your model's system prompt, the text it reads before every conversation, with Agentcard's instructions. Your model then tells the shopper what Agentcard can buy in Agentcard's own words, sends every shopping request to the buy tool, and never confirms a cart the shopper only liked.

## Know what the instructions teach

* What Agentcard can do: buy from Amazon, Walmart, Target, Best Buy and thousands more stores, plan a whole trip, order food delivery and book restaurant tables. The model never says whether a store the shopper names is supported. It calls the buy tool, which knows.
* How to ask: the model passes the shopper's words to the tool as they said them, and asks for one thing per message, the step `next_action` names.
* Links: the model never writes a link your app already shows, and says a link is waiting instead.
* Confirming: the model confirms a cart only on the shopper's yes to that cart. "Looks good" is interest, not a yes.
* Writing: the model matches the shopper's tone and keeps ids, hashes and tokens out of the chat.

## Load the instructions

Agentcard's text changes from one release to the next, so log which version each conversation used.

> [tab] SDK
>
> `appInstructions()` returns the text as a string, from inside the package, with no request. Use it as your system prompt, with the buy tool beside it:
>
> ```ts agent.ts theme={null}
> import Anthropic from '@anthropic-ai/sdk';
> import { appInstructions, buyTool } from '@agent-cards/commerce-sdk';
>
> const buy = buyTool({ agentcard, externalUserId: shopper.id, sendLink }); // sendLink: your code
>
> const answer = await new Anthropic().beta.messages.toolRunner({
>   model: 'claude-sonnet-5-5',
>   max_tokens: 16000,
>   system: appInstructions({ markdown: true }),
>   tools: [buy],
>   messages,
> });
> ```
>
> `sendLink` hands your app each link, as [Send each link](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md) shows. `APP_INSTRUCTIONS_VERSION` names the version of the text. A new SDK release can bring new text, which your app picks up when you update the package.

> [tab] MCP
>
> The Commerce MCP server serves the instructions as a skill named `agentcard-shopping`, a Markdown file your agent reads like any other MCP resource. A client that loads skills from MCP servers reads it for you. Otherwise, read `SKILL.md` when your server starts and use it as the system prompt. This example uses the AI SDK client from [Connect your agent](https://docs.agentcard.com/commerce-mcp/index.md#connect-a-client):
>
> ```ts agentcard-skill.ts theme={null}
> import { generateText } from 'ai';
> import { mcp, toolsFor } from './agentcard-mcp';
>
> const { contents } = await mcp.readResource({ uri: 'skill://agentcard-shopping/SKILL.md' });
> const skill = contents.map((part) => ('text' in part ? part.text : '')).join('\n');
>
> export async function answer(shopperId: string, chatId: string, message: string) {
>   return generateText({
>     model: yourModel, // the model you already use
>     system: skill,
>     tools: await toolsFor(shopperId, chatId),
>     prompt: message,
>   });
> }
> ```
>
> `SKILL.md` links to two more files. Read them by URI with `resources/read` when your model handles carts or recovers from errors, because `resources/list` shows only `SKILL.md`:
>
> | URI | Holds |
> | - | - |
> | `skill://agentcard-shopping/SKILL.md` | The tone, the links rule, confirming and approving, and the arguments of every tool |
> | `skill://agentcard-shopping/references/buying.md` | Reading a `buy` result, picks, the details Agentcard asks for in chat, and plan changes |
> | `skill://agentcard-shopping/references/transactions.md` | Confirming, recovering a call whose outcome is unclear, editing a saved cart, relaying updates, and following an order |
>
> The server serves the current skill on every read. [The shopping skill](https://docs.agentcard.com/opencommerce/guides/give-your-model-instructions.md) has more.

> [tab] API
>
> No request returns these instructions. If your server sends the shopper's words straight to `POST /buy` and shows `reply`, no model of yours talks to the shopper, and there is nothing to give.
>
> If your own model calls `POST /buy` as a tool, copy the text the SDK ships in the public npm package `@agent-cards/commerce-sdk`. Print it once from an empty folder with Node:
>
> ```bash theme={null}
> npm install @agent-cards/commerce-sdk
> node -e "import('@agent-cards/commerce-sdk').then((m) => console.log(m.APP_INSTRUCTIONS_VERSION + '\n\n' + m.appInstructions({ markdown: true })))"
> ```
>
> The first line of the output is the version, such as `0.2.85`. Copy the rest into your prompt, and change the two lines that name the SDK's own fields, `link_sent` and `shopper_need_not_reply`, which a `POST /buy` answer does not carry. Write instead that your app sends `add_card_url`, `approval_url` and `store_login_url` to the shopper, and that the model says a link is waiting when one is set. The copy stays as it was, so print it again when you update.

## Say how your app shows text

Tell your model whether your app shows Markdown, the formatting that turns `**bold**` and `| a | b |` into bold text and tables. In an app that shows Markdown, a shopper who asks for a table gets a table. In an app that shows plain text, such as an SMS chat, the model writes no Markdown and starts each list line with `• `.

> [tab] SDK
>
> Pass `markdown: true` when your app shows Markdown, and leave it out for plain text. Pass `textingStyle: true` when your app is a chat that writes in lowercase, the way a person texts, with the same value you pass to `buyTool`, so the model's words and Agentcard's read alike.
>
> ```ts agent.ts theme={null}
> const system = appInstructions({ markdown: false, textingStyle: true });
> ```

> [tab] MCP
>
> The skill is one text for every app, takes no options and says nothing about Markdown. Say in a line of your own whether your app shows it, as the next section shows.

> [tab] API
>
> Print the text with the options the SDK tab names, such as `appInstructions({ markdown: false, textingStyle: true })` for a plain-text chat that writes in lowercase.

## Add your own lines

Write your own lines after Agentcard's, and keep them about your app, such as its name or the current date. Leave out lines about which stores Agentcard reaches, which Agentcard's text covers as it adds stores. A line of your own that says "most online stores" contradicts Agentcard's, and the shopper then reads two different answers in one chat.

> [tab] SDK
>
> Leave out lines about formatting too: `markdown` and `textingStyle` set it, and a line such as "no markdown" contradicts them.
>
> ```ts agent.ts theme={null}
> const system = [
>   appInstructions({ markdown: true }),
>   'You are the shopping assistant in Acme. Each message opens with the shopper\'s local time.',
> ].join('\n\n');
> ```

> [tab] MCP
>
> ```ts agentcard-skill.ts theme={null}
> const system = [
>   skill,
>   'You are the shopping assistant in Acme. Acme shows Markdown, and shows product cards and a button for each link.',
> ].join('\n\n');
> ```

> [tab] API
>
> Put your lines after the text you copied. Leave out lines about formatting: the options you printed the text with set it.


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