Skip to content

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.

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

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.

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 No effect today. The greeting comes from the Welcome message on the General tab, or from your blocks when Welcome mode is Advanced
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
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.