Prompt instructions settings

Prompt instructions are rules you add to one step of one specialist agent of the AI Shopping Assistant, for one agent only. Each has a type, a tag and up to 8,000 characters of prompt text. Enabled instructions apply from the next message.

Overview

The Prompt instructions tab holds the rules you write for one agent of the AI Shopping Assistant, such as brand voice, answer length and business rules. Each prompt instruction is added to the end of the instructions for one step of one specialist agent. The Type you pick chooses that step. The instruction applies only to this agent.

Only instructions with the status Enabled apply. Changes apply from the next message, with nothing to publish. Prompt instructions shape how the AI Shopping Assistant uses what it already knows. Facts belong in Trainings. Actions, such as collecting details or handing off to a person, belong in custom workflows.

Stores that use the standard view of the embedded Shopify app see a single agent page with no Prompt instructions tab.

The prompt instructions list

The tab lists every prompt instruction on the agent, one row for each type. With no instructions, the tab reads “No prompt instructions yet”.

Column	What it shows
Prompt instruction	The prompt text, shortened to fit the row
Tags	The instruction’s tag
Type	The stored type, such as product_qna_agent:answer
Status	Enabled or Disabled
Created by	The console user who created the instruction
Created	When the instruction was created

Filters

Filter	What it does
Search box	Narrows the list to instructions that match the text you type
Date range	Narrows the list to instructions created in a date range
Tags	Narrows the list to the tags you choose
Type	Narrows the list to the types you choose
Clear	Removes every filter

Actions

Action	Where	Effect
Add prompt instruction	Tab header	Opens the form for a new instruction. Works once the agent has been saved
Select a row	List	Expands the row to show the instruction’s details
Double-click a row	List	Opens the instruction for editing
Disable or Enable	Row menu	Switches the instruction off or on without deleting it
Edit	Row menu	Opens the instruction for editing
Delete	Row menu	Deletes the instruction after you confirm in the Delete prompt instruction dialog
Edit	Selected rows	Edits the selected rows together. Offered when two or more selected rows share a tag
Delete	Selected rows	Deletes every selected row

Prompt instruction fields

The form opens in a side panel. It has Cancel and Create when you add an instruction, or Cancel and Save changes when you edit one.

Field	What it does	Allowed values	Default
Type	Chooses the specialist agent step the instruction is added to. Each type you pick saves as its own row with the same tag and prompt text	One or more types from the picker. Use new adds a type you type in, but a type that no part of the AI Shopping Assistant reads has no effect	None. Required
Tag	Names the rule. Instructions on the same type apply together, each under its own tag	Lowercase letters, digits, hyphens and underscores, up to 64 characters. Can’t be changed when editing	default when left blank
Prompt text	The rule itself. A live counter shows the characters used	Text, up to 8,000 characters	None. Required

Saving a type and tag that already exist replaces the prompt text saved there. When you edit an instruction, you can add or remove types. Removing a type deletes that type’s row when you save.

Types

The Type picker groups types under a header for each specialist agent. The group and option below match the picker. The Type column of the list shows the stored value.

Group	Option	Stored as	What the instruction shapes
CUSTOMER SUPPORT AGENT	system	customer_support_agent:system	Store policy and support answers drawn from Trainings
DIALOG AGENT	system	dialog_agent:system	General conversation
IMAGE AGENT	vision	image_agent:vision	How a photo a shopper uploads is described
INVENTORY AGENT	system	inventory_agent:system	Answers about stock
ORDERS RETURNS AGENT	Intent Understanding	orders_returns_agent:intent_analysis	How order and return requests are recognized
ORDERS RETURNS AGENT	response	orders_returns_agent:response	Replies about orders and returns
PRODUCT COMPARE AGENT	comparison	product_compare_agent:comparison	How comparisons read
PRODUCT COMPARE AGENT	extraction	product_compare_agent:extraction	Which products are picked out to compare
PRODUCT DISCOVERY AGENT	DSL + LLM Refine	product_discovery_agent:dsl_llm_search	Applies only when Product Discovery uses a search method Webscale sets up. Most stores see no effect
PRODUCT DISCOVERY AGENT	LLM Search	product_discovery_agent:llm_search	Applies only when Product Discovery uses a search method Webscale sets up. Most stores see no effect
PRODUCT FAQ AGENT	system	product_faq_agent:system	The FAQs generated for product pages
PRODUCT IMAGE SEARCH AGENT	Query Intent	product_image_search_agent:dsl_intent	How a photo search is read
PRODUCT IMAGE SEARCH AGENT	Results Intro	product_image_search_agent:response	The intro line above photo search results
PRODUCT LLM SUGGESTOR AGENT	Query Intent	product_llm_suggestor_agent:adsl_intent	How a request to Product LLM Suggestor is read, such as whether the shopper wants an accessory, a compatible item or an upgrade, and which product it is for
PRODUCT LLM SUGGESTOR AGENT	narrative	product_llm_suggestor_agent:narrative	The short message shown with Product LLM Suggestor’s results, which explains why the products fit or says that nothing matches
PRODUCT LLM SUGGESTOR AGENT	sku_suggest	product_llm_suggestor_agent:sku_suggest	Which products Product LLM Suggestor proposes and in what order. Only products in your catalog are shown
PRODUCT QNA AGENT	answer	product_qna_agent:answer	The answer to a product question, including its tone and length
PRODUCT QNA AGENT	Catalog Answer	product_qna_agent:catalog_answer	Answers drawn from the whole catalog
PRODUCT QNA AGENT	Query Intent	product_qna_agent:qna_intent	How a product question is classified
PRODUCT QNA AGENT	system	product_qna_agent:system	Ground rules for product questions
PRODUCT TEXT SEARCH AGENT	Query Intent	product_text_search_agent:dsl_intent	How a typed product search is read. Shapes everyday Product Discovery searches
PRODUCT TEXT SEARCH AGENT	Results Intro	product_text_search_agent:response	The intro line above product search results. Shapes everyday Product Discovery searches
RAG AGENT	system	rag_agent:system	Answers drawn from Trainings
ROUTER	routing	router:routing	Which specialist agent handles each message. Custom workflow triggers still take priority
WELCOME AGENT	system	welcome_agent:system	The greeting

How prompt instructions apply

Rule	Effect
Scope	An instruction applies only to the agent it was created on
Placement	An instruction is added to the end of the instructions for the one specialist agent step its type names
Status	Only Enabled instructions apply. A Disabled instruction stays in the list with no effect
Several instructions on one type	Every enabled instruction on the same type applies together, each under its tag name
Same type and tag	Saving replaces the prompt text already saved for that type and tag
Timing	Changes apply from the next message
Specialist agent switched off	A specialist agent switched off under Advanced settings never runs, so instructions on its types have no effect
Custom workflow triggers	A message that matches a custom workflow trigger goes to that workflow, whatever a ROUTER instruction says
Who can edit	Creating, editing and deleting instructions needs the merchant admin role

Limits

Limit	Value
Prompt text	8,000 characters
Tag length	64 characters
Tag characters	Lowercase letters, digits, hyphens and underscores
Types per instruction	One or more. Each type is stored as its own row
Agents per instruction	One

Frequently asked questions

Do prompt instructions apply to every agent in my account?

No. A prompt instruction applies only to the agent it was created on. Add the same instruction to each agent that needs the rule.

What happens if I save a type and tag that already exist?

The new prompt text replaces the text already saved for that type and tag. Use a different tag to keep both rules.