Write prompt instructions for brand voice and business rules
Open the agent's Prompt instructions tab, select Add prompt instruction, pick the type for the reply you want to change, add a tag and write the rule. Enabled instructions apply from the next message, for that agent only.
Before you start
Section titled “Before you start”Use prompt instructions when the AI Shopping Assistant has the right facts but says them the wrong way, or when it must follow a business rule. The Prompt instructions settings reference lists every field and type.
| The problem | Where to fix it |
|---|---|
| The answer has the right facts but the wrong tone, length or wording | Prompt instructions, with this guide |
| The answer must follow a business rule, such as never promising a delivery date | Prompt instructions, with this guide |
| The answer is missing a fact or uses an outdated policy | Trainings. See Add training documents |
| The AI Shopping Assistant should do something, such as collect details or hand off to a person | Custom workflows |
| The greeting a shopper sees when a chat starts | The Welcome message on the agent’s General tab, or the blocks you choose under Welcome mode. See Specialist agents |
Choose a type
Section titled “Choose a type”Each prompt instruction changes one step of one specialist agent of the AI Shopping Assistant, chosen by its Type. The Type picker groups types under a header for each specialist agent. These are the types most rules need.
| To change | Group | Option |
|---|---|---|
| The answer to a product question, including tone and length | PRODUCT QNA AGENT | answer |
| Store policy and support answers | CUSTOMER SUPPORT AGENT | system |
| Other answers drawn from Trainings | RAG AGENT | system |
| Replies about orders and returns | ORDERS RETURNS AGENT | response |
| How a typed product search is read | PRODUCT TEXT SEARCH AGENT | Query Intent |
| The intro line above product search results | PRODUCT TEXT SEARCH AGENT | Results Intro |
| How comparisons read | PRODUCT COMPARE AGENT | comparison |
| General conversation | DIALOG AGENT | system |
| The FAQs generated for product pages | PRODUCT FAQ AGENT | system |
| Which specialist agent handles each message | ROUTER | routing |
For product searches, use the PRODUCT TEXT SEARCH AGENT types. The two PRODUCT DISCOVERY AGENT types apply only when Product Discovery uses a search method Webscale sets up, so most stores see no effect from them.
Prompt instructions don’t change the greeting. The WELCOME AGENT system type has no effect on what shoppers see today.
A rule such as brand voice often needs to cover several kinds of reply. Pick every type it should cover in the same form. Each type saves as its own row with the same tag and text.
Add a rule
- Go to Assistant > Agents, open the agent and select the Prompt instructions tab.
- Select Add prompt instruction.
- Under Type, pick the replies the rule should shape. Pick more than one type to apply the same rule to each.
- Under Tag, name the rule in lowercase letters, digits, hyphens and underscores.
- Write the rule under Prompt text. The counter shows how much of the 8,000 characters you have used.
- Select Create. Each type saves as its own row, switched on as Enabled.
- Go to Assistant > Agents and open the agent.
- Select the Prompt instructions tab.
- Select Add prompt instruction.
- Under Type, pick the type for the reply you want to change. Pick more than one type to apply the same rule to each. Avoid Use new, which adds a type you type in. A type that no part of the AI Shopping Assistant reads has no effect.
- Under Tag, enter a short name for the rule, such as
brand-voiceorno-delivery-promises. Use lowercase letters, digits, hyphens and underscores, up to 64 characters. A blank tag saves asdefault. - Under Prompt text, write the rule. The counter shows how many of the 8,000 characters you have used.
- Select Create.
- Find the new row and check that Status shows Enabled. If it shows Disabled, open the row menu and select Enable.
Give each rule its own tag. Saving a type and tag that already exist replaces the text saved there.
To change a rule later, or switch it off without losing it, see Edit or pause a prompt instruction.
Check that it worked
Section titled “Check that it worked”Open the agent and select Playground to open the Playground panel. Ask the question that produced the reply you wanted to change. The Playground answers from saved settings. It answers only when the agent is active.
Check it in the Playground
- Before the rule, a shopper asking about Friday delivery got a promise the store can't keep.
- With no-delivery-promises enabled, the same question gets the shipping range instead. Rules apply from the next message.
Compare the new reply with one from before the change. For a side-by-side check, select Disable in the instruction’s row menu and ask again, then select Enable and ask once more. See Test changes in the Playground for more ways to test.
If the reply hasn’t changed, check which specialist agent answered. Open Logs, open the conversation and read the Routing agent field in the Agent section. The instruction’s type must belong to that specialist agent.
Write rules the AI Shopping Assistant follows
Section titled “Write rules the AI Shopping Assistant follows”The AI Shopping Assistant follows short, direct rules most reliably. These habits help.
- Keep one rule in each instruction, with its own tag. You can then switch off or delete one rule without touching the others.
- Write the rule as a direct instruction. Starting with ALWAYS or NEVER can make a rule clearer.
- Say what to do instead, as well as what to avoid.
- Keep facts in Trainings. A policy written into an instruction can go out of date without anyone noticing.
- Change one rule at a time and test it before you add the next.
| Goal | Type | Tag | Prompt text |
|---|---|---|---|
| Shorter product answers | PRODUCT QNA AGENT > answer | answer-length |
Keep answers to three sentences or fewer. Lead with the direct answer. |
| Brand voice for product answers | PRODUCT QNA AGENT > answer | brand-voice |
Write in a warm, plain voice. Speak to the shopper as “you” and avoid jargon. |
| No delivery promises | CUSTOMER SUPPORT AGENT > system | no-delivery-promises |
NEVER promise a delivery date. Point shoppers to the shipping times in our shipping policy instead. |
| Final sale reminder | ORDERS RETURNS AGENT > response | final-sale |
When a shopper asks about a return, ALWAYS remind them that final sale items can’t be returned. |
| Store vocabulary in search | PRODUCT TEXT SEARCH AGENT > Query Intent | kids-sizes |
When a shopper asks for kids’ sizes, search for youth sizes. |
Troubleshooting
Section titled “Troubleshooting”| Problem | Fix |
|---|---|
| There is no Prompt instructions tab | Stores that use the standard view of the embedded Shopify app see a single agent page without this tab |
| Create shows “Tag may only contain lowercase letters, digits, “-” and “_”.” | Change the tag to lowercase letters, digits, hyphens and underscores, then select Create again. Nothing is saved until it does |
| Add prompt instruction does nothing | Save the agent first. The button works once the agent has been saved |
| You can’t create or edit instructions | Writing prompt instructions needs the merchant admin role. Ask an admin on your account |
| The reply hasn’t changed | Check that the row shows Enabled. Then check in Logs that the instruction’s type belongs to the specialist agent that answered |
| The reply still hasn’t changed | Check that the specialist agent is switched on under Advanced settings. A specialist agent that is off never runs, so its instructions don’t either |
| An earlier rule’s text is gone | A new instruction with the same type and tag replaced it. Add the earlier rule again under a different tag |
| You need a different tag | Tags can’t be changed when editing. Add a new instruction with the new tag, then delete the old one |
| A search rule has no effect | Use the PRODUCT TEXT SEARCH AGENT types. The PRODUCT DISCOVERY AGENT types affect only search methods Webscale sets up |
| A type added with Use new has no effect | Pick a type from the list. A type that no part of the AI Shopping Assistant reads does nothing |
| A ROUTER rule is ignored for some messages | Messages that match a custom workflow trigger go to that workflow first |
| The answer has the wrong facts | Prompt instructions don’t add facts. Add the missing content to Trainings |
When Create shows an error
- A tag with capitals or spaces stops Create with an error. Nothing is saved.
- Fix the tag and select Create again. Saving a type and tag that already exist replaces that rule's text.
Frequently asked questions
- Do prompt instructions apply to all my agents?
- No. A prompt instruction applies only to the agent it was created on. Add the same rule to each agent that needs it.
- How quickly do prompt instructions reach shoppers?
- Enabled instructions apply from the next message, with nothing to publish. Disabling an instruction takes effect just as fast.
- Should store policies go in prompt instructions?
- No. Policies and other facts belong in Trainings, where the AI Shopping Assistant looks them up. Use prompt instructions for how answers are written and for business rules.
- Why don't I see a Prompt instructions tab?
- Stores that use the standard view of the embedded Shopify app see a single agent page without a Prompt instructions tab.