Building an assistant

What an assistant is

An assistant is a chat window you embed on your own site that can actually do things, like look up an order, check stock or price a basket, by calling your workflows. You choose which of your tools it can reach, what it's allowed to say, who has to sign in first, and what it looks like.

Assistants are managed on the Agentic page (titled Agentic Commerce). You can run as many as you like: a support assistant on your help pages and a sales one on your product pages, with different tools and instructions.

Creating and managing assistants

1. Select New Assistant, give it a Name (for example "Support Assistant") and select Create. Only a name is asked for; everything else is set on the assistant's own page.
2. The list shows each assistant's status (Live or Off), how many tool sources it has and whether sign-in is required. Search by name, slug or description, and switch between list and grid.
3. Export and Import in the page header move assistants between stores as a JSON file.

Open an assistant to configure it. It has nine tabs: Instructions, Model, Tools, Appearance, Authentication, Embed, Test, Insights and Settings.

The header has a Live checkbox, Save and Delete. An assistant that is not Live won't load on your site. Nothing is stored until you select Save, with one exception: attaching or removing a tool source takes effect immediately. If something required is missing, Save tells you what and takes you to the right tab. Delete removes the assistant permanently, along with its conversations and its access to any attached tool sources, and anything embedding it stops working.

Instructions

Free text telling the assistant what it is, what it should do, and what it must not do. This is the single biggest lever on how it behaves.

Useful things to put here: who it is talking to, which topics to stay on, what tone to use, what to do when it doesn't know something, and when to hand off to a human. Be explicit about limits. "Never quote a delivery date, direct the customer to the tracking page instead" works better than hoping it won't.

Model

Two choices.

Included model is the default. There is nothing to set up, nothing to pay for separately, and no model to choose; it is managed for you and kept up to date over time. It is the recommended choice unless you need a specific model.

Or use your own account runs the assistant on your provider account instead, with your key, your quota and your bill. Choose a provider:

• Claude
• OpenAI
• Amazon Bedrock
• Gemini Enterprise Agent Platform
• Azure AI Foundry

Each needs a Connection, an active connection of that provider's own type from your Connections (only matching connections are offered, since another provider's credentials cannot work), and a Model:

• Amazon Bedrock: the model id, or the inference profile id where the model needs one. It must be enabled in your account, in the connection's region.
• Gemini Enterprise Agent Platform: a model id such as gemini-2.5-flash, or a Claude model. It must be enabled in your project, in the connection's location.
• Azure AI Foundry: your deployment name in the Foundry resource. Claude deployments use Foundry's Anthropic API; everything else uses its OpenAI-compatible API.

Switching provider clears the connection and model. Test connection sends one real message and shows the provider's own reply or the reason it was rejected. Nothing is saved by testing.

Response style

Applies to either choice:

• Creativity: from 0 to 1. 0 is focused and repeatable, 1 is varied. Keep it low for anything involving real order or product data.
• Longest reply: roughly how long an answer can get before it is cut off. Higher costs more per message.

Tools

An assistant can only do what you connect. Tools come from your MCP servers, each of which exposes a set of your workflows.

Use Choose an MCP server… and Attach. Each attached server lists the tools it currently offers; if it shows No tools available right now, the server can't be reached or its key was revoked. Attaching a server makes every tool on it available. The assistant decides which to call and when, based on your instructions and what the customer asks. A turn can involve several calls in sequence, like looking up a customer and then their orders, up to the maximum tool steps under Settings.

• Tool descriptions matter as much as your instructions. The assistant picks tools by reading them, so a route described as "Handles the thing" will be used badly or not at all.
• Only attach what the assistant genuinely needs. Every extra tool is another thing it can choose wrongly, and another thing a customer can provoke it into calling.

Appearance

A live preview sits beside the controls.

• Wording: Title, Opening message (shown before the visitor types anything), Starter prompts (one per line, up to 6, shown as buttons until the visitor sends something) and Input placeholder.
• Colours: Accent, Background and Text. Use a gradient blends the accent into a second colour; choose a preset or set the Second colour, Angle and Background wash.
• Type and size: Font, Font size, Width, Height and Corner radius.
• Layout: Launcher (Round button or Ask bar), Chat opens as (Floating window or Side panel that moves the page aside), Button position (bottom left or right) and an optional Avatar image URL.
• Visitor features: Let people speak their question adds a microphone button. Let people attach files adds a paperclip, up to 5MB a file, and file contents count towards the assistant's daily allowance. Allow new conversations adds a New conversation button to the chat header, and each new conversation counts against your plan's monthly conversation allowance. Waiting phrases are shown in turn while the assistant works, and you can replace the built-in ones. Show token usage displays the tokens each reply used, which is useful while testing cost but not something visitors need.

The opening message is worth more thought than the colours. It sets a customer's expectation of what this assistant can help with.

Authentication

Controls whether visitors must sign in before they can chat, and what the assistant knows about them once they have.

Require sign-in

Off by default: anyone who can see the page can chat. Turn it on for anything that touches a customer's own data. Choose a Login Method:

Custom Login sends the username and password to a workflow you wrote, so the platform never sees how credentials are checked. Choose the Login Workflow and the Route Path within it, and name the Username Field and Password Field it expects.

OAuth Provider redirects to an external identity provider instead. Give it the Authorization URL, Token URL, Client ID, Client Secret and Scopes. The client secret is write-only: once saved it is encrypted and never shown again, and leaving it blank on a later save keeps the existing one.

Either way you can set a Login Page Title and a Sign-in image (your logo, shown above the form; PNG, JPG, GIF, WEBP, AVIF, SVG or ICO, up to 2MB). You can't turn sign-in on until the login workflow, or both OAuth URLs, are set.

Personalise answers for the signed-in customer

Tick Personalise answers for the signed-in customer to pass who is signed in through to your workflows, so the assistant sees that customer's own prices and only the products they are allowed to see. Identity comes from the sign-in, never from the conversation.

This reveals the forwarded headers, which map values out of the sign-in response into headers sent with every tool call:

Header	Value
Authorization	Bearer {{body.data.access_token}}
X-Customer-ID	{{body.data.customer_id}}
X-Request-ID	{{header.x-request-id}}

{{body.…}} reads a dot-path out of the sign-in response body (array indexes work: {{body.users[0].id}}), and {{header.…}} reads one of its response headers, case-insensitively. Anything else in the value is sent literally, which is where the Bearer prefix comes from.

• A header whose template can't be filled is left out entirely, never sent as Bearer undefined. An absent header is far easier to diagnose than a present but empty one.
• They are resolved once, at sign-in. Changing the mapping doesn't affect sessions that are already open.
• They are merged after the assistant's own arguments, so the assistant cannot overwrite them. It cannot name somebody else's customer id and read their prices.

Session expiry

How long before a visitor has to sign in again: 1 hour, 8 hours, 1 day, 7 days, 30 days, or a custom number of seconds (at least 60). Longer sessions mean fewer interruptions; shorter ones limit how long a shared or forgotten browser stays signed in.

Signed-in visitors get a Sign out link in the chat header, which clears their session, the forwarded headers derived from it, and the conversation.

Embed

Paste one of the snippets into your site's HTML:

• Floating button: a script that adds a floating chat button and opens the conversation from it. This is the usual choice.
• Inline frame: places the conversation directly in the page, for a dedicated support page or a sidebar.

If your store or organisation has custom domains, Serve the assistant from sets the address the snippets use, and Chat calls go to sets the API address the chat uses for every call. When you use a custom API domain, make sure your firewall or content security policy allows it.

React to cart changes: when the assistant adds to, updates or removes from a customer's cart, the page receives an event you can listen for (yd-agent-cart-add, yd-agent-cart-updated, yd-agent-cart-deleted) with the item reference, the quantity and the previous quantity. For the inline frame the same names arrive as postMessage messages.

The tab warns if the assistant is turned off, and shows which sites can load it, or that any website can embed it until you add allowed sites under Settings.

Test

The Test tab runs your assistant in the real chat window so you can try it before it goes on your site. Choose a width, Reload, start a New conversation (which clears the stored session and sign-in), or Open in a tab.

• It runs the saved assistant, so save first and then reload to see what you changed.
• It is a real conversation, not a simulation: tools run against your live connections, replies use tokens from the daily budget, and the message limits apply.
• Sign-in behaves as it does on your site, so you will be asked to sign in here too when it's required.

Insights

Insights shows how the assistant is doing, for the last 7, 30 or 90 days or a custom range. It shows totals and patterns, not individual conversations.

• Usage: conversations, messages per conversation, how many people left after one message, and typical reply time.
• Performance: how many tools were called, how many failed, replies that used no tool, tokens used, and a per-tool table.
• Asked for, not found: searches that came back empty, which shows what shoppers wanted that the assistant couldn't show them.
• Audience: how many were signed in, top countries and devices.

Settings

• Basics: Name and Description for your own reference, and Maximum tool steps per message (1 to 20): how many times the assistant may call tools before it must answer. Higher allows more thorough answers and costs more per message.
• Allowed websites: the sites that may show the assistant. Add the address visitors see, including any subdomain, so www.example.com and help.example.com are separate entries. Leave it empty to allow any site.
• Values from your website: things your site already knows about the visitor, such as their open basket, passed to the assistant's tools as headers. Pick a source (a cookie or local storage), its name on your site and the header name, and optionally parse JSON and a path inside it. Mark one Required to show the assistant only on pages where it exists. A visitor can change these values, so treat them as a hint rather than proof of who someone is; if the assistant signs people in, that identity wins.
• Predefined headers: sent with every tool call the assistant makes, whether or not the visitor is signed in. Use them for a partner id or a fixed key a workflow needs.
• Message limits: see below.

Message limits

Anyone who can open your chat can also call it from a script. These limits keep that bounded. Set any to 0 to switch it off.

Limit	Default	What it does
Per visitor, per minute	10	Slows one person down without affecting anyone else
Per visitor, per day	200	Caps what a single visitor can cost you in a day
Per conversation	100	The conversation ends after this many messages. A visitor can start a new one only if Allow new conversations is on
Total per day	5000	The hard ceiling on this assistant's daily cost

The first three key on the visitor's network address, so they limit one abuser rather than a distributed one. Total per day counts every message the assistant answers regardless of who asked, so nothing gets past it. It is the number to set with your budget in mind. When a visitor hits a limit the chat tells them so and the message isn't answered.

Going live

1. Write the instructions.
2. Choose the model, or keep the included one, and use Test connection if you bring your own.
3. Attach the MCP servers holding the tools it needs, and no more.
4. Set the appearance, especially the opening message.
5. Decide on sign-in, and if it's on, map the forwarded headers your workflows expect.
6. Check the message limits against what you're willing to spend, and list your allowed websites.
7. Tick Live, select Save, and try it in the Test tab, with sign-in turned on if you use it.
8. Copy the embed snippet onto your site, then watch Insights.