Skip to content

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.

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

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

  1. Go to Assistant > Agents, open the agent and select the Prompt instructions tab.
  2. Select Add prompt instruction.
  3. Under Type, pick the replies the rule should shape. Pick more than one type to apply the same rule to each.
  4. Under Tag, name the rule in lowercase letters, digits, hyphens and underscores.
  5. Write the rule under Prompt text. The counter shows how much of the 8,000 characters you have used.
  6. Select Create. Each type saves as its own row, switched on as Enabled.
  1. Go to Assistant > Agents and open the agent.
  2. Select the Prompt instructions tab.
  3. Select Add prompt instruction.
  4. 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.
  5. Under Tag, enter a short name for the rule, such as brand-voice or no-delivery-promises. Use lowercase letters, digits, hyphens and underscores, up to 64 characters. A blank tag saves as default.
  6. Under Prompt text, write the rule. The counter shows how many of the 8,000 characters you have used.
  7. Select Create.
  8. 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.

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

  1. Before the rule, a shopper asking about Friday delivery got a promise the store can't keep.
  2. 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.
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

  1. A tag with capitals or spaces stops Create with an error. Nothing is saved.
  2. 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.